This tutorial covers all the main features the Perforce Versioning system has to offer.
Windows, Perforce Server(P4D/P4S), Perforce Visual Client(P4V), [Optional: Visual Studio, Perforce Visual Studio Plugin(P4VS)]
Learn more about how to use Perforce to Version your Source Code and Assets
This tutorial is written in a generic manner so as that you can learn to use Perforce on any project you have regardless of Engine, API or SDK. I will only be covering what I think are the main features of Perforce and what is most useful for Game Developers.
This is only an introduction to setting up the Perforce version control system for managing your games code and assets. The idea behind versioning (source control) is to create a base revision of all your files and for each change you make keep a version for that too. This allows you to go back in time and check the differences against previous versions of the same files. This is very useful for tracking bugs and issues within code and assets. A system like this also serves as a backup in the case of system failure or human error and as a time machine to find where an issue was introduced.
Perforce is not the only free system you can use for this purpose with other popular programs such as GIT, Subversion (SVN) and Mercurial all performing the same basic functions each with its own pro’s and con’s. I have met plenty of people who swear by GIT or SVN and will probably try to convert you if you enter a conversation about which is best. At the end of the day you can use whichever you like so long as you use one because if you lose all your work or cannot revert to a previous working version of your code you have no-one to blame but yourself especially since they are all free and well documented.
The ideal setup for any versioning system would be to have the server on a dedicated machine with automated daily or weekly backups based on how often you make critical changes. You would then have a copy on your work machine where you would create and edit code/assets, once you have checked that your changes work you can commit them to the server. This way if your work machine crashes you have a backup of the code on your server, If the server crashes you have a backup saved somewhere hopefully on a separate drive if you are smart about it or you can use the most local version on your PC, The issue with using the copy on your work machine is that you lose all versioning history.
Since not everyone can afford premium server space or services to run Perforce this guide will walk you through a simple setup on a windows machine where both the server and client reside on Windows. The client code will reside on drive [C] where the Perforce depot will sit on drive [D]. This is the most basic setup that allows for a basic level of parity in the case of drive failure. To further the parity I highly recommend using Dropbox or Mega to sync and backup your files online or even GoodSync to back up to a separate local drive.
What you will need
You will need to download at least two tools from Perforce. P4D & P4V (P4VS is optional). The Perforce license lets you to use their software free if your team is small (less than 20 people) which should be more than enough for small indie mods/Games. You can find the Perforce tools here.
Setup your Perforce Environment
The first thing you will need to do is set up the environment for working with Perforce. I would highly suggest keeping your Perforce Depot/Repository on a separate drive to the one where you will be doing your coding.
Depending on your preference as a developer you might keep your source files separate from your finished game files or relatively close.
What do I mean by this? Source files in this case would be C++ code, Photoshop art, and model files such as obj, dae etc., uncompiled map files. These files are only for development and generally are not released to the public unless you are making it open source.
Finished game files would be dll’s, tga’s, wad’s, mdl’s etc. These files would be compressed, tested and packaged neatly and basically what your players will need to play the game.
In the case of this tutorial my source files will be close to the finished files for the sake of simplicity. However I will be versioning both.
My main working directory (code/art/models) is located at:
My Perforce depot is located at:
If you ever need to change some features of your Perforce setup such as Port, Root, Client etc. There are two methods:
P4 is the Perforce command line utility and was installed with the Perforce visual components. You should see something similar to the following:
Note: They might not all be present on your system, don not worry you may not need them but you can create them easily as shown below.
If you wanted to change one of these it is as simple as the following:
p4 set -s P4PASSWD=12345
p4 set P4ROOT=D:\Backup\Depot
You can also check these values and edit them through Regedit. Launch Regedit and locate the Perforce environment. It should be here:
Right clicking on any of these values lets you modify them.
The next tool we need to check out is P4Admin which should have installed with the Perforce visual components.
The Open Connection Dialog should appear.
In my case the user did not exist when I tried to open the connection.
So we just create a user.
Click on New and fill out the new user details.
You will be presented with the following message if you open the connection. Hit yes because you want to be the administrator on this server.
P4Admin lets you create and manage users, groups and set permissions to each. For our use case, it is not necessary. The last thing I would advise you to do would be to require a password for the depot. You can change the password security level through the administration menu entry.
P4V (GUI for Perforce) is where you typically would create the connection from your local working files and where you want to place them in the Perforce depot.
Firstly start up P4V. You should see this:
A Workspace is what Perforce names the link between your local files and the server files. You will do all your work on the workspace and then submit to the server. If someone else does some work on the server you can copy those files down to your workspace if you like.
The following diagram explains it a little better. Each user / client connects to the server and create a workspace to clone the files that reside on the server to their own machines for editing.
I have added these to demonstrate how to omit certain files and folders from being submitted to the server. You simply add a minus (-) symbol in front of the line you want Perforce to omit. In this case I want perforce to omit all files with the extension .unwantedFile as well as everything inside the folder called unwantedFolder.
-//depot/....unwantedFile //SampleGame/....unwantedFile -//depot/unwantedFolder/... //SampleGame/unwantedFolder/...
Let’s continue by clicking OK. If you are prompted with the following message select No as you want to version any files that may already exist there. In my case I already have some code and art prepared for demonstration.
If a wizard pops up simply cancel it, we will add the files manually now.
In Windows explorer back in my SampleGame folder I will now create some sample folders and files for demonstration. You can do the same yourself here with your own Project files.
Back in P4V it should look something like this now:
Lets make an initial commit of all our files so that we can populate the server with version 1 of our SampleGame
To do that we simply need to select the root directory and click Add.
Back in the main Perforce window the pending changelist tab should look similar to this.
Expand your newly created changelist. You will notice that there is now a small red plus icon next to each file that is currently pending addition to the server.
Note: You may have noticed from the screenshot above that the files we asked Perforce to omit, do not have the small red plus (+) and are not pending addition to the server.
You can now click on submit from the main menu. Perforce will present you with the submit dialog so you can overview what exactly you are submitting.
Perforce Visual Studio Plugin (Note: this will not work with Express versions of Visual Studio)
If you have Visual Studio installed you simply have to double click on the .VSIX to install the plugin.
The purpose of the plugin is to streamline the process of checking in and out files without having to open up the Perforce GUI. I would suggest getting familiar with the Perforce GUI and its terminology before jumping into the deep end with the plugin.
Start-up Visual Studio and open Tools -> Options.
Now if the plugin installed correctly you will see an option for P4VS under source control. Select this.
Further options will crop up under source control specifically for Perforce. The only one you need to worry about is connections. Make sure under connections “Show the Perforce Connection dialog” is selected.
Now under File Select -> Open Connection to a Perforce depot.
Enter the details you need to make a connection to Perforce:
Now you can open the project through File -> Open Solution/Project in Perforce Depot. Select your Visual Studio solution from its directory.
If your solution was checked into Perforce you will probably see something along the lines of this dialog asking you to checkout the readonly files for editing. It is similar to the P4V dialog. Be sure to check the file out if you want to edit it.
If you add a new file in Visual Studio, Perforce will also ask you if you want to add it for version control.
In the solution explorer you should see something similar for your own project.
A helpful toolbar comes packaged with the plugin. You can enable it through View -> Toolbars -> P4VS. This provides useful buttons that are much the same as what the Perforce GUI provides.
You can right click on code and check it out, you will notice that it will be added to a changelist inside the Perforce GUI.
There is a useful context menu for Perforce when you right click on files that either are versioned or can be versioned.
Perforce ideally should be setup on a completely different machine to the one you are developing for reasons that don’t really need explaining. This setup comes in very useful if you need to share your perforce depot with team members who are offsite and often in other countries to develop through.
I make some assumptions:
Open Putty and login to your server
In case you are not already (or don’t have the privileges) make yourself root with:
And enter your password… We will need to get the latest P4D for Linux, check what build of Linux you are using so as to download the correct one. Try this to figure that out.
If the command responds with i386 in the result you are on a 32bit machine
Else it should contain x86_64 for a 64bit OS
Lets change directory to where we will want to download and run Perforce.
Back on your client machine in your browser navigate to…
Look for P4D and download the right version for your setup.
Depending on the internet browser you are using you should be able to decipher the link from the downloads Tab, Once you find it copy it to the clipboard. In Chrome it is here:
Back in putty type…
and then either right click or use SHIFT-INSERT to paste the copied link
Now lets make the downloaded file executable.
chmod +x p4d
Its important that we create a directory where Perforce will save the server files and depot.
This will vary from machine to machine.
In my case I have a special location called storage so I will create a dev directory there.
Now lets start Perforce with some flags for a basic server setup.
p4d -d -p 1666 -r /storage/dev/
It would be a good idea to add p4d to the startup items for your server.
Now you should be able to connect to the server using the servers IP address and port 1666 through P4V on your client machines.
I hope you find this document useful when taking on Version Control for your own projects 🙂
The Support Thread for this tutorial can be found here.
If you find any issues or if you know of anything this tutorial should include please feel free to send an e-mail onto me concerning it.
Copyright © 2020 www.sourcemodding.com
All trademarks are property of their respective owners in the US and other countries.
Sourcemodding is in no way affiliated with the Valve Corporation. This is a non-profit community driven website using content from Valve and the Community.
All files are provided as is and are simply mirrors of files that can easily be found elsewhere online.
If you dispute anything on the website or want something removed please get in touch.