onlyworlds-dev

OnlyWorlds Tool Development

Build applications on OnlyWorlds data.

Quick Reference

Task	Approach
Install SDK	npm install @onlyworlds/sdk
Quick scaffold	See knowledge/scaffold.md
Deployment	See knowledge/deployment.md
Personal tool	Hardcode credentials, run locally
Shared tool	User-provided credentials, deploy to Cloudflare/Vercel
Python/Node script	Direct API calls with curl or requests

Instructions

Step 1: Understand the Goal

What is the user building?

• Visualization: Display world data (maps, graphs, timelines) → read-only SDK calls
• Editor: Create/modify elements → full CRUD SDK calls
• Game: Use world data as content → read + local state
• Integration: Connect OW to other systems → API patterns

Step 2: Load Core Reference

Read for OnlyWorlds overview, URLs, SDK basics:

../../knowledge/onlyworlds-core.md

Step 3: SDK Setup

npm install @onlyworlds/sdk

The SDK (3.x) is v2-native: OwV2Client, with types and constants generated from the canonical schema.

import { OwV2Client } from '@onlyworlds/sdk';

const client = new OwV2Client({
  apiKey: 'ow_w_your_world_key', // ow_w_ write / ow_r_ read / 10-digit legacy
  apiPin: 'your-pin'             // needed for writes on a PIN-protected world
});

const characters = await client.list('character');        // {data, has_more, next_cursor}
const one = await client.get('character', 'uuid-here');

The SDK also exports the canonical element palette and metadata: elementColor(type, mode), ELEMENT_FAMILIES, ELEMENT_ICONS — generated from the schema, so tools that use them stay in sync for free.

Common Operations

// World meta (the container)
const world = await client.getWorld();

// Walk a whole type without touching cursors
for await (const el of client.listAll('character')) { /* ... */ }

// Create / patch / delete — type as the first argument
const made = await client.create('location', { name: 'Feltropolis', description: 'Capital city of Moppetopia' });
await client.patch('character', 'uuid-here', { description: 'Updated' });
await client.delete('character', 'uuid-here');

// Sync + atomic bulk
const changed = await client.changes({ since: cursor });
await client.bulk(items, { atomic: true });