Plugins / First-Join Tour

First-Join Tour Coming soon

A guide that walks new players through their first minutes: the next target on the locator bar, a checklist and rewards.

Get First-Join Tour

Coming soon Not on sale yet. This page gets a buy button the day it is.

Overview

First-Join Tour

New players do not read your rules channel. Give them a guide who walks them to the right places instead.

A new player joins, looks around for ten seconds and leaves, because nobody showed them what to do. First-Join Tour starts a short guided tour the moment they join: a guide walks a few blocks ahead toward the next spot, the target shows on the vanilla locator bar, a boss bar points the way, and every step pays a small reward. You build the tour in game, in a dialog editor, without touching a file.

Plugin name in /plugins: FirstJoinTour
Latest version: 1.0.0
Server: Paper or Purpur, Java 21
BuiltByBit: coming soon

What changed in 1.0.0

A guided tour that starts on a player's first join and resumes where they left off.
A walking guide (Mannequin, 1.21.9+) only its player sees, the target on the vanilla locator bar and a boss bar with an arrow.
Step types: talk to the guide, walk to a place, run a command, chat, trigger by command.
Rewards per step and at the end, a checklist for players, and an in-game tour editor.
Records tour steps as Retention Lens milestones when Retention Lens is installed.

Features

Why server owners pick it

A walking guide that only the new player sees: it leads the way, turns toward the target and says hello when right-clicked
The next target on the vanilla locator bar, in your colour, plus a boss bar with an arrow and the distance
Steps for everything a first session needs: talk to the guide, walk somewhere, run a command (/sethome, /claim, /shop), say hi in chat, or anything another plugin signals
A checklist players open with /tour, and rewards per step and at the end
Build and change tours in game: add a step where you stand, reorder, set rewards, test it on yourself

What makes it different

Built on Minecraft's newest features: the guide is a Mannequin (the player-shaped entity added in 1.21.9) and the target uses the locator bar from 1.21.6. No fake players, no packet library, no resource pack
Private: each player sees only their own guide and their own marker, nobody else's
Resumable: a player who leaves halfway picks up at the same step next time
Measurable: with Retention Lens installed, every step, a finished tour and a stopped tour are recorded as milestones, so you can see whether the tour keeps players
Still works on older servers: below 1.21.9 the tour runs without the guide

What you get

The tour: starts a few seconds after a player's first join, or by command for anyone; one tour is the first-join tour, you can have as many as you like
The guide: a Mannequin with your guide's name and any player's skin, walking ahead at a steady speed, showing the current step under its name
Locator bar target in your colour, and a boss bar with an arrow, the distance and the progress
Step types: talk (right-click the guide), walk to a place (fixed, or relative to spawn so a fresh map works out of the box), run a command, chat, trigger (/tour trigger <player> <key> from a menu, a button or the console)
Rewards: console commands per step and at the end ({player} is filled in)
Checklist for players: done, current and next steps, "show me the way", skip a step, stop the tour, start it again later
In-game editor: tours, steps, titles, text, radius, commands, trigger keys, rewards, guide name and skin, move up and down, test on yourself, how many players are running, finished or stopped each tour
Every word is yours: all messages, buttons and titles in config.yml, in MiniMessage, with one colour theme

FAQ

Do players need a mod or a resource pack? No. The guide and the locator bar are vanilla. The locator bar needs a 1.21.6 or newer client; the boss bar works for everyone.

Can other players see someone's guide? No. Each guide and each marker is shown only to its owner.

What if my server is older than 1.21.9? The tour still runs, with the boss bar and the checklist, without the walking guide.

Can a step wait for another plugin? Yes: a trigger step finishes when anything runs /tour trigger <player> <key>, for example a menu button or a quest plugin.

Where is the data? Tours in plugins/FirstJoinTour/tours.yml, progress in tour.db. Nothing is sent anywhere.

Updates

1.0.0: first release.

Docs

Full documentation: zeropvp.xyz/plugins/firstjointour

Questions and requests: support Discord

Installation

Requirements

Server software: Paper, or a Paper fork such as Purpur. Spigot and CraftBukkit are not supported: the plugin uses Paper-only APIs.
Minecraft version: plugin.yml api-version 1.21; built against Paper API 1.21.11
Java: 21 or newer
Required plugins: none
Optional plugins: RetentionLens
Libraries: org.xerial:sqlite-jdbc:3.53.2.1, downloaded by the server at startup (plugin.yml libraries)

Steps

Download FirstJoinTour.jar from BuiltByBit. There is no licence key to enter.
Stop the server and put the jar into the plugins folder.
Start the server. The plugin creates plugins/FirstJoinTour/config.yml with the defaults shown under Configuration.
Edit config.yml to suit your server.
Apply the changes with /tour reload (Read config.yml and tours.yml again), or restart the server.

Commands

From plugin.yml. "Not set" in the permission column means plugin.yml attaches no permission to the command itself; the nodes the plugin checks are listed under Permissions.

Command	Aliases	Usage	Description	Permission
`/tour`	`/guide`, `/firstjointour`	`/tour [skip\|way\|help\|admin\|start\|trigger\|reset\|reload]`	Your tour checklist, or the tour editor for staff.	not set

Subcommands in detail

/tour                              Your checklist (aliases: /guide, /firstjointour)
/tour way                          Bring your guide and marker back next to you
/tour skip                         Stop the tour (it can be started again)
/tour admin                        The tour editor
/tour start [tour] [player]        Start a tour for yourself or someone else
/tour trigger <player> <key>       Complete a trigger step (menus, buttons, console)
/tour reset <player> [tour]        Reset a player's tour progress
/tour reload                       Read config.yml and tours.yml again

Permissions

From plugin.yml.

Node	Default	Description	Children
`firstjointour.restart`	everyone	Start the first-join tour again after finishing or skipping it.	none
`firstjointour.exempt`	nobody until granted	Never get the first-join tour automatically.	none
`firstjointour.trigger`	operators	Run /tour trigger for any online player (menus and other plugins use this from the console).	none
`firstjointour.admin`	operators	Open the tour editor, start and reset tours, reload.	`firstjointour.trigger`

Placeholders

This plugin registers no PlaceholderAPI placeholders.

Configuration reference

The default files as they ship in the jar, with their comments. The plugin writes them to plugins/FirstJoinTour/ on first start.

config.yml

Top-level keys:

Key	Default	Comment above it
`first-join`	section, 2 keys	none
`guide`	section, 3 keys	none
`display`	section, 5 keys	none
`players`	section, 3 keys	none
`retention-lens`	section, 1 key	none
`theme`	section, 12 keys	none
`messages`	section, 132 keys	none

plugins/FirstJoinTour/config.yml

# 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>"

tours.yml

Top-level keys:

Key	Default	Comment above it
`tours`	section, 1 key	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...

plugins/FirstJoinTour/tours.yml

# 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"

FAQ

Which servers and versions does it run on?

It needs Paper or a Paper fork such as Purpur, because it uses Paper-only APIs (the dialog API for its menus, Adventure text components). Spigot and CraftBukkit are not supported. plugin.yml declares api-version 1.21, the jar is built against Paper API 1.21.11, and it needs Java 21 or newer.

Does it need other plugins?

No other plugin is required (plugin.yml has no hard dependencies). Optional: RetentionLens (plugin.yml softdepend), used when present. The server downloads org.xerial:sqlite-jdbc:3.53.2.1 at startup, so it needs internet access on first start.

How do I apply config changes?

Edit plugins/FirstJoinTour/config.yml and run /tour reload (read config.yml and tours.yml again). A restart works too.

Does it run on Folia, or for Bedrock players?

Not tested on Folia, and plugin.yml does not declare folia-supported. Bedrock players (through Geyser) have not been tested either.

What licence do I get?

The licence terms are the BuiltByBit EULA shown on the listing. There is no licence key to enter, and the plugin never contacts a licence server.