# V2 Perforce Integration Guide

This guide covers `TODOS.phase-72.72.20.1.5`: Perforce setup for studios that
prefer P4 as the primary asset workspace while V2 still keeps the Git LFS mirror
available for OSS-style branches and source-code collaboration.

## Source Of Truth

- Integration guide contract:
  [v2-perforce-integration-guide.json](../../ue/Build/AssetPipeline/v2-perforce-integration-guide.json)
- Migration boundary: [perforce-migration.md](../perforce-migration.md)
- Git binary attributes: [`.gitattributes`](../../../.gitattributes) and
  [V2/ue/.gitattributes](../../ue/.gitattributes)
- P4 ignore source: [V2/ue/.p4ignore](../../ue/.p4ignore)
- Binary asset attributes:
  [v2-binary-asset-attributes.json](../../ue/Build/AssetPipeline/v2-binary-asset-attributes.json)
- Asset locking workflow:
  [v2-asset-locking-workflow.json](../../ue/Build/AssetPipeline/v2-asset-locking-workflow.json)

The Perforce import path for the Unreal project is `//Oshun/V2/main/V2/ue/...`.
Git remains the canonical monorepo source until release engineering approves
full workspace cutover.

## P4 Workspace Setup

Each artist or build machine uses a dedicated client workspace. Required
environment values are:

```bash
p4 set P4PORT=ssl:p4.oshun.example:1666
p4 set P4USER=<studio-user>
p4 set P4CLIENT=<user-or-agent>-v2
p4 set P4IGNORE=.p4ignore
```

The client root should point to a local Unreal workspace such as
`/mnt/v2-p4/<P4CLIENT>`. The client view should include the Unreal subtree and
exclude unrelated monorepo packages:

```text
//Oshun/V2/main/V2/ue/... //my-v2-workspace/V2/ue/...
-//Oshun/V2/main/node_modules/... //my-v2-workspace/node_modules/...
-//Oshun/V2/main/.git/... //my-v2-workspace/.git/...
```

After the first sync, run:

```bash
p4 sync //Oshun/V2/main/V2/ue/...
p4 reconcile V2/ue/...
```

Do not edit binary assets outside a client workspace with `P4IGNORE=.p4ignore`
configured.

## Stream Depot Configuration

Create a stream depot rooted at `//Oshun/V2`. Required streams:

```bash
p4 stream -t mainline //Oshun/V2/main
p4 stream -t development -P //Oshun/V2/main //Oshun/V2/dev
p4 stream -t release -P //Oshun/V2/main //Oshun/V2/release
p4 stream -t task -P //Oshun/V2/dev //Oshun/V2/art
p4 stream -t task -P //Oshun/V2/dev //Oshun/V2/cinematics
```

`//Oshun/V2/main` is the only stream feeding release BuildGraph jobs.
`//Oshun/V2/dev` integrates from main daily and copies up after validation.
`//Oshun/V2/art` is for large asset drops and vendor ingest.
`//Oshun/V2/cinematics` is for Sequencer, audio, and mocap integration.

Initial import uses:

```bash
p4 populate //Oshun/V2/main/V2/ue/...
p4 reconcile
p4 submit -d "Initial V2 Unreal import"
```

## Typemap And Locking

Install the typemap before importing files. Unreal packages remain exclusive:

```text
binary+l //Oshun/V2/.../V2/ue/....uasset
binary+l //Oshun/V2/.../V2/ue/....umap
binary+l //Oshun/V2/.../V2/ue/....ubulk
binary+l //Oshun/V2/.../V2/ue/....uexp
binary+l //Oshun/V2/.../V2/ue/....utoc
binary+l //Oshun/V2/.../V2/ue/....ucas
```

Source media and generated binary review assets use writable binary storage:

```text
binary+w //Oshun/V2/.../V2/ue/....fbx
binary+w //Oshun/V2/.../V2/ue/....glb
binary+w //Oshun/V2/.../V2/ue/....wav
binary+w //Oshun/V2/.../V2/ue/....ogg
binary+w //Oshun/V2/.../V2/ue/....exr
binary+w //Oshun/V2/.../V2/ue/....hdr
binary+w //Oshun/V2/.../V2/ue/....usd
binary+w //Oshun/V2/.../V2/ue/....usdc
binary+w //Oshun/V2/.../V2/ue/....usdz
```

Artists must use `p4 lock` before editing exclusive packages and `p4 unlock`
after a submitted or reverted change. Git LFS users follow the matching
`v2_asset_locking_workflow.py` lock and unlock automation.

## P4 Git Connector Hybrid Workflow

Studios that keep Git source code and Perforce assets in parallel can use P4 Git
Connector:

```text
Git mirror: //Oshun/V2/git
P4 stream:  //Oshun/V2/main/V2/ue/...
Mode:       Git source mirrors into Perforce Unreal workspace until cutover
```

Connector rules:

- Git commits remain the source for code, configs, checks, and documentation.
- P4 streams own Unreal package and source-media asset review once imported.
- P4 Git Connector mirrors approved Git source changes into `//Oshun/V2/git` for
  artists who need one P4 workspace.
- Asset changes flow from Perforce back to Git only through reviewed export or
  release engineering import jobs, never through ad hoc user copies.
- Git LFS mirror history stays available for OSS-style branches, while Perforce
  owns day-to-day binary asset locking for studios that choose P4.

## Daily Sync Workflow

1. Sync the P4 workspace from the correct stream.
2. Reconcile local changes before opening Unreal.
3. Lock exclusive packages with `p4 lock`.
4. Edit assets in Unreal or source tools.
5. Run V2 validation and cook checks for the touched area.
6. Submit with `p4 submit` and include Git source commit references when a Git
   source change is paired with the asset update.
7. Unlock submitted or reverted files with `p4 unlock`.
8. If using P4 Git Connector, verify the connector mirror job completed before
   build farm jobs consume the workspace.

## Validation Commands

```bash
python3 V2/ue/Tools/check-v2-perforce-integration-guide.py
python3 V2/ue/Tools/check-v2-perforce-migration.py
python3 V2/ue/Tools/check-v2-asset-locking-workflow.py
python3 V2/ue/Tools/check-v2-binary-asset-attributes.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 -m json.tool V2/ue/Build/AssetPipeline/v2-perforce-integration-guide.json
python3 -m json.tool V2/ue/Build/Horde/v2-buildgraph-job.json
python3 V2/tools/validate-v2-docs.py
```