ActivateQuest
Referee: put one of the adventure's quests into play.
Full documentation: ActivateQuest. Wire type: activate_quest.
Legal session modes: battle, encounter, exploring, game_over, town, victory
JSON Schema
{
"description": "Referee: put one of the adventure's quests into play.\n\nThis is the first of the quest commands, which change an adventure's quest state:\n`ActivateQuest`,\n`RevealObjective`,\n`CompleteObjective`, and\n`CompleteQuest`. Each quest has a status that\nmoves from `inactive` to `active` to `completed` and never back. Each of its objectives\nis either hidden or revealed, and either complete or not. The session stores this state,\nand only the quest commands change it, so a replay of the command log rebuilds it.\n\nThe quest commands accept only the quest and objective ids that the adventure's\n`QuestSpec`s define, and refuse any other id, because\nthe player view gets an active quest's name, offer, and objectives from its spec.\n`MarkTriggerFired` is different and\naccepts any trigger id.\n\nIssue the quest commands yourself when you run the quests in your code. To have the\nquests run from the rules in the adventure instead, register an\n`Interpreter`.\n\nWhen the quest's author wrote an `offer` text in its narrative, an accepted activation\nadds that text to the journal, and the event includes it. No\n`JournalEntryAddedEvent` follows, because\nthe quest's event already includes the text. Only an `inactive` quest can be activated.\nThis command is legal in every mode, `game_over` and `victory` included.\n\nModes:\n `town`, `exploring`, `encounter`, `battle`, `game_over`, `victory`\n\nRejections:\n - `session.command.unknown_quest` - `quest_id` matches no quest of the\n adventure.\n - `session.command.quest_state` - the quest is already active or already\n completed. The rejection includes the quest id and its current state.\n\nEvents:\n `QuestActivatedEvent` with the\n quest id, the quest's name, and the offer text.\n\nExamples:\n A game runs one quest from start to finish itself: it activates the quest,\n completes its objective, and completes the quest, which ends the adventure.\n\n ```python\n from osrlib.core.alignment import Alignment\n from osrlib.core.character import CHARACTER_CREATION_STREAM, create_character\n from osrlib.core.events import Visibility\n from osrlib.core.rng import RngStreams\n from osrlib.core.ruleset import Ruleset\n from osrlib.crawl.adventure import Adventure, TownSpec\n from osrlib.crawl.commands import ActivateQuest, CompleteObjective, CompleteQuest\n from osrlib.crawl.dungeon import DungeonSpec, LevelSpec\n from osrlib.crawl.narrative import NarrativeBlock\n from osrlib.crawl.party import Party\n from osrlib.crawl.quests import ObjectiveSpec, QuestSpec, TriggerClause\n from osrlib.crawl.session import GameSession\n from osrlib.crawl.triggers import DungeonEnteredPattern, ItemAcquiredPattern\n from osrlib.messages import format_message\n\n stream = RngStreams(master_seed=7).get(CHARACTER_CREATION_STREAM)\n hero = create_character(\n name=\"Hild\", class_id=\"fighter\", alignment=Alignment.LAWFUL, ruleset=Ruleset(), stream=stream\n ).character\n level = LevelSpec(number=1, width=1, height=1, entrance=(0, 0))\n crypt = DungeonSpec(id=\"crypt\", name=\"The Old Crypt\", levels=(level,))\n find = ObjectiveSpec(\n id=\"find\", name=\"Find the relic\", when=TriggerClause(pattern=ItemAcquiredPattern(item_id=\"holy_water\"))\n )\n relic = QuestSpec(\n id=\"relic\",\n name=\"The Lost Relic\",\n activation=TriggerClause(pattern=DungeonEnteredPattern(dungeon_id=\"crypt\")),\n objectives=(find,),\n concludes_adventure=True,\n narrative=NarrativeBlock(offer=\"The abbot wants the relic back.\", completion=\"The relic is home.\"),\n )\n adventure = Adventure(name=\"A First Delve\", town=TownSpec(name=\"Threshold\"), dungeons=(crypt,), quests=(relic,))\n session = GameSession.new(Party(members=[hero]), adventure, seed=7)\n\n result = session.execute(ActivateQuest(quest_id=\"relic\"))\n print([format_message(event) for event in result.events])\n # ['A new quest: The Lost Relic. The abbot wants the relic back.']\n print([objective.state for objective in session.view(Visibility.PLAYER).quests[0].objectives])\n # ['incomplete']\n\n session.execute(CompleteObjective(quest_id=\"relic\", objective_id=\"find\"))\n result = session.execute(CompleteQuest(quest_id=\"relic\"))\n print([event.code for event in result.events], session.mode)\n # ['session.quest.completed', 'session.adventure.completed'] victory\n print([entry.text for entry in session.view(Visibility.PLAYER).journal])\n # ['The abbot wants the relic back.', 'The relic is home.']\n\n # Quest state only moves forward, so a second activation is refused.\n print(session.execute(ActivateQuest(quest_id=\"relic\")).rejections[0].code)\n # session.command.quest_state\n ```",
"properties": {
"command_type": {
"const": "activate_quest",
"default": "activate_quest",
"title": "Command Type",
"type": "string",
"description": "The name that identifies the command class in serialized data. Each command class fixes\nit to a distinct snake_case string, like `\"move_party\"` or `\"open_door\"`, and constructing\nthe class sets it, so you never pass it yourself.\n`parse_command` and the\n`AnyCommand` union use it to rebuild the right class\nfrom a serialized mapping. A class's value never changes between releases."
},
"source": {
"anyOf": [
{
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Source",
"description": "Who or what issued the command on whose behalf: an authored trigger or quest id, or the\nname of one of your game's systems. The engine never reads it, so a command with a\n`source` does exactly what the same command without one does. The session logs and\nreplays it with the command, so the log alone shows why something happened. Leave it\n`None` when there's nothing to record. An empty string fails validation when the command\nis constructed."
},
"quest_id": {
"minLength": 1,
"title": "Quest Id",
"type": "string",
"description": "Which quest to put into play, by\n`QuestSpec.id` from the adventure's quests. The session\nrefuses an id that matches no quest spec with `session.command.unknown_quest`."
}
},
"required": [
"quest_id"
],
"title": "ActivateQuest",
"type": "object"
}