Documentation

Unity Engine

User Manual

Script Reference

Unity Engine

Create samples for your package

Include optional samples that help users learn the package and import example content.
Read time 6 minutesLast updated 12 days ago
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:
  1. 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.
  2. Open the package manifest file (
    package.json
    ) for editing. To locate the file, refer to Locate the manifest file.
  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 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.
  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.

Images support

If you include the 
images
array, consider the following when adding images:
  • The recommended aspect ratio is 16:9, such as 1920 × 1080.
  • Supported formats are BMP, EXR, HDR, IFF, JPG/JPEG, PICT, PNG, PSD, SVG, TGA, TIFF.
  • The PNG format is recommended for images with an alpha channel or transparency.

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:
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

Example of a samples array in the manifest file

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"]		}	]}

Samples folder naming convention

When creating your package with the Create package function, the creation process performs several operations. These operations include:
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.

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
  • images
    (array)

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.
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
:
  • 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 include the 
    images
    array, make sure all values start with 
    "Samples~/"
    . Be sure to include the trailing tilde.
  • If you plan to use 
    package.json
    for all samples metadata, delete all 
    .sample.json
    files from the 
    Samples
    directory tree.

Additional resources