KAIVERSE + Oracle Social — Hard Part Plan (phase 2+)

> Written before signup/agent UX work. Re-skim after each social surface lands —

> new constraints may change zone/place linking.

Status: phase-2 started (2026-07-16) — overlay depth, LOD hysteresis, zone manifest stub, places API. Full mesh/streaming still open.

Owner: Ryan · Implementer: continue eyeball fly-tests for hard visuals.

---

0. North star

One society, two skins:

2D Oracle OS — Home Feed, Shorts, Chat, profiles, groups (present).
3D KAIVERSE — same accounts; groups claim a planet place; live social activity can mirror in-world (future).

Humans and guests are the same public-user path. Social AIs are first-class; industrial AIs stay host-only.

---

1. Planet render / LOD / distance / scale math

1.1 Goals

Correct apparent size of planets, ships, buildings at near / mid / far distances.
No “pop” or flat discs at horizon; no mesh exploding when camera approaches.
Stable world units: 1 unit = N meters (document constant in kaiverse.js / native client).

1.2 Work items

1. Inventory current distance math (camera far plane, planet radius, LODs) in browser kaiverse.js and any src/bin/kaiverse paths.

2. Define scale table: planet radius, building footprint, avatar height, draw distances.

3. LOD rungs: impostor / low / mid / high; hysteresis so LODs don’t thrash.

4. Verify FIRST-PERSON flight controls stay untouched (additive render-only layers only).

5. Eyeball loop with owner: fly → screenshot → tune (hard visual items — no blind bulk edits).

1.3 Later verification

Screenshots at 10m / 1km / 10km from a known planet.
No NaN camera / infinite matrix warnings in console.

---

2. Zone loading (multi-file assets)

2.1 Goals

Split world into zones (planet regions / biomes / social parcels).
Load only nearby zone packs; unload far packs to cap memory.
Manifest-driven: zones/<id>/manifest.json → meshes, textures, collision, spawn points.

2.2 Work items

1. Design zone manifest schema (id, bounds AABB, assets[], streamPriority).

2. Loader: async fetch + cache; cancel in-flight when leaving zone.

3. Prefer many medium files over one giant bundle for progressive load.

4. Error surface: missing zone → placeholder prop + log, never hard crash shell.

2.3 Later verification

Enter zone A only A’s assets in GPU memory estimate; leave A, enter B → A released.

---

3. Mesh overlays / glitch fixes (current pain)

3.1 Known failure modes (to catalogue in code)

Mesh overlays z-fighting / depth fighting.
Incorrect normals or double-sided flags causing flicker.
Overlay scale not matching parent mesh.
Transparent overlays sorting wrong (alpha order).
Stale overlay after zone unload (ghost geometry).

3.2 Work items

1. Reproduce each bug with a minimal scene flag (?debugOverlay=1).

2. Fix depth: polygonOffset / render order / separate pass.

3. Parent–child transform: overlays must use same world matrix pipeline as host mesh.

4. Unload hooks: dispose geometry + materials on zone exit.

5. Regression checklist in SCRATCH with before/after notes (owner fly-test).

3.3 Later verification

No flicker at grazing angles; no ghost meshes after 10 zone swaps.

---

4. Social object → place link (2D ↔ 3D)

4.1 Data model (proposed)

Place {
  id, tenantId?, groupId?,
  planetId, lat, lon | xyz,
  kind: 'building' | 'land' | 'room',
  label, createdBy, createdAt
}

Group / page / agent hub in Oracle OS may own one Place.
Creating a group later: “Pick planet from discovered set → spawn parcel.”

4.2 Work items

1. Persist places in tenant or shared public store (not host secrets).

2. KAIVERSE API: list places near camera; resolve place by groupId.

3. Spawn placeholder building from place record (box/glTF later).

4. Click in-world → open 2D group/profile; click group → “Enter place” jumps camera.

4.3 Guest rules

Public users see public places only; no host telemetry overlays.
Create place = member/guest allowed for own groups only.

---

5. Live simulation bridge (feed ↔ world)

5.1 Goals

Posts / shorts / chat spikes can update in-world props (billboards, room lights).
Not full physics sim day one — event stream is enough.

5.2 Work items

1. Event bus: social.event { type, actorId, placeId?, ts, payload }.

2. Throttle updates (max N/sec per place).

3. 2D-only users never blocked if KAIVERSE offline.

---

6. Shorts / Home Feed (product alignment)

Already in flight as social baseline; hard-part only needs:

Media URLs that can become billboard textures in places.
Guest isolation on media APIs (no host paths).

---

7. Suggested phase order (after signup/agent)

1. P0 — Home Feed + Shorts vertical player (2D), guest-safe.

2. P1 — Place schema + “group has place” metadata.

3. P2 — Zone manifest + load/unload.

4. P3 — Overlay/depth bugfix pass with owner fly-tests.

5. P4 — Live social → world mirrors.

6. P5 — 3D-first default shell (optional).

---

8. Constraints (must not violate)

No whole-file rewrite of oracle.html / kaiverse.js.
Do not break first-person flight feel.
Hard visuals: iterate with owner screenshots.
Secrets stay out of guest APIs.

---

9. Re-skim notes (update after social work)

| Date | Note |

|------|------|

| (initial) | Signup/agent first; KAIVERSE plan-only this goal. |

| 2026-07-16 | Public users now have profile (bio/pronouns/tz/email/locationLabel/interests) + social agents (/api/social-agents, DiceBear avatar). Place.createdBy can be userId or agentId. Guest public channels tightened (no kai-training in allowlist). |

| 2026-07-16 | Hard-part code: shared/kaiverse-hard-part.mjs (LOD hyst, zone validate, placeOnPlanet); kaiverse-graphics.js atmo/cloud polygonOffset; kaiverse.js overlay LOD + dispose + zones bootstrap; POST/GET /api/kaiverse/places; example zone manifest. |

---

10. Files likely involved later

kaiverse.js, oracle.html (surgical)
tools/oracle-discord/command-center-server.mjs (places API)
src/bin/kaiverse/ only if owner switches focus to native client
Zone asset dirs under kaiverse_assets/ or public/ (TBD)