Quests & Quest Forge
Crossworlds has a working, Unity-side quest system β authored in the editor with Quest Forge, driven at runtime by a Mirror-networked, server-authoritative progress tracker. It landed on 2026-07-26 and reached database persistence on 2026-08-04 via QuestPersistenceService.
The Node auth server has exposed /api/quests/* (available/accept/complete/progress) since early July, but no Unity code calls it. The system on this page uses a separate /api/game/quests/* path through QuestPersistenceService for definitions and player state. The dormant /api/quests/* endpoints remain legacy/unused. See Canonical Facts & Doc Divergences and Implementation Status.
The shape of it in one paragraph
A designer authors a QuestDefinition ScriptableObject (identity, dialogue, objectives, rewards) in Quest Forge (BCE βΆ Quest Forge) and drops quest objects into a scene β a quest giver, and targets for each objective. At runtime the player talks to the giver (press E), accepts through a dialogue window, and the Unity dedicated server owns their progress. Kills, item pickups, interactions, and area entries are reported to the server, which advances objectives, flips the quest to ready to turn in, and β on turn-in β grants gold/XP/item rewards to that one player. Quest state is persisted to the database when CROSSWORLDS_GAME_SERVICE_TOKEN is set on the server.
Architecture β authoring β runtime β transport
Quests are deliberately layered so the networking stays isolated from the quest rules.
| Layer | Script(s) | Role |
|---|---|---|
| Authoring data | QuestDefinition, QuestObjectiveDefinition | ScriptableObject assets: identity, dialogue text, ordered objectives, rewards |
| Editor tool | QuestForgeWindow (Editor/QuestForge/) | BCE βΆ Quest Forge β creates/edits definitions, places world objects, and deletes quests with full scene/prefab cleanup |
| Runtime rules | QuestLocalRuntime | Server-authoritative progress state + client view; all [Server] logic lives here |
| Persistence | QuestPersistenceService | Server-side adapter: syncs definitions to /api/game/quests/definitions, loads per-player state on connect, saves on progress change, claims rewards via the database |
| Deletion manifest | QuestDeletionManifest | ScriptableObject at Resources/QuestDeletionManifest; records quest IDs deleted via Quest Forge; server sends DELETE to the API for each tombstoned quest on startup |
| World hooks | QuestWorldComponents.cs | Quest giver, objective markers, and per-objective-type targets |
| Dialogue UI | QuestLocalDialogue | Client-only IMGUI offer/accept/turn-in window |
| Transport | RodChatManager | The one shared NetworkBehaviour that carries quest Commands/TargetRpcs |
Quests need a networked object that already exists for every player to carry ownerβserver requests and serverβowner responses. Rather than add a second global NetworkBehaviour, the system reuses the chat manager purely as a transport pipe (RequestQuestAccept/Complete/Interaction β Cmd* β QuestLocalRuntime; server replies via TargetReceiveQuestState / TargetGrantQuestReward / TargetRefreshQuestRewards). The comment in code is explicit: "Quest rules remain isolated in QuestLocalRuntime; this global Mirror object only carries owner requests and responses." See Mirror Networking & Discipline.
Data model
QuestDefinition fields
QuestDefinition (ScriptableObject) carries:
questIdβ stable slug, auto-generated by Quest Forge from the quest namedefinitionVersionβ increment when a deployed quest changes incompatibly with saved progress; minimum 1title,descriptionβ player-facing name and descriptionminimumLevelβ minimum player level required; minimum 1objectivesMustBeCompletedInOrderβ if true, each objective must be fully met before the next is eligibleofferText,activeText,completionText,turnInPrefabβ dialogue and turn-in NPCobjectivesβ list ofQuestObjectiveDefinitiongoldReward,experienceReward,itemRewardId,itemRewardQuantityβ on-completion rewards
QuestObjectiveDefinition fields
objectiveIdβ stable persistence key assigned automatically by Quest Forge (GUID); do not reassign manuallytypeβQuestObjectiveType: KillEnemy, CollectItem, InteractWithObject, EnterAreatargetIdβ enemy template ID, inventory item ID, object ID, or area IDdescriptionβ displayed to the playerrequiredAmountβ minimum 1
LocalQuestProgress (server runtime state)
questId,definitionVersion,status(LocalQuestStatus)objectiveIdsβ parallel list toobjectiveProgress, keyed byobjectiveIdGUID for stable lookup across definition changesobjectiveProgressβ current completion countsrewardClaimedβ set when the database has recorded the reward transaction
Server authority & the state model
QuestLocalRuntime holds two dictionaries:
ServerStates(server-only) βconnectionId β { questId β LocalQuestProgress }. The single source of truth. All mutations are[Server]-gated._clientStates(owner client) β a synchronized view pushed down as JSON (QuestStateEnvelope) and consumed by markers/UI. The client never advances its own progress.
A quest moves through LocalQuestStatus: Available β Active β ReadyToTurnIn β Completed.
Key server methods (all [Server]):
ServerLoad(conn)β called byRodNetworkManagerimmediately after a player spawns; loads the player's persisted quest state fromQuestPersistenceServiceand populatesServerStates.ServerAccept(conn, questId)β validates the player is near the quest giver (QuestGiver.ServerPlayerIsNearQuest) before creating progress. Anti-spoof.ServerReport(conn, type, targetId, amount)β the objective-advance funnel. Matches the reported target against every active quest's objectives, clamps progress, and flips to ReadyToTurnIn when all objectives are met. HonorsobjectivesMustBeCompletedInOrder. Objective progress is keyed byobjectiveIdfor stable lookup; falls back to positional index for legacy progress records.ServerComplete(conn, questId)β requires ReadyToTurnIn and proximity to the turn-in giver. When persistence is enabled, callsQuestPersistenceService.ClaimReward, which records the reward in the database and triggersTargetRefreshQuestRewardson the client (inventory/progression reload). When persistence is disabled, awards directly viaServerGrantQuestReward.RegisterDefinition(definition)β caches aQuestDefinitionand callsQuestPersistenceService.SyncDefinition.ServerClear/ServerForgetβ reset or drop a connection's quest state.
Persistence (QuestPersistenceService)
Active when NetworkServer.active and CROSSWORLDS_GAME_SERVICE_TOKEN is set on the server.
- On server start: reads
QuestDeletionManifest; for each tombstoned quest ID, sends DELETE to/api/game/quests/definitions/{questId}. Then syncs all live definitions to/api/game/quests/definitions. - On player connect:
ServerLoadfetches the player's state from/api/game/quests/state/{characterId}and restoresServerStatesfor that connection. - On progress change:
SaveStatePUTs the updatedLocalQuestProgressto/api/game/quests/state/{characterId}. - On reward claim:
ClaimRewardPOSTs to/api/game/quests/claim/{characterId}/{questId}; on success the server triggers a client-side inventory and progression refresh viaTargetRefreshQuestRewards. - Skips syncing definitions whose
questIdappears inQuestDeletionManifest.
Objective types & how each is reported
QuestObjectiveType has four kinds, each wired into an existing gameplay system so designers don't write code:
| Objective | Reported by | Hook |
|---|---|---|
| KillEnemy | QuestEnemyTarget (auto-attached to every enemy via EnemyController.OnStartServer β QuestEnemyTarget.EnsureAttached) | On death, reports the enemy's identity |
| CollectItem | WorldItem.ServerPickup | On pickup, reports itemId Γ quantity (gold pickups gold:* are excluded) |
| InteractWithObject | QuestInteractableTarget (INPCInteractable, press E) | Player interact β QuestLocalRuntime.RequestInteraction(targetId), server re-checks proximity |
| EnterArea | QuestAreaTarget (trigger volume) | Player enters trigger β reports areaId |
Kill objectives match by a normalized enemy id: QuestTargetId.NormalizeEnemy strips (Clone), _(9), (2), and a _discovery suffix, lowercases, and replaces spaces with underscores β so scene instances gunda_(9), Gunda (2), and gunda(Clone) all count toward a gunda objective. This is why quest targetIds are lowercase identity names, not prefab names.
World components (QuestWorldComponents.cs)
QuestGiver(INPCInteractable) β holds a list ofQuestDefinitions, an interaction radius, and a marker anchor. Prompt: "Press E to discuss <title>".ServerPlayerIsNearQuestis the server-side proximity gate reused by accept/complete.QuestMarkerBillboard/QuestObjectiveMarkerβ floating world markers that show where a quest can be picked up or which object an objective refers to.QuestEnemyTargetβ auto-attached to enemies; reportsKillEnemyon death.QuestInteractableTarget(INPCInteractable) β a "press E" object that reportsInteractWithObject(e.g. examining a grave).QuestAreaTargetβ a trigger volume that reportsEnterArea.QuestDiscoveryBindingBootstrapβ a scene-load hook that auto-binds any GameObject namedQuestArea_<targetId>into a workingQuestAreaTarget+ marker, and repairs bindings after every scene load. Convention over wiring: name the object right and it self-configures.
Quest Forge (the editor tool)
BCE βΆ Quest Forge (QuestForgeWindow, menu priority 36) is where quests are built:
- Create/load
QuestDefinitionassets underAssets/Game/Quests/Quest Forge. - Edit identity (
questId,definitionVersion,title,description,minimumLevel), dialogue (offer/active/completion text), objectives, and rewards inline. - Place the quest giver and objective targets into the open scene.
- Delete Open Quest β removes the quest asset, strips associated quest giver components, objective markers, and exclusive target components from all scenes and prefabs, and records a deletion tombstone in
QuestDeletionManifest. Cannot be undone through Unity Undo.
The tool carries the banner: "The Quest Forge itself remains local; deployed server builds synchronize quest persistence with the database."
Rewards
On turn-in, when persistence is enabled, QuestPersistenceService.ClaimReward records the award in the database before triggering a client-side inventory and progression reload. When persistence is not enabled, ServerGrantQuestReward β TargetGrantQuestReward β ClientGrantReward on the owning client applies:
- Gold β
PlayerProgressManager.Local.AwardGold - Experience β
PlayerProgressManager.Local.AwardXp - Item β
InventoryManager.Instance.OnItemPickedUp(itemRewardId, qty)
These reuse the existing progression/inventory pipelines, so quest rewards persist the same way any gold/XP/item does (via the Node API's value-trusted save path β see Loot, Inventory & Crafting).
item_templateAn itemRewardId only resolves if that id exists in the sacred item_template table the client already reads. A reward pointing at a non-existent item id grants nothing. See Database Schema.
Quest content in the build
Authored quests currently in Assets/Game/Quests/Quest Forge/:
| Quest | Zone | Objective |
|---|---|---|
| Kill Ogres | Darkwood | KillEnemy β O'gar Brute ogres |
How it developed (context & why)
- Early July: the Node API grew
/api/quests/*endpoints, but the Unity client never got a quest UI β quests sat in the "server exposes it, client ignores it" bucket alongside talents/guilds/leaderboards. - 2026-07-26: the team built a Unity-native quest system instead of wiring the dormant API β
QuestForge+QuestLocalRuntime(commit Quest testing), first exercised in Ashen Wastelands with Find The Grave. - Same day: Quest Testing in Darkwood added
QuestEnemyTarget, hooked kills intoEnemyController, and shipped Kill Gunda / Kill Ogres. - 2026-08-04:
QuestPersistenceServicelanded, wiring definitions and per-player progress to/api/game/quests/*(separate from the dormant/api/quests/*). Quest state now loads on player connect and saves on every progress change; reward claims go through the database.QuestDeletionManifestpropagates quest deletions to the server. Find The Grave and Kill Gunda quest assets were removed from the project; Kill Ogres remains.
Related: NPCs & Interaction Β· Editor Tooling Β· Mirror Networking & Discipline Β· Loot, Inventory & Crafting Β· Known Issues & Tech Debt