Project and package manager for Unity3D
Project description
upkit — Unity3D project/package toolkit
upkit
is a command line toolkit that helps you create/organize your Unity3D projects and manage their dependencies.
If you are in a hurry, go to Getting Started to see it in action, otherwise, take a few minutes reading the following section to see what problems it tries to solve.
Why should you use it?
Existing tools' limitations
There are tools that already helped with managing dependencies. In fact, we are big fans of the great tool Projeny
for its simplicity, CI friendliness, and have used it frequently in our team. However, as Projeny
model imposes a flat, exclusive package hierarchy (everything must be in either Assets
or Plugins
folder), it is not always possible to link external packages directly without repackaging. For example, two packages having different native libraries under the same folder Plugins/Android
will not work together unless we copy these native libraries to another folder, namely Plugins_Android
and link it under Plugins/Android
.
As for Unity built-in Package Manager, although looking promising, it does not offer the following capabilities that we need:
- Management of our private asset packages, legacy Unity packages, and even Nuget packages.
- CI friendliness.
upkit
remedies those issues and adds some tricks
upkit
was initially designed as a tool sitting between nuget
(dependency resolving) and Projeny
(project linking) in our pipeline, where extra links are generated before the actual project structure is created. As the tool evolves, upkit
gradually becomes a superset to some of Projeny
main features, to a point that it replaces Projeny
completely in our pipeline.
In particular, upkit
provides the following main features:
- Packages can be linked to any location in the project folder, not just
Assets
andPlugins
. - Packages can have sub-links pointing to anywhere in its content, not just its root. Therefore external or Nuget packages can be linked without repackaging.
- File-level links, not just folders.
- Packages can have their
linkspec.yaml
file to define how they should be linked (for cross-project reusable packages). - Simple configuration, yet extensible with parameters.
Getting Started
These instructions will create a simple Unity3D project with a Nuget dependency (Newtonsoft.Json) using upkit
.
The source code to this project can be also found under examples/appkit
.
Prerequisites
upkit
requires Python (2.7 or above) to work. You will also need pip
to install it.
For this example, you will also need nuget
to resolve Nuget dependencies.
Installing
Run the following command to install upkit
from Github repository.
$ pip install git+https://github.com/finderseyes/upkit.git
Create the project structure
We will need to create an initial structure for our project, as below:
(project)/
├── dependencies/
├── project-packages/
│ ├── Scenes/
│ └── Scripts/
├── project-settings/
├── unity-projects/
├── packages.config
├── project-config.yaml
└── initialize.sh
In this folder:
dependencies
is where Nuget packages are installed.project-packages
is where we create project scripts and scenes.project-settings
is where Unity project setting files are stored.unity-projects
is where the actual Unity projects are generated.packages.config
is Nuget packages file, declaring our project dependencies.project-config.yaml
is theupkit
configuration file.initialize.sh
is the script that we actually execute to link and generate Unity projects.
packages.config
Declaring project dependencies is simple, just a typical Nuget config file.
<?xml version="1.0" encoding="utf-8"?>
<packages>
<package id="Newtonsoft.Json" version="11.0.2"/>
</packages>
project-config.yaml
This is the main configuration file, which upkit
uses to generate the Unity project. The configuration has two sections:
params
defines parameters used by the project.links
defines how the project and its packages should be linked.
The following configuration should be self-explanatory. For more information please see the documentation.
params:
project_name: appkit
platform: windows
project_dir: '{{__dir__}}/unity-projects/{{project_name}}-{{platform}}'
project_settings: '{{__dir__}}/project-settings'
assets: '{{project_dir}}/Assets'
plugins: '{{assets}}/Plugins'
dependencies: '{{__dir__}}/dependencies'
packages: '{{__dir__}}/project-packages'
links:
- source: '{{project_settings}}'
target: '{{project_dir}}/ProjectSettings'
- source: '{{packages}}/Scripts'
target: '{{assets}}/Scripts'
- source: '{{packages}}/Scenes'
target: '{{assets}}/Scenes'
- source: '{{dependencies}}/Newtonsoft.Json.11.0.2/lib/net35'
target: '{{plugins}}/Newtonsoft.Json'
initialize.sh
#!/usr/bin/env bash
# resolve Nuget dependencies
nuget restore packages.config -PackagesDirectory dependencies
# call upkit to link and generate Unity projects.
upkit link -c project-config.yaml -p platform=ios
upkit link -c project-config.yaml -p platform=android
Generate Unity projects
It's simple, just run initialize.sh
script. There will be two new folders, namely appkit-ios
and appkit-android
, under unity-projects
. Open these folder in Unity and voilà, ready to go.
(project)/
├── unity-projects/
| ├── appkit-ios/
| └── appkit-android/
Documentation
Work in progress.
Authors
- Vu Le - Initial work - FindersEyes
License
This project is licensed under the MIT License - see the LICENSE.md file for details
Acknowledgments
- This tool uses
xmltodict
,pyyaml
,yamlordereddictloader
, andjinja2
under the hood. Thanks to the respected authors for the hard work.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.