Advice for shared code between multiple Unity projects

[RxMarcus]

I've started writing a Unity project that has become sort of a "core" codebase that my team would like to use as a foundation for all future game projects we create. I've done various googe searches and have had a hard time understanding how Plastic's approach to this could work. I believe with something like Git, you can use "submodules" or packages in some fashion. In Plastic there are "x-links" but I haven't explored or understood how they work very well (when I google about them I see posts from a decade ago so it makes me wary).

With all of that said, I'm looking for some advice in the context of how modern (2023) Plastic works for how I might approach having a base unity project that is brought into multiple other unity projects in the most effective way possible.

Thanks in advance!

[Rafael]

Hi,

Xlinks are what you are looking for, they are the equivalent of git submodules.

This is the modern approach, you just need to follow the Xlinks guide: https://docs.plasticscm.com/xlinks/plastic-scm-version-control-xlinks-guide

You most likely will be creating new repositories and creating a Xlink for each that point to this core project.

 

If you have further or more specific questions let me know.

Regards,

Rafael

Unity Plastic SCM Support
Virtualize your Workspace. Make it dynamic.

[Wolfram]

Xlinks are what we used for this for many years. They have many advantages, for example each project using the linked codebase can even have its own local changes, and for writable Xlinks you could even extend your codebase from within each project, and then integrate these changes (or just the relevant parts from them, using cherrypicking) individually from within the Xlink repo.

However, a while ago we switched to Custom Unity Packages for most of our projects. These are especially useful if your individual projects don't need (or shouldn't!) make changes in the codebase. The setup is a bit more complex, though, as you'll either need your own package server, or use a (publicly accessible...) server such as https://openupm.com/ .

Here is a bit more info on how to convert your codebase into a custom Unity package for the Package Manager: https://docs.unity3d.com/Manual/CustomPackages.html

[RxMarcus]

Thank you both.

@Wolfram With your setup using Unity packages, do you have 1 mono package that has "all the things"? Or are you breaking up your shared code into "modules" of sorts so that a project could bring in more granular code from the shared code base?(i.e. I only need character controller, so I just bring in that package)

We are a very small part time indie studio so maybe I should stick with xlinks for now. One pain point I found in getting setup on xlinks was that I wanted my "core / shared" code to be an actual unity project so I could write Unit Tests on it and what not, but then with xlinks you must take the whole repo's base folder if you want a writable xlink. So it'd be importing a full unity project into my other unity project that is using the "core" codebase project. I ended up doing a read only xlink so that I could at least specify a specific shared code folder and not have to bring in the whole Unity Project. But now it will be a pain when I need to update the shared code project since it's a read only xlink.

[Wolfram]

Yes, we split up our Framework into thematically useful modules, and created individual packages from each.

If you managed to create the general package structure once, it is quite simple to work with it, and it is really comfortable to use Unity's PackageManager to include whatever modules you need into your projects. This includes being able to choose an explicit version of your package (as opposed to having to always using the most current one).

But as I said, for the UPM packages you need some place to host them - either OpenUPM or similar (but this would expose your code to be publicly accessible, which is probably not what you want), or running a local package a.k.a registry server (such as Verdaccio, which is not very complicated to set up).

Concerning your repository question - you're correct that read-only Xlinks are the way to go if you only want to include a specific folder (and you'll have to use the CLI to create such an Xlink, it can't be done via the GUI). However, it complicates things if you want to regularly/often make changes to your framework from within such a referencing project (as opposed to making the changes in the original Xlink-host repository itself).

What we did in the past for our Xlink repo was not to create it from a full Unity project, but just for a single directory in an otherwise empty local project (for example, create an empty Unity project, copy your initial framework source to /Assets/Plugins/MyFramework (or wherever you want it), and then create a new Plastic repository for just this one folder. This way you can keep referencing that whole repository as your writeable Xlink target.

Additionally, in that Xlink repository we then created individual, long-term "project branches" for each project that wants to reference to it via writable Xlink. This way, each project can "locally" modify stuff on its Xlink branch, without messing with the global/main framework code (and therefore all other projects using it). Then, from time to time, your framework maintainer can go through the Xlink source repo, and check all incoming changes from each project, and decide whether these changes should be integrated into the /main branch (preferrably using Plastic's Cherrypicking feature, so that you only integrate the changes you need, but can keep other changes local to the project branches.

[RxMarcus]

@Wolfram Thank you so much for your detailed response. Your suggestion for having an empty Unity Project but only make a Plastic repo of the specific framework directory is perfect. I think that is exactly what I was looking for. Thank you again!