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.

⚠️ Two different "quest" API paths exist β€” don't conflate them

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.

LayerScript(s)Role
Authoring dataQuestDefinition, QuestObjectiveDefinitionScriptableObject assets: identity, dialogue text, ordered objectives, rewards
Editor toolQuestForgeWindow (Editor/QuestForge/)BCE β–Ά Quest Forge β€” creates/edits definitions, places world objects, and deletes quests with full scene/prefab cleanup
Runtime rulesQuestLocalRuntimeServer-authoritative progress state + client view; all [Server] logic lives here
PersistenceQuestPersistenceServiceServer-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 manifestQuestDeletionManifestScriptableObject at Resources/QuestDeletionManifest; records quest IDs deleted via Quest Forge; server sends DELETE to the API for each tombstoned quest on startup
World hooksQuestWorldComponents.csQuest giver, objective markers, and per-objective-type targets
Dialogue UIQuestLocalDialogueClient-only IMGUI offer/accept/turn-in window
TransportRodChatManagerThe one shared NetworkBehaviour that carries quest Commands/TargetRpcs
ℹ️ Why route quest traffic through RodChatManager?

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 name
  • definitionVersion β€” increment when a deployed quest changes incompatibly with saved progress; minimum 1
  • title, description β€” player-facing name and description
  • minimumLevel β€” minimum player level required; minimum 1
  • objectivesMustBeCompletedInOrder β€” if true, each objective must be fully met before the next is eligible
  • offerText, activeText, completionText, turnInPrefab β€” dialogue and turn-in NPC
  • objectives β€” list of QuestObjectiveDefinition
  • goldReward, experienceReward, itemRewardId, itemRewardQuantity β€” on-completion rewards

QuestObjectiveDefinition fields

  • objectiveId β€” stable persistence key assigned automatically by Quest Forge (GUID); do not reassign manually
  • type β€” QuestObjectiveType: KillEnemy, CollectItem, InteractWithObject, EnterArea
  • targetId β€” enemy template ID, inventory item ID, object ID, or area ID
  • description β€” displayed to the player
  • requiredAmount β€” minimum 1

LocalQuestProgress (server runtime state)

  • questId, definitionVersion, status (LocalQuestStatus)
  • objectiveIds β€” parallel list to objectiveProgress, keyed by objectiveId GUID for stable lookup across definition changes
  • objectiveProgress β€” current completion counts
  • rewardClaimed β€” 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 by RodNetworkManager immediately after a player spawns; loads the player's persisted quest state from QuestPersistenceService and populates ServerStates.
  • 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. Honors objectivesMustBeCompletedInOrder. Objective progress is keyed by objectiveId for 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, calls QuestPersistenceService.ClaimReward, which records the reward in the database and triggers TargetRefreshQuestRewards on the client (inventory/progression reload). When persistence is disabled, awards directly via ServerGrantQuestReward.
  • RegisterDefinition(definition) β€” caches a QuestDefinition and calls QuestPersistenceService.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: ServerLoad fetches the player's state from /api/game/quests/state/{characterId} and restores ServerStates for that connection.
  • On progress change: SaveState PUTs the updated LocalQuestProgress to /api/game/quests/state/{characterId}.
  • On reward claim: ClaimReward POSTs to /api/game/quests/claim/{characterId}/{questId}; on success the server triggers a client-side inventory and progression refresh via TargetRefreshQuestRewards.
  • Skips syncing definitions whose questId appears in QuestDeletionManifest.

Objective types & how each is reported

QuestObjectiveType has four kinds, each wired into an existing gameplay system so designers don't write code:

ObjectiveReported byHook
KillEnemyQuestEnemyTarget (auto-attached to every enemy via EnemyController.OnStartServer β†’ QuestEnemyTarget.EnsureAttached)On death, reports the enemy's identity
CollectItemWorldItem.ServerPickupOn pickup, reports itemId Γ— quantity (gold pickups gold:* are excluded)
InteractWithObjectQuestInteractableTarget (INPCInteractable, press E)Player interact β†’ QuestLocalRuntime.RequestInteraction(targetId), server re-checks proximity
EnterAreaQuestAreaTarget (trigger volume)Player enters trigger β†’ reports areaId
ℹ️ Enemy name normalization

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 of QuestDefinitions, an interaction radius, and a marker anchor. Prompt: "Press E to discuss <title>". ServerPlayerIsNearQuest is 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; reports KillEnemy on death.
  • QuestInteractableTarget (INPCInteractable) β€” a "press E" object that reports InteractWithObject (e.g. examining a grave).
  • QuestAreaTarget β€” a trigger volume that reports EnterArea.
  • QuestDiscoveryBindingBootstrap β€” a scene-load hook that auto-binds any GameObject named QuestArea_<targetId> into a working QuestAreaTarget + 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 QuestDefinition assets under Assets/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 rewards depend on item_template

An 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/:

QuestZoneObjective
Kill OgresDarkwoodKillEnemy β€” 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 into EnemyController, and shipped Kill Gunda / Kill Ogres.
  • 2026-08-04: QuestPersistenceService landed, 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. QuestDeletionManifest propagates 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