Skip to content

HowTOExample1.md

Latest commit

 

History

History
278 lines (193 loc) · 7.77 KB

HowTOExample1.md

File metadata and controls

278 lines (193 loc) · 7.77 KB
Raw

How To Example 1: Building a Multi-User Metaverse Scene

This example shows a typical sequence of API calls for creating and evolving a shared metaverse world with multiple users, scene assets, and portals.

Scenario

Imagine a virtual world with:

  • a central lobby
  • a few interactive assets (chairs, lamps, signs)
  • a portal to another area
  • multiple users entering and editing the world at the same time

The API is centered around a shared scene graph, so the main job is to create nodes, attach them to parents, update their positions or appearance, and watch for live changes from other users.

Step 1: Open the world and load basic metadata

First, a client should load the current world summary.

curl http://localhost:3000/wow/world

Example response shape:

{
  "content": {
    "label": "OpenSpatialWorld",
    "version": 1
  },
  "users": {
    "active_user_count": 1,
    "total_user_count": 1
  },
  "views": {
    "view_count": 1
  },
  "portals": {
    "portal_count": 1
  }
}

Step 2: Load the root scene node

The root node is the top of the scene graph and is usually the starting point for building the world.

curl http://localhost:3000/wow/scene/node/0

This returns the root node and any child references that define the scene structure.

Step 3: Connect to the live event stream

Open a WebSocket connection to the event endpoint so the client can receive live updates from other users.

ws://localhost:3000/events

The server will broadcast messages such as:

  • user_joined
  • user_left
  • node_created
  • node_updated
  • node_deleted

Step 4: Create a lobby node

Create a parent node that represents the lobby area.

curl -X POST http://localhost:3000/wow/scene/node/0 \
  -H "Content-Type: application/json" \
  -d '[{"label":"Lobby","children":[],"localTransform":[1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1]}]'

The server responds with the created node, including an assigned numeric id.

Step 5: Add a portal node under the lobby

Create a portal node as a child of the lobby.

curl -X POST http://localhost:3000/wow/scene/node/1 \
  -H "Content-Type: application/json" \
  -d '[{"label":"Portal to Arena","children":[],"spatialAssetURI":"https://example.com/assets/portal.glb"}]'

Here 1 is the id returned for the lobby node in the previous step.

Step 6: Add a prop asset under the lobby

Add a lamp or chair asset as another child node.

curl -X POST http://localhost:3000/wow/scene/node/1 \
  -H "Content-Type: application/json" \
  -d '[{"label":"Lamp","children":[],"spatialAssetURI":"https://example.com/assets/lamp.glb"}]'

Step 7: Position or style the new assets

Once an asset exists, update it with placement or appearance details.

curl -X PUT http://localhost:3000/wow/scene/node/2 \
  -H "Content-Type: application/json" \
  -d '{"label":"Lobby Lamp","localTransform":[1,0,0,0,0,1,0,0,0,0,1,0,0,2,0,1]}'

The nodeId in the URL should be replaced with the actual id returned by the create call.

Step 8: Load a view or portal definition if needed

If the scene includes special viewpoints or teleport destinations, fetch them explicitly.

curl http://localhost:3000/wow/view/1
curl http://localhost:3000/wow/portal/1

Step 9: React to remote updates from other users

As other users connect, create nodes, or update nodes, your client will receive event messages over the WebSocket connection.

Typical handling logic:

  • on user_joined, show presence
  • on node_created, refresh the scene tree
  • on node_updated, update the relevant node in the UI
  • on node_deleted, remove the node from the local view

End-to-end flow summary

A typical authoring sequence is:

  1. GET /wow/world
  2. GET /wow/scene/node/0
  3. Open ws://localhost:3000/events
  4. POST /wow/scene/node/0 to create the main area
  5. POST /wow/scene/node/{lobbyId} to create child assets and portals
  6. PUT /wow/scene/node/{assetId} to refine placement and appearance
  7. GET /wow/view/{viewId} or /wow/portal/{portalId} as needed
  8. Continue listening to /events for concurrent changes from other users

Sequence diagram

sequenceDiagram
    participant ClientA as Author Client A
    participant Server as simpleWorlds API
    participant ClientB as Author Client B

    ClientA->>Server: GET /wow/world
    Server-->>ClientA: world summary

    ClientA->>Server: GET /wow/scene/node/0
    Server-->>ClientA: root scene node

    ClientA->>Server: Open WebSocket /events
    Server-->>ClientA: user_joined

    ClientA->>Server: POST /wow/scene/node/0
    Server-->>ClientA: created lobby node

    ClientA->>Server: POST /wow/scene/node/{lobbyId}
    Server-->>ClientA: created portal node

    ClientA->>Server: POST /wow/scene/node/{lobbyId}
    Server-->>ClientA: created asset node

    ClientA->>Server: PUT /wow/scene/node/{assetId}
    Server-->>ClientA: updated node

    ClientB->>Server: Open WebSocket /events
    Server-->>ClientB: user_joined
    Server-->>ClientA: user_joined

    ClientB->>Server: POST /wow/scene/node/{lobbyId}
    Server-->>ClientB: created node
    Server-->>ClientA: node_created

    ClientA->>Server: GET /wow/portal/1
    Server-->>ClientA: portal data
Loading

Example 2: User joins, edits, and deletes a node concurrently

This second example focuses on the live collaboration pattern: a user joins, a second user edits an existing node, and then one of them deletes it.

1. User A joins the world

User A opens the app and connects to the event stream.

curl http://localhost:3000/wow/world
ws://localhost:3000/events

The server creates a temporary user record and broadcasts a user_joined event.

2. User A loads an existing node

Suppose User A wants to edit an existing node with id 7.

curl http://localhost:3000/wow/scene/node/7

3. User B joins and edits the same node

User B opens a second client, connects to the same event stream, and updates the node.

curl -X PUT http://localhost:3000/wow/scene/node/7 \
  -H "Content-Type: application/json" \
  -d '{"label":"Updated Sign","localTransform":[1,0,0,0,0,1,0,0,0,0,1,0,0,1,0,1]}'

The server responds with the updated node, and both clients receive a node_updated event over /events.

4. User A deletes the node

User A decides to remove the node entirely.

curl -X DELETE http://localhost:3000/wow/scene/node/7

The server removes the node and its subtree and broadcasts a node_deleted event.

5. User B receives the deletion event

Because User B is still listening to /events, it receives the deletion notice and should remove the node from its local UI immediately.

Sequence for Example 2

sequenceDiagram
    participant UserA as User A
    participant UserB as User B
    participant Server as simpleWorlds API

    UserA->>Server: GET /wow/world
    Server-->>UserA: world summary

    UserA->>Server: Open WebSocket /events
    Server-->>UserA: user_joined

    UserA->>Server: GET /wow/scene/node/7
    Server-->>UserA: node data

    UserB->>Server: Open WebSocket /events
    Server-->>UserB: user_joined
    Server-->>UserA: user_joined

    UserB->>Server: PUT /wow/scene/node/7
    Server-->>UserB: updated node
    Server-->>UserA: node_updated

    UserA->>Server: DELETE /wow/scene/node/7
    Server-->>UserA: success
    Server-->>UserB: node_deleted
Loading

What this demonstrates

  • Multiple clients can participate in the same shared scene.
  • Updates are broadcast to all connected clients over /events.
  • A delete operation can race with an edit, so clients should treat the node as stale if they receive a delete event after a prior update.

Important note

This API does not include upload endpoints for assets. Each asset must already be available at a public or reachable URI before it is referenced by spatialAssetURI or appearanceURI.