Known Issues & Tech Debt
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.csused to hardcode a 5-scene list, so_Containerand 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 legacyrod-serverunit also lingers and has been mis-pointed at a non-existent binary. Manual server launches have left orphaned processes squatting on :7777. Operate the managedcrossworlds-serverunit; 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:7777alongside 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, staleGameAssembly.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). Anode server.jshad been hand-launched directly in/opt/crossworlds-auth-stagingon 2026-07-28 (outside systemd, reparented to PID 1 once its launching shell exited) and held port:3010continuously from that point on. Everysystemctl restart crossworlds-auth-stagingsince then spun up a fresh systemd-tracked process that loggedlistening on port 3010and then sat idle โ the log line fires unconditionally onapp.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 viass -ltnpthat the systemdMainPIDnow matches the actual port holder โ a full sweep of every othercrossworlds-*service the same day found no other instance of this pattern. Never hand-launch a service directly withnode server.js/python3 app.pyetc., 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_NAMESsays 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-progressaccepts 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
| Trap | Symptom | Fix |
|---|---|---|
#if !UNITY_SERVER alone | Client code silently stripped in editor | Use #if UNITY_EDITOR \|\| !UNITY_SERVER (details) |
Missing NetworkTransform | Players/enemies spawn but freeze in MP | BCE โถ Setup โถ 4n |
| Deployables not networked | Mines/walls invisible to other players โ prefabs don't exist yet | Build the deployable prefabs (Ability Atlas & Synergies) |
Canvas blocksRaycasts | Invisible UI eats mouse, breaks camera | Set blocksRaycasts = false explicitly (UI) |
| Root motion + Rigidbody | Mesh "flies wild in POV" | applyRootMotion = false |
| Out-of-editor asset moves | GUID churn โ "Missing Prefab" | Restore GUID; move inside Unity (Editor Tooling) |
LFS-tracked *.prefab | Merge markers โ null prefabs | Recover from LFS cache; untrack prefabs |
Design-level debt (don't drive-by fix)
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
WaveManageris legacy and orphaned โ the live loop isWaveSpawner. Always editWaveSpawner.- 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)
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