Skip to content

CLAUDE.md

Latest commit

 

History

History
73 lines (60 loc) · 5.84 KB

CLAUDE.md

File metadata and controls

73 lines (60 loc) · 5.84 KB

Technical Caveats

@AGENTS.md

Documentation Sync Rule

SKILL.md and CLAUDE.md MUST update on every code change. SKILL.md = agent-facing API reference (agents have NO source access). CLAUDE.md = engine internals index for contributors. No line numbers — stale immediately. Use function/file names. Deep engine internals are ingested into rs-learn (exec:recall <topic>) — this file points at them, doesn't restate them.

gh-pages Deployment Structure

  • Landing: client/landing/index.html (webjsx + 247420 design system, at /spoint/); styles via anentrypoint-design SDK (installStyles() + .ds-247420 scope)
  • Demo: /spoint/demo.html (was index.html)
  • Content: client/landing/content/ — section JSONs merged by flatspace at CI time into content.json
  • CI order: build dist → build landing → mv dist/index.html dist/demo.html → copy landing as dist/index.html
  • Singleplayer auto-redirect sed targets dist/demo.html only — never dist/index.html
  • World config path resolution: ?world=<name> loads world config (e.g. survivor.js) with playerModel: './apps/tps-game/cleetus.vrm'. Runtime path values need resolution against document.baseURI in client/app.js to inherit /spoint/ prefix. Wrap path-valued config fields in resolveWorldConfigPaths(wd) before BrowserServer.connect(wd).

Key Architecture

  • Server entry: node server.js (port 3001, 64 TPS world config, 128 TPS SDK default)
  • World config: apps/world/index.js (default); WORLD=<name> node server.js to switch
  • Apps: apps/<name>/index.js with server and client exports
  • Physics: Jolt via src/physics/World.js
  • GLB extraction: src/physics/GLBLoader.js
  • Terrain: client/TerrainSystem.js — auto-init from world config terrain field; terrain: false disables
  • Vegetation: client/VegetationSystem.js + src/terrain/VegetationPlacement.js + src/physics/VegetationPhysics.js — opt-in via vegetation: { ... }

Key File Locations

  • Physics world: src/physics/World.js (coordinator, ≤200 lines)
  • Character physics: src/physics/CharacterManager.js
  • Shape builder: src/physics/ShapeBuilder.js
  • App context: src/apps/AppContext.js
  • App runtime: src/apps/AppRuntime.js (+ mixins: AppRuntimePhysics.js, AppRuntimeTick.js)
  • Tick handler: src/sdk/TickHandler.js
  • Player collision: src/netcode/CollisionSystem.js (applyPlayerCollisions)
  • Snapshot encoder: src/netcode/SnapshotEncoder.js
  • Snapshot processor: src/client/SnapshotProcessor.js
  • Client interpolation: src/client/interpolation.js
  • Base client: src/client/BaseClient.js (extended by PhysicsNetworkClient, BrowserServer, planned WebRTCClient)
  • WebRTC transport: src/transport/RTCDataChannelTransport.js
  • Wireweave transport: src/transport/WireweaveTransport.js (per-peer wrapper around wireweave DataSession)
  • Wireweave client adapter: src/transport/WireweaveClient.js (createWireweaveClient({ namespace, room, voice }) — nostr-discovered p2p data + optional voice; URL hash → room via getRoomFromHash)
  • Edit panel DOM: client/EditPanelDOM.js
  • Maps: apps/maps/*.glb (Draco-compressed; CI strips via scripts/optimize-models.js)
  • Singleplayer Worker: src/sdk/WorkerEntry.js + client/BrowserServer.js

Engine Internals — Recall Topics

Deep reference is in rs-learn. Query with exec:recall <topic> to pull full text on demand:

  • terrain engine — createTerrainSystem, FBM worker pool, IDW early-exit, LOD skirts, biome palette slots, debug API
  • vegetation engine — placement sampler, ez-tree species bake, ground cover billboards, server/client placement parity
  • terrain collision — server-side TerrainPhysics, height formula parity with worker, COLLIDER_RES 32×32
  • singleplayer worker — WorkerEntry, BrowserServer, transferable ArrayBuffer transport, importmap requirements, AppLoader BLOCKED_PATTERNS
  • client architecture — three modes one BaseClient, SceneGraph node management, TransformLerp Map vs plain object trap, renderer + shader warmup
  • AppRuntime mixins — physics-then-tick order, dynamic body tracking, idle skip
  • entity scale parity — physics + visual must match, Jolt non-uniform scale restrictions on capsule/sphere, addTrimeshCollider deferred
  • snapshot encoding — quaternion smallest-three packing, player vs entity field order, encode/decode sync rule
  • app api — renderCtx + engineCtx, design principle (apps are config), reusable apps, primitive rendering, interactable, state survival
  • glb model loading — Draco/meshopt support, GLBTransformer + KTX2, build-time strip, IndexedDB ModelCache + GeometryCache
  • jolt wasm memory — getter destruction rules, setter reuse, raycast cleanup, capsule param order
  • physics rules — bodies in setup() only, CharacterVirtual gravity, substeps=2, Quake-style movement
  • spatial physics LOD — physicsRadius suspend/restore, body id stability, _bodyDef
  • snapshot delivery — SNAP_GROUPS rotation, static vs dynamic encoding, priority accumulator, tick dilation
  • perf optimizations — physics player divisor, idle skip, snap phase spatial cache, collision grid pruning
  • client loading pipeline — checkAllLoaded five gates, pure-terrain caveat, singleplayer VRM OOM invariants
  • hot reload — ReloadManager / AppLoader / client reload, BLOCKED_PATTERNS, exponential backoff
  • xstate convention — when to use vs boolean, isomorphic import pattern, list of xstate-backed systems
  • editor DX — EditorShell layout, Inspector direct-DOM, Apps panel + Monaco, HookFlow viewer, gizmo modes, snap grid, undo/redo
  • misc engine — WORLD_DEF entity strip, message types hex, msgpack, EventBus wildcards, debug globals, heartbeat, input rate

If a recall query returns nothing useful, the fact may have aged out — git log --diff-filter=D -p -- CLAUDE.md recovers the original deep-reference text from history.