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 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:
Put the asset files or C# code files under the Samples folder. You can have more than one sample in a package. Each subfolder of the Samples folder has one sample.
Open the package manifest file (package.json) for editing. To locate the file, refer to Locate the manifest file.
If the file doesn’t contain a JSON array called samples, add it.
For each sample you want to include, add a JSON object in the samples array.
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 appears in the Samples tab of the Package Manager window’s details panel. |
path |
The path to the sample’s folder, starting with Samples. |
images(optional) |
An array of strings that specifies image file paths, relative to the package root, starting with the sample folder path specified in path. The images appear in the details panel when viewing a sample from the All Samples view. |
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.
Save the file.
If you include the images array, consider the following when adding images:
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:
MyPackage
├── package.json
└── Samples
├── SamplesHDRP
│ ├── Images
│ | ├── CarouselImage1.png
│ | └── CarouselImage2.png
│ ├── Shader
│ | ├── Lit Texture Blend HDRP.ShaderGraph
│ | └── Lit Vertex Color HDRP.ShaderGraph
│ └── Textures
│ ├── MossyRock.bmp
│ └── SandyRock.bmp
└── SamplesStandard
│ ├── Images
│ | ├── CarouselImage1.png
│ | └── CarouselImage2.png
│ ├── Shader
│ | ├── StandardTextureBlend.shader
│ | └── StandardVertexColor.shader
│ └── Textures
│ ├── MossyRock.bmp
│ └── SandyRock.bmp
└── SamplesUniversalRP
├── Images
| ├── CarouselImage1.png
| └── CarouselImage2.png
├── Shader
| ├── Lit Texture Blend URP.ShaderGraph
| └── Lit Vertex Color URP.ShaderGraph
└── Textures
├── MossyRock.bmp
└── SandyRock.bmp
Using the same structure as the example for Location of sample files, the samples array in package.json looks similar to this:
{
"samples": [
{
"displayName": "HDRP Shaders",
"description": "Contains sample shaders for the High Definition render pipeline",
"path": "Samples/SamplesHDRP",
"images": ["Samples/SamplesHDRP/Images/CarouselImage1.png", "Samples/SamplesHDRP/Images/CarouselImage2.png"]
},
{
"displayName": "Standard RP Shaders",
"description": "Contains sample shaders for the Standard render pipeline",
"path": "Samples/SamplesStandard",
"images": ["Samples/SamplesStandard/Images/CarouselImage1.png", "Samples/SamplesStandard/Images/CarouselImage2.png"]
},
{
"displayName": "URP Shaders",
"description": "Contains sample shaders for the Universal render pipeline",
"path": "Samples/SamplesUniversalRP",
"images": ["Samples/SamplesUniversalRP/Images/CarouselImage1.png", "Samples/SamplesUniversalRP/Images/CarouselImage2.png"]
}
]
}
When creating your package with the Create package function, the creation process performs several operations. These operations include:
Samples subfolder.Samples/Example/.sample.json. For more information, refer to Define sample metadata with .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), 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. During the packing process, Unity also adjusts Samples to Samples~ in the package manifest file that gets cached in the target project. You don’t need to adjust the path values for samples in your local package manifest file before you export or pack your package. The Package Manager will resolve the sample path correctly. After developers import your sample, they can find it in the Assets folder of the Project window.
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:
displayNamedescriptionimages (array)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.
If you specify the images array in .sample.json, the values must start with "Samples~/", even if the Samples directory in your development directory doesn’t end with the tilde (~).
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:
.sample.json, create one file per sample, store all samples metadata in those files, and remove any overlapping metadata from package.json. If you include the images array, make sure all values start with "Samples~/". Be sure to include the trailing tilde.package.json for all samples metadata, delete all .sample.json files from the Samples directory tree.