Known Issues & Tech Debt

๐Ÿ“ Historical playtest reports

The 2026-08-08 history audit recovered several Discord reports that need current-build reproduction before they are called active bugs: pink wave-spawn prefabs, multiple suns after additive zone changes, Toujam wave startup overriding arrival position, and broad terrain sticking. Their context and provenance are in Historical Context & Decision Register.

The project's real risks are the doubles, the trust gaps, and a handful of sharp edges that bite silently. Present-state, grouped by how much they hurt.

Structural

  • Build scene-list drift (fixed). BuildScript.cs used to hardcode a 5-scene list, so _Container and newer zones silently dropped out of every build โ€” the direct cause of the "stuck on CONNECTING" login hang against a server that couldn't load its online scene. Now derives from the Scenes-In-Build list. See Build & Deploy.
  • Two game-server units on the VPS. Active is crossworlds-server; a legacy rod-server unit also lingers and has been mis-pointed at a non-existent binary. Manual server launches have left orphaned processes squatting on :7777. Operate the managed crossworlds-server unit; don't hand-launch. Confirmed directly (2026-07-29) this is worse than a stuck port: a second instance on the same host can bind UDP :7777 alongside the live one without erroring, risking real player packets getting misrouted rather than the second instance just failing to start. Never run a second copy on this host โ€” see Build & Deploy and Admin Dashboard.
  • Partial deploys. A build that half-uploads (fresh UnityPlayer.so, stale GameAssembly.so, or a truncated scene set) runs but mismatches the client โ€” clients hang mid-connect. Always deploy the full set and restart via systemd.
  • Same orphaned-process failure mode hit crossworlds-auth-staging, but silently, for days (found and fixed 2026-08-02). A node server.js had been hand-launched directly in /opt/crossworlds-auth-staging on 2026-07-28 (outside systemd, reparented to PID 1 once its launching shell exited) and held port :3010 continuously from that point on. Every systemctl restart crossworlds-auth-staging since then spun up a fresh systemd-tracked process that logged listening on port 3010 and then sat idle โ€” the log line fires unconditionally on app.listen()'s callback regardless of which process actually won the bind, so the failure gave no visible error. Net effect: days of code/config changes to that service were silently inert, because the real traffic was still being served by the stale 2026-07-28 process the whole time. Fixed by killing the orphan and confirming via ss -ltnp that the systemd MainPID now matches the actual port holder โ€” a full sweep of every other crossworlds-* service the same day found no other instance of this pattern. Never hand-launch a service directly with node server.js / python3 app.py etc., even "just to test" โ€” always go through its systemd unit, and if one ever must be started manually, confirm no systemd-managed instance is expected to also own that port. See Build & Deploy.
  • Client/server class-name divergence. Client says Marauder/Ironclad; server CLASS_NAMES says Engineer/Guardian. Cosmetic today, but any code that string-matches class name across the boundary is fragile. See Canonical Facts & Doc Divergences.

Security (alpha-accepted)

  • No server-side player HP โ€” a hacked client can ignore all damage. Biggest cheat vector.
  • Client-trusted progression writes โ€” save-progress accepts whatever level/xp/gold the client sends (JWT-gated, value-trusted). Kills are mitigated server-side; the save path isn't.
  • In-process anti-exploit maps โ€” hit gates / kill cooldowns live in server memory and clear on restart.

Sharp edges that bite silently

TrapSymptomFix
#if !UNITY_SERVER aloneClient code silently stripped in editorUse #if UNITY_EDITOR \|\| !UNITY_SERVER (details)
Missing NetworkTransformPlayers/enemies spawn but freeze in MPBCE โ–ถ Setup โ–ถ 4n
Deployables not networkedMines/walls invisible to other players โ€” prefabs don't exist yetBuild the deployable prefabs (Ability Atlas & Synergies)
Canvas blocksRaycastsInvisible UI eats mouse, breaks cameraSet blocksRaycasts = false explicitly (UI)
Root motion + RigidbodyMesh "flies wild in POV"applyRootMotion = false
Out-of-editor asset movesGUID churn โ†’ "Missing Prefab"Restore GUID; move inside Unity (Editor Tooling)
LFS-tracked *.prefabMerge markers โ†’ null prefabsRecover from LFS cache; untrack prefabs

Design-level debt (don't drive-by fix)

โš ๏ธ Damage-reduction single channel

Health DR is one scalar; consumable resist buffs, ThreatProtocol, and SiegeMode clobber each other. Needs a ref-counted refactor โ€” a deliberate task, not an inline patch. See Loot, Inventory & Crafting.

Orphaned / unused in the current client

  • WaveManager is legacy and orphaned โ€” the live loop is WaveSpawner. Always edit WaveSpawner.
  • No PartyManager / guild / talent UI in this repo, even though the server exposes those endpoints. See Implementation Status ยท Party System.
  • The server's /api/quests/* endpoints are dead code relative to the client. The game's quests run on the newer Unity-native Quest Forge system over Mirror, not the API. Two parallel quest implementations now exist; only the Unity one is wired. See Canonical Facts & Doc Divergences.

Quest system (testing-stage)

โš ๏ธ Quest progress is in-memory and wipes on restart

QuestLocalRuntime.ServerStates lives in server RAM keyed by connectionId; nothing is saved to the DB. A crossworlds-server restart or a reconnect loses all quest progress and re-offers completed quests. Intentional while the system is in testing, but the first fact to know before building on it. The item-reward path also silently no-ops if itemRewardId isn't in item_template. See Quests & Quest Forge.


Related: Implementation Status ยท Canonical Facts & Doc Divergences ยท Mirror Networking & Discipline ยท Admin Dashboard