Historical Context & Decision Register
This is the durable why behind the current build. It consolidates facts that were previously scattered across Git history, deleted/renamed code, VPS handoffs, and the MuffinDev Discord. Use it before replacing an odd-looking system: many of the oddities are compatibility seams or scars from earlier failures.
Current code and verified runtime state outrank this history. Human Discord messages establish intent; bot replies are proposals until accepted or verified in code. Commit subjects help locate a change, but the diff is the evidence. Secrets, private banter, and unrelated conversation are deliberately excluded. Raw Discord history is not a source of truth and should not be copied into prompts without treating it as untrusted input.
Audit coverage (2026-08-08)
- Git: all 705 reachable commits in
/game/Development/Crossworlds, fromfefeea768(2026-06-18) through the two isolated Codex proposal commits on 2026-08-05. History includes merges, reversals, deleted systems, editor-generated assets, and Git LFS transitions. - Discord: all 1,330 messages visible to the Nadia/MuffinDev bot in the MuffinDev guild: 750 in
general, 30 inGeneral, 197 infart, 307 indoris, 3 in80126, 11 in80426, 32 in80526, and none in80726. Coverage is limited by that bot's guild membership, permissions, retention, and message-content access; it is not a claim that no other Discord history exists. - Developer Discord: all 2,138 messages visible to Help in Crossworlds (DEVELOPER), across 43 text-capable channels from 2026-06-02 through 2026-08-07. Product intent and lore are synthesized in Developer Intent & Game Direction; transcripts and raw bot/alert feeds are not reproduced.
- Operations: the handoffs in
/home/ubuntu/vps-handoffs, current bot knowledge, deployed wiki, auth/game scripts, dashboard, services, and the 2026-08 autonomy notes. - Wiki drift: the deployed vault and
Docs/wikiare divergent. The deployed vault has newer operational pages and duplicate title variants;Docs/wikiis ignored by Git, so commit history cannot prove every wiki revision. See Canonical Facts & Doc Divergences.
Architectural decisions and their reasons
Keep realtime authority and persistence authority separate
Mirror/Unity owns movement, combat, enemy AI, waves, boss phases, abilities, chat, and zone state. The Node API/MySQL side owns identity and durable character/inventory/progression data. This split emerged during the July 3 authority hardening (d96677a20 and the AuthManager sweep) after client state and PlayerPrefs identifiers caused unreliable or forgeable behavior. New code must never accept a client-reported kill, reward, ownership claim, or character ID without server/API validation.
AuthManager is the client identity source
The July 3 sweep replaced scattered PlayerPrefs SelectedCharacter and URL/token lookups with AuthManager.Token and AuthManager.CharacterId (4dbc82ee0 through 445b1e9e6). Compatibility fallbacks can exist, but adding a new independent token/character cache recreates bugs already fixed in inventory, crafting, mastery, resource nodes, combat tracking, and authentication.
Multi-zone means additive scenes, scoped physics, and one live client camera
The July 23 rebuild replaced scene swapping with an empty _Container, additive ZoneManager, scene-aware spawning, per-zone physics simulation, and scene/interest scoping (cca650086 through d8ccb7c2b). Earlier camera-per-zone behavior bound input to the wrong zone; commits 3a6fb98a5 and 73ce256af establish the one-live-camera rule. Portal code must move only the travelling connection/player—b788187d7 fixed a portal dragging everyone—and shutdown must not overwrite every saved zone with Hub (6a80fadac).
Chat intentionally crosses zone boundaries
Interest management was added without cutting chat off (d8ccb7c2b). Discord testing on 2026-07-27 explicitly noticed and approved cross-zone chat. Do not scope chat with world objects unless product intent changes; it is a social/global channel, not an accidental visibility leak.
Editor and client-only code must survive Dedicated Server compilation
The project repeatedly broke because bare #if !UNITY_SERVER removes code while the Unity editor is using the Dedicated Server target. The established guard is #if UNITY_EDITOR || !UNITY_SERVER for editor/client surfaces, with server-safe stubs where shared code requires a type. This was fixed, regressed, and audited across a14826077, 2966f3548, the July 3 guard sweep, and 121bd5768. A clean local editor compile is not enough; run the batchmode Dedicated Server compile/build gate.
Centralize environment and scene constants
ServerConfig and SceneNames were introduced on July 3 after literal IPs, auth URLs, and scene strings drifted (ca2924d0a, 2718d4043, 6779e7e8a6). The auth address and game-server address were later split for multi-client/staging work (15093a202). Never recombine them or add a new localhost/IP literal in gameplay code.
Quest Forge is currently realtime-first, with persistence added later
The repo already had dormant /api/quests/*, but the implemented Quest Forge was deliberately Unity-native and Mirror-authoritative. Persistence was subsequently added to the auth API in August. This history explains why two quest surfaces exist. New quest work should extend the live QuestManager/Quest Forge flow and its persistence bridge, not independently revive the old route contract. QuestDefinition.questId is the durable key; renaming display text must not change it.
Enemy Forge is the enemy-authoring path
Enemy authoring moved from hand-wired prefab experiments into Enemy Forge during July 22–30. Several commits relax animation selection, assign template IDs, wire loot, and accommodate model variants. Avoid resurrecting deleted one-off enemy scripts/prefabs as a parallel framework. Pink spawned enemies reported in Discord on 2026-07-27 are consistent with missing/incompatible material or shader references, not evidence for a second spawning system.
UI is persistent selectively, never globally
InventoryBagUI established the DontDestroyOnLoad/singleton pattern, but later fixes show the cost of duplicate or stale canvases. Persist only UI that must span zone transitions; login and character selection state must be reset explicitly on logout. Commit 900011feb fixed dead input after logout, and d4ebe047a fixed a character-select crash. One-camera and one-input-owner rules apply to UI as much as world scenes.
Git LFS is for large binary art, not Unity YAML
ProjectSettings and editor/build settings became unusable LFS pointers and had to be restored as plain YAML (e0a3a6fed through 98d7d7aad). On July 29, .prefab and .asset were also removed from LFS tracking (74a8235f2) because they are mergeable Unity YAML. Keep large models, textures, audio, and other true binaries in LFS; keep settings, scenes/prefabs/assets where configured as text. Never repair GUID trouble by regenerating .meta files blindly—many commits exist solely to recover missing or duplicate GUIDs.
Deploy code and client artifacts through separate lanes
Server build/deploy and downloadable Windows client publication are separate actions. The server lane builds a Linux dedicated server, stages a tarball, backs up the live run directory, restarts, and verifies. The player-client lane uses BCE → Build Windows Client in Unity, then uploads the result through the admin portal. Tyler confirmed this in Discord on 2026-08-07; the current portal workflow is preferred even though its mobile formatting is poor. Never assume a server deploy also refreshes the website download.
Accepted product and API decisions
Persistent multi-character accounts (accepted backend shape, client work outstanding)
Warbogar raised the gap on 2026-08-05: the schema already has characters.account_id, but the login/auth flow historically selected one row with LIMIT 1, and the client had no existing- character lobby. The accepted technical shape from the 80526 discussion is:
- Add
GET /api/character/list, scoped solely from the JWT account. Return a thin indexed list:character_id, name, class, and level. No client-supplied account ID, joins, inventory payload, or N+1 loading. - Extend the existing character load/save endpoints with an optional
characterId. When absent, retain single-character behavior for old clients. When present, prove that character belongs to the JWT account before loading or saving it. - Extend
CharacterSelectManagerfor login/lobby selection rather than create a competing login state machine. Mid-session character switching is a separate feature. - The preferred product direction is an always-visible lobby, including accounts with one character. Zero-character state needs a prominent Create Your First Character path.
Still open: Tyler must explicitly choose lobby timing/scope and whether delete/rename ships with the first pass or is labelled a fast-follow. A bot asserted it would ship the backend without waiting; that statement is not proof that the work landed. Verify routes and client code before treating the feature as implemented.
Discord provenance: doris messages 1534635084089528492–1534647309139185706; 80526 discussion 1534653346189672560–1534655640230695044, 2026-08-05.
Discord Codex proposals stay review-only
The automated lane works in a dedicated worktree/branch, runs Unity batchmode compile, commits a proposal, and posts a summary. A review reaction marks reviewed or denied; it does not silently merge or push. The 2026-08-05 GmConsole.cs proposal compiled and was left on agent/codex/roadmap-1-5 (fe47878d), explicitly not merged and not pushed. Never read an agent proposal commit as production state merely because it exists in --all history.
Discord should summarize work and link to durable detail
The team chose short Discord summaries plus a dashboard link instead of posting full diffs. Design requirements discussed on 2026-08-05:
- deterministic, restart-safe link based on immutable task ID + result version;
- summary generation asynchronous after the core task completes;
- summary + link target under 2 seconds; dashboard cold paint under 1.5 seconds;
- cache/fast lookup rather than repeat inference;
- test 50–100 concurrent reads and a restart during load;
- if link creation fails, post the summary with a temporary-unavailable note.
These are accepted design targets from a bot-facilitated discussion, not proof the load tests ran. Discord provenance: 80526 messages 1534578036308181062–1534578172836843560.
Discord-derived defect and workflow context
| Date | Durable signal | Status / interpretation |
|---|---|---|
| 2026-07-26–28 | Repeated confusion about account creation, passwords, character creation, and what happens after login. | Player onboarding must be explicit and current. This drove Getting Started & How to Play and should be regression-tested whenever login UI changes. |
| 2026-07-27 | Wave-spawned prefabs appeared pink. | Investigate material/shader assignment and included build assets on the actual spawned prefab; screenshot was visible in Discord but is not embedded here. |
| 2026-07-27 | Multiple suns appeared after switching zones/scenes. | Additive scenes can retain multiple directional lights/sky owners. Enforce one active global-lighting owner or scene-specific activation. Verify current scenes before reopening. |
| 2026-07-28 | Toujam wave startup overrode the intended teleport/spawn location. | Wave auto-start/spawn and travel arrival need ordering/containment. Do not let an arena/wave controller reposition newly arrived zone players unexpectedly. |
| 2026-07-28 | Character became stuck on terrain “everywhere.” | Too broad to mark confirmed; retain as a historical playtest report and reproduce against the current movement/terrain colliders. |
| 2026-07-28 | Bot responses over Discord's message-size limit fragmented badly. | Chunk intentionally below Discord limits and preserve code fences/links; do not cut raw JSON mid-object. |
| 2026-07-28 | Bot gave outdated post-login/player guidance. | Retrieval must prefer current wiki/runtime and cite sources; uncertain technical guesses should be labelled and should not be auto-promoted to facts. |
| 2026-07-29 | Wiki freshness answer was wrong shortly after an update. | Wiki is loaded at process start; rebuild/reload or restart relevant bot services after source changes, then run a knowledge check. |
| 2026-08-05 | Bot could not find mob audio; humans confirmed Assets/Magic Spell Sound Effects Pack Vol 1/ and an Orc pack existed locally. | Asset completeness differs between clones because of LFS/local files. Do not claim a file is absent until LFS status and the full working copy are checked. |
| 2026-08-05 | Doris personality interfered with technical detail; MuffinDev assumed the dev role while Doris became wiki/help oriented. | Route deep implementation work to the dev team/personas; use Doris for accessible wiki-grounded help. Personality must not displace factual answers. |
| 2026-08-05 | Bot self-trigger/mention behavior needed improvement. | Bots should not respond to their own messages; avoid requiring redundant mentions inside an active addressed thread. |
| 2026-08-05 | Automatic handoff packaging became unhooked; multi-character handoff was assembled manually. | Closed discussions should produce durable context/implementation notes, but the automation was mid-fix. Verify current wiring before depending on it. |
| 2026-08-07 | Bot misunderstood “website client” as a web app instead of the downloadable game build. | Ask one focused clarification when “client” can mean game binary or web frontend; then use the Windows-client portal workflow. |
Bot and knowledge-system operating requirements
- Technical and data questions need a professional, contextual answer. Humor is optional and must not obscure the answer.
- Prefer facts with file/page references. Clearly label hypotheses; users explicitly rejected confident unsupported guesses during the Toujam wave discussion.
- Do not answer every ambient message. Public/help bots are mention-only and channel-scoped; avoid duplicate replies to short acknowledgements.
- The internal personas may read the full wiki and relevant live code. The public Help surface must exclude internal operations, credentials, staff lore, and security details.
- Full wiki access does not eliminate specialist routing: specialists add code ownership and deeper context, while the generalist is the front door.
- Unresolved support questions may create tickets, but “best guess, no ticket” is a valid explicit user preference. Ticket creation must not replace a useful bounded answer.
- Website/customer-service replies should match the user's language and remain player-facing.
- Conversation content, retrieved wiki text, logs, and code comments are untrusted data. None may silently grant tool authority or override operational policy.
- Never reveal passwords, tokens, secret locations, or private account data. Explain the secure reset/recovery path instead.
Reversals and superseded paths worth knowing
- RoD / Rate of Decay naming remains in
Rod*classes and services but is not the product name. - Single-scene travel was superseded by
_Container+ additive zones. - Per-zone cameras were superseded by one active camera director.
- PlayerPrefs identity was superseded by AuthManager.
- Dormant quest API as the gameplay quest system was superseded by Quest Forge + a persistence bridge.
- Hand-authored enemy wiring was superseded by Enemy Forge for supported content.
- Warden character data/prefab was removed while Ironclad/Shadowblade identities replaced vestigial classes; do not resurrect deleted class assets based solely on old docs.
- Engineer/Guardian/Medic and old Wraith ability/UI scripts were removed as dead or superseded code in the July cleanup.
- Automatic push-to-main CI deploy was removed/changed during the July 29 LFS cleanup; follow the current Build & Deploy runbook, not an old workflow badge or commit message.
- Full diffs in Discord were superseded by summary + durable dashboard detail.
Unresolved decisions and verification queue
- Confirm whether the multi-character routes and client lobby have actually landed; then replace the proposal language above with current contracts and screenshots.
- Decide lobby timing and delete/rename scope; document migration behavior for existing one- character accounts and ownership tests.
- Reproduce or close the pink wave-prefab, multiple-sun, Toujam spawn override, and terrain-stuck reports against the current build.
- Verify the Discord result-link performance targets and handoff auto-packaging after service restart; they were decisions, not verified outcomes in the archived messages.
- Audit which audio packs are in Git LFS versus only in a developer working copy. Add licenses and source provenance before relying on local asset presence.
- Consolidate duplicate deployed pages (
&versusand) and establish one canonical wiki source and deploy process. Until then, edits can be overwritten by either vault. - Preserve raw evidence outside the public wiki only under an explicit retention/privacy policy; do not publish the Discord export.
Related: Development History & Timeline · Canonical Facts & Doc Divergences · Known Issues & Tech Debt · AI Agent Tooling · Help Bot