Quests and NPCs · Black Box

The quest engine runs stories players join by talking to NPCs and objects. You build quests and conversations on the website, then put a prop, an NPC titler or a linked object in-world to touch. Use this guide to write a quest, wire it into the sim, or fix a player who got stuck.

Where it lives

Everything is under Game Design › Quests & NPCs:

Menu entry	What it’s for
Quests	The quest list, and each quest’s stages, requirements, rewards and quest items
Story map	The conversations: what each NPC or object says, and the choices
Quest NPCs & objects	Everything a character can talk to
Quest triggers	Quest steps that fire when someone finishes an object interaction
Quest progress	One character’s quests, story flags and quest items, and staff fixes
NPCs and NPC generator	NPC characters, for titlers and fights

Editing needs Quest - Edit (quest_edit) or Admin. Quest - Player Progress (quest_players) opens only the Progress tab.

Build the quest

Open Quests and press New quest. Give it a Name and a Journal description, which players read in their journal. Active off means nobody can start it. Repeatable lets them start it again once completed.
Press Add stage for each step. Number them 10, 20, 30 so you can fit more between later. Each has a Name, a Task (the journal entry) and an optional Talk to, who the journal says to see next.
Set Ends the quest on your last stages: Completes the quest or Fails the quest. Choices that send characters to different stages are how a story branches.
Save a stage, then add what happens When a character reaches this stage.
Add Start requirements if the quest needs a level, an item or another quest first, and Rewards (when it completes).
Add Quest items if the story needs props the character carries. They sit in the journal, not the inventory, and go when the quest ends or is abandoned.

The warning box at the top of a quest lists problems, such as a stage nothing sets. Copy makes a copy that starts switched off. Delete wipes every character’s progress on it.

Conditions

Conditions decide who can start a quest, which greeting shows and which choices appear. Every condition on one thing must pass. For an “or”, make two greetings or two choices.

You can check Quest status, Quest stage, Story flag, Has item, Has quest item, Level, Stat, Skill rank, Coins, Class, Race, Profession, Group member, Group role and Perk.

A story flag is a number the story remembers about a character, 0 until set. Name it anything, such as trash_burned, and use the same name where you check it. A flag tied to a quest is cleared when that quest restarts. Leave its quest empty to share it across every quest.

Effects

Effects run when a choice is picked, a stage is reached, a quest completes or a trigger fires, lowest Order first.

Effect	What it does
Start quest, Set quest stage, Complete quest, Fail quest	Move a quest. Setting a stage starts the quest if they never had it
Set story flag, Add to story flag	Change a flag
Give item, Take item, Give quest item, Take quest item	Hand things over
XP, Coins	Give, or take with a negative amount
Change class	Their HUD resets when the talk ends
Give perk	At a rank, outside level-up picks
Add group role, Remove group role, Remove from group, Group reputation	Group standing
Message	A line shown above the next line
Repair gear	Mends gear, if your game system uses repairs

A choice does all of its effects or none. If it starts a quest they can’t start, or takes items or coins they lack, it can’t be picked.

Make NPCs and objects

Open Quest NPCs & objects and press New NPC or object:

Name, and It’s: An NPC or An object.
When it has nothing to say: shown when none of its greetings fit.
NPC character (its NPC titler talks too) and Env object (its touch menu shows the choices): optional links.
Active: off means it only shows its nothing-to-say text.

Each one gets a prop description, quest:<id>, shown in the list with a copy button.

Write the conversation

Open Story map, pick the NPC or object under NPC or object, and press New line.

A Greeting is what it opens with. When several greetings fit, the highest Priority wins. Add Greets with this only if conditions so one NPC greets differently at each stage.
Click a line to edit it and Add choice. A choice has the words the player says, Then (the next line, or Ends the talk) and an Order. A line with no choices gives the player a Leave button.
Drag from a line’s + to another line to add a choice between them.
Show it even when its conditions fail shows a locked choice marked with what’s missing, such as [Level 5]. Otherwise it’s hidden.
Roll for it makes a skill check: a Saved formula or a typed one, a Target (reach it to pass), a Label on the button, and where to go If the roll fails. One try only stops a character trying again. When the roll fails holds its own effects.

Tag lines with their Quest so they show on the quest’s page. Whole quest switches the map to one quest from start to finish, across every speaker.

On the HUD, the talk shows who’s speaking, a QUEST line with their stage, the text and numbered answers. Roll results and what the effects gave or took appear above the next line.

Put it in the world

Quest prop: put the quest prop script in any object, fill in its auth key, and set the object’s description to quest:<id>. A player within 2 metres touches it to open the talk.
NPC titler: rez the NPC titler, touch it as its owner, choose Set NPC and pick the NPC. Anyone else who touches it talks to the quest NPC linked to that character. The owner gets Talk in the titler’s menu.
Linked object: a door, terminal or other world object linked as an Env object adds the greeting’s choices to its own touch menu.
Triggers: under Quest triggers, press New trigger and pick When someone completes an interaction (set up under World Building › Setup, Interactions tab), optionally Only on this env object. Then add Only if conditions, usually “quest at stage N”, and Then effects such as setting the next stage.

Test before players see it

On the Story map, press Try it as… and pick a character. You see which greeting wins, and each choice shown, locked or hidden with the reason. Nothing is applied, so later lines are judged on where the character is now.
For a real run, use a staff test character. On Quest progress, find them, pick the quest under Put them on a quest and press Start them, or start it in-world.
Touch the prop and play it through.
Check History on their progress page. Only what went wrong shows refused choices and skipped triggers, with the reason. Can they start…? checks each start requirement.
Press Reset on the quest when you’re done.

Tip: Keep the quest switched off while you test, and start your test character from Quest progress, which works on a quest that’s off. A Start quest effect won’t start it for players. A Set quest stage effect still will, so don’t rely on the switch alone if your opening choice uses one.

Fix a player’s progress

Find the character on Quest progress. For each quest you can pick a Stage and press Set stage, Complete, Fail or Reset. Untick Run its effects to skip the stage’s effects, or the rewards when completing. Reset forgets the quest for that character, with its flags and quest items. You can also set or clear Story flags and give or take quest items.

Their HUD tells them what changed, marked [Staff]. Logs › Quests shows the quest trace for everyone.

Players follow quests in their journal: the stage, the task, Talk to and what they’re Carrying. Abandon fails a quest and takes its quest items.

NPC characters

NPCs lists NPC characters, with the fight each is in and who controls it. NPC generator makes a new one from a form: a name, a class, and the other fields your sim’s character sheet type uses.

To put an NPC in a fight, open the fight under Storytellers › Party control and press Add NPC. Pick the NPC, who it’s Controlled by and its Team.

What goes wrong

The prop shows “nothing for you”: no greeting’s conditions pass, or the speaker is switched off. Run Try it as….
A choice won’t pick: the character lacks an item or coins it takes, or the economy is paused and the choice gives or takes items or coins.