A set of utility classes and components useful to any Unity project, 2D or 3D.
Work in progress!
This package has been under open-source development since ~2017, but only since late 2022 has it been seriously considered for "usability" by 3rd parties, so documentation content/organization are still in development.
- Make sure you have both Git and Git LFS installed before adding this package to your Unity project.
- Add the UnityNuGet scoped registry so that you can install NuGet packages through the Unity Package Manager.
- Install dependencies in your Unity project. This is an opinionated list of 3rd party assets/packages that UnityUtil leverages for certain features.
Unfortunately, some of these assets cost money. In the future, UnityUtil's features will be broken up into separate packages,
so that users can ignore specific packages and not spend money on their Asset Store dependencies.
- Odin Inspector (v3.0.12 or above). We strongly recommend not installing Odin as an embedded UPM package, as it just makes later updates to the asset more difficult.
- In the Unity Editor, open the Package Manager window, click the
+button in the upper-left and chooseAdd package from git URL.... - Paste a URL like the following:
https://github.com/DerploidEntertainment/UnityUtil.git?path=/UnityUtil/Assets/<package>#mainfor the latest stable version of<package>(see the list of packages below)https://github.com/DerploidEntertainment/UnityUtil.git?path=/UnityUtil/Assets/<package>#unity<unityVersion>for the latest stable version of<package>built against Unity<unityVersion>(e.g.,unity6)https://github.com/DerploidEntertainment/UnityUtil.git?path=/UnityUtil/Assets/<package>#<version>-unity<unityVersion>for<version>of<package>built against Unity<unityVersion>(e.g.,0.1.0-unity6)https://github.com/DerploidEntertainment/UnityUtil.git?path=/UnityUtil/Assets/<package>#unity<unityVersion>-devfor the latest development version of<package>built against Unity<unityVersion>. These versions are bleeding-edge and very likely to contain bugs!
You can update this package from Unity's Package Manager window, even when it is imported as a git repo. Doing so will update the commit from which changes are imported. As the API stabilizes, I will move this package to OpenUPM and add a changelog to make its versioning more clear.
- Serilog.Enrichers.Unity: Implements a Serilog enricher to dynamically add Unity data to log events like frame counts, GameObject hierarchies, etc.
- UnityUtil: utility classes and components related to dependency injection, logging, mathematics, data storage, etc.
- UnityUtil.Configuration.RemoteConfig: Implementats a
Microsoft.Extensions.Configurationconfiguration provider for Unity Remote Config - UnityUtil.Inputs: abstracted player inputs
- UnityUtil.Interactors: interaction with in-world objects
- UnityUtil.Inventory: in-game item inventories
- UnityUtil.Legal: legal/privacy consent
- UnityUtil.Movement: in-game movement mechanics
- UnityUtil.Physics: 3D physics helpers
- UnityUtil.Physics2D: 2D physics helpers
- UnityUtil.Triggers: event-based behavior in-game
- UnityUtil.UI: in-game and in-Editor user interfaces
Sometimes, you need to preserve code elements from managed code stripping by IL2CPP during builds.
For example, your app may produce runtime code that doesn't exist when Unity performs the static analysis, e.g. through reflection and/or dependency injection.
You can use Unity's [Preserve] mechansim to preserve these elements in your own code;
however, UnityUtil intentionally does not annotate any code with [Preserve] so that you have total control over the size of your builds.
Therefore, if you need to preserve UnityUtil code elements (types, methods, etc.),
then you must use the link.xml approach described in the Unity Manual.
For bug reports and feature requests, please search through the existing Issues first, then create a new one if necessary.
Make sure you have Git LFS installed before cloning this repo.
To build/test changes to this package locally, you can:
- Open the test Unity project under the
UnityUtil/subfolder. There you can run play/edit mode tests from the Test Runner window. - Open the Visual Studio solution under the
src/subfolder. Building that solution will automatically re-export DLLs/PDBs to the above Unity project. - Import the package locally in a test project. Simply create a new test project (or open an existing one), then import this package from the local folder where you cloned it.
See the Contributing docs for more info.