Source of truth. This page mirrors state-server/docs/JS/getting-started.md. The repo is canonical — update there first, then resync here.
npm install @state-server/sdk
| Format | File | Usage |
|---|---|---|
| ESM | dist/state-server-sdk.esm.js |
import { StateServerSDK } from '@state-server/sdk' |
| CJS | dist/state-server-sdk.js |
const { StateServerSDK } = require('@state-server/sdk') |
| UMD | dist/state-server-sdk.umd.js |
<script src="..."></script> then window.StateServerSDK |
| UMD min | dist/state-server-sdk.min.js |
Production browser builds. |
import { StateServerSDK } from '@state-server/sdk';
const { StateServerSDK } = require('@state-server/sdk');
<script src="node_modules/@state-server/sdk/dist/state-server-sdk.umd.js"></script>
<script>
const sdk = new window.StateServerSDK({ baseUrl: 'https://localhost:8443' });
</script>
The SDK exports convenience aliases so you can use whichever name fits your codebase:
import { StateServerClient } from '@state-server/sdk';
import { SceneClient } from '@state-server/sdk';
Both StateServerClient and SceneClient are identical to StateServerSDK.
import sdk from '@state-server/sdk';
const client = sdk.create({
baseUrl: 'https://localhost:8443',
wsUrl: 'wss://localhost:8443/ws',
});
The following example registers a user, creates a brane (3D scene), adds a block to it, and subscribes to real-time updates:
import { StateServerSDK } from '@state-server/sdk';
const sdk = new StateServerSDK({
baseUrl: 'https://localhost:8443',
wsUrl: 'wss://localhost:8443/ws',
});
await sdk.initialize({ connectWebSocket: true, loadSession: true });
const auth = await sdk.register({
username: 'john_doe',
email: '[email protected]',
password: 'TestPass123',
display_name: 'John Doe',
});
console.log('User ID:', auth.user.id);
const brane = await sdk.entities.createObject({
type: 'brane',
name: 'My First Scene',
});
const block = await sdk.entities.createObject({
type: 'block',
name: 'Red Cube',
parent_id: brane.id,
model: { uri: '/models/cube.glb', type: 'model/gltf-binary' },
transform: [1,0,0,0, 0,1,0,0, 0,0,1,0, 0,1,0,1],
properties: { color: '#ff0000' },
});
const subId = await sdk.subscribeToEntity(brane.id, (event) => {
console.log('Update:', event.event_type, event.object_id);
});
await sdk.unsubscribeFromEntity(brane.id, subId);
sdk.destroy();
Built-in fetch and modern crypto APIs from Node 18 onward. For older Node versions, provide a global.fetch polyfill (undici, node-fetch).
Use the UMD or ESM build. Some bundlers (especially those targeting older environments) may require a Buffer polyfill since the CBOR codec uses Buffer internally.
The SDK does not disable certificate verification. For local self-signed certs, trust your local CA in the OS store or configure your environment explicitly (NODE_EXTRA_CA_CERTS for Node).
Authentication — registration, login flows, OAuth, sessions.
Objects — blocks, groups, branes.
Real-Time WebSocket — streaming and subscriptions.
Model Processing — async pipelines for previews, objects, projections.
For options on the SDK constructor and the data model, see state-server/docs/JS/configuration.md and state-server/docs/JS/core-concepts.md in-repo (not yet mirrored).