How to template your Unity project?

Created with mid-journey

Hi,

You can easily speed up starting a new Unity project by preparing a template Unity project based on common best practices and depending on your needs. That saves you time when you can start a new project from your custom template with your lovely packages, project settings, and all template assets, presets, and even textures. That makes sense if you create prototypes frequently, work on short-lifetime games, or want to share a unified initial project across different teams.

I can offer two ways to prepare your custom Unity template:

1. Create a Unity project template and use it from Unity Hub.

2. Prepare a GitHub repo and use it as a template git repo with Unity assets.

Unity Project Template

Unity already provides some templates in the Unity hub:

But I am personally not happy with this. For example, it will install some unused in my case packages within the manifest. It does not customize PlayerSettings. I have to do many things manually. Let's see packages for the 2D mobile core template from Unity 2022. I want to exclude all red-marked packages:

Otherwise, I would like to include my starter kit for development and some regular packages for development, like UniTask, Core Utils SDK, etc.

A good start tutorial can be found here. Some comments from my side because from the first attempt, I had trouble.

The idea is to prepare tgz archive with specific structure from your Unity project and put it inside the Unity application ProjectTemplate sfolder with other templates:

On Mac, it can be found /Applications/Unity/Hub/Editor/2022.3.10f1/Unity.app/Contents/Resources/PackageManager/ProjectTemplates

I recommend taking any existing Unity template tgz archive, unpacking it, and seeing inside the format and structure. The easiest way to prepare the first template is by modifying an existing one. Libcache is optional for your new template, so let's skip it. If you unpack, for instance, com.unity.template.2d-7.0.3.tgz you see the structure as :

I put the important parts inside a red box.

The main things are package.json and ProjectData~ folder. You can skip other files and save time for supporting them.

Let’s see package.json. I attached a min working variant. You can change values for “name”, “displayName” and description for Unity Hub, and put the Unity min version in “unity”.

I recommend leaving empty dependencies and putting all you need inside ProjectData~/Packages/manifest.json

Next, see the ProjectData~ folder. There are Assets, ProjectSettings, and Packages folder. The Library you can skip. That is a regular folder from any Unity project. From ProjectSettings, you have to remove the ProjectVersion file.

Troubles if UnityHub does not fetch templates:

When package.json has an error or the archive is not in the tgz format.

1. The archive should be tgz format and named name-version.tgz. Name and version are taken from package.json

On Mac, you can use, for example, the command in the terminal:

tar czf name-version.tgz package/

=> tar czf com.unity.template.coremobile-1.0.0.tgz package/

on Windows 7Zip tool for example or any other.

2. The package.json does not have syntax JSON format errors.

3. You excluded ProjectVersion.txt from the ProjectSettings folder.

4.

And my one-hour special waste time issue. I modified the package folder inside the ProjectTemplates folder. Unity hub fetched successfully template but it threw errors when I tried to create a project from a template. Please prepare your template package folder from some other location on your machine and next copy or move tgz archive only to ProjectTemplates folder

If you did everything correctly after relaunching Unity Hub, you will see your template in the list, and you can successfully create a new project. Well done!

Disadvantages of the approach with Unity project templates

• You should manually (or with a custom tool) put your templates tgz inside the Unity app. If you update the Unity app on your CI/CD, you must update your Unity app instances. That adds complexity to configuring the environment.
• The format of the template project can be changed sometimes. For instance, a template from Unity 2018 can not be supported in Unity 2023 because of different formats of dependencies in manifest.json or inside package.json. That is why really important to make it as easy as you can.
• Unity loves to update the Unity hub regularly. When the new Unity hub breaks your template, it can be tricky to find the reasons.
• It will not be configured for the git control version from scratch

These disadvantages might be mitigated when Unity adds an easier way to create your custom project templates. I do not provide any discovered tools on Git to make it easier because some of them are already broken or can soon become.

I can not imagine working nowadays without some control version. I prefer the git control version. And even though when you have a good template, you will have to link with a repo for more convenience with team members etc. Let's look at another way to prepare a Unity template with Git's advantages.

Github template repo

About template repositories

You can create a template from an existing repository. Anyone with access to the template repository can create a new repository based on the template with the same directory structure, branches, and files..

A repository with LFS content cannot be used as a template. That means you should not abuse binaries. Verify that all necessary binaries are not located within LFS; otherwise, when you try to create a new project from your template, the binaries will not be fetched. If you have .gitattributes file remove it from a template or rename it differently for the next usage.

1. Let's create a new repo in GitHub

If you are not familiar with private repo types to simplify it please use the Public option.

You see it as:

2. Go to Settings and check the Template repository option:

3. You already can use the repo as a template:

4. Push your template files into the repo:

4. Create a new project from the template. Select “Use this template-> Create a new repository.”

You can even copy branch structure from the template repo

And now you can work on a new project!

Benefits of the approach creating a Unity template project with a Github repo template

• That is already linked with the Git control version.
• You can template even branch structure
• You can template .editorconfig for your lovely IDE
• You can put all other files, for instance, some Python scripts, for the build process.
• You exclude unclear underhood issues that can come from the Unity hub

Disadvantages:

• That is a bit of overhead to migrate to other control versions like Perforce
• You can not template assets from LFS

In conclusion

We looked into two ways to prepare a Unity template project. I preferred an option with the GitHub repo template. That is a more intuitive way to support it from the developer side with all the benefits you get from Git and enhance the template with additional assets like config with code style for your IDE.

If you liked this, please show your support by 👏 or follow me to get the latest publications in the future.