How to Create Custom Unity Project Templates

Getting started in a new Unity project with the right template can be an effective way to skip the somewhat grindy setup stage and get you into the fun part of production right away. Although Unity offers a range of both useful and educational templates to choose from by default, sometimes you need something a little more bespoke.

Creating your own Unity project templates is an easy process that can rapidly speed up your workflow, especially if you create a lot of similar projects. By adapting the existing templates found in your installation folder you can be up and running in no time.

This tutorial will run you through the quick process of creating a customizable template from which you can generate new projects via Unity Hub.

Let’s get started!

#1) Locate your project templates folder

To get started you’ll need to navigate to where Unity Hub keeps its templates. On PC they can be found inside your Unity installation folder at the following directory:

Unity\Hub\Editor\2021.1.7f1\Editor\Data\Resources\PackageManager\ProjectTemplates

If you’re using a Mac I think the path is the same (or at least very similar) but I don’t own a Mac so I’ve not been able to confirm. Please reach out if you can shed any light on this.

Remember to sub-out the version number in the above path for the version of Unity for which you want to make your template. Backward/forwards compatibility can be an issue, so pick carefully.

#2) Create a new template

Now we’re in the right place we’re going to make a copy of an existing template so we can edit it to create our own. This isn’t strictly necessary as we could always make one from scratch, but that would include a lot of small details which just present more opportunities for things to go wrong. Editing an existing template is the safer option so that’s what I’ll be doing.

If you’re not sure which template to copy I recommend starting with one of the standard 3D or 2D templates. They’re always a good place to start. In this example I’m using the 3D template.

#3) Name your new template

Naming conventions are really important here. Unity Hub will cross check the name of the archive with its contents and it won’t work if you don’t follow the format it expects. Your archive will need to match the following convention:

com.unity.template.name–versionnumber.tgz

Fill in the name and version number fields for your custom template. Keep it lowercase and make sure your version number has the full three digits.

#4) Configure your templates package file

Use a file archiver tool like 7-zip to open your custom template. You do not need to unpack/unzip it.

Navigate through the archive until you reach the package folder. Inside will be a .json file called package.json. This is the file Unity Hub will go to for instructions on how to interpret the project template. Open it up in a text editor (Notepad will do) as we’ll need to make some changes.

name

Make sure you change the name field to exactly match the name you gave your archive in Step #3 (sans the version number). If you don’t do this Unity Hub won’t be able to read your template.

displayName

Your display name can be anything. I’m interested in making a custom variation of the standard 3D template, so I’ve decided to be unimaginative and run with ‘techarthub 3D’.

version

The version field needs to match the version number you added in Step #3 or Unity Hub won’t recognize it.

description

You can use this optional field to add a description to your template. I recommend using it to remind your team (or yourself) of the template’s intended purpose.

dependencies

My template has no dependencies so I’ll be leaving this field as-is, but if yours has prerequisites you can add them in here. Here is an example from the HDRP Template which shows the correct way to format this section.

repository

You’ll need to delete this section if you’re not hosting your template repository online. You won’t need it as your project template will just be sitting locally in your install folder, and it will confuse Unity Hub.

Of course, if you are hosting your template in an online repository you should add those details in here.

Result

At the end of this process my package file looks like this:

When you’re done, save your file and update it in your archive.

#5) Add your project data

Now your package configuration file is finished you can start adding assets, packages, and setting presets into your template. Inside the ProjectData directory you’ll find three folders: Assets, Packages, and ProjectSettings.

You can drag files into your archive to add them to the template, or make changes to your template’s project settings by using a text editor to modify the .asset files.

When you finish adding content you can close out of the archive. If it’s been sitting on your desktop, copy it back into your Unity installation directory. You’re good to go!

#6) Restart Unity Hub

The last step is to reopen Unity Hub to see if your custom template shows up in the list. You will need to completely restart the Hub for it to notice the change and properly update.

Troubleshooting

Creating custom project templates can be a little finicky. Most of the issues I encountered while doing the research for this article concern the specific syntax of the package.json and the title of the template itself.

Here are a few of the more common issues that may arise.

The template isn’t appearing in the list

This is most likely caused by a mismatch in the name or version number between the template archive file and the package.json within.

Double check they both line up, and remember that the version number needs to include three values separated by periods.

name-#.#.#

The Unity Hub is hanging on ‘Retrieving list of available templates’

This is likely caused by an errant comma in your package file. The way these files work is that each field is separated by a comma which indicates when the field is finished, and declares that there is another to follow.

If you’re removing unnecessary sections of your package file you may have a comma at the end which means Unity Hub never gets to the end of reading the template and will hang indefinitely. Just getting rid of the comma should clear this problem.

I have duplicate templates in my new project window

This happens when two packages share a name. If this happens to you (as it happened to me) it’s because after editing your package.json file the .tgz archive didn’t properly update. 

This may be a mistake, or might be because the Unity installation folder requires admin privileges and your PC isn’t happy about modifications to the files within.

Try opening it from your desktop, and see if it properly updates.

Wrap-up

Although creating your own Unity project templates does have an associated setup cost, if you find yourself always stripping out the starter content, or creating the same kinds of projects over and over, custom templates will save you so much more time in the long run.