Skip to content

Project layout

What lives where, and which parts are tracked in Perforce vs generated by the engine (kept out via .p4ignore).

Top-level folders

Folder Tracked Purpose
Source/ yes C++ code. The only folder where engineers write code by default.
Content/ yes Blueprints, data assets, levels, materials, particles, audio, fonts. Authored in the editor.
Config/ yes .ini settings: input bindings, collision channels, default game settings, editor preferences.
Rephrased Wiki/ yes This wiki, the TDD, the dev log.
tools/rephrased-mcp/ yes Team MCP toolkit (tasks, wiki, review). Agents call it; engineers do not need the tool names.
Plugins/ sometimes Project-local plugins. Unreal MCP ships with the engine, not this folder.
Binaries/ no Compiled DLLs. Built locally; ignored.
Intermediate/ no Build artifacts, generated .gen.cpp files for the reflection system. Safe to delete; will be rebuilt.
Saved/ no Logs, autosaves, shader cache, screenshots. Per-machine.
DerivedDataCache/ no Cooked asset cache. Per-machine.

If something is in Intermediate/, Saved/, Binaries/, or DerivedDataCache/, do not check it in.

C++ module

The project ships one runtime module, Rephrased, and one editor module, RephrasedEditor (Source/RephrasedEditor/), which holds Details-panel customizations and editor tools for rune content.

Source/Rephrased/Rephrased.Build.cs declares its dependencies:

  • Public: Core, CoreUObject, Engine, InputCore, UMG, Niagara, EnhancedInput, GameplayTags
  • Private: Slate, SlateCore, RenderCore, RHI, ImageCore, ApplicationCore

If you need a new engine module (e.g. AIModule for navigation), add it to PublicDependencyModuleNames and rebuild.

The two .Target.cs files (Rephrased.Target.cs, RephrasedEditor.Target.cs) define the game and editor build targets. Don't touch them unless you know why.

Source/Rephrased subfolders

Source/Rephrased/
  RephraseCharacter.*            player movement, interaction, native RuneCoordinator
  RuneDataAsset.*                word definitions and noun rules
  Save/                          checkpoint save subsystem, save game, save id component
  RuneSystem/
    Activation/                  WorldRune, RuneCoordinator, RuneTransaction
    Core/                        shared rune enums and structs
    Drawing/                     drawing graph, state, widget, presentation, unlock actor
    Effects/                     RuneableObject, noun rules, status tags, puzzle actor
    Behaviors/                   puzzle performance behaviors
    Puzzles/                     mural puzzle controller, light blocker volume
    Tests/                       rune automation coverage (PROT-001, CORE-009, SAVE-001)

Files at the top level are project-wide actors (RephraseCharacter, PedestalActor, AudioManager, etc.). Anything under RuneSystem/ is part of the rune subsystem and is grouped by responsibility.

Content folder conventions

Shipped layout (reorganization merged 2026-09-05, PR #19). Source of truth: Content organization.

Current depot note, refreshed after art reorganization CL 114583:

  • Content/Rephrased/ is the shared project-owned content root.
  • Content/Developers/ is a root-level scratch tree with discipline folders: Art/, Audio/, Design/, Engineer/, Owner/, QA/, UIUX/, Usability/.
  • Content/Imports/ is for vendor/template packs and should be treated as read-only source material.
  • Content/Rephrased/Art/ currently contains Archive-Prepro/, Audio/, BP/, Characters/, Decal/, Environments/, Fonts/, MaterialFunction/, Materials/, Mesh/, Props/, Shaders/, Texture/, and VFX/.

  • Content/Rephrased/Audio/Archive-Prepro/ exists for legacy/pre-production audio reference from CL 114583; new reusable audio should still follow lead direction before promotion.

  • Content/Rephrased/Art/ — art library by type: Characters/ (main character + Animation/newAbp), Audio/, Fonts/, Materials/, Shaders/, VFX/, Environments/, Props/, Archive-Prepro/.

  • Content/Rephrased/Gameplay/ — gameplay assets by system: Core/ for player/game framework, Runes/Nouns/ and Runes/Verbs/ for word data, Runes/WorldRunes/ for world runes, Runes/Drawing/ for the drawing graph, and PuzzleDevices/ for puzzle devices.
  • Content/2ndPlayable/LV_2ndPlayable — current playable map.
  • Content/Rephrased/Input/ — default and rune-drawing mapping contexts plus IA_* actions.
  • Content/Rephrased/UI/ — drawing and gameplay widgets.
  • Content/Rephrased/Levels/Prepro/ — archived pre-production maps.
  • Content/Rephrased/Levels/Archives/ — old demo and playable builds.
  • Content/Rephrased/_Archives/ — prototyping-only assets.
  • Content/Imports/ — vendor/template packs only (Underworld, Stylish Fire VFX, Variant_Platforming, UnrealTemplate, Fab, Mannequins, Kenney_Keyboard_UI, Zacksly_PS5_Controls).
  • Content/Developers/<Discipline>/<Name>/ — personal playground maps and scratch experiments (Art, Audio, Design, Engineer, Owner, QA, UIUX, Usability).

Move .uasset and .umap files through Unreal Editor or Unreal MCP, then fix redirectors and verify references. Do not move content folders in Explorer.

.uproject

Rephrased.uproject declares the engine version (5.8), enabled plugins, and module list. Plugins currently enabled:

  • ModelingToolsEditorMode — editor only, used for blockout
  • GameplayStateTree — reserved for future NPC scripting; not used yet
  • Aura — disabled
  • ModelContextProtocol + EditorToolset + AllToolsets — suggested Unreal MCP in the 5.8 editor (see Unreal MCP)
  • GameInput + GameInputWindows — Windows gamepad input (Win64 only); RawInput and XInputDevice — disabled
  • NiagaraFluids — Niagara fluid simulation

If you enable a new plugin via the editor, the change lands in the .uproject — review the diff before submitting.

Where new code goes

  • New puzzle performance behavior → Source/Rephrased/RuneSystem/Behaviors/
  • New rune-responsive puzzle actor → Source/Rephrased/RuneSystem/Effects/ when it belongs to the rune system
  • New activation or transaction behavior → Source/Rephrased/RuneSystem/Activation/
  • New drawing behavior → Source/Rephrased/RuneSystem/Drawing/
  • New rune automation → Source/Rephrased/RuneSystem/Tests/PROT-001/

If your file doesn't fit anywhere, ask before introducing a new folder.

Change history

  • 2026-10-02 — Gabriel Li — Listed the RephrasedEditor module, the full Build.cs dependencies, the Save/, Core/, and Puzzles/ source folders, the current Art and Imports folders, and the input and Niagara plugins (CORE-011).
  • 2026-09-29 — Gabriel Li — Updated rune source and content folders (CORE-009).

  • 2026-09-07 - Gabriel Li - Matched the Content folder summary to the current depot after art reorganization CL 114583.

  • 2026-09-05 - Gabriel Li - Source-control wording flipped to Perforce (tracked-in-Perforce, ignored via .p4ignore, review diff before submit); git is legacy. Supersedes the 2026-05-23 GitHub note below.

  • 2026-09-05 - Gabriel Li - Replaced pre-reorg content rules with the shipped hybrid layout (PR #19) and Developers// scratch convention.

  • 2026-08-27 - Gabriel Li - Added content organization plan link and current Rephrased/Imports/Developers folder policy.

  • 2026-08-14 — Gabriel Li — Unreal MCP plugins listed as suggested.

  • 2026-08-13 — Gabriel Li — Listed tools/rephrased-mcp and Unreal MCP plugins; engine pin remains 5.8.
  • 2026-08-12 — Gabriel Li — .uproject engine pin is 5.8.
  • 2026-05-23 — Gabriel Li — Moved under Rephrased project track; source control wording updated to GitHub (not Perforce).