Class MolrooWorld

Main SDK entry point for interacting with a molroo world instance.

Provides methods for chat, events, ticking, time jumps, mutations, snapshots, and querying world state. Optionally integrates with LLM, storage, memory, and event adapters for richer functionality.

Example

import { MolrooWorld } from '@molroo-ai/sdk';

const world = await MolrooWorld.create(
  { baseUrl: 'https://api.molroo.io', apiKey: 'key' },
  {
    definition: { identity: { name: 'Cafe World' } },
    entities: [
      { name: 'user', type: 'user' },
      { name: 'Sera', type: 'persona' },
    ],
    personaConfigs: { Sera: { identity: { name: 'Sera', role: 'barista' } } },
  },
);

const result = await world.chat('Sera', 'Hello!');

Constructors

constructor

new MolrooWorld(
    config: MolrooWorldConfig & {
        events?: EventAdapter;
        llm?: LLMAdapter;
        memory?: MemoryAdapter;
        storage?: StorageAdapter;
    },
): MolrooWorld
Parameters
- config: MolrooWorldConfig & {
      events?: EventAdapter;
      llm?: LLMAdapter;
      memory?: MemoryAdapter;
      storage?: StorageAdapter;
  }
Returns MolrooWorld
- Defined in src/world.ts:71

Accessors

id

get id(): string
Unique identifier for this world instance.

Returns string
- Defined in src/world.ts:89

worldId

get worldId(): string
Unique identifier for this world instance (alias for id).

Returns string
- Defined in src/world.ts:94

Methods

addEntity

addEntity(
    input: {
        name: string;
        profile?: UserProfile;
        spaceId?: string;
        type?: string;
    },
): Promise<MutateOp & { data?: unknown }>
Add a new entity to the world.
Parameters
- input: { name: string; profile?: UserProfile; spaceId?: string; type?: string }
  Entity name, type, optional profile and initial space.
Returns Promise<MutateOp & { data?: unknown }>
The mutate operation result with optional data.
- Defined in src/world.ts:346

addSpace

addSpace(
input: { capacity?: number; name: string; spaceType?: string },
): Promise<MutateOp & { data?: unknown }>
Add a new space to the world.
Parameters
- input: { capacity?: number; name: string; spaceType?: string }
  Space name, optional type and capacity.
Returns Promise<MutateOp & { data?: unknown }>
The mutate operation result with optional data.
- Defined in src/world.ts:395

chat

chat(to: string, message: string, options?: ChatOptions): Promise<ChatResult>
Send a message to an entity and get an emotion-processed response.

With LLM adapter: Fetches world context, generates a response via the configured LLM, then sends it to the API for emotion processing.

Without LLM adapter: Requires options.appraisal to be provided. Sends the message directly to the API.
Parameters
- to: string
  Target entity name (e.g., 'Sera').
- message: string
  The message text to send.
- Optionaloptions: ChatOptions
  Chat options (from, appraisal, history, propagateToSpace).
Returns Promise<ChatResult>
Chat result with emotion data and optional observer reactions.
Example
```
// With LLM (automatic appraisal)
const result = await world.chat('Sera', 'How are you?');
console.log(result.response.emotion.discrete.primary); // 'joy'

// Without LLM (manual appraisal)
const result2 = await world.chat('Sera', 'Hello', {
  appraisal: { goal_relevance: 0.5, goal_congruence: 0.8, ... },
});
```
- Defined in src/world.ts:247

destroy

destroy(): Promise<void>
Soft-delete this world. Can be restored with restore.

Returns Promise<void>
- Defined in src/world.ts:605

event

event(input: EventInput): Promise<EventResult>
Dispatch a world event that affects one or more entities.

Events can target specific entities or broadcast to a space. Optional stimulus parameters allow direct manipulation of emotion state.
Parameters
- input: EventInput
  Event type, target, payload, and optional appraisal/stimulus.
Returns Promise<EventResult>
Affected entities with their emotion responses.
- Defined in src/world.ts:477

fetchPersonaConfigs

fetchPersonaConfigs(): Promise<Record<string, PersonaConfigData>>
Fetch persona configs from API and cache locally.

Returns Promise<Record<string, PersonaConfigData>>
- Defined in src/world.ts:205

getContext

getContext(entityNameOrId: string): Promise<WorldContext>
Get the world context from the perspective of a specific entity.

Returns spatial awareness, nearby entities, recent events, and world state.
Parameters
- entityNameOrId: string
  Entity name or ID to get context for.
Returns Promise<WorldContext>
World context data used for LLM prompt building.
- Defined in src/world.ts:332

getPersonaConfig

getPersonaConfig(entityName: string): PersonaConfigData | undefined
Get cached persona config for a specific entity.
Parameters
- entityName: string
Returns PersonaConfigData | undefined
- Defined in src/world.ts:215

loadSnapshot

loadSnapshot(snapshot: WorldSnapshot): Promise<void>
Restore the world state from a previously saved snapshot.
Parameters
- snapshot: WorldSnapshot
  The snapshot to restore.
Returns Promise<void>
- Defined in src/world.ts:556

loadSnapshotFromStorage

loadSnapshotFromStorage(key?: string): Promise<void>
Load a world snapshot from external storage and apply it. Requires a StorageAdapter to be configured.
Parameters
- Optionalkey: string
  Storage key. Defaults to snapshots/{worldId}/latest.json.
Returns Promise<void>
- Defined in src/world.ts:584

moveEntity

moveEntity(target: string, toSpace: string): Promise<void>
Move an entity to a different space.
Parameters
- target: string
  Entity name or ID to move.
- toSpace: string
  Destination space name or ID.
Returns Promise<void>
- Defined in src/world.ts:381

mutate

mutate(ops: MutateOp[]): Promise<MutateResult>
Execute one or more mutation operations on the world atomically.

Supports: add/remove entities, move entities, set relationships, add spaces/connections, update environment, manage facts/phases.
Parameters
- ops: MutateOp[]
  Array of mutation operations.
Returns Promise<MutateResult>
Results for each operation (ok/error).
- Defined in src/world.ts:462

query

query(include?: QueryInclude[]): Promise<QueryData>
Query world state, selecting which data to include.
Parameters
- Optionalinclude: QueryInclude[]
  Data sections to include (entities, spaces, environment, definition, phase). If omitted, returns all sections.
Returns Promise<QueryData>
Selected world state data.
- Defined in src/world.ts:533

removeEntity

removeEntity(target: string): Promise<void>
Remove an entity from the world.
Parameters
- target: string
  Entity name or ID to remove.
Returns Promise<void>
- Defined in src/world.ts:369

restore

restore(): Promise<void>
Restore a previously soft-deleted world.

Returns Promise<void>
- Defined in src/world.ts:614

saveSnapshotToStorage

saveSnapshotToStorage(key?: string): Promise<WorldSnapshot>
Save current world snapshot to external storage. Requires a StorageAdapter to be configured.
Parameters
- Optionalkey: string
  Storage key. Defaults to snapshots/{worldId}/latest.json.
Returns Promise<WorldSnapshot>
The snapshot that was saved.
- Defined in src/world.ts:569

setRelationship

setRelationship(
    entityA: string,
    entityB: string,
    relationship: RelationshipInput,
): Promise<void>
Set a relationship between two entities.
Parameters
- entityA: string
  First entity name.
- entityB: string
  Second entity name.
- relationship: RelationshipInput
  Relationship data (type, strength, trust).
Returns Promise<void>
- Defined in src/world.ts:420

snapshot

snapshot(): Promise<WorldSnapshot>
Get a full snapshot of the world state, including all entities, spaces, environment, knowledge, progression, and persona snapshots.

Returns Promise<WorldSnapshot>
Complete world snapshot that can be saved and restored.
- Defined in src/world.ts:547

tick

tick(seconds: number): Promise<TickResult>
Advance world time by the specified number of seconds.

Processes emotion decay, pending events, and phase transitions.
Parameters
- seconds: number
  Number of seconds to advance.
Returns Promise<TickResult>
Tick result with elapsed time and any phase changes.
- Defined in src/world.ts:501

timeJump

timeJump(
seconds: number,
milestoneEvent?: Record<string, unknown>,
): Promise<TickResult>
Jump forward in time with an optional milestone event.

Unlike tick, time jumps can span large periods and optionally inject a milestone event at the destination time.
Parameters
- seconds: number
  Number of seconds to jump forward.
- OptionalmilestoneEvent: Record<string, unknown>
  Optional event to inject at the destination time.
Returns Promise<TickResult>
Tick result with elapsed time and any phase changes.
- Defined in src/world.ts:517

updateDefinition

updateDefinition(definition: Record<string, unknown>): Promise<void>
Update the world definition (identity, rules, culture, etc.).
Parameters
- definition: Record<string, unknown>
  Partial definition to merge with the existing one.
Returns Promise<void>
- Defined in src/world.ts:625

updateEnvironment

updateEnvironment(environment: Partial<EnvironmentInput>): Promise<void>
Update the world environment (weather, location, ambiance, etc.).
Parameters
- environment: Partial<EnvironmentInput>
  Partial environment data to merge.
Returns Promise<void>
- Defined in src/world.ts:442

`Static`connect

connect(
    config: {
        apiKey: string;
        baseUrl: string;
        events?: EventAdapter;
        llm?: LLMAdapter;
        memory?: MemoryAdapter;
        storage?: StorageAdapter;
    },
    worldId: string,
): Promise<MolrooWorld>
Connect to an existing world by ID.

Verifies the world exists and fetches persona configs.
Parameters
- config: {
      apiKey: string;
      baseUrl: string;
      events?: EventAdapter;
      llm?: LLMAdapter;
      memory?: MemoryAdapter;
      storage?: StorageAdapter;
  }
  API connection config and optional adapters.
- worldId: string
  The ID of the world to connect to.
Returns Promise<MolrooWorld>
A connected MolrooWorld instance.
- Defined in src/world.ts:161

`Static`create

create(
    config: {
        apiKey: string;
        baseUrl: string;
        events?: EventAdapter;
        llm?: LLMAdapter;
        memory?: MemoryAdapter;
        storage?: StorageAdapter;
    },
    setup: CreateWorldInput,
): Promise<MolrooWorld>
Create a new world on the molroo API and return a connected instance.
Parameters
- config: {
      apiKey: string;
      baseUrl: string;
      events?: EventAdapter;
      llm?: LLMAdapter;
      memory?: MemoryAdapter;
      storage?: StorageAdapter;
  }
  API connection config and optional adapters.
- setup: CreateWorldInput
  World definition, entities, spaces, and persona configs.
Returns Promise<MolrooWorld>
A connected MolrooWorld instance.
Example
```
const world = await MolrooWorld.create(
  { baseUrl: 'https://api.molroo.io', apiKey: 'key', llm },
  {
    definition: { identity: { name: 'My World' } },
    entities: [{ name: 'Sera', type: 'persona' }],
    personaConfigs: { Sera: { identity: { name: 'Sera' } } },
  },
);
```
- Defined in src/world.ts:119

`Static`listWorlds

listWorlds(
config: { apiKey: string; baseUrl: string },
): Promise<{ nextCursor?: string; worlds: WorldSummary[] }>
List all worlds for the authenticated tenant.
Parameters
- config: { apiKey: string; baseUrl: string }
  API connection config (baseUrl + apiKey).
Returns Promise<{ nextCursor?: string; worlds: WorldSummary[] }>
List of world summaries with optional pagination cursor.
- Defined in src/world.ts:187

Class MolrooWorld

Example

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

Returns MolrooWorld

Accessors

id

Returns string

worldId

Returns string

Methods

addEntity

Parameters

Returns Promise<MutateOp & { data?: unknown }>

addSpace

Parameters

Returns Promise<MutateOp & { data?: unknown }>

chat

Parameters

Returns Promise<ChatResult>

Example

destroy

Returns Promise<void>

event

Parameters

Returns Promise<EventResult>

fetchPersonaConfigs

Returns Promise<Record<string, PersonaConfigData>>

getContext

Parameters

Returns Promise<WorldContext>

getPersonaConfig

Parameters

Returns PersonaConfigData | undefined

loadSnapshot

Parameters

Returns Promise<void>

loadSnapshotFromStorage

Parameters

Returns Promise<void>

moveEntity

Parameters

Returns Promise<void>

mutate

Parameters

Returns Promise<MutateResult>

query

Parameters

Returns Promise<QueryData>

removeEntity

Parameters

Returns Promise<void>

restore

Returns Promise<void>

saveSnapshotToStorage

Parameters

Returns Promise<WorldSnapshot>

setRelationship

Parameters

Returns Promise<void>

snapshot

Returns Promise<WorldSnapshot>

tick

Parameters

Returns Promise<TickResult>

timeJump

Parameters

Returns Promise<TickResult>

updateDefinition

Parameters

Returns Promise<void>

updateEnvironment

Parameters

Returns Promise<void>

Staticconnect

`Static`connect

`Static`create

`Static`listWorlds