Files
aeternalis/docs/MILESTONE-5.md
T

105 lines
6.3 KiB
Markdown

# Milestone 5: playable hub travel
Implemented for manual testing. Milestone 4.5 presentation work remains pending;
the user explicitly requested proceeding with 5. Terrain depth/traversal remains
in [the environment backlog](../planning/ENVIRONMENT-BACKLOG.md).
## Player behavior
- **Travel** opens the destination menu. Hubs accept existing characters through
travel; new characters begin in survival worlds.
- A living, connected character can use **one escape stone** to leave a survival
world before victory. This first implementation activates instantly, requires
remaining daily time and an unsheltered character, and grants no survival credit.
The stone is spent once when departure succeeds, even if arrival needs retrying.
- Harbinger victory opens a visible portal at **0, 0**. Survivors remain able to
move/jump. Use **Find victory portal**, stand within gathering range, then click
the portal or open Travel. This route consumes no escape stone.
- From a hub, switch hub instances or enter a survival world. Survival admission
remains open during collapse until admissions close, capacity fills, or the
world is destroyed. Arrival checks these conditions again.
- If travel is interrupted, the account page offers **Resume travel**. The same
pending journey can choose another available destination; escape/victory must
finish in a hub. A journey from a hub may return to its viable source hub.
- No new allowance, character, inventory, equipment ID, title, or progression is
created by travel. Existing daily-time accounting continues in hubs. Time spent
in transit is offline time. Esc closes the focused travel menu.
- Hubs have no Harbinger, collapse, gathering nodes, mobs, combat, or XP awards.
Existing crafting consumes resources and creates items without crafting or
character XP. Discovery and the expanded professions arrive in milestone 6;
learned spells and weapon proficiency arrive in milestone 7 and must use the
same character ownership and XP-location rules.
## Administration and deployment
`WORLD_KIND=survival|hub` selects the instance kind; existing populated legacy
worlds default to survival. A saved typed instance cannot change kind. Only a
legacy untyped gathering instance with no characters, corpses, or end record may
initialize as a hub, supporting empty instance bootstrap during image promotion.
Never repurpose an existing played world as a hub.
The deployment values add **hub-001** and **hub-002** for switching tests. Wait
for the new image to become ready before entering these instances. Control's
**New world** form includes an instance-type selector. Additional provisioning
requires the existing GitOps setup; its configured operator limit is unchanged.
Control refuses mob spawning, awakening the Harbinger, and ending a hub.
Admins can grant **escape_stone** through player item controls, and select it in
loot tables. It is not automatically granted to new characters. Loot drop rates
remain authored content. The existing escape activation is provisional; channels,
charges, interrupt rules and presentation can be added later.
## Persistence and compatibility
`character_transfers` stores a server-generated journey ID, request nonce,
account/source/route, character payload and accepted destination. A unique pending
transfer and a registry reservation including `transit` prevent replacement or
two destinations owning the same life.
Departure commits the item cost, source removal, registry reservation, and escrow
under the source lease/revision in one transaction. Arrival commits destination
snapshot, transfer consumption, and registry ownership under the destination
lease/revision in one transaction. Live worlds change only after commit. Lock
order is world, transfer, legacy passage, character registry. A failed validation
keeps the journey recoverable; an uncertain database result freezes its world
owner so stale state cannot keep serving gameplay. Retries return saved outcomes.
Legacy passage records remain readable for migration/history, but `/api/join`
rejects the old direct passage shortcut. Legacy survivor characters can reconnect
to their winning world and use its portal. Claims are marked during travel to
prevent stale passage copies from reclaiming a character. The legacy title ledger
migration is still a separate pending decision; this milestone preserves titles.
Do not roll back to writers that do not understand in-transit reservations while
travel records exist. Production still requires PostgreSQL/OIDC; development auth
remains loopback-only. Capacity claims have not changed.
## Manual test handoff
1. Grant a living player two escape stones. Note character/item IDs, inventory,
levels, stats, profession XP, titles and daily time. Travel to hub-001: exactly
one stone is spent; the same life and belongings arrive.
2. Reload during travel. Resume from the account page. Retry or choose another
hub if the selected one is unavailable/full; verify no duplication.
3. Switch hub-001 -> hub-002 -> hub-001. Check other connected players keep moving.
Close the Travel menu with Esc and check movement resumes.
4. Craft in the hub: resources decrease and output appears, while all XP stays
unchanged. Attack/gather and destructive hub admin commands must be rejected.
5. Enter a survival world. Verify return fails without a stone, including during
collapse. Test full/closed/destroyed destinations and late admission.
6. Defeat the Harbinger. Walk to the visible portal and travel with no stone cost.
Remote portal use must fail. Reconnect before using the portal and repeat.
7. Confirm dead, sheltered and daily-capped characters cannot initiate travel;
hub switching and world entry never refresh the daily budget.
Automated coverage includes server lifecycle, authorization/origin checks, source
and destination fencing, concurrent acceptance, interrupted travel, source loss,
destination rejection, repeated hub journeys, progression/items, and hub rules.
The PostgreSQL version runs when `TEST_DATABASE_URL` is configured. Browser
automation expansion remains a later TODO; this milestone uses manual playtesting.
Local validation passed: `npm run check`, `npm run build`,
`npm run test:contracts`, and `go test ./...` in `server`. PostgreSQL integration
was not run locally because `TEST_DATABASE_URL` was not configured. No Playwright
run was added to this milestone's local validation.