Samples in Packages - Manual Setup

ethan_jl_unity · Mar 4, 2019

In Package Manager UI 2.0 (compatible with Unity 2019.1), you can include samples in a package.

A sample could be a piece of example code, or some beginner assets that can be optionally brought into the user's project under the `Assets` folder.

In the future, the editor will expose packaging functionality to properly expose samples, but in the meantime, here's is an example on how samples can be manually configured to be recognized in the Package Manager UI.

First, make sure to place your samples under the `Samples~` folder.
<Root>

 ├── package.json

 ├── Samples~

 │   ├── Sample Folder 1

 │   │   └── …

 │   └── Sample Folder 2

 │       └── …

 └── ...
Then you need to specify them in the `package.json` file. Note that each sample needs to point to a directory.
{

 "samples": [

   {

     "displayName": "Sample Name 1",

     "description": "Description for sample 1",

     "path": "Samples~/Sample Folder 1"

   },

   {

     "displayName": "Sample Name 2",

     "description": "Description for sample 2",

     "path": "Samples~/Sample Folder 2"

   }

 ]

}
Then you'll be able to see the import buttons in Package Manager UI as shown below.

When the user chooses to import a sample, samples will be copied to the project’s `Assets/Samples/Package Name/Version/Sample Name` directory, thus allowing it to be modified.

Novack · Feb 1, 2019

Thank you Ethan. As soon as I can move to Unity 2019.1 will jump into this.

col000r · Feb 20, 2019

It took me a long time to figure out why this wasn't working for me. As it turns out, you need to spell samples with a lower-case s, so not upper-case like in your example

Code (CSharp):

"samples": [

ethan_jl_unity · Mar 4, 2019

Oops sorry about that.

@col000r Thanks for pointing it out! I just updated the post

pablothedolphin · Mar 17, 2019

is this the only way assets like prefabs can be brought into projects from a package? or just the recommended way? what other options are there?

okcompute_unity · Mar 25, 2019

Hi @pablothedolphin

(sorry for the delay)

I don't understand your question. Can you elaborate more on your use cases?

Regards,

Pascal

pablothedolphin · Mar 25, 2019

Sorry I should have elaborated more. I was hoping to design packages that would extend the create menu for the scene/hierarchy as cleanly as possible. For example, Unity offers menu options for creating UI objects that automatically add a canvas if there isn't one already, and the same for an event system. But the prefabs of those exact objects aren't in the assets folder because they shouldn't be. They're almost like "read only" prefabs that are just there to provide tools for developers.

With my own package, I'd like to refer to prefabed objects that would be instantiated via editor scripts without needing to import those originals into the assets folder. Basically to have the same set up and Unity's own basic game objects.

Is this something that can be done or will be considered for the package manager? I know I can just create plain game objects and add components to them but sometimes we need sprite references and other stuff that we don't necessarily want in the assets folder but in the packages folder.

okcompute_unity · Mar 25, 2019

@pablothedolphin No problems. I will transfer your question to the prefab team. Sadly, I don't know enough about the features/limitations of Prefab system to properly respond to your question.

Let me reach out to them!

okcompute_unity · Mar 25, 2019

@pablothedolphin I just reach out the Prefab team. They told me there is no issue with using Prefab inside a package.

onMouseUp · May 23, 2019

Is there a way to flatten the sample folder path? Imagine I have a package with a template structure inside a 'WebGLTemplates' folder. My custom Template only appears in Player Settings if my WebGLTemplates folder is located in "Assets/WebGLTemplates/MyTemplate", but the Package Manager imports assets as follows:
"Assets/Samples/Package Name/Version/WebGLTemplates/.....
Is there a solution to solve that issue?

okcompute_unity · May 23, 2019

@onMouseUp You should avoid expecting an asset to be located at a specific folder location. This is not a good approach. Instead, base your logic on asset GUID presence or through scripting.

Regards,

Pascal

bdominguezvw · May 23, 2019

okcompute_unity said: ↑

@onMouseUp You should avoid expecting an asset to be located at a specific folder location. This is not a good approach. Instead, base your logic on asset GUID presence or through scripting.

Regards,

Pascal
Click to expand...

That's a Unity requirement.

https://docs.unity3d.com/Manual/webgl-templates.html

See "Structure of a WebGL Template" section.

okcompute_unity · May 23, 2019

@bdominguezvw Ok! I was not aware of this. I'll reach out the WebGL team.

Thanks,

Pascal

okcompute_unity · May 23, 2019

@onMouseUp Would you mind filling up a bug for this issue? (https://unity3d.com/unity/qa/bug-reporting). This is something for Unity to figure out ways to let you bundle a WebGlTemplate in a package.

Thanks,

Pascal

De-Panther · May 24, 2019

As commented in this thread
https://forum.unity.com/threads/webgltemplates-folder-in-packages.678823/
WebGLTemplates location is hard-coded.

I'll open a bug report

De-Panther · May 24, 2019

Reported - 1157275
Thanks

okcompute_unity · May 24, 2019

@De-Panther , Thank you very much!

onMouseUp · May 24, 2019

Thanks for response! I created a bug report --> https://fogbugz.unity3d.com/default.asp?1157287_a5u6jn4stvnt4b9h
But nevertheless I still struggling with the question: How can I put assets into special folders like Plugins or Editor? With *.unitypackage file export/import behaves exactly how it should. Would be great if you could export Assets the old fashion way but with a "new" package as a result. Or maybe extracting assets into an existing package.

onMouseUp · May 24, 2019

Oh, didn't see that @De-Panther already opened a thread regarding that topic!

Erothez · May 29, 2019

Any chance of having extra dependencies related to Samples?

For example, I don't want my actual package to need Unity.ugui as a dependency but the sample will need it?

okcompute_unity · May 29, 2019

@Erothez , you can only achieve this through scripting for the moment via the Package Manager API: https://docs.unity3d.com/ScriptReference/PackageManager.Client.Add.html

But, I think it would be nicer to have a full UX supporting this use case. What I mean by that, is letting you list the required packages in a sample manifest and Unity should add the packages automatically. Will look into bringing this feature to life

Regards,

Pascal

Erothez · May 29, 2019

Sweet, didn't think about client.add haha.

That'll be cool to have it supported out the box though.

N3uRo · Jun 2, 2019

Erothez said: ↑

Any chance of having extra dependencies related to Samples?

For example, I don't want my actual package to need Unity.ugui as a dependency but the sample will need it?
Click to expand...

I have this same requirement.

Also I think that it's annoying that when we click the import button it doesn't show the preview window to see what are we going to import and it starts automatically. I expected the same behaviour as when you are importing a unitypackage.

Erothez · Jun 23, 2019

Worth noting in 2019.3 the UI bugs out, with it showing both Samples and Dependencies in the same place. Not sure if this just bug with Unity Dependencies in 2019.3, or bug with way your handling samples?

okcompute_unity · Jun 23, 2019

Hi @Erothez

This is a known bug in the UI library. Not a bug specific to the Package Manager UI.

Thanks for reporting!

Pascal

paulrts · Jun 28, 2019

@okcompute_unity

Is this 'samples' approach required for prefabs too? Is it on the roadmap to be able to drag prefabs from a custom package into my scene (see gif) ?

okcompute_unity · Jun 28, 2019

@paulrts, can you drag the prefab from the Packages folder to the Assets folder and then into your scene? Would you mind asking your question (dragging from packages in the scene) in the Prefabs forum, please?

Regards,

Pascal

paulrts · Jul 9, 2019

@okcompute_unity

I cannot drag into the Assets folder. The same issue occurs for fbx assets; I cannot drag from Packages folder into scene or Assets

okcompute_unity · Jul 9, 2019

@paulrts Ok. Thanks for checking. Can you ask why this doesn't work in the Prefabs forum, please? Thank you!

runevision · Jul 9, 2019

Is not being able to drag from Packages to Assets specific to Prefabs and FBX files, or does it apply to all assets that are not scripts, like Materials, Textures, etc?

paulrts · Jul 9, 2019

@okcompute_unity I cannot drag materials and textures either, does this mean it is not a Prefab specific issue?

okcompute_unity · Jul 9, 2019

Looks like it! I'm asking around internally to figure what is going on.

okcompute_unity · Jul 11, 2019

@paulrts , can you tell me which version of Unity you are using?

paulrts · Jul 11, 2019

@okcompute_unity 2019.1.8f1

okcompute_unity · Jul 12, 2019

@paulrts, the dev was able to reproduce the bug but only in the *One-Colum* layout. He says he cannot reproduces in the *Two-Columns* layout. Can you confirm?

Would you mind filling a bug report for this issue? (https://unity3d.com/unity/qa/bug-reporting)

And in the mean-time, can you use *Two-Columns* layout as a workaround?

Thank you for reporting this issue!

Pascal

paulrts · Jul 12, 2019

Ok, issue 1169200 created. Two-col layout works fine for now. Thanks

Search Unity

Unity ID

Samples in Packages - Manual Setup

Unity Technologies

Unity Technologies

Unity Technologies

Unity Technologies

Unity Technologies

Unity Technologies

Unity Technologies

Unity Technologies

Unity Technologies

Unity Technologies

Attached Files:

Unity Technologies

Unity Technologies

Unity Technologies

Unity Technologies

Unity Technologies

Unity Technologies

Unity Technologies

Nearly there...

Oops...