Quest scripts

The quest script language: events, commands, values, conditions and what is checked.

Staff write quest scripts on the quest form (Quests and progress → Quests → a quest → Script). The panel compiles them to Skript (app/Services/QuestScript/: Lexer, Parser, Compiler), checks the result with the Skript linter, and publishes it with each category's addons, like Script editor projects and custom Tag skills: scripts/addons/quest-scripts/QuestScripts.sk, installed by the updater within a minute, no restart. Network-wide quests go to every category, others to their own; drafts aren't published.

The editor colours the script to match the panel, light or dark (it follows the switch at the top), with colour codes such as &6 and &#ff8800 highlighted in text and speaker names. Suggestions pop up as you type (Tab or Enter takes one, Esc closes them, Ctrl+Space asks for them), for what fits where the cursor is: commands after a ( at the start of a line, written out with their parts to fill in (Tab moves to the next); speakers after (Dialogue: and (Choice:; the quest's steps after (Await: and on; its custom script events after (Progress:; materials the network uses and custom items after (Give: and (Take:; sounds after (Sound:; fields after player.; the names after var( and save( (most used first); and blocks, functions and values elsewhere, also inside {...} in text. The speakers, steps and events are the form as it is on screen. (App\Services\QuestScript\Completions.) It checks the script as you type, against the form as it is on screen (the giver and the NPCs in the steps), and marks each problem on its line with a message. Click a problem to jump to it. A script with errors can be saved with the rest of the quest's draft, but the quest can't be published until it's fixed: the form shows each error with its line and column under the script, and Publish and "Save and publish" are refused. Warnings (a value set but never used, a (Progress) no step counts, a risky console command) don't block publishing. "The Skript it makes" shows the generated code of the draft (or of the published version when there's no draft); servers get the script only when the quest is published, within a minute.

// Breu speaks in gold everywhere in this script.
(Speakers: &6Breu)

// Lines outside any block run when the quest starts.
(Dialogue: Breu) "Heyyyyy, you're new?"
(Dialogue: Breu) "So uh, what do I call you exactly?"

(Input: var(name))

if var(name) == "" {
    player.name = "Traveler"  // the player didn't answer in time
} else {
    player.name = var(name)
}

(Dialogue: Breu) "Nice to meet you, {player.name}!"
(Dialogue: Breu) "Could you have a look round the &bharbour&f for me?"

// The script waits here until the player has finished step 1.
(Await: step 1)
(Dialogue: Breu) "Back already? Thank you, {player.name}."

on step 2 {
    (Choice: Breu) "Will you help me mend the nets?" {
        "Sure" {
            save(helped) = true
            (Give: BREAD, 3)
            (Progress: nets_mended)
        }
        "Not now" {
            (Narrate) "Breu sighs and turns back to the sea."
            (Stop)
        }
    }
}

on complete {
    if save(helped) && player.level >= 5 {
        (Money: 100)
        (Command) "give {player.username} fishing_rod 1"
    }
    (Message) "&aThanks, {player.name}!"
}

Events #

Events. Lines outside any block run when the quest starts. on step 2 { } runs when the player reaches step 2 (step 1 is the start), on complete { } when they finish, on fail { } when they fail a step (time ran out, a "Fails if" happened, they left the step's place, or a (Fail)), whether the quest then fails or the step starts over. Each event is used once; the steps must exist on the quest. In a quest that branches, on step 3 { } runs each time the player reaches step 3, from wherever they came.

Quest hooks #

Scripts can move the quest along, not only react to it. Each hook asks the panel straight away (the script action of /server/quests), and what follows (the next step's on step N, on complete, the giver's lines) runs as usual.

(Choice: Breu) "Will you help me, or keep the reward for yourself?" {
    "Help" {
        (Reward: helped_breu)
        (Step: 2)
    }
    "Keep it" {
        (Step: 4)   // the selfish ending
    }
    "Neither" {
        (Fail) "Breu won't speak to you again."
    }
}

on fail {
    (Message) "&7Talk to Breu to try again."
}
  • (Step: done) counts the current step as finished, with its step rewards, and the quest goes on as if its objectives were done (to the next step, or where "Then go to" says). (Step: 3) finishes it and goes to step 3 instead. It can't be used in on complete, and the step must exist.
  • (Fail) fails the whole quest, whatever "If they fail a step" says, and runs on fail. It can't be used in on complete or on fail.
  • (Start: slug) warns when no quest has that short name yet; the player gets the usual message when they can't start it.
  • (Reward: name) must name one of this quest's bonus rewards (the editor suggests them). It works while the quest is going and in on complete.
  • Branching and waiting: when the quest's steps go anywhere but the next one ("Then go to" on a step or objective), on step N can't assume the steps before N are done, so (Await: step 2) in on step 3 is allowed there; it waits until step 2 has really been finished in this go.

Waiting for a step #

(Await: step 2) pauses the script until the player has finished step 2, then carries on in the same run, with every var() still set. Use it to keep one conversation going across steps: say what to do, wait, then react.

  • Already done: if the step is finished by the time the script gets there, it carries on straight away. Finishing the whole quest counts as finishing every step.
  • Checked when compiling: the step must exist, and it must still be ahead at that point. In on step 3 { } steps 1 and 2 are already done, in on complete { } every step is, and after (Await: step 3) a later (Await: step 2) would never wait; each of these is an error. An (Await) inside an if or one answer of a (Choice) only counts for the lines after it in that branch.
  • Abandoned: when the quest is no longer among the player's quests for a few seconds, the script stops.
  • Leaving: a player who leaves the server (or a server restart) ends the script, and it doesn't resume when they come back. Put what must always happen in an on step N { } or on complete { } block, which run whenever the step is reached, wherever the player is.
  • There's no time limit: the script waits as long as the player stays online. The server checks twice a second, from the quest state the panel sends whenever a step changes.

Commands #

Commands are written in brackets. Text in quotes goes after the bracket.

Command What it does
(Dialogue: Breu) "Hello!" An NPC says a line ([Breu] Hello!), then a short pause.
(Narrate) "The gulls scream." Narration, in grey italics.
(Message) "&aYou found the key." A plain chat line; & colour codes work in all text.
(Input: var(name)) "What's your name?" Asks the player to type an answer in chat (the text after it is optional). Their next chat message is the answer and nobody else sees it. After 2 minutes without one, the value is "". Works with var(), save() and player.name.
(Choice: Breu) "Help me?" { "Yes" { ... } "No" { ... } } Clickable answers (2 to 9), also picked by typing their number or text. The speaker and question are optional: (Choice) { ... }. Without an answer in 2 minutes the script stops.
(Wait: 2s) Waits: 10 ticks, 2s, 3 seconds, 1 minute (up to 10 minutes).
(Command) "give {player.username} bread 1" Runs a command as the console; (Command: player) "spawn" runs it as the player. A leading / is fine. Values in {...} keep only letters, numbers and _ . : -, so a typed answer can't add arguments, @a or other commands.
(Progress: nets_mended) Counts a "Custom script event" objective ((Progress: nets_mended, 3) for more than one). Jobs and badges that count the event see it too.
(Give: BREAD, 3) / (Take: BREAD, 3) Gives or takes items: a material, or citem-<ID> for a custom item. The amount is optional (1).
(Money: 100) / (Xp: 50) In-game money on this server, and network XP.
(Sound: click) Plays a sound.
(Await: step 2) Waits until the player has finished step 2 (see Waiting for a step).
(Speakers: Tobin, Old Maren) At the top: more names that can speak, besides the quest giver and the NPCs the steps mention. A colour here is that speaker's colour for the whole script: (Speakers: &6Breu, &#ff8800Tobin).
(Stop) Ends the script here.
(Step: done) / (Step: 3) Finishes the step the player is on now; with a number, the quest then goes to that step (see Quest hooks).
(Fail) "You were seen." The quest fails, with the reason shown to the player (the text is optional).
(Start: the-next-quest) Starts another quest (by its short name, as in its web address), if the player could start it; hidden quests too.
(Reward: helped_breu) Gives one of the quest's bonus rewards (Rewards > Bonus rewards), at most once per go at the quest.

Values #

Values. var(name) is a value for this run of the script. save(name) is kept for the player (with their game mode save, so per category) and can be read in later events. player.name is what quest scripts call the player: their username until a script sets it, then shared by every quest script. Other fields can only be read: player.username, player.uuid, player.level, player.health, player.world, player.money and player.language. Values are text ("..."), numbers (5, 2.5) or yes/no (true, false); a name keeps the type it was first given. Names ignore case.

Text #

Text. {...} in text shows a value: "Hi {player.name}, you have {player.money}.". Write \" for a quote, \{ and \} for braces and \\ for a backslash. Text players read is translatable: each line is listed under Quest script lines on the Translations page (key qs.<quest id>.<code>), with its values as {name} placeholders.

Colours #

& colour and format codes (&a, &6, &l, &o, &r...) work in every text players read: dialogue, narration, messages, input prompts, choice questions and answers. A dialogue line is white after the speaker unless it sets its own colours; narration is grey italics.

  • Speakers: (Dialogue: &6Breu) "..." colours that line's name, and (Speakers: &6Breu) at the top sets it for the whole script (a colour written on a line wins). Names still match NPCs without their colours, so &6Breu is the NPC called Breu. Speakers without a colour are yellow.
  • Hex colours: &#rrggbb, e.g. "&#ff8800Sunset orange" or (Speakers: &#ff8800Tobin). Modern servers (lobby, survival, tag) show them; Pit on 1.8 can't, so there they're left out and the text keeps its other colours. Clickable choice answers can't show hex colours on any server, so they're left out of answers too. &# must be followed by six hex digits.
  • Values can't add colours: colour codes inside values shown with {...} (a typed answer, player.name, a save()) are removed when they're shown, so a player who types &4&lAdmin as their name shows as Admin in the line's own colour. Put colours in the text around the value instead: "Hi &a{player.name}&f!".

Conditions and maths #

Conditions and maths. if ... { } else if ... { } else { }, with ==, !=, <, >, <=, >=, && (or and), || (or or) and ! (or not), and brackets. Comparing text ignores capitals. + - * / work on numbers, and + joins text. repeat 3 { } runs a block several times. Functions: random(1, 10), has_item("BREAD", 3), has_permission("neutine.vip"), contains(var(answer), "yes"), length(text), lower(text), upper(text), number(text) (0 if it isn't one) and round(number). // starts a comment.

What's checked #

What's checked: unknown commands, events, functions, speakers, bonus rewards and player fields (with a "did you mean"), steps that don't exist in (Step: N), (Fail) and (Step) where they can't work, unclosed text, brackets and braces, values read before they're set on every path (including only in some branches of an if or a choice), text compared with numbers and other type mistakes, save() values never set, steps the quest doesn't have (in on step N and (Await: step N)), awaits for a step that's already done at that point, hex colours that aren't six digits, values that can't be changed, and anything the Skript linter finds in the generated code (reported on the line it came from).

The Skript it makes #

The Skript it makes keeps to Skript 2.6.5 (Pit) as well as 2.17: conditions are never joined with or/and (they're worked out into {_c} flags one at a time), nothing uses trimmed or a variable name starting with %, # in text is written ##, and text goes through Trf. Each event is a function QScript_<quest id>_<event>(p); when the panel says a quest started, reached a step or was finished (run in replies, quest_run when pushed), network/Quests/QuestStory.sk queues the run after any dialogue, and the generated file's dispatcher calls the function. The helpers it uses (QuestScript_Say, QuestScript_Ask and the chat prompt, QuestScript_Choices and /questanswer for clicks, QuestScript_Give, QuestScript_Hook for the quest hooks...) are in network/Quests/QuestStory.sk. (Await) uses the steps finished in this go (done in the state) when the panel sends them, so it's right for quests that branch or go back. (Await) reads the quest state the panel sends (each active quest's id and current step) and a "finished" mark set when the panel says the quest is complete; the panel sends start and complete for every quest with a script for this. QuestScript_Plain removes colour codes from values and QuestScript_Hex turns &#rrggbb into the form modern servers show (or drops it on 1.8). A player who leaves ends their script; another question replacing an open one ends the older script.