Development Setup

VPE uses Unity's Package Manager to fetch its code. For users that's great because they get updates without having to deal with git, and the actual project to work with is very small because the heavy dependencies get pulled in by UPM. We use our own scoped registry. Packages get published automatically when something gets merged or pushed to master.

However, packages are immutable in Unity, meaning code can't be updated and thus they are not suitable for local development. For that, you need to clone each package locally and manually add them to the project.

Repositories

VPE consists of multiple repositories. We have split them because of two reasons:

1. We want to have code separate from the rather heavy assets (textures, models, etc)
2. URP and HDRP aren't compatible and cannot live together in the same project (and we support both).

Here an overview of VPE's repositories:

Order of Setup

When using the HDRP or URP project, the scoped registry is already set up and Unity will pull in dependencies in from that. So the first step is to remove it. For that, go to project settings, and remove the Visual Pinball Engine registry under Package Manager. Then, remove the VPE packages. The most-parent package is Visual Pinball Engine (HDRP), so removing that should remove the others as well.

The second step is to clone all the repos:

git clone [email protected]:VisualPinball/VisualPinball.Unity.AssetLibrary.git
git clone [email protected]:VisualPinball/VisualPinball.Unity.AssetLibrary.Hdrp.git
git clone [email protected]:freezy/VisualPinball.Engine.git
git clone [email protected]:VisualPinball/VisualPinball.Unity.Hdrp.git
git clone [email protected]:VisualPinball/VisualPinball.Unity.Urp.git

HDRP

In your Unity project, add the repositories as package from disk in the following order:

1. VisualPinball.Unity.AssetLibrary
2. VisualPinball.Unity.AssetLibrary.Hdrp
3. VisualPinball.Engine
4. VisualPinball.Unity.Hdrp

URP

When working with URP, use these repositories in this order:

1. VisualPinball.Unity.AssetLibrary
2. VisualPinball.Engine
3. VisualPinball.Unity.Urp

VisualPinball.Unity.AssetLibrary.Urp does not exist yet, but it will be added here when it does.

Releasing

One advantage of UPM is that it makes it easy for users to upgrade:

In order for that to work, we use GitHub actions to increase the package version on each merge to master, publish the package to our registry and update the dependents. For example, if you commit to vpe.assets, GitHub will:

• Increase the version of vpe.assets and publish a new package to our package registry
• Update vpe.assets.hdrp, vpe.assets.urp and main to use the new version
• Since they got updated, the three repos in the last step will also increase their version and publish themselves
• The will also update their dependents, e.g. vpe.assts.hdrp will update vpe.hdrp, which then will bump its version and publish itself, too.

Summary: Committing to master on any repo will automatically release itself and its dependents. So avoid committing to master directly and use PRs!

Cross-Repo Features

Sometimes you'll be working on features that span over multiple repositories. We recommend branching each repository to the same branch name so it's clear which branches belong together when testing the feature.