Database

Unia provides a really simple Database for storing and updating JSON files.

world.db.set(key, object, isPublic?, publicEdit?) -> Promise: {status: 'okay'}

world.db.get(key) -> Promise: stored value | {error: string} | undefined

Writes require login. The first writer owns a document. By default only that owner can replace it. The owner can set publicEdit to true to allow other logged-in users to replace its content. Only the owner may submit permission flags on an existing document; public editors must omit both optional flags. Denied writes reject the promise. All documents are currently readable without login, including documents with isPublic set to false.

Each write replaces the complete value; there is no field merge or atomic increment. Concurrent read-modify-write operations can lose updates.

You can use the database for anything you want, or use your own database.

Please note that document names are scoped to a specific project. For example, if you use:

await world.db.get("myKey");

in different source projects, each call addresses a different document. Attached scripts, their local imports, and scripts attached through world.attachScript() use the calling script's source-project context. An imported Chess scene therefore accesses Chess documents even when hosted in a Lobby scene. Async callbacks retain that context. Multiple copies of Chess share its documents; use distinct keys when instances need separate state.

The script-local world forwards ordinary properties to the shared world but provides a database handle bound to the source project. window.world.db is the explicit outer-editor database and remains tied to the active editor project. External URL modules are not rewritten with a script context; pass the scoped world.db handle to them when needed.

Project scoping prevents accidental collisions, not malicious access. The server enforces document ownership. Any logged-in user may create an unused key, so names are first-come-first-served, not reserved by project ownership or by a username prefix. Existing document owners are retained. User IDs are not part of the document's primary key.

Network behavior

The current API sends requests directly to the backend. It does not queue offline writes or provide change subscriptions. A missing document returns { error: 'Not found' }; a failed network read can return undefined.

Examples

Get a document

// Get a document you have uploaded
const object = await world.db.get('objectKey')

console.log(object) -> {very: 'meaowy!'}

Set a document

// Create or update a file
const data = { player: "data" };
const result = await world.db.set("someKey", data);

Another example,

Lego brick game: Anyone who uses your app can save the maps they create:

const save = (bricks, mapName)=>{
    // Document containing the map
    const fileKey = world.username + '_' + mapName

    const data = { map: mapName, bricks: bricks }
    const result = await world.db.set(fileKey, data)

    // Another document storing the maps they have created
    usedData.maps.[mapName] = { version: 1}
    const result = await world.db.set(world.username, userData)
}

let bricks = [
	{ x: 0, y: 1, z: 3 },
	{ x: 5, y: -1, z: 2 },
]

save(bricks, 'utopia')

Public editing

// Owner creates or updates a shared document and enables public editing.
await world.db.set('shared-board', { pieces: [] }, true, true)

// Another logged-in user updates content without submitting permission flags.
await world.db.set('shared-board', { pieces: ['piece-a'] })