Consequence Client Perforce Workspace Setup

Consequence Client uses a Perforce workspace to exchange data between Consequence and your game project.

This workspace must allow Consequence Client to sync the files it reads and to submit the files it manages.

Recommended Setup

We recommend creating a dedicated Perforce user and workspace for Consequence Client rather than sharing a developer's normal workspace.

This helps keep automated Consequence operations separate from local developer changes and prevents background sync or submit operations from interfering with somebody's active work.

The workspace should be persistent. Do not use an ephemeral Docker filesystem for the workspace.

Perforce User

Create a Perforce user for Consequence Client with access to the relevant parts of your project.

The user requires read access to any directories Consequence Client needs to sync, and write/submit access to the files Consequence Client is expected to modify.

Depending on your configuration, these normally include:

  • the Consequence submission directory containing ConsequenceExport.json
  • the project's Gameplay Tag .ini files, including /Config/DefaultGameplayTags.ini and .ini files inside the /Config/Tags/ directory.
  • the configured audio directory
  • the configured TTS output directory, if TTS is enabled

If your project uses more restrictive Perforce protections, ensure that the Consequence Client user has sufficient permissions for each configured path.

Creating the Workspace

Create a normal Perforce workspace for the Consequence Client user.

For the simplest setup, map the relevant project or project Stream into the workspace rather than creating an unusually narrow workspace View.

Consequence Client does not sync all directories or files in your workspace - only the specific files it needs access to. In the case of audio files, it only syncs actual file data when specifically requested for live preview.

If you do use a restricted View, make sure every directory referenced by your Consequence Client configuration is mapped into the workspace.

For example, a non-Stream workspace might contain a mapping similar to:

Client: consequence-client-project
Owner: ConsequenceClientUser
Root: /Workspace

View:
    //depot/MyProject/... //consequence-client-project/MyProject/...

For a Streams-based Perforce project, configure the workspace for your normal project Stream instead.

Docker Workspace Root

When Consequence Client runs in Docker, the Perforce commands themselves execute inside the container.

For that reason, the workspace root seen by Perforce must correspond to the path available inside the container, not the host machine's path.

The recommended Docker mount is:

/[DOCKER_HOST_PERSISTENT_P4_WORKSPACE_LOCATION]:/Workspace

The host directory on the left can be wherever you want to persist the workspace.

Inside the container, however, the workspace is available at:

/Workspace

Your Perforce workspace and the local Consequence Client paths should therefore agree with that container-side layout.

For example:

P4CLIENT=consequence-client-project

CONSEQUENCE_CLIENT_SUBMISSION_DIRECTORY=/Workspace/MyProject/Consequence/
CONSEQUENCE_CLIENT_FACTS_TAG_DIRECTORY=/Workspace/MyProject/Config/
CONSEQUENCE_CLIENT_AUDIO_DIRECTORY=/Workspace/MyProject/Wwise/MyProject_WwiseProject/Originals/Voices/English(US)/

The matching _PERFORCE settings should point to the corresponding depot locations.

Perforce Connection Variables

If Perforce has not already been configured inside the environment running Consequence Client, configure:

P4USER=ConsequenceClientUser
P4PASSWD=[password or authentication value]
P4CLIENT=consequence-client-project
P4PORT=perforce-server:1666

When using Docker these will normally be provided as environment variables in your docker-compose.yml.

See Consequence Client Installation for the complete Consequence Client configuration.

Verifying the Workspace

Before starting Consequence Client, verify that Perforce can connect using the same user and workspace that the Client will use.

From the environment in which Consequence Client will run, verify:

p4 info

and:

p4 client -o

Then confirm that the Client can sync the project paths required by your configuration.

For example:

p4 sync //depot/MyProject/Consequence/...
p4 sync //depot/MyProject/Config/...

If TTS or audio synchronization is enabled, also confirm that the configured audio directories are mapped and can be synced.

Gameplay Tag Files

Consequence Client synchronizes Facts using your project's Gameplay Tag .ini files.

The configured tag files should already be managed by Perforce.

Consequence Client will refuse to overwrite an unexpected unversioned .ini file in the configured Gameplay Tag directories, and will also avoid submitting Fact changes if the local files are not at the latest Perforce revision. This protects against accidentally overwriting newer changes to your project's Gameplay Tags. Simply retry the submit operation if this occurs.

Starting Consequence Client

Once the workspace is configured:

  1. Configure the remaining Consequence Client environment variables.
  2. Start Consequence Client.
  3. Confirm that it successfully logs into your Consequence project and connects to Perforce.
  4. From Consequence, run a Sync Facts or Submit to Source Control operation.
  5. Confirm that Consequence Client can sync and submit the expected files.

Once these operations succeed, the workspace is ready for normal Consequence Client use.

Common Setup Problems

If Consequence Client cannot sync or submit, check the following:

  • P4CLIENT points to the intended workspace.
  • P4PORT, P4USER, and authentication details are correct.
  • The workspace View includes every depot directory configured in Consequence Client.
  • Docker paths use the container-side /Workspace/... path rather than the host filesystem path.
  • The workspace directory is mounted persistently into the container.
  • The Consequence Client user has appropriate Perforce permissions.
  • Gameplay Tag .ini files in the configured directories are versioned in Perforce.
  • Locally synced files are able to update to the latest depot revision.

See Consequence Client Installation for the remaining Consequence Client configuration.