This is a guide that has was originally created in 2014 so it may not be entirely up-to-date. All the concepts should still be very similar, though. Enjoy!
NOTE: This is guide was created and tested using Windows 7 Professional 64Bit. I cannot guarantee that you will not have unexpected issues if you use a different operating system.
I’ve spent the last few days researching and attempting to get a source control system in place for some future UE4 (Unreal Engine 4) projects that I intend to work on, and I was surprised by the lack of documentation advising on how to set up either Perforce or SVN for use with Unreal Engine 4 projects for complete beginners.
So I decided to put together this complete guide to assist any other individuals in setting up SVN (Subversion) source control with their Unreal Engine 4 projects. I have broken this guide down into two parts, the first part will be the initial setup, and the second part will be interacting with the SVN repository on a remote server to “check-out” and “check-in” files.
Commit means to “push” or upload your local changes onto a remote server. So to do an initial setup, you need to create your Unreal Engine 4 project and have it commit the entire project onto the remote server. You need two things to do this:
- An SVN Client
- And a remote SVN server
- My SVN client of choice is TortoiseSVN. Download and install the correct version for your OS from here.
- And for the remote SVN server I used Cloudforge. I chose Cloudforge because they offer free hosting with the only real limitation being 2GB storage space, which can be upgraded for a minimal monthly charge if required.
- NOTE: Cloudforge do not offer free hosting anymore, so a user in the comments has suggested https://www.assembla.com/ . I have not tested this website myself so use at your own risk! The process will differ slightly with Assembla but the general principals will be the same (this guide will continue to cover Cloudforge for the time being).
- Create an account for free with Cloudforge (the domain name can be whatever you want) and find the Create Project button. You should have a screen similar to below:
- Insert a project name and be sure to check the SVN option (see above image). Click Create Project when you are ready.
- Now you should be on the project page for your newly created SVN repository. You can add users to this project via the menu on the left, and you’ll notice a Quick URL for SVN on the right. You’ll need this URL in a moment, so keep the project tab open. See image below for more details:
- Ok. Now that we have our server set up, we need to do the actual initial commit to the server. This will be done using TortoiseSVN (which you should have downloaded and installed earlier).
- Navigate to the folder where your Unreal Project is located on your local machine (the folder that holds all your project files and folders, like “Content”, “Binaries” and “[Your_Project_Name].uproject”, etc.) and Right-Click>>SVN Checkout… on that folder (see image below):
- You should then be presented with a TortoiseSVN Checkout window. Remember the Quick URL from the Cloudforge project page earlier? Copy that and paste it into “URL of repository” text field.
- IMPORTANT NOTE: Doing this appears to change the values in the “Checkout directory” text field. Ensure the directory points to the Unreal Project folder that we Right-Clicked earlier, and not something else. See image below:
- Leave everything else as default and click OK. Click yes when prompted to (you may also be required to insert you Cloudforge Username and Password at some point; be sure to enter those correctly or this step and/or all subsequent will fail).
- Once the Checkout is complete, we can tell SVN to ignore certain folders that are “not needed” for source control. This does not need to be done, but it will substantially reduce the size of your commits (and that of everyone else’s in the team). Go into your Unreal Project folder and you will be presented a number of folders and files.
- There are 7 selections that are NEEDED: “Binaries”, “Config”, “Content”, “Source”, “Build”, “[Your_Project_Name].sln” and “[Your_Project_Name].uproject”. All other files and folders can be added to the SVN Ignore List by selecting them, right-clicking and adding to ignore list (see image below).
- This alone has saved me over 2GB of space on my Mouse Project (from 3.4GB, down to 1.1GB). These folders being ignored represent Cooked content and Built Levels for Unreal Engine 4. They are important, but it is easy to re-cook and re-build levels locally if required via the Unreal Editor, rather than increasing project size massively.
- Now we need to mark the entire project for Add. Go back to the Unreal Project folder directory (in my case, the Mouse folder). Right-click it>>TortoiseSVN>>Add…
- A window should pop up with check boxes for every file in that directory. Have a quick look through to make sure the Ignored folders and files from earlier are not included (if they are, then go back and make sure they are ignored by following the previous steps). Make sure every object is checked, and click OK. Another window will pop up Adding all those files to the next commit.
- Now to do the Initial Commit. Once again, Right-Click the project folder (in my case, the Mouse folder) and click on “SVN Commit.” You should be presented with the following window:
- You should notice all the files you “Added” earlier are in that list. Simply click OK and your project will begin uploading to the Cloudforge server earlier that you specified during the “Checkout” step. The upload may take a while depending on your Internet connection and the size of your project.
- Once this is done, you should notice on the CloudForge project page that you have 1 commit. This commit should be your entire project (minus the ignored files).
- Well done. You’ve got your entire project onto the CloudForge server! The next step is to figure out how all this “collaboration” works with Unreal Engine 4. This is what the next section will cover:
Collaborating in Unreal Engine 4
Unreal Engine 4 has SVN and Perforce support integrated as part of the editor. What does this mean? It means users can log into the SVN server and “Check out/Lock” a certain file while they are working on it. For example, your project may have a Blueprint (UE4-specific asset) called “MyCharacter” that needs some changes. While making these changes, you do not want anyone else touching and making changes to the “MyCharacter” asset, so you have “Checked Out” the file, which locks any other member of the team from doing anything to this asset. There are visual indicators within the Unreal Editor which specifies a lot of this (for more information, click here).
- This section assumes you have downloaded and installed TortoiseSVN and have access to a SVN repository on Cloudforge. Ask the person in your team that did the Initial Commit to create additional users and assign them to your e-mail (this is done through Cloudforge).
- NOTE: You do not need to do this step if you already did the “SVN Checkout” from the first section. First you will need a “working copy” of the repository on your local machine. So make a new folder somewhere (try to keep the name the same as the actual project, as UE4 does not like name changes). Right-click the folder and click “SVN Checkout”. Enter the URL of the repository from CloudForge (it is the Quick URL on the right side of the CloudForge project page) and make sure the “Checkout directory” is the folder you Right-clicked on (this program likes to automatically change it, so be sure to double-check). Hit OK once done (see image).
- Once you have hit OK, it may ask you for your credentials. Type them in and it’ll begin downloading the entire repository. This may take a while depending on your Internet connection and the size of the project.
- Once the project is downloaded, go ahead and open the editor by opening the .uproject file.
- Once inside the editor, you’ll want to activate source control (so you can do some SVN commands through the editor rather than always going to Windows Explorer and doing it via TortoiseSVN). Click on the little symbol at the top-right of the editor, just next to the Commands text field, and then enter all necessary details and credentials for the SVN server (make sure to select SVN and NOT Perforce):
- The editor will now be connected with the CloudForge SVN server, so you will be able to do tasks such as Checking Out and Checking In assets. Checking Out allows you to make changes to an asset, but it is “locked” for other developers so they cannot make any changes to that individual asset until you have done a Check In of that asset (UE4 prompts you to Check In any files that you have Checked Out when you attempt to close the editor).
- However, there appears to be a problem with the editor (as of writing, version 4.2.1, BUT THIS HAS BEEN FIXED IN LATER ENGINE VERSIONS SUCH AS VERSION 4.5) as it does not allow to you Check Out a file for editing through the editor (Check In works fine, though). However, there is a workaround:
- Locate the file you want to “Check Out” through the UE4 editor, for this example we’ll use the “MyGame” blueprint (see images below). Right-click and Refresh it to make sure it is available for Check-out (meaning no other user has currently Checked-Out the file). You’ll notice once the Refresh is done, that Right-clicking the asset will also bring up the “Checkout” command. Go ahead and click “Checkout” (but you will see that it does not work).
- Then locate the same file via the Windows Explorer. Right-click it>>TortoiseSVN>>Get Lock…
- Enter a reason for why you are locking, and click OK. See the image sequence below for a better view:
- Now go back to the editor and refresh the asset (refresh can take a while). You’ll notice a red tick next to the asset:
- Now that we have Checked Out this file, we can make changes to it. I will open up the Blueprints graph and add a simple little event that does nothing:
- I am now done editing this file and would like to “push” this version back to the server so other team members can use it and Check Out themselves if they need to. To do this all you need to do is save this file and then right-click it>>Check In…
- You will be prompted to give a change description. Do so, then click OK. UE4 will then upload those changes to the server.
- That’s it! Those changes are now live on the CloudForge server:
- So you may be thinking, this is great and all, but how do the other users get this new “revision” with my updated files onto their local machine. They don’t have to create a new folder and do the “Checkout” procedure from the beginning of this section again, do they?
- You’ll be happy to know that you only need to do that “Checkout” procedure from the beginning of this section only once. It needs to be done once as it creates a something called “working copy” into that folder, so now that folder has a hidden .svn file containing all the necessary server information. Anyway, I’ll cut with the boring stuff and show you how to update your local copy with the most up to date version on the server (it’s very simple):
- That’s it! You now have the latest version of the project from the server.
I hope this guide has been helpful in getting you started with source control in Unreal Engine 4. One notable area this guide is lacking in is the general procedure to follow when dealing with “code assets.” There may be some SVN tools that integrate with Visual Studio 2013, but that area is out of the scope of this blog post, which was to give a general introduction on getting started with SVN Source Control in Unreal Engine 4.
If there are any issues with this guide, please comment below or get in touch with me via the Contact form on this website, and I will try and get back to you ASAP.