Guidebook welcomes players to the places they walk into. Staff define named Areas in a world; when a player enters
one, Guidebook shows the Area's title on screen and sends its description in chat, at most once a minute per Area.
Staff create and edit Areas from WorldEdit selections and Paper dialogs, Area text is MiniMessage with a few Guidebook
tags of its own, and every Area is drawn on the web map when Dynmap runs. This page describes 2.0.1, the latest
release on master (tag v2.0.1), the Paper 26.2 rewrite. The source is public at
MCME/Guidebook under the GPL-3.0 licence.

At a glance

The repository has a GLOSSARY.md for its domain words
(Area, Shape, Warp point, Welcome, Opted out, …) and architecture decision records in
docs/adr. Read both before changing code.

How the code is organised

Everything lives under com.mcmiddleearth.guidebook.

Building and testing

./gradlew build       # compile, run Spotless and the tests, write build/libs/Guidebook-<version>.jar
./gradlew runServer   # start a Paper test server in run/ with WorldEdit and PluginUtils downloaded

• The Paper and library versions are in
  gradle/libs.versions.toml: paper-api
  26.2.build.129-stable, PluginUtils 2.0.4, WorldEdit 7.4.5, DynmapCoreAPI 3.8, StrokkCommands 2.3.0. Everything is
  compileOnly, so the jar bundles no libraries.
• Formatting: Spotless with Palantir Java Format. The build points git at .githooks/, whose pre-commit hook formats
  staged Java files; ./gradlew build also fails on unformatted code.
• Tests: JUnit 5 unit tests for the pure parts (name suggestions, file loading, legacy conversion, placement and
  overlap checks, Area text rendering, map markers). WebMapBoundaryTest keeps the webmap package free of Guidebook
  imports.
• runServer (the run-paper plugin) downloads WorldEdit from Hangar and PluginUtils from MCME's Maven repository.

CI and releases. .github/workflows/build.yml builds and tests every push to master and development, every pull
request, and every v* tag, and uploads the jar as a workflow artefact. On a v* tag it then:

1. checks that the tag matches the version in the built plugin.yml;
2. takes the release notes from the tag's dated section in CHANGELOG.md (an "Unreleased" heading fails the run);
3. publishes com.mcmiddleearth:Guidebook (with a sources jar) to repo.mcmiddleearth.com, releases or snapshots
   by the version suffix;
4. creates the GitHub release with the jar and its .sha256, titled "version X for mc Y".

A manual run from the Actions tab also publishes. The releases repository refuses to overwrite a version, so each
version is published once. Publishing needs the MCME_MAVEN_NAME / MCME_MAVEN_SECRET organisation secrets; without
them only the publish step fails.

Configuration

Guidebook ships no config.yml. Its data folder holds:

Area names are unique ignoring case and may contain only letters, digits and _ - . +. The convention is
<world>-<project>-<place>, and the name suggestions follow it.

Guidebook tags can be used in a title, subtitle or description next to MiniMessage's own tags: <guide>,
<date>…</date>, <term:'meaning'>, <wiki:page> (opens the page on Tolkien Gateway), <warp:name> (runs
/warp <name>) and <bullet>. They are permanent once stored text uses them (ADR 0004): a tag may change how it looks,
but removing or renaming one breaks every Area that uses it.

Commands and permissions

/guidebook is a Brigadier command with no aliases. Bare /guidebook, or an incomplete command, shows the help for
what the sender may run.

When you add a subcommand, put its @Permission on an @Executes("<name>") with a non-empty path, never on the class:
an empty path puts the permission on the /guidebook root and locks guidebook.user players out (ADR 0001).

APIs and extension points

GuidebookSendEvent (com.mcmiddleearth.guidebook.events) is fired on the main thread just before a player gets a
Welcome. It is Cancellable; getPlayer() gives the player and getGuidebookName() the Area's name. Cancelling it
stops that Welcome. It is not fired when the per-Area cooldown (one minute) suppresses the Welcome, and it is fired
before Guidebook checks whether the player opted out.

To compile against it:

repositories {
    maven("https://repo.mcmiddleearth.com/releases")
}

dependencies {
    compileOnly("com.mcmiddleearth:Guidebook:2.0.1")
}

Then add Guidebook to your plugin's depend or softdepend. No MCME plugin listens for the event today.

The web map API in webmap is deliberately generic (layers of markers with a circle or polygon outline and a
plain-text popup), so supporting another map (BlueMap, squaremap, Pl3xMap) means one new adapter. It is meant to move
into a shared MCME library; until then it is internal to Guidebook.

How it talks to other plugins and systems

flowchart LR
  S[Staff: /guidebook create, move, edit] --> WE[WorldEdit selection]
  S --> D[Paper dialogs]
  D --> F[(Area files per world)]
  F --> PU[PluginUtils regions]
  T[Every second: player inside an Area?] --> E{GuidebookSendEvent cancelled?}
  E -- no --> W[Welcome: title, boss bar, chat]
  F --> M[Dynmap layer 'Guidebook']

Further reading

• README,
  CHANGELOG (upgrade notes from 1.x),
  GLOSSARY and
  ADRs on master
• Setting up, Maven repository
• Guidebook manual on the forum, the manual the in-game help links to