Files

TheRON e199f88d4a Update handover-game-dev.md

OTIVM-II complete, OTIVM-III defined, full design corpus documented

2026-04-28 11:56:16 -04:00

12 KiB

Raw Blame History

Handover — OTIVM Game Development

Date: 2026-04-28

For: Incoming assistant (game development track)

Read this completely before doing anything

0. Your role

You are the game development assistant. You design and build the OTIVM browser game at otium.civicus.us. You work in Claude chat (claude.ai), produce one file at a time as a downloadable attachment, and Claude Code on the container commits and pushes.

You do not touch pipeline scripts, SQL schema, or TESSERA extraction code. That work belongs to the dataset assistant (see docs/handover-dataset.md). You share the OTIVM Gitea repo but work on different files.

The game is live. The server is running. Every change you make is visible to real users within seconds of pm2 restart otivm.

1. Read these files before writing any code

In order:

CLAUDE.md — workflow, three-shell model, ground rules, deployment facts
docs/architecture/infrastructure.md — container topology, API protocol
docs/architecture/terminology.md — three-layer vocabulary, naming convention
docs/architecture/latin-bridge.md — Latin terms, admission standard, semantic entries
docs/architecture/parameter-registry.md — all simulation parameters, scope, layer, maturity
docs/actors/CHARACTER-FRAMEWORK.md — six backgrounds, twelve starting parameters
docs/scenarios/SCENARIO-MERCHANT-0000.md — the BALNEA prologue, background selection
docs/scenarios/SCENARIO-MERCHANT-0001.md through 0003.md — the founding trilogy
docs/cities/CITY-OSTIA-0001.md — Ostia as pressure field, not backdrop
docs/roadmap.md — where the game is going (warning: body is stale, vision and principles still valid)
This file

The parameter registry is the bridge between the design documents and the schema. Read it before touching any database code.

2. Infrastructure

OTIVM container (otivm-dev, CT 1105)

App user: otivm
Repo at /home/otivm/OTIVM
Claude Code runs here as otivm user via work alias (cd ~/OTIVM && claude)
Python venv: /home/otivm/venv
Pipeline venv: /home/otivm/pipeline-venv
PM2 home: /home/otivm/.pm2
Node: /usr/bin/node (v22)
App port: 3000
WireGuard: 10.110.0.18

Five containers on srv-a (10.0.0.11)

See docs/architecture/infrastructure.md for the full topology. The architecture is settled: REST over HTTPS on the WireGuard mesh, one write domain per container, no shared filesystems between containers.

CT	Role
1101	tessera-pipeline
1102	tessera-store (master database)
1103	tessera-dev (aggregation)
1104	apt-cache
1105	otivm-dev (this container)

Nginx proxy

Lives on wg-pk (198.58.111.109) — not on this container
Proxies otium.civicus.us → 10.110.0.18:3000

Gitea

Repo: https://gitea.barternetwork.us/TheRON/OTIVM
Branch: main (direct push, Claude Code handles this)
MCP: connected via mcp.civicus.us — Claude chat reads any file directly

Backups

Command: vzdump 1105 --compress zstd --storage local --mode snapshot on srv-a (root shell)
Document every backup in docs/archives.md immediately after — see existing entries for format
Download each dump to workstation cold storage
Never take a backup without documenting it. Never document one not taken.

3. Stack

React 19 + Vite 8 frontend (src/)
Fastify backend (server/index.js) — serves dist/, save API, TESSERA map endpoint
data/otivm.sqlite3 — TESSERA physical data, read-only by game server
data/saves/ — per-player JSON save files (gitignored)
better-sqlite3 installed — used by server for TESSERA queries
PM2 under otivm user (never root)
Ecosystem file: ecosystem.config.cjs

4. Current game state — as of 2026-04-28

OTIVM-I — complete

Five trade routes Ostia → Alexandria, journal, otium/negotium mechanic, per-player saves via 8-char hex token, 128 concurrent players supported.

OTIVM-II — complete and live

The map is live and rendering from real TESSERA data.

src/screens/Map.jsx — fog-of-war SVG map
H7 land cells rendered at real geographic positions (lat/lon from API)
Progressive reveal by chapter — only visited waypoints are visible
Sea = permanent darkness — no data needed, no storage needed
/api/map/:h5/:epoch endpoint — H7 land/sea classification with centroids
Epoch parameterised — default roman_14bce (sl_offset_cm = -10)
data/otivm.sqlite3 — 12,005 H9 rows, five H5 waypoints, paleo_epochs table live
Session lifecycle — session_abandoned event written on new game, old saves preserved
active_dispatch, events[] in save state — sequencing substrate for future releases
galleyProgress() utility in gameState.js
Provenance fields on all routes (origin_h3_r5, origin_region, cultural_note)

Architecture decisions locked in OTIVM-II

H3 IDs on all waypoints — permanent, TESSERA-compatible
Sea hexes are dark by definition — no data, no storage
session_abandoned event — saves are never deleted, they receive a terminal event
REST API for all inter-container data flows — no shared filesystems
Per-player SQLite (128 files) replacing JSON saves — planned for OTIVM-III

Known deferred items

Journal local state does not reset on new game (React state issue, low priority)
H7 cells rendered as circles — hex geometry deferred pending client-side h3-js
Map coastline is five isolated H5 clusters — route corridor coverage deferred to OTIVM-III+
Roadmap body is stale — rewrite planned under project owner direction

5. OTIVM-III — defined, not yet started

OTIVM-III is the data plumbing release. Three things:

1. Per-player SQLite — 128 pre-provisioned databases

Replace JSON save files in data/saves/ with SQLite databases in data/players/. Pre-provision all 128 at container setup — no database created on demand under player load. The schema is defined by the parameter registry and the SQLite schema document (pending — this is the next document to be produced).

The atomic unit is time. The database is a time-series of events. Current parameter values are derived from event history. The schema must treat uncertainty, confidence, and perceived-vs-true values as first-class records, not comments.

2. RATIONES tab — the third screen

Add a third tab alongside Ledger and Map. This is the disaggregated accounts — the line items of every NEGOTIVM. Not a dashboard. A Roman merchant's RATIONES: what was spent at each ITER, on what, at what rate.

The player sees a historically authentic accounting surface. The system records parameters beneath it. Raw parameter values remain hidden or available only in advanced view.

3. Internal API for aggregation (1103)

1105 exposes an internal endpoint that 1103 can call on a schedule to collect player event snapshots for aggregation. Anonymised behavioral data only — no save file contents transferred raw.

Before any OTIVM-III code is written: Read docs/architecture/parameter-registry.md in full. The schema must not flatten AVCTORITAS into an integer. Uncertainty, observability, and perceived-vs-true are structural requirements, not optional features.

6. Design corpus — what ChatGPT produced this session

The following documents were produced in collaboration with ChatGPT and represent the design substrate for OTIVM-III and beyond. Read them in order.

Scenarios (docs/scenarios/):

SCENARIO-MERCHANT-0000.md — The BALNEA Conversation (prologue, background selection)
SCENARIO-MERCHANT-0001.md — The Bronze Forge Fire (second-order market logic)
SCENARIO-MERCHANT-0002.md — The Capuan Timber Yard Fire (upstream choke-point logic)
SCENARIO-MERCHANT-0003.md — The FAENUS Offer (capital without cargo)

These form a trilogy with a prologue. Each success condition is sharper than the last. The trilogy teaches: event → dependencies → price → capital.

Actors (docs/actors/):

CHARACTER-FRAMEWORK.md — twelve parameters, hidden traits, background rules
BACKGROUND-0001 through BACKGROUND-0006 — six asymmetric starting lives

These are not classes. They are starting parameter profiles that drift toward decision history over time (background_drift parameter).

Cities (docs/cities/):

CITY-OSTIA-0001.md — Ostia substrate: urban zones, population model, infrastructure parameters, social nodes, daily and seasonal rhythm

Ostia functions as a pressure field. It is not scenery. Every parameter in the city document connects to actor parameters and scenario triggers.

Architecture (docs/architecture/):

infrastructure.md — settled container topology and API protocol
terminology.md — three-layer vocabulary, rejected terms, naming rules
latin-bridge.md — Latin term admission standard and full semantic entries
research-brief-roman-venture.md — ChatGPT research instructions
parameter-registry.md — all parameters, scope, layer, maturity

7. The SVCCINUM thread

The amber (SVCCINUM) in the grain route cargo is not merely a goods label. It is the first explicit connection between OTIVM and CIVICVS. The amber originated in Maglemoisian forests in approximately 8000 BCE — the same territory and period that CIVICVS models. When both simulations share a TESSERA substrate, the amber in the MERCATOR's hold will be traceable to a specific H3 cell where a CIVICVS Constructor gathered or traded it.

This thread runs through the origin_h3_r5 provenance stub in constants.js, through the SVCCINUM entry in latin-bridge.md, through the occ_flag stub parameter in the registry, through to OTIVM-VIII and OTIVM-IX.

Do not lose this thread. It is the architectural consequence of building both systems on the same physical reality layer from the start.

8. Workflow — one file, one step, one confirmation

Every change follows this sequence without exception:

Claude chat discusses the change and produces one downloadable file
Human uploads to Gitea manually, or pastes into Claude Code
If code: npm run build && pm2 restart otivm
Human confirms result
Claude chat proceeds to next step

One file. One step. One confirmation. Never batch.

9. Hard rules

Never run PM2 as root — always as otivm user
Never commit secrets — no tokens, no keys, no passwords
Never push to main without building — npm run build must pass first
JSON flat files for player state — until OTIVM-III replaces them with SQLite
H3 IDs on every location — never a coordinate pair or string name alone
Never make assumptions about disk state — always read from Gitea MCP first
Uncertainty is a first-class record, not a comment — applies to all schema work
The data warehouse is the product — the game is the public interface
Real weather only in CIVICVS — DWD data always, no simulation

10. Commit message convention

Imperative mood, present tense, under 72 characters. Add Mediterranean SVG map to Map screen not Added map.

11. What the dataset assistant is doing in parallel

See docs/handover-dataset.md for full detail. Current state:

data/otivm.sqlite3 live — 12,005 rows, paleo_epochs populated, FK clean
staging_otivm.sqlite3 in sync
Pipeline venv provisioned at /home/otivm/pipeline-venv
Four datasets pending download to Drive 1 (BGR IGME5000, HYDE 3.3, KK10, HydroRivers)
Per-H5 pipeline architecture not yet designed — next dataset session task

When otium.sqlite3 is expanded with new H5 hexes (OTIVM-III first new waypoint), the game development assistant will be told. The /api/map/:h5/:epoch endpoint requires no changes — it is already parameterised by H5 ID.

Handover 2026-04-28 — game development track Claude chat designs. Claude Code implements. The human decides.

12 KiB Raw Blame History