Search Unity

  1. Good news ✨ We have more Unite Now videos available for you to watch on-demand! Come check them out and ask our experts any questions!
    Dismiss Notice

Samples in Packages - Manual Setup

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

Page 1 of 2

  1. ethan_jl_unity

    ethan_jl_unity

    Unity Technologies

    Joined:
    Sep 27, 2018
    Posts:
    99
    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
    ethan_jl_unity, Feb 1, 2019
    #1
    codestage, Aaron2348, Sarkahn and 15 others like this.

  2. Novack

    Novack

    Joined:
    Oct 28, 2009
    Posts:
    725
    Thank you Ethan. As soon as I can move to Unity 2019.1 will jump into this.
     
    Novack, Feb 1, 2019
    #2

  3. col000r

    col000r

    Joined:
    Mar 27, 2008
    Posts:
    671
    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": [
     
    col000r, Feb 20, 2019
    #3
    Novack and bddckr like this.

  4. ethan_jl_unity

    ethan_jl_unity

    Unity Technologies

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

    @col000r Thanks for pointing it out! I just updated the post
     
    ethan_jl_unity, Mar 4, 2019
    #4

  5. JakHussain

    JakHussain

    Joined:
    Oct 20, 2016
    Posts:
    311
    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?
     
    JakHussain, Mar 17, 2019
    #5

  6. okcompute_unity

    okcompute_unity

    Unity Technologies

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

    (sorry for the delay)

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

    Regards,

    Pascal
     
    okcompute_unity, Mar 25, 2019
    #6

  7. JakHussain

    JakHussain

    Joined:
    Oct 20, 2016
    Posts:
    311
    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.
     
    JakHussain, Mar 25, 2019
    #7

  8. okcompute_unity

    okcompute_unity

    Unity Technologies

    Joined:
    Jan 16, 2017
    Posts:
    726
    @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
    #8

  9. okcompute_unity

    okcompute_unity

    Unity Technologies

    Joined:
    Jan 16, 2017
    Posts:
    726
    @pablothedolphin I just reach out the Prefab team. They told me there is no issue with using Prefab inside a package.
     
    okcompute_unity, Mar 25, 2019
    #9

  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?
     
    onMouseUp, May 23, 2019
    #10
    De-Panther likes this.

  11. okcompute_unity

    okcompute_unity

    Unity Technologies

    Joined:
    Jan 16, 2017
    Posts:
    726
    @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
     
    okcompute_unity, May 23, 2019
    #11

  12. bdominguezvw

    bdominguezvw

    Joined:
    Dec 4, 2013
    Posts:
    96
    bdominguezvw, May 23, 2019
    #12
    johanhelsing_attensi likes this.

  13. okcompute_unity

    okcompute_unity

    Unity Technologies

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

    Thanks,

    Pascal
     
    okcompute_unity, May 23, 2019
    #13
    johanhelsing_attensi likes this.

  14. okcompute_unity

    okcompute_unity

    Unity Technologies

    Joined:
    Jan 16, 2017
    Posts:
    726
    okcompute_unity, May 23, 2019
    #14
    De-Panther likes this.

  15. De-Panther

    De-Panther

    Joined:
    Dec 27, 2009
    Posts:
    365
    De-Panther, May 24, 2019
    #15

  16. De-Panther

    De-Panther

    Joined:
    Dec 27, 2009
    Posts:
    365
    Reported - 1157275
    Thanks
     
    De-Panther, May 24, 2019
    #16
    okcompute_unity likes this.

  17. okcompute_unity

    okcompute_unity

    Unity Technologies

    Joined:
    Jan 16, 2017
    Posts:
    726
    okcompute_unity, May 24, 2019
    #17

  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.
     
    onMouseUp, May 24, 2019
    #18
    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! :)
     
    onMouseUp, May 24, 2019
    #19

  20. Erothez

    Erothez

    Joined:
    May 27, 2015
    Posts:
    20
    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?
     
    Erothez, May 29, 2019
    #20

  21. okcompute_unity

    okcompute_unity

    Unity Technologies

    Joined:
    Jan 16, 2017
    Posts:
    726
    @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
     
    okcompute_unity, May 29, 2019
    #21
    brand_at_tobii, Randhall and De-Panther like this.

  22. Erothez

    Erothez

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

    That'll be cool to have it supported out the box though.
     
    Erothez, May 29, 2019
    #22

  23. bdovaz

    bdovaz

    Joined:
    Dec 10, 2011
    Posts:
    793
    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.
     
    bdovaz, Jun 2, 2019
    #23

  24. Erothez

    Erothez

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

    Erothez, Jun 23, 2019
    #24

  25. okcompute_unity

    okcompute_unity

    Unity Technologies

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

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

    Thanks for reporting!

    Pascal
     
    okcompute_unity, Jun 23, 2019
    #25

  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 ?
     
    paulrts, Jun 28, 2019
    #26

  27. okcompute_unity

    okcompute_unity

    Unity Technologies

    Joined:
    Jan 16, 2017
    Posts:
    726
    @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
     
    okcompute_unity, Jun 28, 2019
    #27

  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
     
    paulrts, Jul 9, 2019
    #28

  29. okcompute_unity

    okcompute_unity

    Unity Technologies

    Joined:
    Jan 16, 2017
    Posts:
    726
    @paulrts Ok. Thanks for checking. Can you ask why this doesn't work in the Prefabs forum, please? Thank you!
     
    okcompute_unity, Jul 9, 2019
    #29

  30. runevision

    runevision

    Unity Technologies

    Joined:
    Nov 28, 2007
    Posts:
    1,825
    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?
     
    runevision, Jul 9, 2019
    #30

  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?
     
    paulrts, Jul 9, 2019
    #31

  32. okcompute_unity

    okcompute_unity

    Unity Technologies

    Joined:
    Jan 16, 2017
    Posts:
    726
    Looks like it! I'm asking around internally to figure what is going on.
     
    okcompute_unity, Jul 9, 2019
    #32

  33. okcompute_unity

    okcompute_unity

    Unity Technologies

    Joined:
    Jan 16, 2017
    Posts:
    726
    @paulrts , can you tell me which version of Unity you are using?
     
    okcompute_unity, Jul 11, 2019
    #33

  34. paulrts

    paulrts

    Joined:
    Jan 4, 2018
    Posts:
    12
    paulrts, Jul 11, 2019
    #34

  35. okcompute_unity

    okcompute_unity

    Unity Technologies

    Joined:
    Jan 16, 2017
    Posts:
    726
    @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
     
    okcompute_unity, Jul 12, 2019
    #35

  36. paulrts

    paulrts

    Joined:
    Jan 4, 2018
    Posts:
    12
    Ok, issue 1169200 created. Two-col layout works fine for now. Thanks
     
    paulrts, Jul 12, 2019
    #36
    okcompute_unity likes this.

  37. rfadeev

    rfadeev

    Joined:
    Oct 1, 2013
    Posts:
    19
    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 back 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).
     
    Last edited: Jan 12, 2020
    rfadeev, Sep 21, 2019
    #37
    MegamaDev, reeseschultz, Hypertectonic and 3 others like this.

  38. cassandraL

    cassandraL

    Unity Technologies

    Joined:
    Dec 7, 2017
    Posts:
    108
    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!
     
    cassandraL, Sep 23, 2019
    #38
    nicolasgramlich, reeseschultz, Sarkahn and 2 others like this.

  39. rfadeev

    rfadeev

    Joined:
    Oct 1, 2013
    Posts:
    19
    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.
     
    rfadeev, Sep 24, 2019
    #39

  40. cassandraL

    cassandraL

    Unity Technologies

    Joined:
    Dec 7, 2017
    Posts:
    108
    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!
     
    cassandraL, Sep 24, 2019
    #40
    rfadeev likes this.

  41. rfadeev

    rfadeev

    Joined:
    Oct 1, 2013
    Posts:
    19
    Hello @cassandraL,
    Great, thank you very much for the explanation!
     
    rfadeev, Sep 24, 2019
    #41

  42. quabug

    quabug

    Joined:
    Jul 18, 2015
    Posts:
    58
    Use soft link and ignore linked directory of `Samples~` in your ignore file of VCS would be a workaround of this issue.

    Code (csharp):
    1. ln -s Samples~ Samples # and ignore Samples in .gitignore
     
    quabug, Dec 25, 2019
    #42
    Sarkahn and Favo-Yang like this.

  43. Sarkahn

    Sarkahn

    Joined:
    Jan 9, 2013
    Posts:
    278
    Just wanted to say I found this fantastic repo https://github.com/TrismegistusDevelopment/unity-package-manager-ci

    It will automatically create upm-ready package branch whenever you push to your master repo. A little complicated to set up (for me at least) but it works great. I created a pull request to solve this issue: https://github.com/TrismegistusDevelopment/unity-package-manager-ci/pull/2. With that change you can maintain a "Samples" folder in your master branch and the build system will automatically rename it to "Samples~" before it pushes to the UPM branch.
     
    Sarkahn, Jan 7, 2020
    #43

  44. Favo-Yang

    Favo-Yang

    Joined:
    Apr 4, 2011
    Posts:
    402
    Favo-Yang, Jan 14, 2020
    #44
    cecarlsen, ThatMunk, g__b and 6 others like this.

  45. PolyCrusher

    PolyCrusher

    Joined:
    Jul 3, 2012
    Posts:
    6
    PolyCrusher, Jan 15, 2020
    #45

  46. Wolfram

    Wolfram

    Joined:
    Feb 16, 2010
    Posts:
    182
    Kind of a weird special case here, but this will invariably happen while developing a package:

    - During development, we include the Code+Assets as a local package in the PackageManager / manifest.json.
    - We also remove the ~ from the "Samples~" folder: "Samples"
    - When we now drag a regular Texture "MyTexture.png" from /Assets into /Packages/MyPackage/Samples/MySample, it shows up as expected, and the Windows explorer correctly shows "MyTexture.png.meta" with the correct settings. BUT:
    - When we now change the Max Size in the import settings of that texture to say 32, and apply, the Metafile suddenly gets renamed to "mytexture.png.meta", and the name in Unity also changes to "mytexture". The texture itself is still named "MyTexture.png".
    - This also generates the Console error "Refresh case sensitivity failure. Asset: Packages/com.nmy.huba/Samples/MySample/mytexture.png ; Metafile: Packages/com.nmy.huba/Samples/MySample/mytexture.png.meta" (that message shows "mytexture.png", but Windows explorer does show it as the original "MyTexture.png"

    Windows 10
    Unity 2019.2.10f1
    Package Manager UI 2.2.0
     
    Last edited: Jan 24, 2020
    Wolfram, Jan 23, 2020
    #46

  47. Favo-Yang

    Favo-Yang

    Joined:
    Apr 4, 2011
    Posts:
    402
    @Wolfram I've been experienced with something similar on Windows OS. It sounds a bug.
     
    Favo-Yang, Jan 24, 2020
    #47

  48. kassskata

    kassskata

    Joined:
    Sep 24, 2019
    Posts:
    9
    "Samples" folder is good to start. However, can we have an option to rename that Samples folder with a custom name like "Assets/FOO/[package-name]/[version_number]/[example_directory]" ??
    Our team needs to rename it with "Documentation" because our documentation is a folder with multiple files.
     
    kassskata, Jan 29, 2020
    #48
    reeseschultz likes this.

  49. Jichaels

    Jichaels

    Joined:
    Dec 27, 2018
    Posts:
    235
    Been experimenting with custom packages, is there a way to move / specify where a sample / sub folder of the sample goes ?

    My use case is that I've a localization system that fetches languages files from StreamingAssets, is there a way for me to have a file (a basic .json language file for exemple) go there ?

    Thanks !
     
    Jichaels, Jan 30, 2020
    #49
    g__b, antoined73 and kassskata like this.

  50. kassskata

    kassskata

    Joined:
    Sep 24, 2019
    Posts:
    9
    1. I have same question.
    Meanwhile
    This case you will catch some way on scene load or On initialization load events. and move it with C# File class.
    Use some kind of editor assembly of scripts logic to workaround it for now.
    2. Can you add some callback event "OnImportSamplePreprocessor" & "OnImportSamplePostprocessor" to create our logic after and before the importings.
    Thanks
     
    kassskata, Feb 11, 2020
    #50
    quabug, fherbst, g__b and 2 others like this.
Page 1 of 2
unityunity