Skip to content

Perforce workflow (week one)

How Team Rephrased gets latest, checks out, reviews, and submits on the Perforce depot (GL_Main_PC). Use this page before your first submit.

Perforce is how we work now. Git/GitHub is legacy reference only — do not branch, commit, or open pull requests for day-to-day work. The old git repo and its hooks/PR template are frozen; ignore them.

Why Perforce (not git branches)

Unreal assets (.uasset, .umap) are binary — they cannot be merged. So we do not branch per task. The whole team works one mainline and relies on exclusive checkout (file locking): when you check out a binary asset, Perforce locks it so nobody else can edit it at the same time. The unit of work is a changelist, not a branch; review happens on a shelved changelist, not a pull request.

One-time editor setup

Before your first checkout, connect the editor to Perforce once (the editor does not check files out until it is connected):

  1. In Unreal, open the Source Control button (bottom-right) and choose Connect to Source Control.
  2. Provider: Perforce. It usually picks up your server, user, and workspace from p4 set; fill them in if not.
  3. Save something in the editor. Unreal asks "check out?" when you modify an asset - that prompt is the checkout, and it takes the exclusive lock.

P4V fallback: you can also check files out manually in P4V before editing. Unreal marks unchecked-out files read-only until you do.

Daily rhythm

  1. Get latest before you touch anything: MCP sync_latest (or P4V → Get Latest Revision, or p4 sync). Always sync before you check anything out — you cannot merge a stale binary asset.
  2. Start a task: MCP start_task syncs and opens a numbered pending changelist described <task_code> [Name] <description>. If your agent doesn't know the Accretion task code, the MCP asks you for it. Answer once: it's saved in the changelist description, so review and submit read it from there and don't ask again. The review server moves your Accretion work item to IN PROGRESS with the shared team token. Set that changelist as your current changelist in the UE editor / P4V so checkouts land in it.
  3. Work in Unreal, C++, Blueprints, or wiki Markdown. The editor checks out files as you edit them (binary assets get an exclusive lock; other people see them read-only until you submit).
  4. Self-review: MCP convention_check scans the C++ you have checked out against UE conventions.
  5. Compile + PIE the affected gameplay/level/docs path (PIE on LV_2ndPlayable, your personal playground, or your assigned level). This is always yours.
  6. Team review: MCP request_review sends your opened change (C++/config diffs + asset paths) to the team review server. Pass a changelist number with shelve: true to p4 shelve it so a reviewer (or Swarm) can pull the exact change — this is the pre-commit review that replaces the PR.
  7. devlog the session (MCP devlog).
  8. Submit after review passes: MCP submit (reverts unchanged files, then p4 submit), or submit the changelist from P4V / the editor.

Discord review threads

The Rephrased Review Bot opens a Discord thread in the team server's review channel for every reviewed shelf. The bold first line and thread title identify the changelist, risk, and verdict, and the thread pings Gabriel and the author. The linked Accretion work item keeps the shelf connected to production work. Requesting review moves that item to IN REVIEW.

  • LOW: LLM review passed; author may submit after normal self-check.
  • MED: LLM review passed; author may submit after PIE/build check. Gabriel may spot-check in editor.
  • HIGH: LLM review passed, but Gabriel playtest is required before submit.
  • Fail/error: do not submit; fix the issue and re-shelve.

Agent users get this automatically when their coding agent calls MCP request_review with shelve: true and task_code: "<Accretion code>". The MCP shelves the changelist, sends it to the review server, and returns the Discord thread link.

Manual users shelve from P4V, then request review in Discord:

  1. In P4V, right-click the pending changelist and choose Shelve....
  2. In the team Discord review channel, run /review changelist:<number> task_code:<Accretion code> (the Rephrased Review Bot handles it).
  3. Add optional notes: only for implementation or playtest context that is not already on the Accretion card.
  4. Use the created thread for fixes, playtest notes, and approval.

If Accretion is configured on the review server, the thread includes the item title, stage, URL, and whether the stage update succeeded. If Accretion is unavailable, the review still runs and the thread keeps the task code visible.

Approval does not submit anything automatically. The author owns the final submit from P4V, Unreal, or MCP submit.

Accretion stage changes are intentionally narrow:

  • MCP start_task task_code:<code> -> Accretion IN PROGRESS
  • MCP request_review task_code:<code> -> Accretion IN REVIEW
  • Discord /review changelist:<number> task_code:<code> -> Accretion IN REVIEW
  • Submit does not change the stage yet; the author still submits in Perforce.

Who moves the task. Every stage move runs on the review server with the shared team Accretion token — MCP users hold no task-board credential. The linked Accretion work item is resolved by its code field (e.g. TOOL-011), the same code written first in the changelist description.

Onboarding & credentials

Run /onboard once before your first task. It's idempotent and it records the two things your agent needs to drive the workflow for you:

  • Discord ID — so the review bot can @mention you (and Gabriel) in your review thread. Enable Discord → Settings → Advanced → Developer Mode, then right-click your name → Copy User ID.
  • Review key (engineers only) — your personal rephr_ key from Gabriel / your lead, so your agent can reach the review server.

/onboard also verifies your Perforce connection, the exclusive-lock typemap, and P4IGNORE, and registers your review-server key. If you already onboarded under the old git flow, re-run it — the review key is still valid (no re-issue), but the Perforce checks and the Discord ID recording are new. You hold no task-board credential: Accretion stage moves all happen on the review server with the shared team token.

Task naming (changelist description)

The old branch taxonomy now lives in the changelist description, so review and telemetry stay consistent. start_task builds it for you.

Pattern: <task_code> [Name] <description> — the Accretion task code first, your name in brackets, then a one-line description of the change.

Examples:

  • TOOL-011 [Jeffery Hu] two test Level Instance rooms in Lvl_Act3
  • CAM-002 [Jeffery Hu] Camera tutorial for designers
  • UI-003 [Jiacheng Sun] gameplay controls overlay

The task code must stay the first token — review and telemetry read it from there. The [Name] stamp is who did the work; it comes from your /onboard display name. Keep the description one line and specific: what changed, not why.

Exclusive checkout — the golden rules

  • Sync before you check out. A locked binary you edited against a stale revision is the #1 cause of lost work.
  • Keep checkouts short. Because binaries lock, holding a .umap checked out for days blocks the level for everyone. Check out, make the change, submit, release the lock.
  • Small, frequent changelists beat one giant submit — smaller lock windows, easier review, easier rollback.
  • If someone needs a file you have locked, submit or revert it — don't sit on the lock.
  • A checked-out World Partition map such as Lvl_Overworld.umap holds the level Blueprint and World Settings; placed actors are separate files and stay editable. See What the map file locks.

Submit checklist

Before you submit:

  • [ ] You synced latest and resolved anything the sync flagged.
  • [ ] Project compiles (Development Editor | Win64 for engineers).
  • [ ] You PIE-tested the change (or documented why not).
  • [ ] convention_check is clean and request_review passed.
  • [ ] Unchanged files are reverted (submit does this for you).
  • [ ] Wiki edits under Rephrased Wiki/ have a ## Change history entry.
  • [ ] A devlog exists if the session was substantial.

Submit-time enforcement (rejecting a bad submit automatically) is a server-side Perforce trigger on the USC Helix Core server and needs a Perforce admin — it cannot be self-installed from a workspace. Until that exists, submit discipline is manual + the review gate + a human reviewer.

Devlogs

Write a devlog when you finish a feature slice, fix a blocking bug, or change onboarding/docs teammates rely on.

Change history

  • 2026-10-07 - Gabriel Li - Golden rules link to what a checked-out World Partition map file locks.
  • 2026-09-27 - Gabriel Li - Task board migrated from ClickUp to Accretion: the changelist stamp now carries the Accretion work-item task code, and all stage moves (IN PROGRESS / IN REVIEW / SUBMITTED) run on the review server with the shared Accretion token — onboarding no longer collects a ClickUp token.
  • 2026-09-20 - Gabriel Li - Changelist naming simplified to <task_code> [Name] <description>: the category/area/task slug taxonomy is dropped; start_task now takes a free one-line description after the task code and the name stamp.
  • 2026-09-10 - Gabriel Li - The MCP now asks the engineer for the ClickUp task code when it's missing, and finds the changelist on its own (default-changelist work gets its own numbered changelist before review). Reviews no longer post as "CL unspecified" with no task code.
  • 2026-09-07 - Gabriel Li - Added the one-time editor setup step (connect Unreal to Perforce source control) so auto-checkout is documented; review threads are task-code-first and the Rephrased Review Bot runs in the team server review channel.
  • 2026-09-07 - Gabriel Li - Documented own-token ClickUp attribution (agent users move their own tasks via the token recorded at /onboard, server token as fallback), title-prefix task-code resolution, and the /onboard credential recording (Discord ID + ClickUp token). Corrected the status label to needs review to match the live board.
  • 2026-09-06 - Gabriel Li - Added ClickUp status automation: start_task moves task codes to in progress; MCP/Discord review moves them to need review while Perforce submit stays author-owned.
  • 2026-09-06 - Gabriel Li - Updated Discord review workflow for the live /review command and required ClickUp task code. Agent users pass task_code through MCP request_review; manual P4V users shelve then run /review changelist:<number> task_code:<ClickUp code>.
  • 2026-09-06 - Gabriel Li - Added Discord review-thread workflow: risk-labeled LOW/MED/HIGH threads, agent review automation, manual shelved-CL path, and author-owned submit rule.
  • 2026-09-05 — Gabriel Li — Rewritten from the git branch/PR workflow to the Perforce get-latest → task → check out → review → submit flow. Git is now legacy reference only. Changelists replace branches; shelve + review server replaces the pull request; exclusive checkout on binary assets is the safety model. MCP tools: sync_latest, start_task, convention_check, request_review, submit.