Find an API
Choose by the work you want to do. The client draws and sends requests; the server validates actions and changes shared data.
New to the package? Read Understand the SDK first. For exact parameter and return types, open API signatures.
Objects and world content
| I want to… | API | Runs in |
|---|---|---|
| Add something to the editor | editorItems + objectRenderers | Manifest + client |
| Configure each placed object | propertySchema + renderer properties | Manifest + client |
| Configure the mod for a world | configSchema, useModConfig(), ctx.config | Both |
| Find ground height | useTerrainSampler(), ctx.world.getGroundHeight() | Both |
| Read nearby world entities | useWorldEntityQuery(), ctx.world.entities.findNearby() | Both; world.entities.read |
| Read or change my placed objects | ctx.objects | Server; object read/write permissions |
| Spawn temporary shared objects | ctx.entities | Server; world.entities |
| Draw those entities | useModEntityList() | Client; world.entities |
Gameplay and persistence
| I want to… | API | Permission / behavior |
|---|---|---|
| Handle a player request | onMessage + messageSchemas | Validate gameplay on the server |
| Read players | ctx.players | players.read; detached snapshots |
| Share a score or phase | ctx.state + useModState() | Replicated; not saved automatically |
| Save across restarts | ctx.storage | storage; await and check writes |
| Send a notification event | ctx.messages | Not retained for late joiners |
| Grant items | ctx.inventory | players.inventory; check boolean result |
| Grant money or XP | ctx.rewards | players.modify; check boolean result |
| Detect entry into an area | ctx.zones | world.zones |
| Register a validated interaction | ctx.interactions | world.interactions |
| Run a cooperative activity | ctx.activities | world.activities |
| Run a timer | ctx.schedule | Host-managed cleanup |
Presentation and physics
| I want to… | API | Reference |
|---|---|---|
| Animate a model | useModFrame() | Frame loop |
| Load a model or texture | useModGltf(), useModTexture() | Assets |
| Play positioned audio | useModSpatialAudio(), useModAudioBus() | Audio |
| Show a hint, objective, or dialog | useModNotifications(), useModHudSurfaces(), useModDialogs() | HUD |
| Register an input action | useModInputAction() | Input |
| Render a shared physics body | ReplicatedDynamicBox | Physics |
| Apply authoritative forces or joints | ctx.physics | Server physics |
| Release a custom resource | useModResourceScope(), ctx.resources | Cleanup |
How to read the reference
- A
Promise<T>must be awaited to obtain the result. nullusually means missing or rejected; check before using a returned ID.booleanmutations can fail. Do not show success without checking the result.- A client hook runs inside a host-mounted mod component.
- A permission is declared in
vibelands-mod.json. A TypeScript import does not grant it.
Legacy synchronous mutation results in an isolated worker are not necessarily host-confirmed completion. Use the documented return semantics and verify the result in a hosted test. Experimental ctx.operations provides selected host-confirmed operations on matching development builds.
Versions and experimental APIs
Use runtime apiVersion: 2 for public mods. ctx.operations, ctx.services, and the v3 migration output are evolving development contracts. Do not infer that a production host supports them from their presence in local SDK types. See Experimental contracts.