Samples in Packages - Manual Setup

Hey,

@ethan_jl_unity

Is this supposed to be an officially supported way of adding examples to the packages?
Why it's not documented at the official docs yet?

I'm trying to figure out if it's production ready and can be widely used at the custom packages in the scoped registries.

 

I see Unity apparently decided not to bother fixing this - it's marked WONTFIX and, I quote:

"issue affects not enough users"

I'm intrigued. Does Unity feel not enough people were using packages at the time (which is fair, because they were literally unusable in most versions of Unity, so you needed to keep using the old system anyway)? ... or that not enough people were using WebGL (which is also fair, because for most of 2019 WebGL builds were broken in many ways, and often failed even for simple projects - but most of that has been fixed now)?

Now that 2019 is LTS, and packages are supported in all official Unity versions, it seems that bugs like this ought to be fixed?

 

@ethan_jl_unity @okcompute_unity
Is there currently a recommended way to handle samples that are a completely separate Unity project? Imagine I need to make a sample that has specific Project Settings, different render pipelines, etc.... and I also want those samples to only be downloadable by people who bought my package

 

Just to give an update on this, we are aware that documentation needs to be updated and is being worked on - we'll share updates once we have something

 

Is it possible to include StreamingAssets in a sample? It's great for the Sample code to import directly into the unity project, but my samples require resources to exist in StreamingAssets -- how can I add those files to the project directory as well?

 

Getting GUID warnings even if my folder is correctly named, and all .meta files are deleted before uploading the package on the repository (tried with .meta files uploaded too). When I import the package in another project via the package manager and look at the folder structure under Packages, I found the "Samples" folder in my package folder, without the tilde.

I wonder what's the point of all of this renaming shenanigans if in the end, the sample folder is imported nevertheless.

EDIT: In the end, it was a Unity Cache issue. When you are working on your package and iterating quickly, make sure to delete the unity global cache if you want the updated version (same version number), because it will use the cached version instead of redownloading the package.

 

Hi @bszalapski,

The way I've got around this, for now, is to use an approach similar to what @samuelb_unity suggested, borrowing slightly from the approach taken in TextMeshPro.

Code (CSharp):

1. [InitializeOnLoad]
2. public static class InstallDependencies
3. {
4.     static InstallDependencies()
5.     {
6.         if (Dependencies.Instance == null)
7.         {
8. #if UNITY_EDITOR
9.         AssetDatabase.ImportPackage("Packages/com.companyname.packagename/path_to_your/dependencies.unitypackage", false);
10. #endif  
11.         }
12.     }
13. }

Where the file dependencies.unitypackage contains both my StreamingAssets folder and a scriptable object singleton (called Dependencies in this example). This means that on each domain reload, if the scriptable object singleton isn't present in the project then it will trigger an import, otherwise nothing will happen. This is very much a hack which I am not happy with, but I have not found a better solution to date.

I was hopeful that IPackageManagerExtension would solve my issues, but by the time a package that contains a self-registering class implementing this interface has been imported and scripts recompiled, the opportunity to intercept package installation via OnPackageAddedOrUpdated has already passed. Similarly, Addressables might be an option here, but I do not want to add any more package dependencies when there is no complete 3rd-party package management solution with dependency management offered by Unity yet.

@samuelb_unity is there any discussion internally as to a potential solution to this problem? I was hoping by now there would be some form of editor event fired after a package is installed to perform any additional setup, or perhaps a similar method to the samples directory for automatic dependency installation as @bszalapski suggested.

 

Will this be available in Unity 2019? It should go along with the Package Manager, that is available since 2019.1.

 

Thanks for your answer.
I'm developing a custom package and I'd like to offer samples with other dependencies than the base package (I'm thinking of VR examples).
Is it considered a good practice to auto import dependencies when the user imports a sample? since basically I need to overwrite the ProjectSettings.
Is it better to have a .unitypackage or .assets inside the imported sample, so that the user can choose whether to import them? Or should I add some popup message explaining them how to setup the editor for the samples to work?
Maybe the TextMeshPro approach is the better choice, so having a popup window that can setup what is needed with a single click of the user.
Any other suggestions?

 

Yes it's working good for me, as far as I don't need other dependencies for a specific sample.
In that case, I'd like to have a "dependencies" field inside the sample structure, something like:

Code (JavaScript):

1. {
2.  
3. "samples": [
4.  
5.    {
6.  
7.      "displayName": "Sample Name 1",
8.  
9.      "description": "Description for sample 1",
10.  
11.      "path": "Samples~/Sample Folder 1",
12.  
13.      "dependencies":
14.         [
15.             "com.unity.xr.interaction.toolkit",
16.             "com.unity.xr.management"
17.         ]
18.    }
19. ]
20.  
21. }

Is this (or will be) possible?

 

Hey there,

What is the process for doing active development on samples in a package embedded to a project? Anything in the Package/mypackage/Samples~ folder is hidden in the Project Window, and the scripts aren't being compiled.

I can import the samples into the project for editing and testing. But after I make any modifications, I have to manually copy each file back into the Samples~ folder, except for the .meta files, which all have different GUIDs of course. This doesn't seem practical for daily development.

 

I suspect this reply, and this subsequent suggestion are still relevant. A pretty annoying downside to working with samples, nonetheless.

 

Thank you for linking those posts! Looks like I missed those when scanning this thread's history.

Yeah, that should work. Still very annoying as it requires manual configuration on each client, and it's quite difficult to automate if you're not running CI.

Note that creating a shortcut won't work. On Windows, you can create a soft directory link using the following command:

mklink /D NewFolder OriginalFolder

We already use this with multiplatform development. For each platform, there's a separate project folder, but all of the Assets, ProjectSettings etc. folders are actually soft links pointing to a master project folder. The Library, Temp, obj etc. folders are separate for each platform, containing the imported assets for that platform.

 

I'll leave this here for anyone that's been asking about a way to specify the structure or layout of their samples.

Digging through Unity's UPM and lackluster docs(sometimes) I found out that UPM can actually import asset packages (*.unitypackage) this is how you can do it!

1. Select the folder(s) containing your samples in the Assets folder. Right click and export to *.unitypackage
   
2. Save the exported package in a folder under the samples folder in your package (Sample~/Example)
3. If you want the import preview to show up as normal, add this field to your json samples object

   "interactiveImport": true

   . Otherwise, it will just import the package silently.
4. Try to import it
   
   
5. Delete a file and try to reimport it again!
   

NOTE

• If the sample includes other files they won't be imported! As the *.unitypackage import take priority.
• Only 1 *.unitypackage can be imported per sample.

Hope that helps!

 

Hi guys,
There is a "description" field for each sample. But where is this text displayed? It seems not visible from the the Package Manager.

 

Alright, now it's documented, yay!

As docs say:

 

Hi,

Recently been delving into making my own packages and was really happy to see the samples folder option. However from my initial research there seems to be a huge blind spot regarding sample dependencies that are not covered with the initial package dependencies.

This could of course all be easily resolved on Unity's end if they supported dependencies in the sample.json. Sadly this does not appear to be a priority and worse I fear it may even get hard-locked behind a specific version of Unity!

So looking at the package API it appears we could do this through code, but delving deeper I feel this is fraught with various levels of problems, some of which i'll list below.

• Every developer will write their own version.
• Requires InitializeOnLoad on the script - I have a sneaking suspicion that the ease of which of this attribute can be applied has caused an explosion of editor ran scripts on every load of a project and each time the project is played, both from my own project scripts and third party assets/packages. Its frustrating as usually the code needs only run once after loading/reloading the project and not every time. Maybe there is a way to do that natively?
• Each package will do their own dependency check, each with their own InitializeOnLoad script. Seems massively inefficient and prone to causing conflicts ( see Client.Add below ) while a developer could write their own manager for this, i'm unsure if its practical from the standpoint of collecting all the dependencies from each of their loaded packages and only running the Client.Add or other methods once.
• Client.Add
  • How do i know its safe to start my first say Client.Add or Client.List? The documentation is unclear in that it says you should wait for one to finish before doing another as it can lead to weird results, but I have no idea what other third party code is doing!
  • Does this check if the dependency version is already installed and thus ignore the request or does it always overwrite any existing packages?
  • Does it cache a list of installed packages so that repeated requests ( from different packages to add dependencies ) can be quickly ignored?

Considering all these factors it seemed that what we need is a native centralized method added to the Client.API to collate required dependencies and load them. Unfortunately following that through ends up essentially being the same thing as adding dependencies to samples.json! Also while there is a good chance that code would not be editor version locked, its at least going to package manager locked.

So in conclusion there is no good answer. Not having dependencies supported in samples from the beginning is going to end up user packages needing different code paths. Then there is the problem of how to code up a sample dependency manager that will work error free and ideally have it only run once.

Love to hear how others may be addressing this as at the moment i'm sorely tempted to just ignore it and add some text to instruct users to install any missing packages - for which we are mostly just talking about TextMeshPro, which may well be a default install package anyway.

 

Thank you so much for this process, makes working with samples so much easier!

 

This sounded like a good workflow but the sample did not show up in my latest asset store release.
Maybe I got the path wrong? This '~' thing is really confusing.

package.json
```json
"samples": [
{
"displayName": "Examples",
"description": "Various examples in how this package can be used.",
"path": "Samples~/Examples"
}
]
```

Working with the sample in another folder and then exported the stuff into:
MyPackage/Samples~/Examples/Examples.unitypackage

It would be nice if the Asset Store Tools could treat the folder Samples like a special folder some how.

 

Are there any ETAs for this?

 

Hi @okcompute_unity

The Samples is a cool feature.
I would like to have something similar, but still different

I am developing an extension which includes a feature that is optional. It should be optional because it lowers edtior performance but increases productivity. It also contains a third-party dll.
I wonder if I could somehow install this module through the package manager as another package. Preferable through a similar UI as with the samples. Is this possible?

 

Or ... Assuming you can't just turn it on/off with a bool (?), and it has compile-time impact ... you could make a #define for it and then #if MY_FLAG_IS_DEFINED all the code/classes for it. You can add your own #defines to an asset (put them in the asmdef) or I believe there's a snippet of code floating around that lets you insert them into the editor/player settings from your asset -- so you could provide a UI in your asset for 'enabling/disabling' the module, that would add/remove the #define, and have the side-effect of turning it on/off (I think?)

 

Is there a reason to not use samples for that? Have been using it for some extras in my packages with the same reason you pointed out.
Another option is to have a second package, that depends on the first, but it only works nicely with custom package scopes.
Or the suggestion above about the defines with a custom UI, which I used to use until samples in a package was a thing.

 

This would not strip the extra DLL. That's my main point, as I am not sure if people want that dll (It is harmony - which allows to modify existing c# assemblies).

AFAIK, samples land in the assets folder and not in the packages... also, the name "Samples" would be misleading.

Yes, I was thinking about this as well. Probably, I try this... However, I am not sure how hard it will be to manage references here...

 

I ship a couple of assets as multi-package installs. Works fine so far, and UnityEditor is happy - so long as you're using the asmdef conditional defines - that if a secondary-package is not installed Unity preserves the "if it appears in future, I'll start using it -- but I won't complain that it's missing for now".