P4Connect - Perforce Integration for Unity

P4Connect is now FREE!

We’re very happy to let you know that P4Connect has been acquired by Perforce Software.
P4Connect is now Open Source and free of charge for everyone who wants it.

The latest build of P4Connect is available from the Unity Asset Store, as well as from the Perforce website and FTP site.

The source for P4Connect is available on the Perforce Workshop Perforce Workshop Our intent is to create a thriving Open Source community of developers and users who thrive on creating a game development ecosystem centered on Unity and Perforce. Join us!

Thanks, and enjoy!

Let Unity take care of your Version Control with P4Connect!

P4Connect is the simplest Perforce integration tool for Unity yet. It will:

  • Allow you to perform all basic version control operations directly from inside Unity.
  • Show you the list of pending changes.
  • Let you enter submission notes and diff your files against the Depot.
  • Automatically check out / move / add / delete files when you make changes in the project view.
  • Handle project settings and Solution files.

P4Connect does NOT require a Pro or Team License. It works with any version of Unity (Release 4.5 and above).

Additionally, P4Connect supports:

Issues? Feature Requests? Let me know right here.


Quick Start

  1. Import the package from the Asset Store
  2. Go to Edit->Perforce Settings
  3. Follow the prompts


Start by importing the P4Connect Package from the Asset Store.
import package

If your project does not have Visible Meta files enabled, you will need to set this correctly.
To fix it, turn Meta files on (or "Visible Meta Files" in Unity 5) in Edit->Project Settings->Editor

Open the Perforce Settings dialog window from Edit->Perforce Settings.
Open Perforce Settings
In the Settings Window you may need to click "Enable" to enable Perforce before you enter your server settings. When your settings have been entered, just hit "connect". The Settings Window will then attempt to connect to the perforce server.
If any connection setting is invalid, the connection dialog will point out the settings which are questionable.
Server Invalid
Go ahead and enter the address of your server. Mine is on my localhost. The port is the standard Perforce port of 1666.

Load Settings

To assist with configuring p4connect there are a number of buttons in the "load settings" group. These buttons are enabled only while p4connect is being configured:
  • Load Defaults - Fill Connection Settings with the "Factory Defaults"
  • Load P4 Environment - Look for Perforce Environment variables and use them to populate the form
  • Load P4Config - use P4CONFIG environment variable to search for P4CONFIG file which contains connection settings
  • Load Editor Prefs - use the UNITY EditorPrefs library to fill out all settings
  • Load Config Asset - Look for a Configuration Asset, and if it exists, use it to fill out all settings

Using P4V to Test Settings

Since workspace names are often cryptic, I find the best way to set up a new configuration is to first connect using P4V, and then copy the Workspace name and other settings from the P4V Open Connection Dialog:

There are a couple of additional connection settings available for customization:
  1. The P4HOST field is normally left empty unless you are connecting to an Assembla depot, where a specific HOST value is required.
  2. The P4CHARSET field is normally left empty unless you are using a perforce server configured to use Unicode, in which case this character set will be used as your default.

Once all settings have been entered in the 'Connection' panel, just hit the "connect" button and P4Connect should test the settings and report that the Perforce Integration is ACTIVE.
Settings Valid
At this point, you are ready to go roll! We’ll look at the rest of the settings later.

Saving Settings

If this is the first time you connected to a server, or if you changed some important settings, you may wish to save your settings using the "Save Settings" button on the bottom right of the status pane. The default is to save your settings as Editor Preferences, but this can be changed with a option on the options page. There are two options for saving your settings:
  • Editor Preferences - This saves your settings in the Registry using Unity Editor Preferences
  • Config Asset - This saves your settings in an asset stored in "Assets/P4Connect/Editor/Config.asset"

Performing Source Control Operations

Let’s see if you can add files to the Depot. Open the Pending Changes Window from Window->Perforce Pending Changes. If you started a new project, it is most likely going to be empty.
Nothing in the pending changes
To add an existing file to the depot, simply right click on it and go to Perforce->Add to Depot
Add main scene
P4Connect will print a message to the console indicating that it has added the file, and the Pending Changes Window, as well as the Project View, should update to reflect the pending addition.
main scene added
Most of the time though P4Connect will perform Version Control operations automatically for you. Try and add a folder for instance. You will notice that P4Connect marked the folder for Add in Perforce without you doing anything.
Added Scripts Folder
Similarly, when you edit an asset, delete or move it, P4Connect will mirror those changes to the Perforce depot. When you are ready to commit your changes to the depot, you can use the Pending Changes Window to do just that. Simply select the files you want to submit, enter a description and click “Submit Selected” Submit initial changes
P4Connect will ask you to confirm and then commit your changes to the server.
Confirm submit changes
After you have submitted the changes, you see the Pending Changes Window and the Project View update to reflect the fact the files are now in the depot (green dot).
Has latest changes
After that, if you want to update your workspace, you simply need to right click on Assets and Select Perforce->Get Latest Revision
Update All Assets

P4Connect Options

P4Connect allows you to customize its behavior using the Options Pane of the P4 settings window:


Display Status Icons
This option enables the P4Connect Icons in the Project View.

Gray out invalid menu options
If checked, P4Connect will first look at the current state of the file and gray out any options that do not apply to the file, such as checking out a file that isn't on the depot, or reverting a file that isn't modified. This is useful when working with on file at a time, but it can make the menu unresponsive when you have too many files selected. For that reason, P4Connect will skip checking for valid options if you have too many files selected (as specified in the associated edit field).

Diff Tool Executable
P4Connect allows you quickly launch a diff view between your file and the file as it was when you last synced it. Click on browse to select a external diff tool (for instance P4Merge, WinMerge, or Araxis Merge).

Ask Before Check out on Edit
By default, P4Connect will automatically check out files that you edit (by double-clicking on a source file or modifying an asset for instance). If you do not want this behaviour, simply check this box. P4Connect will then ask you before checking out any file.

Reserved Character Warning

This option tells P4Connect to pop up a confirmation dialog whenever a file with "special characters" (@#*%)is being submitted.

Include Solution Files / Include Project Files

By default P4Connect will check out project and solution files from the Perforce depot. If you did not add them to source control (Unity usually recreates these for you), then you can disable those options.
If you do have project and solution files under Perforce, you need to make sure that they have all been added to the server before enabling this option.

Integrate with UnityVS

If you use UnityVS - (Unity Tools for Visual Studio) to integrate Unity with Visual Studio, you can make sure that P4Connect checks out the UnityVS project files as needed.
Please make sure that all your UnityVS project files have already been added to Perforce before enabling this option.

Close Perforce Connection after X seconds

P4Connect usually keeps connected to the Perforce server for a while after each operation, so that if it needs to perform subsequent operations, it doesn't waste time login in again. This allows to modify how long P4Connect keeps its connection up.

P4Connect Diagnostics

P4Connect allows you to configure diagnostics which allow you to see and capture additional behavior about its actions, using the Diagnostics Pane of the P4 settings window:


Display P4 Timings
Sometimes, Perforce connections are really slow (for instance when you are connected over the internet). This options can help you track down how much time P4Connect is spending talking to the server. It doesn't do anything other than display timing info.

Show File Paths in Console
By default, P4Connect only shows you the file name of files it performs operations on. If you would like to see the full path just check this option.

Enable Logging

P4Connect has its own log, independent from the Unity Log. If you select this option the P4Connect log will be created in the file you specify. Use the "Browse" button to assist in setting the log file location.

Console Log Reporting Level

This option is only available if P4Connect logging has been enabled. It determines how much of the P4Connect log should be sent to the Unity Console Window. choosing "Debug" will send the most log output to the console. Setting it to "Fatal" will limit reports to just show-stopping FATAL errors

P4Connect Utilities

Some administrative tools are available, these tools can be dangerous, and should only be used by those who understand their purpose.

Delete Configuration Asset

This button will look for an asset called Assets/P4Connect/Editor/Config.asset and if it exists, delete it.

Clear Editor Prefs

This button will remove all Editor Preferences from your machine, This will erase any existing configuration settings stored in the Editor Preferences
WARNING! this will also reset Unity's remembered project locations.

Pending Changes Explained

The pending changes window lets you inspect and eventually submit your files to the Perforce depot.
It features a list-view of all your modified files. You can sort the files by:

  • Checked status: Want to make sure which files you are going to submit? Use this!
  • Type: click on the header above the file icons and the list will be sorted by file extension
  • Filename and Directory
  • Change: Allows to quickly see which files you are adding, moving or deleting

The list supports multi-selection and keyboard shortcuts:

  • ‘A’ will select all the items
  • ‘I’ will invert the current selection
  • ‘Enter’ will check/uncheck the currently selected items
  • ‘Up’ and ‘Down’ will move the current highlight, use Ctrl or Shift to add or remove to your selection
  • ‘D’ will launch a Diff-against-HAVE-revision on the selection

Icons Legend

The icons in the Pending Changes Window and Project view use the following legend (identical to P4V)

Thank you for Using P4Connect!

Additional Resources