Unreal Engine and GitHub for remote collaboration

Tl;dr

If you want to collaborate on an Unreal Engine project, GitHub will serve as the cloud storage for your files. GitHub is based on the version control system called "Git". To upload and download files to GitHub, you can use Anchorpoint, a version control application that is also based on Git.

Git vs. GitHub

You may have heard both terms and feel a bit confused. Here is an explanation:

Git

This is the version control system. It is the underlying technology that checks if files have changed, stores new file versions in a history, and allows you to restore previous versions. Think of it as a little tool that organizes your files. You don't need to worry that something gets lost or how you send files to your team members. Git takes care of that. It's like a smarter Dropbox alternative.

It is also a standard that is used by GitHub or any other tools and services so that they are compatible with each other.

GitHub

GitHub is one of many cloud storage providers that are based on Git. It is very popular for hosting open-source software, such as the Unreal Engine source code. GitHub will be the place where our files will live in the cloud.

Don't use Dropbox, Google Drive, or any other shared file server for your Unreal Project

Unreal Engine does not support incremental saving and locks assets when you reference them in a level. If you put that on a shared or sync network drive and work on it together, you will constantly override each other's work. It would not be clear who has done what, and the whole project would break and end up in total chaos.

How to use GitHub for your Unreal project?

To upload and download our files to GitHub, we will use Anchorpoint, which is a desktop application optimized for game development. There is also GitHub Desktop or SourceTree, but Anchorpoint can deal better with binary files, has file locking, and is much more simplified so that an artist can use it.

Create a repository on GitHub

Go to github.com and go through their account creation process if you haven't done it yet.

Create a new repository and give it a name. A "repository" is the name of your project. It's the same as a folder with all your project files. It will be public by default, so everybody can view and download your source files. If you don't want that, just switch the option to "private".

To invite your team members, click on "Invite collaborators". Click on the green "Add people" button and type the email of your team members. They will get an invite to create a GitHub account.

Make sure you have enough storage and bandwidth

GitHub is pretty restrictive when it comes to storage and bandwidth. By default, you only have 1GB of available storage and bandwidth. To expand that, you don't need to upgrade your GitHub plan but purchase storage packs. Storage packs are bought via subscription and are not dependent on your member count. A storage pack is $5 per month and gives you 50GB of storage and bandwidth. If you run out of storage and bandwidth, Anchorpoint will show you information that you need to buy additional storage on GitHub. Here is how you do that:

Finally, copy the URL of the repository to clipboard

Anchorpoint will need this URL so that it knows where to upload the files later on.

Get Anchorpoint

Go to anchorpoint.app, create an account, download and install the application. When you open it for the first time, just click on the login with email button, and it will automatically log in with the account you created. Fill out the form and start the trial.

‍

Create a new project

Create a new project in Anchorpoint and choose the option "Git Repository". Let Anchorpoint know where your Unreal Project is located and browse to the project folder. Once this is set, Anchorpoint should automatically recognize that it's an Unreal Project and set the proper .gitignore configuration. This configuration just makes sure that you won't upload folders like DerivedDataCache and other files that are temporarily generated on your local computer. They should not be shared with others.

Just follow the steps and invite the same team member whom you invited to GitHub, here as well.

Upload your Unreal project to GitHub

We need to push (that's the Git term for upload) all the files to GitHub. Go to the "Timeline" and click on "Changed Files". You should see all your project files, except the ones that are ignored (files in DerivedDataCache, etc.).

Enter a short note into the text field and press push. Then, all files will be uploaded. If you do this for the first time, a popup from GitHub will show up. Just click on "Sign in with your browser" to connect Anchorpoint with GitHub.

Do your work in Unreal Engine

Work on your asset or level in Unreal. Keep Revision Control (or Source Control if you are on 5.1 or lower) off. Once you save a level or asset, Anchorpoint will detect that automatically and lock the files for anybody in your team to prevent conflicts.

Once you feel that you want to publish your work, simply add a note and press "push". In Git terms, you are calling this process "creating a commit". It's definitely recommended to commit quite often and usually when you have finished a task. You will have a better documentation what you have done and you can always go back if something breaks.

What your team member needs to do

To work together, your team members need to

1. Accept the invite to GitHub
2. Accept the invite to Anchorpoint

On GitHub, they just need to create an account and accept the invite. In Anchorpoint, once they launched the application, they will be invited to your workspace by getting a popup. Once they accept it, they will be automatically assigned to the project. In the next step, they only have to tell where the Unreal Engine project should be downloaded.

After that, they are also able to make changes and commit them to GitHub.

Things to keep in mind

1. You need disk space

Git is a distributed version control system, which means that it stores everything on your computer so that you can work faster (there is no constant connection to a server). This also means that it creates a huge amount of data cache. The rule of thumb is having twice the disk space that you need for your Unreal Project.

2. Use World Partition

Since Unreal Engine 5.0 you can use World Partition, which does not store everything of the level in the .umap file, but splits it up into small .uasset files. The benefit is that you can work at the same level without blocking each other. Furthermore, your pushes to GitHub will be much lighter and will cost you less storage.

3. You can work offline

You can create new commits even if you are offline. You can then push them later when you are back online.

4. You can restore versions any time

That's the beauty of a version control system. It's like a backup. Click on commits and use "Undo" to revert changes that broke the project or simply use "Restore Project" to travel back in time.

‍

Alternatives to GitHub

GitHub is the most popular Git hosting provider out there. But it's not always the best choice in game projects. Luckily, there are plenty of alternatives out there. One good solution is Azure DevOps from Microsoft, which does not charge for storage. And you will need storage unless you are making a simple 2D game. AWS code commit might also be worth a try.

Because Git is open source, there are many ways to set up a server on your cloud or NAS. In this case, Gitea, which is an open-source project based on Git, is also a good choice.

Frequently asked questions

What is Git LFS?

Git LFS (Large File Storage) serves as an extension for Git, enabling efficient management of binary files. In the case of game projects, which often involve numerous binary files, Git LFS becomes essential to maintain optimal repository performance and capacity. Without it, your repository may swiftly encounter limitations in handling these files. Git LFS handles storage operations adeptly, ensuring the streamlined storage and transfer of your binary files. This results in a smoother version control experience and prevents bottlenecks caused by large file sizes.

Why do I need version control?

Version control is a crucial tool for several compelling reasons. Firstly, it maintains a clean project folder by storing a comprehensive history of your files, allowing easy access to previous versions with explicit comments. Secondly, it ensures transparency throughout the entire design process, enabling seamless collaboration with teammates and real-time visibility into who is working on specific files. Additionally, version control organizes files logically, eliminating the need for strict naming conventions and reducing confusion. Moreover, it offers an increased level of security, allowing you to revert to previous states or safeguard against accidental damage to someone's work. Lastly, version control facilitates the onboarding of new team members or freelancers by providing clear documentation of the project's progress and changes.

What is Anchorpoint?

Anchorpoint is a version control application that is based on Git and therefore compatible with any Git hosting provider such as GitHub, GitLab, or Azure DevOps. It extends Git with an artist-friendly interface, good binary support, and file locking. Anchorpoint is also an asset manager that allows you to organize files outside your Unreal Engine project, e.g., Blender files, 3D scans, or models.

Why not use the integrated Git plugin in Unreal Engine?

The reason why it makes sense to turn this off is speed. The Git plugin does slow the engine down and has no proper file locking. However, if you want to commit directly from the engine, you can do that with the plugin. You have to push your commits to GitHub later via Anchorpoint.

‍