First-Join Tour

# First-Join Tour by Frostyh: a guided first few minutes for new players.
#
#   New players get the tour marked first-join in tours.yml a few seconds after they join. A
#   guide walks ahead of them, the next target shows on the locator bar and in a boss bar, and
#   /tour opens their checklist. Staff build tours in game with /tour admin.
#
# The guide is a Mannequin, the player-shaped entity added in Minecraft 1.21.9: only its owner
# sees it. On an older server the tour runs the same without the guide.
#
# With Retention Lens installed, every finished step, a finished tour and a skipped tour become
# milestones there ("tour:<tour>:<step>"), so you can see whether the tour keeps players.
#
# Text is MiniMessage, written against the theme colours (<accent>, <text>, <muted>, ...).
# Updating: keys added in a new version work straight away, even with an older config.yml.

# ============================================================================
#  ████ ███ ███   ███ ███      ██  ██  ███ █   █
#  █     █  █  █ █     █        █ █  █  █  ██  █
#  ███   █  ███   ██   █        █ █  █  █  █ █ █
#  █     █  █ █     █  █     █  █ █  █  █  █  ██
#  █    ███ █  █ ███   █      ██   ██  ███ █   █
# ============================================================================
first-join:
  # Seconds after joining before the tour starts (and before a running tour resumes).
  delay-seconds: 3
  # Also give the tour to players who joined before this plugin was installed, the next time they
  # join (once). Off: only brand new players get it.
  also-existing-players: false

# ============================================================================
#   ███ █  █ ███ ███  ████
#  █    █  █  █  █  █ █
#  █ ██ █  █  █  █  █ ███
#  █  █ █  █  █  █  █ █
#   ███  ██  ███ ███  ████
# ============================================================================
guide:
  # The walking guide. Needs a 1.21.9 or newer server.
  enabled: true
  # How far ahead of the player the guide walks toward the target.
  lead-blocks: 4
  # Walking speed. A little faster than a player walks, so it never falls behind.
  speed-blocks-per-second: 5

# ============================================================================
#  ███  ███  ███ ███  █     ██  █ █
#  █  █  █  █    █  █ █    █  █ █ █
#  █  █  █   ██  ███  █    ████  █
#  █  █  █     █ █    █    █  █  █
#  ███  ███ ███  █    ████ █  █  █
# ============================================================================
display:
  # A boss bar with an arrow toward the target, the distance and the progress.
  bossbar: true
  # The target on the vanilla locator bar (the bar above the hotbar since 1.21.6).
  locator-bar: true
  # How far away the target still shows there, in blocks.
  locator-range: 6000
  # Its colour on the locator bar, as a hex colour.
  locator-color: "#ffb547"
  # A title on every new step and at the end.
  title-on-step: true

# ============================================================================
#  ███  █     ██  █ █ ████ ███   ███
#  █  █ █    █  █ █ █ █    █  █ █
#  ███  █    ████  █  ███  ███   ██
#  █    █    █  █  █  █    █ █     █
#  █    ████ █  █  █  ████ █  █ ███
# ============================================================================
players:
  # Players may skip a step marked skippable (the default for every step).
  allow-skip-step: true
  # Players may stop the whole tour.
  allow-skip-tour: true
  # Players may start the first-join tour again from /tour once it is over.
  allow-restart: true

retention-lens:
  # Record tour steps as Retention Lens milestones when Retention Lens is installed.
  record-milestones: true

# ============================================================================
#  ███ █  █ ████ █   █ ████
#   █  █  █ █    ██ ██ █
#   █  ████ ███  █ █ █ ███
#   █  █  █ █    █   █ █
#   █  █  █ ████ █   █ ████
# ============================================================================
theme:
  accent: "#ffb547"     # headings and anything the player is meant to click
  accent2: "#ffd38a"    # a lighter accent, for a second level of emphasis
  title: "#f4f7ff"      # screen titles
  text: "#c2ccdd"       # ordinary prose
  muted: "#6b7a94"      # hints, separators, anything the eye should skip
  value: "#ffffff"      # the names and numbers the screen is about
  good: "#57e08a"
  warn: "#ffc857"
  bad: "#ff6b6b"
  small-caps: false
  # Real Minecraft item pictures beside the buttons, from the client's own textures: no resource
  # pack. Needs a 1.21.9 or newer client; older ones see the words only.
  item-icons: true
  # A short sound on every click, open and result.
  sounds: true

# ============================================================================
#  █   █ ████  ███  ███  ██   ███ ████  ███
#  ██ ██ █    █    █    █  █ █    █    █
#  █ █ █ ███   ██   ██  ████ █ ██ ███   ██
#  █   █ █       █    █ █  █ █  █ █       █
#  █   █ ████ ███  ███  █  █  ███ ████ ███
# ============================================================================
messages:
  prefix: "<accent><bold>Tour</bold></accent> <muted>»</muted> "

  # ---- general ----
  no-permission: "<bad>You cannot do that.</bad>"
  players-only: "<bad>Only players can do that.</bad>"
  usage: "<text>Usage: </text><value>{usage}</value>"
  reloaded: "<good>Reloaded.</good> <muted>{count} tour(s).</muted>"
  menu-error: "<bad>That button did not work. The console has the details.</bad>"
  menu-back: "<white><icon:back></white>Back"
  menu-close: "<white><icon:close></white>Close"
  save: "<white><icon:save></white>Save"
  saved: "<good>Saved.</good>"
  yes: "<good>yes</good>"
  "no": "<muted>no</muted>"
  player-offline: "<bad>{name} is not online.</bad>"

  # ---- the tour in the world ----
  tour-started: "<text>Welcome! </text><value>{tour}</value><text> shows you around in {steps} steps.</text> <muted>/tour shows your checklist.</muted>"
  tour-resumed: "<text>Picking up </text><value>{tour}</value><text> where you left off.</text> <muted>/tour shows your checklist.</muted>"
  step-now: "<accent>Step {n}/{total}:</accent> <value>{title}</value> <muted>{text}</muted>"
  step-title: "<accent>Step {n}</accent>"
  step-done: "<good>Done: {title}</good>"
  step-skipped: "<muted>Skipped: {title}</muted>"
  tour-done: "<good>You finished {tour}. Have fun!</good>"
  tour-done-title: "<accent>Tour complete</accent>"
  tour-done-subtitle: "<text>Have fun out there</text>"
  tour-skipped: "<muted>You stopped {tour}. /tour can start it again.</muted>"
  no-tour: "<text>You are not on a tour right now.</text>"
  guide-name: "<accent>{name}</accent>"
  guide-hint: "<text>{text}</text>"
  bar-way: "<accent>{arrow}</accent> <value>{title}</value> <muted>{distance} m</muted>"
  bar-other-world: "<value>{title}</value> <muted>(in another world)</muted>"
  bar-task: "<value>{title}</value>"

  # ---- the checklist (/tour) ----
  title-checklist: "<accent>Your tour</accent>"
  checklist-head: "<title>{tour}</title> <muted>{done} of {total} done</muted>"
  checklist-done: "<white><icon:done></white><muted>{n}. {title}</muted>"
  checklist-current: "<white><icon:current></white><value>{n}. {title}</value>"
  checklist-todo: "<white><icon:todo></white><text>{n}. {title}</text>"
  checklist-how: "<text>Now: {text}</text>"
  checklist-way: "<white><icon:way></white>Show me the way"
  checklist-way-tip: "Brings your guide and the marker back next to you"
  checklist-skip-step: "<white><icon:skip></white>Skip this step"
  checklist-skip-tour: "<white><icon:close></white>Stop the tour"
  checklist-none: "<text>You are not on a tour.</text>"
  checklist-finished: "<good>You finished {tour}.</good>"
  checklist-stopped: "<text>You stopped {tour}.</text>"
  checklist-restart: "<white><icon:start></white>Start the tour again"
  title-skip: "<accent>Stop the tour?</accent>"
  skip-confirm: "<text>You can start it again later from /tour.</text>"
  skip-yes: "<white><icon:close></white>Stop it"

  # ---- the editor (/tour admin) ----
  title-admin: "<accent>Tours</accent>"
  admin-intro: "<text>New players get the tour marked first-join. Pick a tour to edit it, or make a new one.</text>"
  admin-no-mannequins: "<warn>This server is older than 1.21.9, so tours run without the walking guide.</warn>"
  admin-tour-line: "<value>{tour}</value> <muted>({id}, {steps} steps)</muted> {first}"
  admin-first-join: "<good>first-join</good>"
  admin-edit: "<white><icon:edit></white>{tour}"
  admin-new: "<white><icon:add></white>New tour"
  title-new-tour: "<accent>New tour</accent>"
  new-tour-intro: "<text>Give it a short id: lower case letters, digits, - and _.</text>"
  new-tour-input: "Tour id"
  new-tour-create: "<white><icon:add></white>Create"
  bad-id: "<bad>An id is 1 to 32 characters: lower case letters, digits, - and _.</bad>"
  tour-exists: "<text>A tour called {id} already exists; here it is.</text>"
  tour-unknown: "<bad>There is no tour called {id} (or it has no steps).</bad>"
  title-tour: "<accent>{tour}</accent>"
  tour-head: "<title>{tour}</title> <muted>id {id}</muted> <text>first-join: {first}, guide: {guide}</text> <muted>running {active}, finished {done}, stopped {skipped}</muted>"
  tour-no-steps: "<text>No steps yet. Add the first one.</text>"
  tour-step-line: "<value>{n}.</value> <muted>{type}</muted> <text>{title}</text>"
  tour-step-button: "<white><icon:step></white>{n}. {title}"
  tour-add: "<white><icon:add></white>Add a step"
  tour-add-tip: "A walk-to step starts at the spot you are standing on"
  tour-settings: "<white><icon:settings></white>Name, guide, rewards"
  tour-test: "<white><icon:test></white>Test it on me"
  tour-test-tip: "Runs the tour for you from the first step"
  tour-empty: "<bad>This tour has no steps yet.</bad>"
  tour-delete: "<white><icon:delete></white>Delete tour"
  title-delete: "<accent>Delete this tour?</accent>"
  delete-confirm: "<text>{id} and its steps are removed from tours.yml. Players' progress in it is kept but goes nowhere.</text>"
  delete-yes: "<white><icon:delete></white>Delete"
  tour-deleted: "<good>Deleted {id}.</good>"
  title-settings: "<accent>{tour}: settings</accent>"
  settings-intro: "<muted>Rewards are console commands separated by |, for example: give {player} bread 8 | eco give {player} 100</muted>"
  set-name: "Name players see"
  set-first: "Give it to new players (first-join)"
  set-guide: "Guide name"
  set-skin: "Guide skin (a player name, or empty)"
  set-rewards: "Rewards at the end"
  title-add: "<accent>Add a step</accent>"
  add-intro: "<text>What should the player do?</text>"
  add-talk: "<white><icon:talk></white>Talk to the guide"
  add-talk-tip: "Done when the player right-clicks the guide"
  add-location: "<white><icon:location></white>Walk here"
  add-location-tip: "Done when the player reaches the spot you stand on now"
  add-command: "<white><icon:command></white>Run a command"
  add-command-tip: "Done when the player runs a matching command (/sethome, /claim, /shop ...)"
  add-chat: "<white><icon:talk></white>Say something"
  add-chat-tip: "Done when the player sends any chat message"
  add-trigger: "<white><icon:reward></white>Wait for a trigger"
  add-trigger-tip: "Done when another plugin or a button runs /tour trigger <player> <key>"
  default-title-talk: "Talk to your guide"
  default-text-talk: "Right-click the guide."
  default-title-location: "Walk over here"
  default-text-location: "Follow the guide or the marker on your locator bar."
  default-title-command: "Try a command"
  default-text-command: "Run the command."
  default-title-chat: "Say hi"
  default-text-chat: "Type anything in chat."
  default-title-trigger: "Do the thing"
  default-text-trigger: "Finish it and the tour moves on."
  title-step: "<accent>Step: {title}</accent>"
  step-head: "<title>Step {n}</title> <muted>{type}</muted>"
  step-where: "<text>Target: </text><value>{where}</value>"
  step-where-missing: "<bad>the world is missing</bad>"
  step-relative: "<muted>(from spawn)</muted>"
  field-title: "Title"
  field-text: "What to do (the player sees this)"
  field-radius: "How close counts, in blocks"
  field-match: "Commands that count, comma separated"
  field-key: "Trigger key"
  field-rewards: "Rewards for this step, separated by |"
  field-skippable: "Players may skip it"
  step-here: "<white><icon:location></white>Target: where I stand"
  step-here-tip: "Moves the target to your position"
  step-up: "<white><icon:up></white>Move up"
  step-down: "<white><icon:down></white>Move down"
  step-delete: "<white><icon:delete></white>Delete step"
  type-talk: "talk"
  type-location: "walk to"
  type-command: "command"
  type-chat: "chat"
  type-trigger: "trigger"

  # ---- staff tools ----
  trigger-ok: "<good>Triggered the step for {name}.</good>"
  trigger-not-now: "<muted>{name} is not on a step waiting for that key.</muted>"
  reset-done: "<good>Reset the tour progress of {name}.</good> <muted>They get the first-join tour again on their next join.</muted>"

  # ---- help ----
  title-help: "<accent>Tours</accent>"
  help-lines:
    - "<text>/tour shows your checklist: what you have done and what comes next.</text>"
    - "<text>/tour way brings your guide and the marker back next to you.</text>"
    - "<text>/tour skip stops the tour; /tour starts it again.</text>"
    - "<muted>Staff: /tour admin (the editor), /tour start [tour] [player], /tour trigger <player> <key>, /tour reset <player> [tour], /tour reload</muted>"

# First-Join Tour: the tours. Edit them in game with /tour admin, or here and run /tour reload.
# Step types: talk (right-click the guide), location (walk to x y z within radius; relative: true
# means offsets from the world spawn), command (run a command starting with one of match),
# chat (say anything), trigger (another plugin or a button runs /tour trigger <player> <key>).
# rewards are console commands; {player} is the player's name.
tours:
  welcome:
    name: "Welcome to the server"
    first-join: true
    guide:
      name: "Guide"
      # A player name whose skin the guide wears. Empty keeps the default look.
      skin: ""
    rewards:
      - "give {player} bread 8"
      - "give {player} torch 16"
    steps:
      - id: hello
        type: talk
        title: "Say hello to your guide"
        text: "Right-click the guide next to you. It walks you through your first minutes."
      - id: look-around
        type: location
        title: "Walk over here"
        text: "Follow the guide, or the marker on your locator bar."
        relative: true
        x: 12
        y: 0
        z: 8
        radius: 4
      - id: say-hi
        type: chat
        title: "Say hi in chat"
        text: "Type anything in chat. People here are friendly."
      - id: help
        type: command
        title: "Open the help"
        text: "Run /help to see what you can do."
        match: ["/help"]
        rewards:
          - "give {player} cooked_beef 4"