Technical Design Document¶

Engineering Lead: Gabriel Li Contact: gli83636@usc.edu Last Revised: 2026-05-06

Contents¶

Game Summary
Platform
Engine
Technical Features
Rune System Core
Rune Actors and Placement
Effect Components
Camera System
Memory Palace (WIP for Rework)
Player Character and Interaction
Puzzle Narrative Devices
Click-based Interaction (WIP)
Content Pipeline and Editor Tools
Audio
VFX
UI / Menus
Save / Load
Technical Development Plan
Technical Risks
Schedule

Game Summary¶

Rephrased is a 3D isometric linguistic puzzle adventure. The player plays Sol, a boy who wakes in a destroyed world with no memory. He finds ancient runes, and by arranging them into short sentences the world reshapes around him. Solve puzzles to progress, restore memories, and uncover what happened to the civilization.

Runes are part of the world, not part of the UI. Tech is judged by how invisible the system is and how readable the world's reaction is.

"Rewrite the world to remember it."

Pick up runes, drop them in slots, form short sentences (NOUN + VERB, or NOUN + VERB + NOUN).
Each valid sentence applies an effect to every object in the world that matches the subject noun. Rocks float. Trees become stone. Fire spreads.
Runes are not just text -- objects in the world can also resemble runes and be interacted with directly (stretch).
Memory palace acts as an in-world notebook for every rune discovered.
Minimal UI. The camera, environment, and rune feedback teach the language.

Design pillars to judge the tech against:

Runes are part of the world. Physical, not UI-first.
Learn by watching the world change. Feedback has to be immediate and readable.
As little screen UI as possible. Lean on camera framing and environmental cues.

Platform¶

Primary: Windows PC (single player, local only).
Input: Keyboard + Mouse and Xbox-style gamepad, routed through Enhanced Input.
Distribution: Steam release post-AGP.
Long-term target platforms: Steam Deck on release. No current plans for console or mobile.

Engine¶

Unreal Engine 5.8, C++ gameplay module with Blueprint content on top.
Installed with Windows target platform only (no Android/iOS/Mac payload).
Visual Studio Version: 2026 Community (stable channel, not Insiders). Pin MSVC v14.50 (not Latest / 14.51).
Workloads (select in installer):
Desktop development with C++.
Game development with C++.
Components: import repo-root .vsconfig, or verify MSVC v14.50 + ATL v14.50 and Windows 11 SDK 10.0.22621.0.
Coding agents (Cursor, Claude Code, Codex, Antigravity, or another MCP-capable IDE) use the Rephrased MCP toolkit plus suggested Unreal MCP in the editor. Engineers talk normally; they do not need to remember tool names. See Rephrased MCP and Unreal MCP.

Details: Project layout.

Technical Features¶

Rune System Core¶

The core gameplay system lives under Source/Rephrased_Demo/RuneSystem/, split across several files so pods can work in parallel without stepping on each other. Editor-facing reference doc: Rune authoring. What follows is the engineering summary.

URuneDataAsset -- the canonical noun/verb definition. Holds the word text, definition, rune mesh, noun mesh + materials, verb effect component class(es), split rules, and per-rune audio. All of the content side of the game is data assets.
USentenceValidator (GameInstanceSubsystem) -- grammar check on a slot array. Today accepts NOUN + VERB and NOUN + VERB + NOUN. New sentence formats are on the roadmap (see Development Plan).
URulePriorityManager (GameInstanceSubsystem) -- tracks the active sentence per (subject noun) and resolves conflicts between multiple calculators using a timestamp: most recently modified wins. Used when two puzzle calculators target the same noun.
Strategy pattern for effects:
UComponentVerbStrategy -- the general case. Spawns the verb's URuneEffectComponent on every matching runeable, adds it to URuneEffectHistory so it can be reverted when the sentence breaks.
UNounTransformStrategy -- the IS identity swap. No component, just rewrite the target's CurrentNounData, re-register with the object registry, swap mesh and materials atomically.
UEffectExecutor -- glue between a validated sentence, the runeable registry, and the strategy. Owns the 3-word object-noun argument passing so verbs like MoveToward, Hidden, and Penetration can target a second noun.
URuneEventBus (GameInstanceSubsystem) -- decoupled broadcast channel. Current consumers: fire-spread chain reactions. Designed so future meta events (explosions, water-flood, etc.) don't require components to know about each other.
URuneRedefinitionManager (GameInstanceSubsystem) -- meta-rules. Lets sentences like "BURN IS WET" redirect one rune's behavior through another. Resolver follows chains. Reserved for late-game puzzles -- not exposed to designers yet.
URuneableObjectRegistry (WorldSubsystem) -- reverse index from noun to runeable actors. Calculators query it when building targets. Registration is automatic at BeginPlay; re-registration is atomic when a noun is swapped by IS.

Details: Rune system core.

Rune Actors and Placement¶

ARune -- the physical rune. Visual mesh comes from RuneData->RuneVisualMesh. Floats with a bob curve. VFX on first pickup (Niagara).
ARuneSlot and subclasses:
ARuneSlot -- generic, any rune fits.
ATestSlot -- accepts one specific rune, for gated puzzle locks.
ACombineSlot -- stacks runes and auto-merges per UMergeRecipeDataAsset.
AMemoryPalaceSlot -- dedicated home slot in the palace hub.
ARuneCalculator -- owns a group of slots, runs the validator, drives the expanding ring, and executes effects. Supports two layouts:
Linear (2 or 3 slots in a row).
Grid (up to 10 x 10, scanned for simultaneous sentences across rows and columns; 3-word sentences take precedence over 2-word overlaps). EmptySlotPositions carves irregular shapes.
ARuneableObject -- the targetable world actor. Carries InitialNounData, a per-instance NounToMeshMap override, and runtime scale/direction modifiers that verbs mutate.
AExpandingRingActor -- the Niagara ring that propagates effects outward from the last rune. Doubles as the pacing device for showcase sequences.

Details: Rune actors and placement.

Effect Components¶

Each verb is a URuneEffectComponent subclass. The strategy adds/removes them, and the component owns the behavior. Current set, all in RuneSystem/Components/:

Motion: FloatUp, Rotate, MoveToward, Slow, Accelerate, Reverse, Stop.
Phasing: Penetration, Hidden, Passing.
Transform: Enlarge, Shrink, Mature, Regress.
Hazard: Fire (with FireSpawnPointComponent for multi-point authoring), Dangerous.
Listener: NounListener (lets a specific noun react to rule events without inheriting from ARuneableObject).

New verbs are authored by subclassing, overriding OnEffectApplied / OnEffectRemoved, and wiring a data asset in the content browser. Engineering overhead for a new verb is minimal.

Details: Effect components. Recipe: Adding a verb.

Camera System¶

Two use cases: gameplay framing (zone-driven) and cinematic spotlight (showcase).

URuneCameraSubsystem (WorldSubsystem) -- central coordinator. Owns a hidden interpolation camera that is the permanent view target. Every frame Tick blends it toward whichever zone or cinematic target is on top of the stack. Having a single persistent view target fixes the "snap back" we used to get when a player oscillated across a zone boundary while a blend was mid-flight.
ACameraZoneActor -- level-placed box trigger with a camera component. Per-zone: priority, tracking, clamp extent, position-based vs time-based blend. Overlapping zones form a priority stack and the top wins.
AEffectShowcaseCamera -- spawned on rune activation for cinematic emphasis. Two modes: PauseAtTarget (ring pauses at each target, camera holds, ring resumes) and LeadingSphere (camera leads ahead, groups close targets). Pushed onto a cinematic stack that supersedes zone logic.

Details: Camera system. Recipe: Adding a camera zone.

Memory Palace¶

Currently flagged WIP for rework.

AMemoryPalace -- hub actor. Auto-generates a ring (or rings) of palace slots on a circle. Knows how to repopulate slots from UPlayerRuneKnowledge when the player enters.
AMemoryOrb -- teleport trigger between the world and the palace. Fade-black transition, saves return transform.
UPlayerRuneKnowledge -- persistent discovery record. Every new rune the player touches is recorded.

Details: Memory palace.

Player Character and Interaction¶

ARephraseCharacter -- third-person ACharacter. Carries the camera boom, a trigger box in front of the pawn for interaction detection, and a URuneCarryComponent. Enhanced Input drives Move, Jump, Interact, Split, Reset, and a debug toggle.
URuneCarryComponent -- pick-up / carry / place pipeline.
Interaction detection: a box in front of the character scans for slots, loose runes, and IInteractableInterface actors. Closest is highlighted with a hover material; the carry component handles swap rules.

Details: Player and interaction.

Puzzle Narrative Devices¶

AClockDevice -- a large clock that drives a story gate. State machine: Dormant -> SecondHandActive -> FullyRunning. Transitions are triggered by rune components arriving on the clock (Rotate, then Passing), not by explicit slot inspection. After reaching FullyRunning it refines the core rune into a TIME rune on a timer.
AStarObservatory -- listens to a linked clock. When the clock activates, a vortex progress fills, and on completion spawns a PASSING rune at an authored point. Feeds back into the clock progression.

This pattern -- puzzle devices that subclass ARuneableObject and react to rune components arriving on them -- is how we plan to build most of the scripted puzzle beats.

Details: Puzzle narrative devices. Recipe: Adding a puzzle device.

Click-based Interaction¶

Click-based Interact Mode (toggle into a mouse-pointer mode, click runes in screen space, validate on exit). That is a planned pivot -- current code is physical walk-up-and-press. See Development Plan.

Content Pipeline and Editor Tools¶

Everything gameplay-authored is a data asset (URuneDataAsset, UMergeRecipeDataAsset, etc.). Designers do not touch code. Blueprints inherit from C++ base classes for art-side subclassing of calculators, slots, and runeable objects.

Expected custom editor work is limited to:

A small rune authoring helper (batch create, validate fields) -- not yet built.
A debug overlay toggle (already in via the G key) that shows rune words on slots.

Details: Content pipeline. Recipes: Adding a rune, Debug toggles.

Audio¶

FMOD is scheduled to land in Fall Midterm. Until then the native Unreal pipeline is shipping: AAudioManager (level-placed BGM/SFX conductor) plus per-rune USoundBase references on data assets, both of which migrate to UFMODEvent at integration.

Details: Audio.

VFX¶

Niagara throughout.
Multi-point fire authoring via UFireSpawnPointComponent: a scene-component marker that lets designers place any number of fire anchors on a burnable actor; the fire component spawns one Niagara instance per anchor.
Ring expansion, rune pickup shimmer, and fire are the main effect authors. More will come with content.

Details: VFX.

UI / Menus¶

Game-facing UI intentionally minimal. Currently implemented:

In-world definition widget that shows a rune's word and definition when the player is near a filled slot (with a debug "show word on slot" toggle).
HUD placeholder class hook on the character.

Not yet implemented (roadmap): main menu, pause menu, settings menu, credits scroll, end-of-level scorecard. All UMG, no engine-side work beyond a gamepad-friendly focus system.

Details: UI / Menus.

Save / Load¶

Partially implemented today. UPlayerRuneKnowledge (a USaveGame) persists discovery state and palace slot assignments. Per-level state, runeable snapshots, and player position are not yet persisted -- a reload starts the level fresh.

Plan: a lightweight JSON-backed save: which runes have been discovered (feeds PlayerRuneKnowledge), last orb used, current level flag, player transform. No mid-puzzle save; each level is short enough that a per-level checkpoint is sufficient.

Details: Save / Load.

Technical Development Plan¶

Interaction model pivot (high priority). A click-based Interact Mode: player toggles in (pointer shown, movement locked), clicks runes in the viewport in sequence, and the sentence validates on exit. The current build is physical carry. Plan: keep URuneCarryComponent as an alternate authoring mode for prototyping, add a pointer-based UInteractModeComponent that drives the same RuneCalculator entry points. Validator does not change.

Blueprint authoring layer for effect components. Today, every new verb requires a C++subclass of URuneEffectComponent. That gates content authoring on engineer time. The Blueprint Engineer / Tech Designer should create a Blueprint-derivable template (URuneEffectComponent_BP) plus exposed virtuals on the existing C++ verbs (OnEffectApplied, OnEffectRemoved, tick hook, target-noun accessors). After the template ships, designers and non-engineers can author new runes and effect components by subclassing in the content browser without touching Source/. C++ stays the path for performance-critical verbs (Fire, MoveToward, anything that ticks against many actors).

Grammar extension. Add VERB + NOUN to USentenceValidator (the GDD says we support it). Straightforward addition; implications live in UEffectExecutor which has to know to pull the subject noun from the verb's trailing position. One engineer-week including the executor side.

Rune redefinition exposure. URuneRedefinitionManager works but is not reachable from designer-side authoring. Need a meta-rune or dedicated calculator type that can push redefinitions, and a visual language for when a rune is "stand-in for" another.

Puzzle device authoring. AClockDevice and AStarObservatory are the template for narrative-bearing runeables. We expect ~6 more of these across acts 2 and 3. Each is bespoke content but shares the base class pattern.

Save / Load. Needs spec + implementation. Targeting JSON through UGameplayStatics::SaveGameToSlot.

Menus. Main / Pause / Settings / Credits. UMG, no complex engineering; allocate one engineer for a sprint.

Accessibility. Color-blind safe rune art and audio cue redundancy are on the art side, but we want to land a key-rebind UI and subtitle/definition size setting on the engineering side.

Controller support full-pass. Enhanced Input is wired for gameplay. Menu navigation with a gamepad is not yet hardened. A sprint of review + fixing.

Showcase camera polish. LeadingSphere mode groups close targets but framing at extreme distances still pops on the first target. Needs a capture-reset pass and probably a post-process vignette tie-in.

Content scaling. Target is ~30-40 runes across the campaign. Current RuneDataAsset coverage is roughly a third of that. Each new rune that needs a component is ~0.5 engineer-days, each reuse of an existing component is ~1 hour.

Fire / hazard polish. Multi-point fire spawning is in. Outstanding: non-uniform intensity authoring per point if needed (currently driven by relative scale which has been enough).

Engineer-facing mirror: Plan/DevelopmentPlan.

Technical Risks¶

Interaction pivot cost. Shipping both carry and click modes in parallel risks double maintenance. Mitigation: the validator and executor are already abstracted from the interaction side. Both can write into the same calculator API. If the schedule tightens, we cut the physical carry path entirely and keep click-only.

Showcase camera edge cases. When multiple runeables are clustered on one side of the ring origin, LeadingSphere can over-rotate between beats. Observed occasionally in PIE. Mitigation: ship PauseAtTarget as the default, reserve LeadingSphere for set-pieces until the framing is fully tuned.

Performance with dense runeables. The registry is a hash per noun, so lookup is cheap, but the expanding ring does distance checks against every matching actor every tick during expansion. Mitigation: at ~1000 runeables we're fine in testing; if we push past that for a final level we add a broadphase.

Save compatibility. Adding fields to save data after players have saved is a support burden. Mitigation: version the JSON from day one, include a migration path even if it's initially a no-op.

Engine upgrade risk. Pinned to UE 5.8 (MSVC 14.50, Visual Studio 2026) for Unreal MCP. Jumping versions still invalidates binaries and can require source fixes. Stay on 14.50; do not compile 5.8 with MSVC 14.51+.

FMOD integration not started. If we use FMOD as the middleware, we are starting from zero: the project has no FMOD plugin installed, no FMOD Studio bank build step in packaging, and every per-rune sound is currently a USoundBase reference on URuneDataAsset. Switching to FMOD would mean replacing those fields with UFMODEvent parameters across every rune asset, rewriting AAudioManager against the FMOD Blueprint API, and re-authoring existing SFX (pickup, place, ring, fire, ambience) as Studio events.

Engineer-facing mirror: Plan/Risks.

Schedule¶

Pre-production for Rephrased. AGP cycle starts Fall 2026, Expo May 2027. Specific dates TBD pending the course calendar -- milestone ordering and the work allocated to each milestone are firm.

The rune-system architecture from Gate 2 (validator, executor, priority manager, redefinition runtime, registry, ring actor, calculators, camera subsystem) carries forward as foundation. Content authored on top of it, and the missing glue systems (click mode, save/load, menus, FMOD), are tracked here as fresh work.

Engineering Allocation¶

Engineering Producer -- schedule, integration, milestone gates, FMOD bank build pipeline.
Blueprint Engineer / Technical Designer -- C++ to Blueprint translation of the rune effect system. Owns the URuneEffectComponent_BP template and the BP authoring workflow that lets designers build new runes without touching Source/.
Systems Engineer -- rune core hardening, VERB + NOUN grammar, redefinition designer surface, save/load.
Puzzle Engineer -- clock and observatory pattern carries forward; owns the ~6 follow-on narrative-bearing runeables for Acts 2 and 3, plus memory palace pacing.
Generalist Engineer -- character, click-mode pivot, camera polish, UI/menus, glue and integration.
Audio Engineer -- FMOD integration, SFX authoring.
Tech Art -- Niagara templates, per-noun visual variation.

Key Milestones¶

First Playable: TBD
Fall Midterm: TBD
State of the Game: TBD
Alpha: TBD
Beta: TBD
Expo: TBD

By Milestones¶

First Playable (TBD)¶

Rune System: stabilization pass on existing core. VERB + NOUN grammar in validator + executor.
Blueprint Authoring Layer: base template URuneEffectComponent_BP shipped, one fully BP-authored example verb working end-to-end, walkthrough doc for designers.
Player: click-based Interact Mode prototype playable on a test level.
Camera: debug visualizer for the zone priority stack.
Audio: FMOD plugin installed, Studio project bootstrapped, one event playing in PIE through AAudioManager.
UI/UX: better controls overlay, in-world definition widget polish.
Tools: rune authoring quick-start doc.
Level: greybox of one vertical-slice puzzle integrating click mode.

Fall Midterm (TBD)¶

Rune System: redefinition designer surface (a meta-rune or dedicated calculator type that can author redefinitions without code).
Blueprint Authoring Layer: all C++ verb base classes expose BP-friendly virtuals (OnEffectApplied, OnEffectRemoved, tick hooks, target-noun accessors). First batch of BP-authored verbs ships in content.
Player: click mode shipped (not prototype). URuneCarryComponent retained as an authoring/debug path. Gamepad-for-UI hardening starts.
Audio: FMOD integration complete. AAudioManager rewritten against the FMOD Blueprint API, all current SFX migrated to Studio events, native USoundBase fields removed from data assets.
Puzzle Devices: 2 new authored devices for Act 2.
VFX: per-verb Niagara templates documented for content team.
UI/UX: temp main menu, basic in-game UI.
Level: first full greybox level integrating click mode and migrated audio.

State of the Game (TBD)¶

Rune System: ~70% rune content authored (target ~20 runes of the planned 30-40). Mix of C++ verbs (perf-critical) and BP-authored verbs.
Save/Load: shipped with versioned JSON. Integrates UPlayerRuneKnowledge, last orb used, current level flag, player transform.
Puzzle Devices: 4 total devices shipped (clock + observatory + 2 from Midterm + 0 net new -- hold for Alpha).
Camera: showcase camera LeadingSphere framing polish, custom-camera authoring helpers for designers.
UI/UX: temp pause menu, level-completed screen.
Memory Palace: re-entry pacing and animation polish.

Alpha (TBD)¶

Rune System: feature-complete on the engineering side. 100% of planned rune content authored.
Blueprint Authoring Layer: tooling polish + validation tool catches missing fields, broken meshes, and unbound references on BP-authored runes.
Puzzle Devices: all ~6+ devices shipped across Acts 2 and 3.
UI/UX: full menu set (main / pause / settings / credits), settings menu, accessibility (rebind UI + subtitle/definition size).
Audio: adaptive music pass authored in FMOD.
Player: gamepad-for-UI complete.

Beta (TBD)¶

Content lock.
Audio: final tuning pass on all events, mix pass.
Controller: full hardening pass including menu navigation.
Performance: dense-runeable stress test; broadphase added if registry distance checks regress.

Expo (TBD)¶

Bug fix only.

By Features¶