Search Unity

  1. Megacity Metro Demo now available. Download now.
    Dismiss Notice
  2. Unity support for visionOS is now available. Learn more in our blog post.
    Dismiss Notice

Confusion About How to Create a Custom Package

Discussion in 'Package Manager' started by PartyBoat, Apr 16, 2019.

  1. PartyBoat

    PartyBoat

    Joined:
    Oct 21, 2012
    Posts:
    97
    So, I like to create a lot of modular assets that get reused across projects. It seems to me like the package manager would be a great way to manage adding these components without cluttering up my Assets folder. The support for Git also looks especially appealing.

    My problem is that the current documentation is fairly unclear/incorrect about how to create custom packages. Specifically the following doesn't make any sense:

    It's not possible to create a subfolder or even create anything at all in the Packages folder from within the Unity editor. Furthermore you can't move anything into the Packages folder. That being said, I suggest that the documentation should be edited to be more clear on this point.

    Does anybody have any idea how to create their own custom packages in 2019.1.02f? Bonus points if you know how to get things set up with git.
     
    Hypertectonic likes this.
  2. use_unity

    use_unity

    Unity Technologies

    Joined:
    Dec 26, 2017
    Posts:
    2
    Hi, PartyBoat. I wrote the documentation for Custom Packages, and I appreciate your feedback!

    You are correct: it is not possible to create a subfolder in the Packages directory from inside Unity. Although it is better to start inside Unity, I think most development will likely happen outside of Unity. For example, if you are creating a tool, you are mostly likely working in an IDE like Visual Studio.

    I will clarify the instructions for the next documentation updates. You do have to create the folder and the package.json manifest file inside the new folder through your computer's file system, as you noted. However, once you have done that and the Package Manager reads it, that folder is writable and you can create scripts, Materials, Playables, Textures, and tons of other Assets directly through the Inspector window.

    Please keep the feedback coming!
     
  3. PartyBoat

    PartyBoat

    Joined:
    Oct 21, 2012
    Posts:
    97
    Ah I see, that makes a lot of sense. So if I understand correctly then, when developing a package it won't be installed as a package in the Unity project you are working on it in. Instead any other project can add it through the "Add package from disk..." option by navigating to that project and selecting the package.json in the file explorer.

    It might be worth noting in the docs that certain files like the package.json file will need to be created out of the editor (the current docs lead me to think the whole process could all be done in editor), although I suppose I should have known that considering txt files work the same way. :p

    Thanks for the help!
     
    use_unity likes this.
  4. samuelb_unity

    samuelb_unity

    Unity Technologies

    Joined:
    Nov 13, 2017
    Posts:
    151
    Just to clarify, there are 2 ways to create your own custom package:
    1. As an embedded package
    2. As a local package
    The difference is described on this page of the docs.

    So when you create a subfolder under Packages - that's called an "embedded" package. When you "Add package from disk..." that's called a "local" package. Either way, the package is installed in your project. The main difference is that a local package can be anywhere on disk whereas an embedded package is inside a specific project.
     
    Last edited: Apr 17, 2019
    wlwl2 likes this.
  5. Karlbovsky

    Karlbovsky

    Joined:
    Jul 11, 2012
    Posts:
    231
    Hi, I'll add my question here without opening a new thread since it's just about me being confused on how to proceed with the development of a package.
    I mean, given a project where I'm developing the package A, I will have all my scripts and assets inside the Project/Assets folder in order to add them to my GIT repository. If I create the package folder, put all the files needed in it, then i can not keep track of them in my "development" repo anymore, the only thing i can see in my remote repository, under the Package folder, is the manifest.json file. I know the question is not clear, but as I said, I'm a bit confused atm :p.
     
  6. samuelb_unity

    samuelb_unity

    Unity Technologies

    Joined:
    Nov 13, 2017
    Posts:
    151
    Hi @Karlbovsky,

    There are many possible workflows, it sounds like you just need to find one that fits your needs. If you want to develop a package in isolation, create a new project, create a package directory under Packages, and initialize a git repository there i.e. the root of the repository is your package folder.

    If you want to develop your package in the context of an existing project which itself is already a git repo, I think your best bet is to use a local package. Create a folder anywhere on your file system, initialize a git repository there, and refer to the package from a Unity project using the "Add package from disk..." button in the Package Manager window. This way your project and package repositories are completely separate.

    A more advanced workflow could be with git submodules. This basically lets you have nested git repos i.e. a repo at the root of your project, and a sub repo at the root of your package (under <my-project>/Packages).

    Let me know if you have any more questions!

    Regards,
    Sam
     
    Last edited: Apr 17, 2019
    NotaNaN, leni8ec and Karlbovsky like this.
  7. Karlbovsky

    Karlbovsky

    Joined:
    Jul 11, 2012
    Posts:
    231
    Hey, thanks! Really helpful advices.
    So, in the case of the second scenario, I can just create a folder ( not a Unity project) which contains the correct structure of a package with its relative files/assets/assemblyDef, refer to the new package from a Unity project by using the "Add package from disk" option and I'm good to go? Anyway, really in love with the Package Manager system already, is gonna be soooo useful!!

    Regards,
    Stefano.
     
  8. samuelb_unity

    samuelb_unity

    Unity Technologies

    Joined:
    Nov 13, 2017
    Posts:
    151
    Yep, that's right. And it's important to note: in this case the package folder doesn't get moved or copied when you add it to a project. We use symbolic links to reference it from the Unity project but it actually lives elsewhere. If you look in your project manifest after adding the package, you'll see how we refer to its location:

    Code (CSharp):
    1. "my-local-package": "file:/path/to/my-local-package"
     
  9. davenirline

    davenirline

    Joined:
    Jul 7, 2010
    Posts:
    969
    Hello. We maintain our common code as a Unity project itself. It has the Assets, ProjectSettings, Package folders. I'm confused with the package layout. I assume we do that in Assets folder but the root of the repository has Assets, ProjectSettings, Package folders. Would it still work if we checkout the repository?

    What about cloud build? You mentioned there are many possible workflows but which workflow would work with cloud build?
     
  10. samuelb_unity

    samuelb_unity

    Unity Technologies

    Joined:
    Nov 13, 2017
    Posts:
    151
    Hi @davenirline, no the package layout refers to the root of the package directory. If the package lives inside a project, the structure would be:

    Project
    - Assets
    - ProjectSettings
    - Packages
    - MyPackage
    - package.json
    - README.md
    - etc.


    This should work fine with Cloud Build because the package directory is just like any other directory inside your project. Where it gets a bit more complicated is if the project is under source control and you want the package to be in its own source controlled repository. However, you might not need that. Let me know if you'd like more advice!
     
    davenirline likes this.
  11. localprojects

    localprojects

    Joined:
    Apr 26, 2019
    Posts:
    8
    Hi,
    I can see the files in my custom package and seems to be imported correctly, but I can seem to access the classes?

    Do you know what might be happening?

    Im using this custom package to get started:
    "com.namespace.unitypackageexample": "https://github.com/neogeek/unity-package-example.git#upm"
     
  12. cassandraL

    cassandraL

    Unity Technologies

    Joined:
    Dec 7, 2017
    Posts:
    111
    Hello @localprojects
    It probably is a matter of correctly configuring the asmdef.

    I would recommend reading how to create your custom package section of the documentation instead of basing yourself on the unitypackageexample you sent. The documentation is here: https://docs.unity3d.com/Manual/CustomPackages.html

    A package structure usually looks like this:
    <root>
    ├── package.json
    ├── Editor
    │ ├── Unity.[YourPackageName].Editor.asmdef
    │ └── EditorScripts.cs
    ├── Runtime
    │ ├── Unity.[YourPackageName].asmdef
    │ └── RuntimeScripts.cs
    ├── Tests
    │ ├── Editor
    │ │ ├── Unity.[YourPackageName].Editor.Tests.asmdef
    │ │ └── EditorExampleTest.cs
    │ └── Runtime
    │ ├── Unity.[YourPackageName].Tests.asmdef
    │ └── RuntimeExampleTest.cs

    Where the Editor folder contains code that would run only in the editor. Useful if you are building tools to extend the editor. The Runtime folder contains code that should run in the game/project you are creating. It is also referred to Play Mode code because it is code that will run when you click the Play button.
     
  13. Tron-Legacy

    Tron-Legacy

    Joined:
    Feb 28, 2017
    Posts:
    3
    @cassandraL The custom package documentation doesn't mention anything about having assets like materials, meshes, scenes, etc. It only specifically mentions editor and runtime scripts. This is causing some confusion (for me at least) on the purpose of packages. I would like to be able to install a package from a GIT repo with some scripts and scenes that represent a portion of reusable game components. The question is where do I put those assets in the package? do they live in the root package folder? do they live in a separate Assets folder? What asset types are supported in a package?
     
  14. cassandraL

    cassandraL

    Unity Technologies

    Joined:
    Dec 7, 2017
    Posts:
    111
  15. g__b

    g__b

    Joined:
    Sep 17, 2014
    Posts:
    39
    Hello,
    I'm building a wrapper for Unity for an opensource multiplatform library, that I'd like to distribute as a package (for free).
    I have native code in the form of .dll (Windows), .framework (macOS), .so (Android) and .a (ios).
    I have successfully created the package but I didn't find any docs on how to include native compiled code inside a custom package.
    Is enough to place the plugins inside the Runtime folder? I am on macOS editor, and also tried building for macOS and Android, but I always get a DllNotFoundException.
    What's missing?
     
  16. Meatloaf4

    Meatloaf4

    Joined:
    Jul 30, 2013
    Posts:
    183
    I would also love to know how this is accomplished :)
     
  17. g__b

    g__b

    Joined:
    Sep 17, 2014
    Posts:
    39
  18. PixelLifetime

    PixelLifetime

    Joined:
    Mar 30, 2017
    Posts:
    90
    Is there a reason unity doesn't allow us to change files and to have support of the IDE in the custom packages, and removes `.git` folder? Without these limitations or with ability to override this it would greatly simplify our workflow.

    Regards,
    Pixel
     
  19. cyrilBoucherApe

    cyrilBoucherApe

    Joined:
    Mar 27, 2020
    Posts:
    1
    I was also very confused as to why it is mentionned that we can edit a custom package once it is imported while you cannot really do it by usual means, meaning loading all the files contained in the package in the current project's solution. You therefore have no reference to outside classes definitions and all your left with is basically using Visual Studio (in my case) as a standard text editor.

    What I found to be the best way for me is to have a Unity Project that contains my package (with the required layout) directly under its Assets folder. If your project is under git, then you can just initialize the repository at the root of the package under Assets. That way you can both use your package with "Add package from disk..." and "Add package from a git URL...".

    As mentioned by @samuelb_unity you could also use git submodules if you need both the Unity project and the package under two different git repositories.

    Please note that I am doing this with a very simple package containing only scripts. I haven't tried with a more complicated one but I would assume that as long as it's under assets, it will behave juste the same!

    Hope that helps!
     
    vieraacademy and PixelLifetime like this.
  20. PixelLifetime

    PixelLifetime

    Joined:
    Mar 30, 2017
    Posts:
    90
    The thing about submodules is that they do not have dependencies by default. I am thinking of writing my own console application to add gitmodules and clone dependencies of each submodule unless I use something like `npm`, but then the whole like idea of using package manager for custom packages is irrelevant, I can just keep using submodules and clone my packages whenever I need with full power of `git`.

    Using the packages as end-user that doesn't develop them is obviously a very neat thing. But when working with packages development, I usually use my packages in development of my projects and while working on it I like to modify packages and fix them along the way, so using packages via package manager becomes inconvenient, I have to store them locally and I can't open scripts from the Editor, because it won't open the script that I want to modify and then push to the remote, it will open a script that is in `Packages` directory (I may be totally wrong, and that Editor might not behave in this way, I haven't tested it, but it seems like locally it would do that. If not then it's counter intuitive and not at all developer friendly, I haven't seen this mentioned in the docs as well).
     
    vieraacademy likes this.
  21. DanielGamaga

    DanielGamaga

    Joined:
    Mar 3, 2017
    Posts:
    4
    Hi!
    I think i have a similar problem to @localprojects. I have a Unity project for my package and another one to test it, and i'm using "add package from disk" to link them.
    The thing is that inside the package project i see everything fine, but inside the test project the code/asmdef files show up like this

    upload_2020-7-27_10-7-1.png

    And the classes inside my package are not visible by the test project.
    What could i be missing? The files hierarchy is just as the documentation, the package.json is showing fine in the test project and the asmdef and code works fine in the package project

    Thanks!
     
  22. Atogus

    Atogus

    Joined:
    Mar 5, 2015
    Posts:
    2
  23. agudmund

    agudmund

    Joined:
    May 6, 2013
    Posts:
    13
    I'm on the boat with PartyBoat here, as they say. "I have a lot of reusable assets that I use across various projects and the packaging system sounds so perfect for maintaining which version of what I have in my current scene", and I have all kinds of confusions wrapped around while trying to set up some preliminary test packages.

    To note, my actual workflow, of just saving out assets as .unitypackage files works great, just looking to add some versioning to my assets and hoping this is a solid route to go.

    My case example, of what I'm having issues with is the samples folder, I dont have any samples only assets.

    Replicable steps where the package manager workflow breaks and becomes more hassle than just the old drag and drop is described in these lovely fun steps here below, and any and all thoughts or suggestions greatly appreciated of course.

    .unitypackage workflow
    1. I have 1x script titled MyLovelyBag.cs
    2. Save it to a package file on disk.
    3. time passes and I forget which versions of what is in my scene
    4. I drag and drop the .unitypackage file into my project and it tells me if the file on disk is different from the current.
    5. I rejoice and go play with my cat and whatever people who have lots of free time do.

    package manager workflow
    1. I have 1x script titled MyLovelyBag.cs
    2. Save it to a package manifest where I get lovely versioning in the package manager and such
    3. except it demands i save it into a samples folder rather than my default file structure hierarchy
    4. when i import this package, i now have 2x MyLovelyBag.cs files in my project
    5. now i need to start chasing errors and which file is what in my samples thing and my actual hierarchy
    6. my cat gets awfully upset over no cuddles because i spend all time manually tracking files between samples folder and actual hierarchy
    7. then i do this all over again if I make the smallest changes to the package.

    Surely there is something Im missing here, all I want to do it "Update all my files to latest version, please overwrite them all since I know whats in there", should be less than a 2 second process.

    Your thoughts?
     
  24. viku_99

    viku_99

    Joined:
    Dec 14, 2016
    Posts:
    11