5.1 KiB
Adding Importable Assets
This part of the manual pertains to the following folders and files:
<root>
├── package.json
└── Samples~
└── Example1
└── Example.txt
Per Unity's documentation, technically, the only required files in this section is package.json and at least one folder. Furthermore, all folders do not have to be named the way they are, or put into hierarchy the way they are. As Unity has not documented on their recommendation of where to place importable assets, Samples~ will be used for this section, as the trailing ~ hides the folder from Unity Project Window's view.
Note that if the project does not contain any importable assets, the folder Samples~, its subfolder, and content can be deleted safely. Do not forget to update the package.json file accordingly, as detailed at the bottom of this section.
This section will assume the developer will rename a few folders an files, and describe how to update the package to work with the new folder naming-scheme:
Samples~ folder
This folder is intended contain assets that can be importaed from the Unity Package Manager window. As a demonstration, the template contains one subfolder, Example1. Since it and its content is obviously just a sample asset, it's recommended to delete this folder and update the Package Manifest accordingly (see the end of this section on how).
If it hasn't been done so already, it's highly recommended to configure the Unity Editor to generate meta files. For more information on Unity meta file settings, see Unity's documentation on Editor Manager.
As seen in the screenshot above, the Unity Package Manager allows the package maintainer to list different groups of assets to import separately from one another (e.g. required assets vs. sample demonstrations). As such, it's recommended to categorize each importable assets first. From there, simply create a subfolder for each category, and copy or move any assets belonging in that category into the new subfolder. Since the Samples~ folder is hidden in the Unity Project window, this must be done in a file manager, e.g. Finder on Mac OSX. Remember when copying or moving any importable assets from the Unity project to a Samples~ subfolder, the meta file with matching file name should be copied/moved into the same subfolder as well for maximum compatibility. Finally, do note that subfolders in Samples~ can have more nested subfolders, if the package maintainer so desires. When the assets get imported, the hierarcy of these subfolders will be copied over as well.
Once this is all finished, the Package Manifest MUST be updated to recognize these new subfolders (see below).
Package Manifest - package.json
This file is required: it should not be deleted, moved, or renamed. That said, it must be edited.
The Package Manifest file is a text file in JSON format storing details about the package that the Package Manager can use to display and categorize the project. This section will only focus on one field: the samples field. As of this writing, Unity does allow editing this field through its Inspector window: the file must be updated with a text editor. For more information about this file, check out Unity's own documentation!
samples
"samples": [
{
"displayName": "Example 1",
"description": "This sample is just an example",
"path": "Samples~/Example1"
}
]
This field is optional, and if this package does not contain any importable assets, can be safely removed. If it does, this field should be updated.
As the name implies, samples is the details of each group of importable assets, split by subfolders. By default, this template lists the Samples~/Example1 folder it came with. The field takes in a list of objects, each with the following fields:
displayName: the human-readable name listed next to the "Import to Project" button.description: the description of the group of assets to import.path: the path to the folder where this group of assets are held in. The path is relative to the root of the package, and the folder names should be divided with a/, regardless of what operating system the package is developed in.
If, for example, there are two sample folders, Samples~/Required and Samples~/Examples, this field could be edited as follows:
"samples": [
{
"displayName": "Required Assets",
"description": "Assets required to make this package work",
"path": "Samples~/Required"
},
{
"displayName": "Examples",
"description": "Examples assets that demonstrates how this package works.",
"path": "Samples~/Examples"
}
]
As of this writing, this field is not documented in Unity's official documentation yet. Most likely, it means this field is still in experimental phases, and may change in the future.