River Oaks District

For coding agents: start with AGENTS.md, the repository map, and the setup and verification workflow. Run pnpm run agent:doctor for prerequisites and pnpm run verify for the core gate.

An inhabited science-fantasy interpretation of Houston’s River Oaks District: mapped streets and real boutique destinations, lush gardens, and human residents with varied romantic, gothic, futuristic and artistic fashion. This is an intentional shift toward a fantastic world rendered with believable materials, anatomy and movement. Play as Jevica, explore in third person, and fly in her bubble. See the creative direction and controls. Compose and share a moment with Commands → Camera · Photo mode: creative lens controls, social crops, film looks, and clean PNG downloads. Photo controls and sharing.

Level design skills

Use the nine shared agent skills to gather references, build and measure blockouts, test player routes, and review spaces before art polish. The guide includes the recommended build order and invocation examples; the skills live in .agents/skills.

Play in the desktop app

Run pnpm install --frozen-lockfile then pnpm run desktop:dev to open River Oaks in its dedicated desktop window with live reload. Use pnpm run desktop:package to build the desktop app; it requires online GitHub sign-in and waitlist approval, and opens the hosted game. Native fullscreen, window restoration, graphics preferences, and renderer recovery are included. See desktop development and verification.

Jev's garage offers a compact pink four-wheel glass-canopy car and rose motorcycle, with gold spinners, fitted passenger clothing and optional Jev smart drive through the API. Streets provide two 3.59 m clear lanes with Palo Alto-derived gutters, curbs and ramps. See vehicle controls and street geometry.

Find your next stop in the Map panel's Explore destinations atlas. It covers 31 destinations browsable by store category (Shopping & culture, Dining, Jewelry & accessories, Beauty & wellness), with search, a live map, Go, shareable links and private saved places across worlds. See places. (The gatherings panel was removed from the client; its service remains, see world events.) An opt-in, draft-only workplace test with a companion is off by default; see workplace operations.

Run the live showcase

Players join the shared town after signing in through WorkOS, with GitHub or an email code behind a Cloudflare Turnstile check, and receiving waitlist approval. The desktop app signs in with GitHub. Browser and desktop play require a town connection, even when only one player is online. Signed-in players in the shared town see each other as their selected appearance, can use town chat, and share residents, wishes, consequences, and community resources. See multiplayer setup and deployment for https://typesafe.place, WorkOS callback settings, waitlist approval, and the Node server. Local development also requires WorkOS; isolated browser acceptance fixtures use temporary local identities.

District geometry and visual assets are bundled; no GIS download is required. pnpm run dev starts the shared town alongside Vite. For optional Jev chauffeur, companion, and speech services, run the bridge in a separate terminal:

uv sync --locked
uv run river-oaks serve

pnpm install --frozen-lockfile
pnpm run dev

Open http://127.0.0.1:5173/. The walkable River Oaks District at 4444 Westheimer uses bundled OpenStreetMap geometry, 30 storefront destinations, and 98 indoor staff and guest encounters. Streets show connected players and Jevica's companion/chauffeur. The server owns residents, wishes, scenarios, and shared resources.

The Map panel (top left) and People panel (top right) sit over the street, and Settings opens as a dialog. If the connection is lost, gameplay pauses behind a reconnect screen. There is no offline gameplay mode.

Cmd/Ctrl+B toggles the Map panel; Cmd/Ctrl+Shift+B toggles play controls. Cmd/Ctrl+K opens searchable commands, ? shows contextual keyboard help, Alt+1/2/3 opens People/Map/Settings, and / searches storefronts. Escape returns from a panel to the world. Each panel's open state is remembered; shortcuts leave text entry and modal dialogs alone. Rail layout and keyboard review

The approved administrator starts as Jevica in third person; other approved accounts start as Sable. Jevica and her multiplayer Jev and vehicle controls belong to that administrator. Shared-town players can select from the other looks built on seven shipped rigs, including fox, wolf, lynx, and human styles. Meet someone nearby opens a conversation with a nearby resident; the People panel ranks encounters by distance. WASD walks, dragging looks around, Shift walks faster, and E talks to someone within reach. Z sits on a nearby bench or seat, stands up again, or waters a nearby planter; townspeople rest on the storefront benches and in the open-air salon on the Dior–Toulouse plaza too. V switches the camera; B takes off or lands, Space rises and C descends. The scene covers the roughly 254 × 290 m River Oaks District footprint at Westheimer and Westcreek.

Every destination now has a walk-in interior: press Step inside (or F at a door) to enter a furnished boutique, salon, gallery, cinema lobby or dining room with sales associates, guests and mannequins, then F again to step back out. Rooms are planned from the mapped footprints and furnished with original procedural fixtures; see visual evidence. The side trigger collapses controls for a native UHD render surface. System/Light/Dark appearance keeps the controls readable around the district’s TypeSafe neutral and pink palette.

Residents have roles, interests, routines, and per-scene conversation memories. Ima Hogg, Barbara Jordan, Hakeem Olajuwon, and Beyoncé are explicitly fictional cultural encounters with linked public biographies. Their dialogue is authored; Jev receives bounded role context and chooses immediate reactions. Clothed CC0 human rigs retain their natural faces, skin and hair, with six coordinated fashion palettes inspired by the playable characters. Shop workers inspect, prepare, serve or present at their stations, pause to attend to conversations, and resume work afterward. Storefronts are deliberately imaginative interpretations; see visual evidence and asset provenance.

Workers support role-specific trays, samples and other props with their hands; reachable counter stations lift and return the load. You can talk across low counters, and selecting a person in the directory brings you within speaking range in their room. See interaction and movement evidence for tested coverage and remaining realism work.

Mature tree models retain stems outside the widened road clearance, with distance-based detail, clipped planter shrubs and ornamental grasses. These are artistic additions informed by the source vegetation record; the independent historical canopy comparison still fails. See vegetation evidence and asset provenance.

Optional free local speech

Install the optional CPU runtime and pinned model, then start the bridge with that extra:

uv sync --locked --extra voice
uv run --extra voice python scripts/fetch_voice_model.py
uv run --extra voice river-oaks serve

On macOS, install eSpeak NG once with brew install espeak-ng. After upgrading from an older voice setup, rerun the model fetch command above to install the duration-capable model.

In Settings → Audio, choose Kokoro · local neural voices. It runs on the local CPU after the initial approximately 142 MB model download, without an inference account or API charge. The 24 encounter presets are distinct generic voices, not celebrity imitations. Device voices · local only uses installed English voices when available. Speech defaults off on reload unless an ElevenLabs key is configured for Jev; muting, changing person, hiding the tab, or closing the conversation cancels playback. Kokoro speech includes phoneme timings that drive the speaker’s mouth. Speech geometry loads on demand and is released from the figure after playback; device voices and older untimed audio retain neutral mouths. One job at a time and a bounded cache keep synthesis out of the render loop. See showcase controls and limitations.

The Scenario lab runs an illustrative neighborhood-service economy. Change demand, service fees, hourly wages, staffing, and storms; watch jobs, queues, revenue, and costs. Decisions travel through the same loopback Jev bridge, with visible live/local/safety provenance. Without a configured key, it runs local fallback and says so. Jev makes reactive micro-decisions; schedules and accounting follow deterministic rules. The browser is a development showcase, not the final UE5 renderer. See controls and model assumptions and local showcase evidence.

Optional source-data tooling

uv sync --locked
brew install gitleaks                 # macOS; required for the commit guard
sh scripts/install-hooks.sh
uv run pytest -q
uv run river-oaks acquire
uv run river-oaks observe
uv run river-oaks build --terrain data/raw/terrain.tif \
  --terrain-source data/raw/terrain-source.json \
  --canopy-reference data/raw/canopy-reference.json \
  --output unreal/Content/Data/world.json
uv run river-oaks verify --world unreal/Content/Data/world.json \
  --terrain data/raw/terrain.tif --canopy data/raw/canopy-reference.json
uv run river-oaks serve

verify currently exits 1 (failed) when supplied the observed canopy reference: generated tree coverage is still zero. Other production gates remain blocked. Exit 2 means blocked without a failing comparison; exit 0 is reserved for complete acceptance. The decision service runs at http://127.0.0.1:8765 using local rules until you supply a Jev key.

Follow the Unreal setup to compile unreal/RiverOaks.uproject, create the map, and explore it. Use UE5.8.2 and its native toolchain. Editor and Game targets compile on macOS; see engine acceptance for runtime verification status. The project is not a finished photorealistic environment.

Current evidence

• Live city/county acquisition on September 17, 2026: 10,420 parcel records and 1,026 road features. Clipping produces 9,981 parcel parts, 940 road parts, and 2,605 synthetic house masses. The bounding box includes adjacent areas; it is not an authoritative River Oaks boundary.
• Geometry retains meter coordinates in EPSG:32615 relative to [-95.425, 29.755]. Unreal converts east/north/up meters into east/south/up centimeters.
• Houses fit source parcel setbacks and use seeded Tudor, Georgian, French, or modern massing. Styles are representative choices, not surveyed labels. Owner names, addresses, and property values are not downloaded or included in NPC packets.
• The local world includes a USGS Houston DEM exported at about 8.82 m resolution and resampled to a 257×257 preview grid, with NAVD88 elevations. Its import fidelity passes; source-date and independent vertical accuracy remain unverified. UE terrain rendering is still pending.
• The H-GAC service labeled 2016 supplies a historical canopy footprint overlay. It provides no individual stems, heights, or species; the generated world still has zero trees and fails its canopy comparison. The export is about 4.32 m/pixel, not a claim about native imagery resolution.
• The 500-agent loopback smoke test covers local fallback reactions. The local benchmark measures Python decisions only; neither establishes Jev throughput nor UE frame rate.

See verification results, GIS layout, machine-readable checks, HTTP evidence, and local benchmark.

Use Jev

Copy .env.example to the ignored .env file and set TYPESAFE_API_KEY locally. Keep it out of Unreal assets and logs.

You can also open Settings → Account → Jev API key in the preview and select Use key. This manual override configures the running local bridge, including its independent Python and Unreal simulation tools; it does not run a browser-owned simulation. It stays in server memory until the bridge restarts. The browser does not save it, and the bridge never returns the key. Select Use server key to remove the override and restore the original server configuration. A configured key is validated by Jev on the next inference request.

uv run --env-file .env river-oaks serve

The adapter uses the documented POST /v1/systemone choice interface with jev-1.14.0 (pinned in src/river_oaks/jev.py), at most 32 questions per batch, four concurrent requests, and a 750 ms overall deadline. It caps starts at 15 batches per second and falls back when overloaded, late, malformed, or low-confidence. Batch priority rotates each tick to avoid starving the last agents. No remote retry backlog accumulates. Each question names its target NPC explicitly. A provided key enables billable remote calls; tests use local transports and synthetic fixtures only.

Unreal sends a snapshot at most every two seconds and never blocks movement on HTTP. One request may be outstanding; old ticks and responses older than 1.5 seconds are rejected. Local collision, schedule, and weather limits remain authoritative. seek_shelter pauses a marker in this foundation; reachable shelter navigation and vehicle lane topology remain unimplemented.

A 60 fps frame is 16.67 ms. A 300 ms network classification cannot finish in that frame; inference runs asynchronously across frames. Full-population latency and fallback frequency require a live benchmark. TypeSafe HTTP API

Test and protect changes

uv run ruff check .
uv run ruff format --check .
uv run pytest -q
pnpm test
pnpm run build
python3 scripts/check_secrets.py --all
gitleaks git --log-opts=--all --redact --no-banner --ignore-gitleaks-allow

The installed Git hook scans the staged index, blocks credential filenames even when force-added, and fails closed if Gitleaks is missing. CI runs the same protection plus a full-history scan, dependency review and pnpm/pip audits, lint, Python 3.11/3.13 tests, unit and Redis-backed server tests, the security browser e2e, preview build and parallel browser journeys on Node 24, an offline pipeline smoke test, and a Monday schedule. Actions and the scanner archive are pinned. pnpm install installs the hooks for every worktree (scripts/install-hooks.sh also checks for Gitleaks). The main ruleset requires the aggregate preview check; see testing.

Tests target observable failure modes: missing ArcGIS pages, coordinate/containment corruption, mismatched canopy placement, malformed Jev answers, bounded timeouts, overloaded HTTP requests, schedule preservation, and real secret-guard rejection in temporary Git repositories. They do not substitute for Unreal compilation, visual inspection, privacy review, or GPU profiling. Testing approach

For multiplayer capacity evidence, see the performance audit. pnpm run audit:multiplayer probes local simulation and transport; pnpm run audit:multiplayer:render measures a real hardware browser with up to 32 synthetic connected players. Local results do not establish global readiness.

Work without downloads

uv run river-oaks demo
uv run river-oaks verify --config data/generated/demo/config.json \
  --raw data/generated/demo --world data/generated/demo/world.json \
  --output data/generated/demo/report.json
uv run river-oaks benchmark --agents 500 --iterations 1000

The demo is a labeled synthetic fixture and never counts as River Oaks accuracy evidence. To explore it in Unreal, copy its world.json into unreal/Content/Data/.

Raw GIS, generated neighborhood manifests, voice weights, review queues, and Unreal binary assets remain ignored. The bundled district derivative is attributed under ODbL; surface maps and HDR lighting have CC0 source receipts. Data contracts and source catalog explain observed canopy inputs and attribution. Execution ledger records what still needs delivery.

Jevica can also Call carriage and Ride carriage from her character controls. W/S rides or reverses, A/D or arrow keys steer, and Leave carriage steps onto clear ground. The ornate rose-and-gold coach, ceramic-and-teal district palette and human residents are intentional; see world direction and character controls.

Street geometry retains the Houston map and applies Palo Alto street details.

Prince Jev now follows Jevica into bubble flight with articulated angel wings and smooth obstacle-aware banking. Use Walk with Prince Jev, then Take flight. His ElevenLabs voice defaults to Adam (s3TPKV1kjDlVtZbl4Ksh); configure the key and optional voice ID in Settings → Audio → ElevenLabs API key. See character controls.