Scripting model
Sanverse has three distinct scripting surfaces for Definitive Edition:
| Surface | Runs where | Use it for | Trust level |
|---|---|---|---|
| Server-side TypeScript | Sanverse server | players, NPCs, actors, vehicles, rules, persistence and authoritative world state | trusted resource |
| Client-side TypeScript | player's Sanverse client | local input, camera, HUD, effects and local presentation | untrusted client |
| CEF/browser UI | embedded client UI | menus, forms, inventory and web-style interfaces | untrusted UI |
The server is authoritative. Client and CEF code never receive join tickets, server credentials, other players' private data or native game-memory access. A client request is validated and applied by a server resource; replicated state is then sent back to eligible clients.
Resource layout
resources/<name>/resource.json # server-side manifest
resources/<name>/dist/index.js # compiled server entry point
client-resources/<name>/resource.json
client-resources/<name>/dist/index.js
Server resources are loaded by server.json. Client resources are delivered only after a validated
join and are versioned and integrity-checked by the launcher/client runtime. CEF bundles are loaded
by a client resource and communicate with it through an explicit UI bridge.
Communication directions
| Direction | Mechanism | Example |
|---|---|---|
| server → client | named client event | show a notification or update a HUD |
| client → server | named server request/event | ask to interact with a vehicle; server validates player and distance |
| client ↔ CEF | local typed UI bridge | submit a menu form or render server-provided state |
| server ↔ native host | internal request/response | read or mutate authoritative NPC/vehicle state |
Use explicit event/request names and versioned payloads. Never trust client-supplied position, health, inventory or entity ownership; the server re-checks all gameplay mutations. Server NPCs, actors and ambient NPC toggles are server-side APIs and do not consume player slots.
API documentation conventions
Each API page will document: side, signature, parameters and limits, return value, events emitted, authority/security rules, and a runnable TypeScript example. Client APIs are documented separately from server APIs so a developer can immediately see which calls are authoritative and which are local presentation helpers.