# Create samples for your package

> Include optional samples that help users learn the package and import example content.

You can create samples to include in a Unity Package Manager (UPM) package you develop.

Although optional, including samples helps users learn how to use your package. A sample might be a piece of example code, some shaders and textures, some animation, or any other files that you typically find under the project's `Assets` folder.

When you open the Package Manager window and select a package containing samples, an **Import** button appears in the package's [details panel](/engine/6000.3/manual/packages-list/upm-ui-window/upm-ui-details.md) for each sample in the package. When you select **Import**, the Package Manager copies the whole subfolder structure for that sample under the project's `Assets` folder.

To add samples to your package:

1. Put the asset files or C# code files [under the Samples folder](#sample-subfolder). You can have more than one sample in a package. Each subfolder of the `Samples` folder has one sample.

2. Open the package manifest file (`package.json`) for editing. To locate the file, refer to [Locate the manifest file](/engine/6000.3/manual/packages-list/cus-pkg-lp/cus-pkg-development/cus-pkg-manifest/cus-edit-manifest.md#locate-manifest).

3. If the file doesn't contain a JSON array called `samples`, add it.

4. For each sample you want to include, add a JSON object in the `samples` array.

5. Include the following keys and values for each JSON object in the `samples` array:

   | **Key**                 | **Description**                                                                                                                                                          |
   | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
   | `displayName`           | The name of the sample as it appears in the package details panel of the Package Manager window.                                                                         |
   | `description`(optional) | A brief description of what the sample demonstrates or contains. This description displays in the **Samples** tab of the Package Manager window's package details panel. |
   | `path`                  | The path to the sample’s folder, starting with `Samples`.                                                                                                                |

6. Make sure that `package.json` contains valid JSON. You can check its validity using an online JSON validator or directly in your code editor, if it supports JSON syntax checking.

7. Save the file.

## Location of sample files

You can add your sample assets under subfolders of the `Samples` folder of your package. For example, a package with shader samples might look something like this:

```lang-plain
MyPackage
  ├── package.json
  └── Samples
        ├── SamplesHDRP
        │    ├── Textures
        │    |     ├── MossyRock.bmp
        │    |     └── SandyRock.bmp
        │    └── Shader
        │          ├── Lit Texture Blend HDRP.ShaderGraph
        │          └── Lit Vertex Color HDRP.ShaderGraph
        └── SamplesStandard
        │    ├── Textures
        │    |     ├── MossyRock.bmp
        │    |     └── SandyRock.bmp
        │    └── Shader
        │          ├── StandardTextureBlend.shader
        │          └── StandardVertexColor.shader
        └── SamplesUniversalRP
             ├── Textures
             |     ├── MossyRock.bmp
             |     └── SandyRock.bmp
             └── Shader
                   ├── Lit Texture Blend URP.ShaderGraph
                   └── Lit Vertex Color URP.ShaderGraph
```

## Example of a samples array in the manifest file

Using the same structure as the example for [Location of sample files](#sample-subfolder), the `samples` array in `package.json` looks similar to this:

```lang-json
{
	"samples": [
		{
			"displayName": "HDRP Shaders",
			"description": "Contains sample shaders for the High Definition render pipeline",
			"path": "Samples/SamplesHDRP"
		},
        {
			"displayName": "Standard RP Shaders",
			"description": "Contains sample shaders for the Standard render pipeline",
			"path": "Samples/SamplesStandard"
		},
		{
			"displayName": "URP Shaders",
			"description": "Contains sample shaders for the Universal render pipeline",
			"path": "Samples/SamplesUniversalRP"
		}
	]
}
```

## Samples folder naming convention

When creating your package with the **Create package** function, the creation process performs several operations. These operations include:

* Creating a [folder structure](/engine/6000.3/manual/packages-list/cus-pkg-lp/cus-pkg-development/cus-pkg-structure/cus-layout.md) in your package folder, including the creation of a `Samples` subfolder.
* Generating a sample configuration file at `Samples/Example/.sample.json`. For more information, refer to [Define sample metadata with .sample.json](#sample-json).

If you choose to delete all `.sample.json` files and control samples metadata with the package manifest file (`package.json`), keep the `path` value (in the `samples` array in `package.json` as `Samples`. Don't append a trailing tilde (`~`).

Any time you run a Unity process that packs your package (such as the [export process](/engine/6000.3/manual/packages-list/cus-pkg-lp/cus-pkg-development/cus-export.md)), Unity renames the `Samples` folder to `Samples~`. Appending the tilde hides the sample in the `Packages` folder of the **Project** window when others install your package. After developers import your sample, they can find it in the `Assets` folder of the **Project** window.

## Define sample metadata with .sample.json

While developing your package, you might find it inconvenient to edit the samples' `path` value in your package manifest file from `Samples` to `Samples~` to test it as an installed package. Instead of renaming `Samples` while testing, another solution is to define sample-specific metadata in a `.sample.json` file inside the individual sample subfolder (or subfolders) within the `Samples` folder for your package. When you pack your package, the packing tool checks for `.sample.json` files. If the tool finds any `.sample.json` files, it ignores the entire `samples` entry in the package manifest (`package.json`) and replaces it with the metadata collected from the `.sample.json` files.

The properties you can define in `.sample.json` are:

* `displayName`
* `description`

### Best practices when using .sample.json

Don't set a `path` property in `.sample.json`. The `pack` operations determine the sample path based on the location of the `.sample.json` files.

If you have multiple sample folders directly under the `Samples` folder, make sure you create one `.sample.json` file for each subfolder directly under `Samples`. Store each samples' metadata in those files. Otherwise, some samples might be missing in the installed package or have missing or incorrect metadata.

Don't mix metadata sources. The recommended best practice is to specify samples metadata in either the `package.json` file or in the `.sample.json` file (or files). The presence of even one `.sample.json` file anywhere under `Samples` causes the packing tool to completely ignore the `samples` array in `package.json`. Every sample must therefore have its own `.sample.json` file. Otherwise, those samples will not appear when others install your package. Use either `.sample.json` files (one per sample) or the `samples` array in `package.json`:

* If you plan to use `.sample.json`, create one file per sample, store all samples metadata in those files, and remove any overlapping metadata from `package.json`.
* If you plan to use `package.json` for all samples metadata, delete all `.sample.json` files from the `Samples` directory tree.

## Additional resources

* [Package creation](/engine/6000.3/manual/packages-list/cus-pkg-lp.md)
* [Package development workflow](/engine/6000.3/manual/packages-list/cus-pkg-lp/cus-pkg-development/custom-packages.md)
* [Edit the package manifest](/engine/6000.3/manual/packages-list/cus-pkg-lp/cus-pkg-development/cus-pkg-manifest/cus-edit-manifest.md)