Writing the Harbormaster

Series: raising-an-island · Part 1

The harbormaster is the island’s first word. Not a welcome screen. Not a help prompt. A person — or at least the presence of a person — standing at the gate with a name and a disposition, who has been standing there since before you arrived and will be standing there after you leave.

Communiqué Zero calls the harbormaster “the island’s seal, its flag, and its refusal.” That is not hyperbole. A traveler’s first impression of your realm comes from this scripted fixture. Write it carelessly and the island feels like a template. Write it with attention and the island exists before they’ve taken a step.

The harbormaster lives in realm.toml. It cannot be edited through build mode. Its configuration is:

[realm.harbormaster]
name           = "Old Cael"
brief          = "A weathered man in an oilskin coat, watching the harbor."
customs_notice = "Your cargo's your own, long as it stays sheathed. This is the Stair."
lines = [
  "Evening. Road's washed out tonight. You'll stay.",
  "Your cargo's your own, long as it stays sheathed.",
  "The beacon's been dark since sundown. Don't expect news from the north.",
  "Seen worse crossings. You made it.",
  "Mm.",
]

[realm.harbormaster.greetings]
familiar = "Back again. Good crossing?"
partner  = "Expected you yesterday. Come in."
known    = "I remember you. Welcome back."
neutral  = "Evening. Papers in order?"
stranger = "First time. Mind the customs."

The brief

The brief is the one-line occupant description — what travelers see when they look at the border room:

  Old Cael is here, watching the harbor.

Write the brief in present tense. Show the harbormaster in the middle of doing something, not standing by waiting. There is a difference between:

A weathered man in an oilskin coat, standing by the gate.

and:

A weathered man in an oilskin coat, watching the harbor.

The second one has a direction. The harbormaster is looking at something beyond the gate — not at the traveler. That attention, turned outward, tells you something about the place. The weather matters here. The water matters. You are arriving into a situation that was already in progress.

The brief should fit the island’s character. A frontier outpost might have:

A lean woman in a canvas duster, cleaning her teeth with a knife.

A counting-house might have:

The factor sits behind his desk, pen moving without looking up.

A monastery might have:

A robed figure stands at the threshold, hands folded, watching you approach.

Keep it short. The brief is not a description — that is what look harbormaster gives. The brief is the first glimpse.

Canned lines

The lines pool is what the harbormaster draws from when addressed. A line is selected at random, without immediate repetition. The pool should be varied enough that a traveler who stays for a session hears something different each time, and specific enough that every line could only belong to this island.

Write lines that could only come from here.

Old Cael’s best line is:

"The beacon's been dark since sundown. Don't expect news from the north."

That line is doing three things: establishing that there is a beacon to the north, that it is dark, and that this is noteworthy enough to mention to a stranger. It builds the world in a single breath. A traveler who hears it starts wondering what is in the north.

Compare it to:

"Welcome to Winding Stair."

That line says the name of the place back to someone who can see the name of the place in the room header. It adds nothing. Cut it.

Lines should vary in kind, not just in mood.

A pool of five lines that are all friendly variations on “welcome” is less useful than five lines that each say something different about the island. Consider covering:

• The current weather or state of the sea
• Something recent that the harbormaster would know (a ship in, a road out, a message waiting)
• The island’s customs or character, stated obliquely
• A line that is almost silence — acknowledgment without content

That last one is worth including. Old Cael’s "Mm." is not a failure of imagination. It is a harbormaster who has seen enough travelers that not all of them merit commentary. It says something about the kind of place this is.

Write at least eight lines. Fewer and the repetition becomes audible within a single session.

The customs notice

The customs notice fires once — on a traveler’s first entry to the realm in a session, after the trust-tier greeting, before the room description. It is the only moment of necessary exposition.

customs_notice = "Your cargo's your own, long as it stays sheathed. This is the Stair."

Keep it to one or two sentences. It should name the most important rule of the island and nothing else. The temptation is to list everything — no PvP, no this, no that. Resist it. A customs notice is a customs notice, not a terms of service. The harbormaster says the one thing that matters here. The rest is discovered.

The notice should be in the harbormaster’s voice, not in the voice of a system announcement. Compare:

Players are expected to follow all posted rules.
Combat requires mutual consent.
This realm uses the standard customs policy.

versus:

Keep your blade in its scabbard and your business your own. First trouble's a warning. Second trouble's the tide.

The second one is a person speaking. It tells you about the place — there is trouble here sometimes, the harbormaster has dealt with it, there is a pattern to how it ends. That is more information than the first version, delivered as character rather than policy.

Trust-tier greetings

When a traveler arrives, the harbormaster checks their trust level and selects the appropriate greeting. Five tiers:

Write these as a relationship, not a gradient of formality. The difference between neutral and known is not that one is warmer — it is that history has accumulated. Old Cael does not become a different person for a known traveler. He becomes a person who has seen this one before.

[realm.harbormaster.greetings]
familiar = "Back again. Good crossing?"
partner  = "Expected you yesterday. Come in."
known    = "I remember you. Welcome back."
neutral  = "Evening. Papers in order?"
stranger = "First time. Mind the customs."

Notice that partner carries expectation — “Expected you yesterday.” That is specific. It implies that news travels between realms, that arrivals are anticipated, that being late matters. Use the tier to say something about the island’s relationship with the category of traveler, not just the individual.

All five tiers are optional. If a tier is absent, the harbormaster falls back to lines. If you only configure stranger and familiar, the three middle tiers draw from the general pool. This is acceptable — many harbormasters only need two registers.

A worked example

Ashpit is a hard island — a working foundry on a rocky shore, cold in all seasons, not in the habit of warmth. Here is its harbormaster:

[realm.harbormaster]
name           = "Gret"
brief          = "A stocky woman in a soot-darkened apron, arms crossed."
customs_notice = "No fire inside the smelting hall. Everything else is your problem."
lines = [
  "Wind's coming from the east. Rough night.",
  "Ironholt had a ship in yesterday. Nothing for you.",
  "The forge is running third shift. Don't let the noise bother you.",
  "You're later than expected.",
  "Mm.",
  "Watch your step on the quay. Ice.",
  "There's a message waiting. Harbormaster's desk.",
  "Come in or stay out. The door's warm on neither side.",
]

[realm.harbormaster.greetings]
familiar = "You again. Come in."
partner  = "The Thornwood ship? Docked this morning. Your timing's decent."
known    = "I remember you. Usual berth is free."
neutral  = "Business?"
stranger = "First time. Read the customs notice. Mind the forge."

Gret does not welcome you. She registers you. The island has its own concerns — the wind, the forge, the ice on the quay — and you are arriving into them. The customs notice is eleven words and leaves everything except the one rule that kills people to be discovered. The neutral greeting is one word.

That is a harbormaster who belongs to a place.

Reload

Harbormaster changes take effect on config reload. No restart required:

systemctl reload pharos-ashpit

Or from admin mode:

watch> reload

Travelers already in session do not see a change to the brief until their next look. The lines pool updates immediately.