Files
aeternalis/docs/MILESTONE-8B.md

7.3 KiB

Milestone 8b: housing controls and lifecycle checkpoint

Follow-up: 8c adds walkable interiors and updates Escape to close the controls while staying inside. Use Return to hub or the door to leave.

This checkpoint adds usable housing ownership, storage, permissions, and recovery alongside 8a's world building. Housing is presented as an interactive floor plan. Walkable 3D interiors, furniture models, in-room avatars, and controller placement remain milestone 8 work; this is not the final interior presentation. No milestone 9 cosmetics are implemented by this checkpoint.

Player controls

Open Inventory → Housing & keys. In a hub, a character who survived a world can create a named house, enter using a carried key or invitation, and recover a creator key when eligible. IDs are generated by Go. Escape closes the focused house controls and requests exit; if the request fails, the server keeps the character inside until exit is confirmed. Reopen Return to house controls to retry. Daily play time continues inside; reaching the limit exits the room.

Click the floor plan to choose a position or select placed furniture. Furniture can be placed, moved without pickup, or picked up when empty. The floor and each storage container have independent item inventories. Unique equipment and crafted stack provenance retain their identities when moved. Furniture placement uses its copied footprint; Go rejects overlap and out-of-room placement. Furniture does not grant equipped stat bonuses. Exit to use the hub crafting workbench.

Control → Content → Equipment includes furniture and storage-container fields. The additive catalog migration supplies Storage chest and House table for manual testing. Admins can grant these through the player item controls; equipment recipes can output furniture through the existing crafting system. Definitions remain immutable, with each instance retaining its copied furniture profile.

Permissions and keys

Owners and co-owners manage invitations and all six guest permissions: move, open, place furniture; deposit into furniture; pick up house items; drop house items. Baselines default to deny. Each invited character can inherit, allow, or deny each permission independently. Opening a container does not grant withdrawal or deposit rights. Withdrawal requires both open and pickup rights. Container contents are hidden from guests without open permission.

Every carried valid key grants owner rights, regardless of invitation settings. Keys are unique, transferable inventory items and ordinary corpse loot. Owners can issue additional keys and assign co-owners; co-owners can invite/remove guests and change guest permissions. Removing an invitation never invalidates a key. These invitation/issuance distinctions are provisional first-build rules.

Destroy key is available in survival worlds as well as hubs. It starts a three-second server action. The key remains valid and lootable until completion. Movement and incoming damage do not cancel it. Death, dropping/depositing that key, departure, disconnect/restart, daily cap, or explicit cancellation do. Completion rechecks the exact living holder and key under the world lease. The key registry counts other players' keys, corpse keys, and stored keys. Admins cannot bypass the action by directly removing a key from inventory.

Destroying a non-last key leaves the house active. Destroying the last key immediately archives the final house contents and removes access; there is no additional three-second house timer. Occupants return to their existing hub position when their membership is reconciled, and every action checks access again before committing. Keys on inaccessible corpses remain valid; automatic retirement of those keys requires a separate product decision.

Recovery and provisional bounds

The original creator account may recover a key to the same house before the recorded original creator's death world is destroyed. A replacement character must first survive a world. Recovery does not recreate withdrawn items or revoke other keys. Ordinary replacement progression, equipment, invitations, and titles are not inherited through this mechanism. The older account-title migration remains a separate backlog item.

Archived data is purged when the recorded death world is destroyed; an active house with valid keys survives. Missing death/world records retain data rather than inventing a purge deadline, and recovery requires a known, unlost world. Purging stored keys also updates their house registries. No recovery is possible after purge. One unpurged created house per account, 128 keys, a 12m room, 64 furniture pieces, 64 invitations, and 256 unique items per inventory/container are provisional bounds. A house's own key cannot be left inside that same house, preventing its only access item from becoming locked inside. Other house keys can be stored. Creation and entry require survival credit; escape alone grants none.

Persistence and validation

The current hub process continues to own the character. Houses are separate shared database documents, so hub-instance changes access the same room and contents. Authenticated /api/housing requests are intents. House row locking, inventory changes, key issuance/destruction, request receipts, and the fenced world snapshot commit together. Guest changes are enforced on every action; revision checks protect UI edits. An old source-world character copy cannot complete a transferred key action. Startup clears room membership and pending actions, preserving keys and house data. Upgrade all world owners before testing new item metadata across worlds; older binaries are not compatible with the new housing fields.

Tests cover baseline/individual permissions, container privacy, forbidden actions, key looting, last-key timing, death/drop/disconnect/restart cancellation, creator recovery, world-loss purge, travel, stale-world fencing, daily limits, provenance, and HTTP authentication/origin checks. SQLite runs locally; the PostgreSQL housing lifecycle test requires TEST_DATABASE_URL. Browser Playwright tests remain deferred to the existing testing backlog, with manual playtesting for this build.

Manual handoff

  1. Survive a world and reach a hub. Create a house in Housing & keys, enter, and verify Escape returns you to the hub.
  2. Grant a chest and table in Control. Place/move both; check overlaps are rejected. Deposit and withdraw resources and crafted gear; refresh/reconnect and verify the exact items and their provenance remain.
  3. Invite a second survivor as a guest. Test each baseline permission, then a per-person override. Verify open, deposit, and pickup work independently.
  4. Create an extra key. Drop it outside the house for another player to loot; verify they have owner rights even after their invitation is removed.
  5. Destroy one of two keys. Verify three seconds elapse and the house remains. Destroy the last key and verify access ends with contents retained.
  6. In a survival world, start destroying a key and die before completion. Verify it remains on the corpse. Repeat with drop, disconnect, and world travel.
  7. Test creator recovery before death-world destruction, including the replacement survival gate. Confirm archived data is purged after destruction, and active houses with another valid key remain accessible across hub switches.