New Player Onboarding¶

Design Philosophy¶

The game teaches through play, not menus. No modal tutorial sequence interrupts the session. Instead, contextual prompts surface exactly once at the right moment, the board is always visible, and every system introduces itself through a real task rather than a practice scenario.

The onboarding arc is the village intro arc defined in character-origins.md. This document covers the client-side flow that wraps that arc: what screens appear, when prompts fire, how the game surface expands as the character progresses, and how the system knows onboarding is complete.

Stage 0 — Account Creation and Character Setup¶

Account creation is handled on a minimal pre-game screen. On first login the character creation flow launches immediately — no home screen, no slot selection. The creation flow is covered in character-origins.md.

After character creation confirms, the server:

Creates the character record with village origin, lineage, archetype, background
Seeds the village intro arc: sets arc state to intro_arc_active, creates the first 2 board tasks for the character's home village
Issues the character's starting inventory (pocket coin, a small ration pack, a basic tool appropriate to the archetype)
Sets first-login flag: flags.first_session = true

Stage 1 — First Screen: Village Board¶

The character's first view is the village board. Not a character sheet, not a tutorial popup, not a world map. The board.

The village board loads with exactly the intro arc's first two tasks visible and no other noise. A single inline header appears above the task cards:

"You've just arrived at [Village Name]. These are the jobs available to you. Pick one to begin."

This header is rendered as a soft announcement row (--text-muted text, no border, no icon). It appears only when flags.first_session = true and only on the board route. It does not repeat on subsequent visits.

The board UI is otherwise identical to the full board: task cards with type, reward, and duration. The player clicks Accept on a task and reads the flavor text. No tutorial gates this.

Stage 2 — First Expedition Accepted¶

When the player accepts their first task, the first_session flag context advances. A single one-time sidebar note appears in the expedition status panel:

"Your expedition is underway. You'll get a result when the time is up — check back later or keep an eye on the status bar at the top."

This note appears once, inline in the expedition panel, in --text-muted italic. It dismisses automatically when the expedition resolves or when the player navigates away.

No popup. No countdown tutorial. The note just exists in the panel as context.

Stage 3 — Village Arc Progression¶

The intro arc runs for 3–5 tasks depending on village origin (see character-origins.md). As the character completes tasks:

Each task completion auto-generates the next arc task in the board queue
Completed arc tasks are visually distinguished with a subtle check mark on the board history
No explicit "arc progress" UI is shown; the player simply sees new tasks appear

Contextual Prompts by Arc Task¶

Prompts fire once, inline, at the specific moments below. All use --text-muted styling, appear in the relevant panel (not as modals), and do not repeat.

Moment	Panel	Prompt text
First task completion	Board	"Task complete. Your reward has been added to your inventory."
First item received	Inventory	"Items you carry appear here. You can equip gear, use consumables, or hold materials for a delivery."
First coin reward	Wallet / character header	"Coin earned. You can spend coin at NPC vendors, on caravan seats, or at the market in Trevalkaan."
First task that involves delivery	Expedition panel	"This task asks you to deliver something. Make sure it's in your inventory before departing."
Character reaches Familiar band in any skill	Skill section (character sheet)	"Skill improved. Skills grow through use — the more relevant work you do, the further they develop."

These are the only onboarding prompts in the village stage. No further interruptions.

Stage 4 — Letter of Introduction and Travel¶

The final intro arc task always ends with the character receiving the Letter of Introduction and committing to the road to Trevalkaan. The client handles this as follows:

The final task card resolves normally
A one-time board announcement row appears at the top of the village board:

"You've earned a Letter of Introduction to Trevalkaan. The city board — and everything beyond it — is now within reach. Travel when you're ready."

The Trevalkaan travel expedition appears as a new task card, flagged intro_travel
The Trevalkaan board preview unlocks: the player can now view Trevalkaan's board in read-only mode before traveling (orders visible but cannot be accepted)
The Trevalkaan board shows a one-time header in the preview pane: "These orders will be available once you arrive."

The character travels to Trevalkaan as a standard expedition. No cutscene, no loading screen. The character resolves as arrived, village board is replaced by Trevalkaan access in the location selector.

Stage 5 — Trevalkaan Arrival¶

On arrival, the server:

Marks flags.intro_arc_complete = true
Removes the intro_arc_active state
Delivers the NPC delivery reward from the village contact (the item or parcel carried for the contact in Trevalkaan)
Unlocks: Adventurers Hall registration, Crafters Hall registration, Trevalkaan market, regional board, caravan board

The Trevalkaan board loads normally. A final one-time header appears:

"Welcome to Trevalkaan. Register with the Hall, check the board, and get to work."

The Adventurers Hall registration is a board action itself — a one-click task card that auto-completes if accepted, adds F-rank to the character's guild record, and prompts the first Hall board order.

From this point onboarding is complete. No further contextual prompts from the onboarding system fire (skills, codex, guilds, and other systems have their own first-use prompts, defined by those systems).

Stage 6 — Returning Sessions¶

After the first session ends (browser close, session idle timeout), the next login lands on the expedition status panel if any expedition is active, or the board if the character is idle in a location.

A returning player never lands on a home screen or a tutorial recap. They land where work is.

Onboarding State Machine¶

The server tracks onboarding via the character flags object in D1. Client reads flags from the character session response.

Flag	Set when	Cleared when
`flags.first_session`	Character created	First board load complete
`flags.intro_arc_active`	Character created	Letter of Introduction received
`flags.intro_travel_pending`	Letter received	Travel expedition completes
`flags.intro_arc_complete`	Arrival in Trevalkaan	Never cleared
`flags.hall_registered`	Hall F-rank accepted	Never cleared

Client uses flags.intro_arc_complete to suppress all onboarding prompts globally. If the flag is absent or false, the contextual prompt system is active. If the flag is true, all onboarding prompt checks short-circuit.

Anti-Patterns Avoided¶

Anti-pattern	Why avoided
Tutorial modal blocking the screen	Breaks browser-fit async model; player cannot see the board
Forced skill tutorial ("Press this button")	Condescending; the task card already explains what to do
Practice expedition with fake rewards	Creates false economy state; better to use real starter tasks
Separate tutorial mode	Bifurcates testing and produces dead code fast
Skip tutorial button	Implies the tutorial has value worth skipping; better to have none

Returning Player Handling¶

A character who has completed flags.intro_arc_complete = true and returns after a long absence (30+ days) receives a one-time return notice in their message log, not a re-tutorial:

"Welcome back. Check the board — the world has moved while you were away."

The message log highlights any expeditions that auto-resolved, any supply changes that affected their town, and any board orders that expired. No new prompts fire.