Search Unity

Samples in Packages - Manual Setup

Discussion in 'Package Manager' started by ethan_jl_unity, Feb 1, 2019.

  1. ethan_jl_unity

    ethan_jl_unity

    Unity Technologies

    Joined:
    Sep 27, 2018
    Posts:
    43
    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.
     
    Last edited: Mar 4, 2019
    Maras, Rallix, Xarbrough and 10 others like this.
  2. Novack

    Novack

    Joined:
    Oct 28, 2009
    Posts:
    647
    Thank you Ethan. As soon as I can move to Unity 2019.1 will jump into this.
     
  3. col000r

    col000r

    Joined:
    Mar 27, 2008
    Posts:
    654
    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):
    1.   "samples": [
     
    Novack and bddckr like this.
  4. ethan_jl_unity

    ethan_jl_unity

    Unity Technologies

    Joined:
    Sep 27, 2018
    Posts:
    43
    Oops sorry about that. :(

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

    JakHussain

    Joined:
    Oct 20, 2016
    Posts:
    105
    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?
     
  6. okcompute_unity

    okcompute_unity

    Unity Technologies

    Joined:
    Jan 16, 2017
    Posts:
    586
    Hi @pablothedolphin

    (sorry for the delay)

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

    Regards,

    Pascal
     
  7. JakHussain

    JakHussain

    Joined:
    Oct 20, 2016
    Posts:
    105
    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.
     
  8. okcompute_unity

    okcompute_unity

    Unity Technologies

    Joined:
    Jan 16, 2017
    Posts:
    586
    @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!
     
  9. okcompute_unity

    okcompute_unity

    Unity Technologies

    Joined:
    Jan 16, 2017
    Posts:
    586
    @pablothedolphin I just reach out the Prefab team. They told me there is no issue with using Prefab inside a package.
     
  10. onMouseUp

    onMouseUp

    Joined:
    Jun 24, 2015
    Posts:
    3
    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?
     
    De-Panther likes this.
  11. okcompute_unity

    okcompute_unity

    Unity Technologies

    Joined:
    Jan 16, 2017
    Posts:
    586
    @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
     
  12. bdominguezvw

    bdominguezvw

    Joined:
    Dec 4, 2013
    Posts:
    92
  13. okcompute_unity

    okcompute_unity

    Unity Technologies

    Joined:
    Jan 16, 2017
    Posts:
    586
    @bdominguezvw Ok! I was not aware of this. I'll reach out the WebGL team.

    Thanks,

    Pascal
     
  14. okcompute_unity

    okcompute_unity

    Unity Technologies

    Joined:
    Jan 16, 2017
    Posts:
    586
    De-Panther likes this.
  15. De-Panther

    De-Panther

    Joined:
    Dec 27, 2009
    Posts:
    287
  16. De-Panther

    De-Panther

    Joined:
    Dec 27, 2009
    Posts:
    287
    Reported - 1157275
    Thanks
     
    okcompute_unity likes this.
  17. okcompute_unity

    okcompute_unity

    Unity Technologies

    Joined:
    Jan 16, 2017
    Posts:
    586
  18. onMouseUp

    onMouseUp

    Joined:
    Jun 24, 2015
    Posts:
    3
    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.
     
    De-Panther likes this.
  19. onMouseUp

    onMouseUp

    Joined:
    Jun 24, 2015
    Posts:
    3
    Oh, didn't see that @De-Panther already opened a thread regarding that topic! :)
     
  20. Erothez

    Erothez

    Joined:
    May 27, 2015
    Posts:
    15
    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?
     
  21. okcompute_unity

    okcompute_unity

    Unity Technologies

    Joined:
    Jan 16, 2017
    Posts:
    586
    @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
     
    De-Panther likes this.
  22. Erothez

    Erothez

    Joined:
    May 27, 2015
    Posts:
    15
    Sweet, didn't think about client.add haha.

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

    bdovaz

    Joined:
    Dec 10, 2011
    Posts:
    688
    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.
     
  24. Erothez

    Erothez

    Joined:
    May 27, 2015
    Posts:
    15
    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?

     

    Attached Files:

  25. okcompute_unity

    okcompute_unity

    Unity Technologies

    Joined:
    Jan 16, 2017
    Posts:
    586
    Hi @Erothez

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

    Thanks for reporting!

    Pascal
     
  26. paulrts

    paulrts

    Joined:
    Jan 4, 2018
    Posts:
    12
    @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) prefab-package-manager.gif ?
     
  27. okcompute_unity

    okcompute_unity

    Unity Technologies

    Joined:
    Jan 16, 2017
    Posts:
    586
    @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
     
  28. paulrts

    paulrts

    Joined:
    Jan 4, 2018
    Posts:
    12
    @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
     
  29. okcompute_unity

    okcompute_unity

    Unity Technologies

    Joined:
    Jan 16, 2017
    Posts:
    586
    @paulrts Ok. Thanks for checking. Can you ask why this doesn't work in the Prefabs forum, please? Thank you!
     
  30. runevision

    runevision

    Unity Technologies

    Joined:
    Nov 28, 2007
    Posts:
    1,636
    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?
     
  31. paulrts

    paulrts

    Joined:
    Jan 4, 2018
    Posts:
    12
    @okcompute_unity I cannot drag materials and textures either, does this mean it is not a Prefab specific issue?
     
  32. okcompute_unity

    okcompute_unity

    Unity Technologies

    Joined:
    Jan 16, 2017
    Posts:
    586
    Looks like it! I'm asking around internally to figure what is going on.
     
  33. okcompute_unity

    okcompute_unity

    Unity Technologies

    Joined:
    Jan 16, 2017
    Posts:
    586
    @paulrts , can you tell me which version of Unity you are using?
     
  34. paulrts

    paulrts

    Joined:
    Jan 4, 2018
    Posts:
    12
  35. okcompute_unity

    okcompute_unity

    Unity Technologies

    Joined:
    Jan 16, 2017
    Posts:
    586
    @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
     
  36. paulrts

    paulrts

    Joined:
    Jan 4, 2018
    Posts:
    12
    Ok, issue 1169200 created. Two-col layout works fine for now. Thanks
     
    okcompute_unity likes this.
  37. rfadeev

    rfadeev

    Joined:
    Oct 1, 2013
    Posts:
    11
    When developing custom package, folder named `Samples~` would be ignored by Unity importer as hidden asset making it difficulty to actually develop sample code/assets (since development is done in some Unity project anyway). The only workaround for now is renaming the folder beck and forth to comply with naming. What is the typical workflow expected for samples development?

    Removing `~` from samples folder name and having assembly definition file in the samples folder allows to import sample via package manager, but after importing there is GUID conflict for sample files as same GUID is present in package and imported sample (I assume that's why samples folder name should be hidden asset).
     
    JakHussain likes this.
  38. cassandraL

    cassandraL

    Unity Technologies

    Joined:
    Dec 7, 2017
    Posts:
    91
    Hello @rfadeev
    Internally, we actually rename the folder using our CI. Therefore, we indeed work with the folder named Samples and rename it through scripts before pushing the new package version. This is indeed not yet as user-friendly as we want it to be. But we are working on it!
     
    JakHussain likes this.
  39. rfadeev

    rfadeev

    Joined:
    Oct 1, 2013
    Posts:
    11
    Hello @cassandraL,

    Many thanks for the answer and great to know you are working on that!

    By "pushing the new package version" do you mean pushing it to be available via package manager or pushing it to git branch? Asking as I'm trying to understand best practices for package development setup of git repository and would be good to know how Unity team does it. I've seen some people do one branch for Unity project and another one for package while others do only one branch with package itself. For second option `Samples~` problem becomes a thing and this is where my initial question came from.
     
  40. cassandraL

    cassandraL

    Unity Technologies

    Joined:
    Dec 7, 2017
    Posts:
    91
    Hello @rfadeev,
    Internally, we have a repo containing the project.
    When we push a new change with git, our CI will then transform the project into a package (we call it packing).
    We then run some tests on that packed package.
    Once we feel all is good, we publish it to the registry. The publish action then uses the packed package and pushes it to the server, making it available to our users.

    Hope this clears things up!
     
    rfadeev likes this.
  41. rfadeev

    rfadeev

    Joined:
    Oct 1, 2013
    Posts:
    11
    Hello @cassandraL,
    Great, thank you very much for the explanation!