simpleWorlds is a small, full-stack world authoring demo built around a REST API, a WebSocket event stream, and a browser-based scene explorer. The repository is organized as a npm workspace with three packages:
- packages/wow-spec — the OpenAPI schema and generated TypeScript types (README)
- packages/wow-backend — the Express server, validation layer, persistence, and WebSocket endpoint (README)
- packages/wow-frontend — the Vite-built UI that renders world data, the scene graph, and a live 3D viewer (README)
The repo uses a simple data flow:
wow-spec -> wow-backend (request validation + business logic)
wow-spec -> wow-frontend (typed API client and schema-based models)
The backend serves the compiled frontend from its static assets directory, so visiting the app at the backend URL loads the UI automatically.
The frontend renders the scene graph two ways: as an expandable tree of nodes, and as a live 3D scene using X3DOM (loaded from a CDN in index.html). Each Node is converted into an X3D <MatrixTransform> using its localTransform, with an <Inline> element for spatialAssetURI assets (e.g. glTF or X3D models) or a placeholder sphere otherwise.
- Node.js 20+
- npm 10+
From the repository root, install all workspace dependencies:
npm installBuild the full workspace in dependency order:
npm run buildIndividual package commands are also available:
npm run build:spec
npm run build:frontend
npm run build:backendThe spec package must be built before the frontend and backend because both consume the generated types from the spec package.
Start the backend server:
npm run start:backendThe server listens on http://localhost:3000. Opening that URL loads the frontend app and exposes the API endpoints.
To build and start everything in one step:
npm run startFor local iteration, the repo includes a watcher that rebuilds and restarts the backend whenever the spec, backend, or frontend source changes:
npm run devThis uses nodemon.json and watches the relevant source files.
The HTTP and WebSocket interfaces are documented in docs/API.md and are defined by the OpenAPI schema in packages/wow-spec/src/schema.yaml.
| Method | Path | Purpose |
|---|---|---|
| GET | / | Serves the app shell and static frontend assets |
| GET | /wow/world | Returns the current world summary |
| GET | /wow/user/{userId} | Returns a user record |
| DELETE | /wow/user/{userId} | Deletes a user record |
| GET | /wow/view/{viewId} | Returns a view record |
| GET | /wow/portal/{portalId} | Returns a portal record |
| GET | /wow/scene/node/{nodeId} | Returns a node |
| POST | /wow/scene/node/{nodeId} | Creates one or more child nodes |
| PUT | /wow/scene/node/{nodeId} | Updates a node |
| DELETE | /wow/scene/node/{nodeId} | Deletes a node and its subtree |
A client can connect to ws://localhost:3000/events to receive JSON event messages.
| Event | Payload |
|---|---|
| user_joined | { user } |
| user_left | { userId } |
| node_created | { node } |
| node_updated | { node } |
| node_deleted | { nodeId } |
The backend persists world state to packages/wow-backend/data/world_state.json. On startup it restores any existing state; on shutdown it writes the current state back to disk.
Run the shared formatting checks and fixes:
npm run format
npm run format:write