Introduction to Perforce

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.

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.

Source Directory

My main working directory (code/art/models) is located at:

Target Directory

My Perforce depot is located at:

Environment Variables

If you ever need to change some features of your Perforce setup such as Port, Root, Client etc. There are two methods:

1. Through CMD via P4 SET
   You can check what your current environment settings are for Perforce in the command line. Run CMD and type:
   

   p4 set

   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

2. You can also check these values and edit them through Regedit. Launch Regedit and locate the Perforce environment. It should be here:

   HKEY_CURRENT_USER\Software\Perforce\Environment

   Right clicking on any of these values lets you modify them.

   

• Show in Explorer:

  To locate a file inside windows through Perforce select the file or folder Right Click -> Show In -> Windows Explorer or use the shortcut CTRL-SHIFT-S.

• Add a new File:

  The same procedure as before except let us add a specific file that we can used as a config for our game.exe. This is typically a text document. Create the file through Explorer in the SampleGame\target directory. I’ve called mine settings.cfg. Back in Perforce locate the file you created (Hit F5 to refresh), Note that the file does not have a green mark next to it so it is not currently versioned. Let us fix that, Right Click on the file and Mark for Add. Add it to a changelist with an appropriate description and submit.

• Check-in/Checkout:

  Files added to Perforce are initially read-only to prevent users from accidentally changing or breaking something. If you want to modify something you must first check it out. Let us add some text to the changelog. You can click and drag it to the default pending changelist or you can right click and select check out. Notice that the file now has a small red check next to it.
  
  
  
  This highlights that it is no longer read-only and is ready for editing. Open the file in a text editor and add some text.
  
  
  
  Save the file. You can now submit the file through Perforce. Notice that the file now says #2/2 this is the count of revisions the file has and which one you currently have. You can check out older versions of the file if you wanted to work with that instead.

• Diff:

  This function lets you check the difference between revisions of files or completely other files. If you are familiar with Beyond Compare it works much the same way. Let us test it. I made an intentional mistake in the change log. The date claims to be 2005, It should have been 2015. Check the file out again and make the fix. Check the file back into the depot and now let us Diff it. To make this a little easier to see, under View -> select History and then select the change log file in the tree.
  
  
  
  You can see that we have 3 revisions of the file. The easiest way to diff a file is to drag one revision on top of another. Try it and examine the results by dragging version 3 on top of version 2.
  
  
  
  The line where the spelling mistake is the difference between both files. You can already see from this simple example how useful this can be when comparing revisions of code to see where a function was added or removed and when. Herein lays one of Perforce’s greatest strengths. The Diff feature will work with image files as well.
  
  

• Delete a file from the server:

  Right Click -> Mark for Delete. Perforce will ask you to add it to a pending changelist. You can create one for this. Below I am deleting a file my project will not be using. Notice that it adds a red X next to the file to denote that it is to be deleted.
  
  
  
  

• Reverting:

  Another great feature of Perforce is reverting, let us take the change log for instance and check the file out. Open the file and write something in it, you realize you have made a mistake and rather than wasting your time, deleting the text within the file you would rather have a fresh instance of the file. Simply right click on the file in question and select Revert. This will remove the file from the changelist. You can Check the file out again and start fresh.
  
  

• Rollback/Backout:

  This is one of the main features of any versioning system. You want to retrieve a previous version of a file you had or recover a file you deleted. To Backout of a changelist simply returns the files selected to the previous revision and adds it to a pending changelist so that you can add a comment as to why you backed out. Rollback is a similar function but rather than being restricted to a changelist it grants you the ability to rollback as far as you like and with as many files as you like. Read more here.
  
  

• Reconcile Offline Work:

  Let’s say you are working hard, forgetting to add new files to Perforce and create a bunch of files while you are coding and they are located in different locations. To save you having to add each one individually in Perforce you can right click on the root directory and select Reconcile Offline work, this will add the files to a new pending changelist for you to review and ultimately add to the depot.

P4VS

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.

P4D on Ubuntu 12.04:

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:

• You do indeed have a server
• Ubuntu 12.04 is the headless operating system we will be working from (should work any recent Debian)
• You are comfortable inside a headless server installation
• You have Putty (or equivalent installed) or direct access to the terminal

Open Putty and login to your server



In case you are not already (or don’t have the privileges) make yourself root with:

sudo -i

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.

uname -i

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.

cd /usr/local/bin/

Back on your client machine in your browser navigate to…

http://www.perforce.com/downloads/helix

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…

wget

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.

• -d starts Perforce as a daemon
• -p sets the port
• -r sets the root location you want to save your files to

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.