Luna UI Documentation

com.cupkekgames.quests is a small quest framework on the Data architecture. Quests are authored as definitions in a catalog, and the player's log saves only small states that name them by CatalogKey. A definition is never saved. The game moves quests on by telling the log what happened.

The parts

Type	What it is
`QuestDefinition`	What a quest is: `Title`, `Description`, `Objectives`, `Rewards` and `Features` (the last two are `[SerializeReference]` lists). `Ordered` makes the objectives complete one after another.
`QuestObjectiveDefinition`	Plain data: a `Kind` ("cook", "hire", "boss"), a `Key` (which meal, which hero; empty accepts any), a `Required` count and optional authored `Text`. The game owns the vocabulary of kinds and keys.
`QuestSO`, `QuestCatalog`	An authored quest, and the `AssetCatalog<QuestSO>` that lists them by key. A generated quest is authored too, as a template.
`QuestState`	A quest the player has, and the only part that is saved: its `CatalogKey`, the progress per objective, its `Status`, an optional `Deadline`, and per-feature state (`IFeatureStateData`).
`QuestRoll`	The package's own feature state: the key and count each objective rolled, for a quest generated from a template.
`QuestLog`	The player's quests (`IData`, saved with the game state), and the one place their progress changes.
`IQuestReward`	Granted when a quest is turned in. It is handed the quest: `Grant(QuestState)`, and a one-line `Describe(QuestState)` for the UI.
`IQuestFeature`	Game data on a definition that the log never reads: the giver, the source, how a template rolls.

Using the log

csharp

QuestLog log = new QuestLog();
log.Bind(key => catalog.GetValue(key.Key).Definition); // after creating or loading, before anything else

QuestState story = log.Add(storyKey);                   // an authored quest

QuestState contract = new QuestState(templateKey, deadline: 3); // a generated one
contract.GetOrCreateState<QuestRoll>().Set(0, "Camp", 3);       // what it rolled
log.Add(contract);

log.Attach(offer);           // show a quest that is not taken yet, like an offer on a board

log.Signal("cook", "stew");  // something happened: matching live objectives move
log.Report("fame", null, 3); // a value the game owns: matching objectives rise to it, never fall
log.Tick(1);                 // time passed, in the game's units: deadlines count down, one at 0 fails

if (story.Status == QuestStatus.Ready) log.TurnIn(story); // completes it and grants its rewards

Status: Active while an objective is open; Ready once every objective is done, waiting for TurnIn; then Completed, or Failed when its deadline ran out or the game called Fail.
Events: Added, Progressed (the quest and the objective's index), Ready, Completed, Failed and Removed. The game decides what follows: a story step can wait for the player to report it, and a generated quest can leave the log once it is done.
Saving: QuestState is an opt-in data contract (only its [DataMember]s are saved). A saved key that no longer resolves when the log is bound is an error: the game removed a quest that a save still holds.

Dependencies

com.cupkekgames.data 0.4.0: CatalogKey, AssetCatalog, IData, IFeature.
com.cupkekgames.services 0.2.0.

Repository

Cupkek-Games/CupkekGames-Quests