DocumentationSubstance 3D

Version control

Last update: Thu Feb 26 2026 00:00:00 GMT+0000 (Coordinated Universal Time)
IMPORTANT
Substance 3D Designer version 14.0.0 upgrades the Perforce support to Python 3.
Make sure your other scripts and version control environment are adjusted accordingly.

Designer offers a Python integration of the Perforce (P4) version control system.

The integration adds a custom ‘Version Control’ submenu to the contextual menu of packages in the Explorer, as well as custom icons to match the status of a package in P4.

Preparing P4

In P4V, make a note of the workspace name and path, as shown below:

P4V workspace information {modal="regular"}

In any text editor or IDE, open this script located in Designer’s installation: ‘tools/version_control/perforce.py’.

On line 19, edit the path to the location of the 'p4' executable on your system.
In the example below, this path is ‘c:/Program Files/Perforce/p4.exe’.


## Editable variables

cPerforceP4AbsPath = os.path.abspath("c:/Program Files/Perforce/p4.exe")

cVerbose = False

Setup in Designer

Version control is configured in the Project settings, which are available in Designer’s Preferences.

'Version control' tab in project settings {modal="regular"}

  1. Go to ‘Edit > Preferences’

  2. Go to ‘Projects’, select the target project file and go to the ‘Version Control’ tab

  3. Check ‘Version Control Enabled’

  4. Fill this information in the ‘Workspace’ section:

    • Name: Enter the ‘Workspace Name’ you previously retrieved from P4V
    • Path: enter the ‘Workspace Path’ you previously retrieved from P4V

P4 setup in Designer: workspace {modal="regular"}

Setting up actions

The actions will be available in the contextual menu of a package in the Explorer. There are predefined actions that match most Version Control tool concepts:

  • All action labels can be changed as needed.
  • All actions need a script in order to be valid.

You may use:

  • one script per action
  • one script for all actions

A starter script for all actions is available in Designer’s installation: ‘tools/version_control/perforce.py’.

IMPORTANT
To be available, the package needs to be saved under the ‘Workspace path’ (E.g., under ‘f:/Dev/perforce’)
  1. In the Actions group, click on the ‘…’ button of the Add action
  2. Select the following script in Designer’s installation: ‘tools/version_control/perforce.py’
  3. The script should automatically be set up for all other actions.

P4 setup in Designer: actions {modal="regular"}

Setting up custom actions

As all version control tools are different and include many features, we allow the user to add custom actions.

  1. Click ‘Add item’
  2. Fill in the label of the new action, and set its script path

Setting up the script interpreter

  1. In the ‘Interpreters’ section, click ‘Add item’
  2. Set a script file extension or suffix, and the path to the interpreter executable
  3. Edit the perforce.py script to update the location of the ‘p4’ binary

P4 setup in Designer: interpreter {modal="regular"}

How to use version control

  1. Create a new package

  2. Save the package under the ‘Workspace path’ directory

  3. Click RMB on the package: you now have access to the ‘Version control’ submenu

  4. Several actions are available, depending on the status of the package file in the workspace:

    • Add: Mark the files as ‘ToAdd’
    • Submit: Submit the selected packages. This action displays a dialog for specifying a change message (see below)
    • Revert: Revert the modifications. This action displays a dialog for selecting the files to revert (see below)
    • Checkout: Check the file out from the depot
    • Get last version: Retrieve the latest version from the depot
    • Refresh status: Refresh the package file status
    table 0-row-2 0-border-0px 1-border-0px 2-border-0px html-authored no-header
    'Submit' dialog {modal="regular"} 'Revert' dialog {modal="regular"}
NOTE
All actions support multi-selection
For P4 and other version control tools that use read-only file permission to restrict modifications, the user will first have to check out the package before modifying it.
Read-only package files can’t be modified in SD.

The package will have the following icons, depending on its status:

Package icon: Up to date

Up to date

Package icon: Checked out

Checked out

Package icon: Added

Marked for add

Package icon: Not in depot

Not in depot

Note that an package which is not up to date is marked with a warning sign.

Action scripts

The command executed by each action is built thusly:

my_script WorkspaceName WorkspacePath ActionName[ActionArgs]

WorkspaceName: the name of the workspace

WorkspacePath: the path of the root directory of the workspace

ActionName: the name of the action:

  • add: for the “Add” action
  • checkout: for the “Checkout” action
  • submit: for the “Submit” action
  • revert: for the “Revert” action
  • get_last_version: for the “Get Last Version” action
  • get_status: for the “Get Status” action

The label is set up in the project settings, with ’ ’ character replaced by ‘_’ — E.g.: “My Action” => “My_Action”.

ActionArgs: arguments of the action:

  • -desc: A description string used by ‘Submit’ action
  • -files: A list of files
  • -files_list: A text file that contains a list of files per line

get_status: Returns a value depending of the status of the specified file:

  • 0: Undefined status

  • 1: not in the depot

  • 2: previous version (not up to date)

  • 3: latest version (up to date)

  • 4: checked out

  • 5: marked for addition

  • other actions:

    • 0: success
    • other: error
recommendation-more-help
dd48abc6-e399-43d2-9777-578ec70c5a23