Skip to content

Development Setup

Jump to bottom Edit New page
empty-set edited this page Aug 4, 2022 · 20 revisions

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:

image

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 git@github.com:VisualPinball/VisualPinball.Unity.AssetLibrary.git
git clone git@github.com:freezy/VisualPinball.Engine.git
git clone git@github.com:VisualPinball/VisualPinball.Unity.Hdrp.git
git clone git@github.com:VisualPinball/VisualPinball.Unity.Urp.git
git clone git@github.com:VisualPinball/VisualPinball.Engine.PinMAME.git

If you receive authentication errors you will need to add an ssh key to your github account.

The third step is to compile the projects

cd VisualPinball.Engine
dotnet build -c Release

cd ..

cd VisualPinball.Engine.PinMAME
dotnet build -c Release

HDRP

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

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

URP

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

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

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.

.meta Files

Unity automatically creates a .meta file for every file and directory it indexes. It also does a somewhat decent job cleaning them up if the original file is missing. The .meta files are particularly important for native binaries, because they tell Unity to which platform they belong and thus avoid conflicts.

The thing is, that in the main repo there are a few native dependencies which we don't include in the repo but rather reference them through NuGet and copy them to Unity's Plugin folder when compiling for the first time. That means that in the repo, we have the .meta files for those dependencies, but not the actual files, resulting in Unity cleaning the .meta files for all platforms when compiling.

Long story short, you'll end up with something like this very soon:

You don't want to commit this because it will break CI and package publishing. We also can't put them into .gitignore because that only applies to files that exist and you don't want to commit (here it's the other way around - you deleted files you don't want to commit).

The solution is to tell git to explicitly ignore those files. You only do that once after cloning.

git update-index --assume-unchanged VisualPinball.Unity/Plugins/linux-x64/FluentAssertions.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/linux-x64/JeremyAnsel.Media.WavefrontObj.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/linux-x64/NLog.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/linux-x64/NetMiniZ.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/linux-x64/NetVips.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/linux-x64/OpenMcdf.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/linux-x64/System.Buffers.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/linux-x64/VisualPinball.Resources.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/linux-x64/libminiz.so.2.2.0.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/linux-x64/libvips.so.42.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/osx/arm64/libvips.42.dylib.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/osx/x64/libvips.42.dylib.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/osx/FluentAssertions.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/osx/JeremyAnsel.Media.WavefrontObj.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/osx/NLog.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/osx/NetMiniZ.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/osx/NetVips.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/osx/OpenMcdf.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/osx/System.Buffers.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/osx/VisualPinball.Resources.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/osx/libminiz.2.2.0.dylib.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/osx/libvips.42.dylib.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x86/FluentAssertions.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x86/JeremyAnsel.Media.WavefrontObj.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x86/NLog.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x86/NetMiniZ.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x86/NetVips.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x86/OpenMcdf.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x86/System.Buffers.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x86/VisualPinball.Resources.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x86/libglib-2.0-0.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x86/libgobject-2.0-0.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x86/libminiz-2.2.0.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x86/libvips-42.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x64/FluentAssertions.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x64/JeremyAnsel.Media.WavefrontObj.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x64/NLog.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x64/NetMiniZ.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x64/NetVips.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x64/OpenMcdf.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x64/System.Buffers.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x64/VisualPinball.Resources.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x64/libglib-2.0-0.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x64/libgobject-2.0-0.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x64/libminiz-2.2.0.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/win-x64/libvips-42.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/android-arm64-v8a/FluentAssertions.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/android-arm64-v8a/JeremyAnsel.Media.WavefrontObj.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/android-arm64-v8a/NLog.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/android-arm64-v8a/NetMiniZ.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/android-arm64-v8a/NetVips.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/android-arm64-v8a/OpenMcdf.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/android-arm64-v8a/System.Buffers.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/android-arm64-v8a/VisualPinball.Resources.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/ios-arm64/FluentAssertions.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/ios-arm64/JeremyAnsel.Media.WavefrontObj.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/ios-arm64/NLog.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/ios-arm64/NetMiniZ.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/ios-arm64/NetVips.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/ios-arm64/OpenMcdf.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/ios-arm64/System.Buffers.dll.meta
git update-index --assume-unchanged VisualPinball.Unity/Plugins/ios-arm64/VisualPinball.Resources.dll.meta

Yeah, we know...

Compiler Flags

There are some flags that might be useful for debugging.

  • WRITE_VP106 omits data not in VPX 10.6, like VPE data, as well as 10.7-specific data. However it writes deprecated data.
  • WRITE_VP107 write deprecated data as VPX 10.7 would.

In theory, WRITE_VP106 and WRITE_VP107 should result in identical binaries compared to what VPX produces. However, VPX contains random memory data when writing the GameData stream, so there are variations even if VPX writes the same file multiple times. An additional difference is that VPE will drop duplicate names in streams, while VPX allows them (for example multiple sounds with the same name). All fixed in latest VPX 10.7.

Add a custom footer
Add a custom sidebar
Clone this wiki locally