ChatResult, EventResult, TickResult, QueryData, MutateResult, and WorldSnapshot.

Result Types

Types returned by MolrooWorld operations.

import type {
  ChatResult,
  EventResult,
  TickResult,
  QueryData,
  MutateResult,
  MutateOpResult,
  WorldSnapshot,
  WorldSummary,
} from '@molroo-ai/sdk';

ChatResult

Result of a chat interaction via world.chat().

interface ChatResult {
  entityId: string;
  entityName: string;
  response: AgentResponse;
  state?: State;
  observers?: Array<{
    entityId: string;
    entityName: string;
    response: AgentResponse;
  }>;
}

Field	Type	Description
`entityId`	`string`	ID of the target entity
`entityName`	`string`	Name of the target entity
`response`	`AgentResponse`	Emotion data, text, memory episode, social updates
`state`	`State`	Full internal emotion state (if `includeState` was true)
`observers`	`Array<{ entityId, entityName, response }>`	Entities that overheard this chat (when `groupAwareness` is enabled)

Example:

const result = await world.chat('Sera', 'I brought you flowers!');

console.log(result.entityName);                        // 'Sera'
console.log(result.response.text);                     // "Oh, how sweet of you!"
console.log(result.response.emotion.vad);              // { V: 0.72, A: 0.55, D: 0.4 }
console.log(result.response.emotion.discrete.primary); // 'joy'
console.log(result.response.emotion.discrete.intensity); // 0.78

// Observers (if groupAwareness is on)
if (result.observers?.length) {
  for (const obs of result.observers) {
    console.log(`${obs.entityName} overheard: ${obs.response.emotion.discrete.primary}`);
  }
}

EventResult

Result of an event dispatch via world.event().

interface EventResult {
  affected: Array<{
    entityId: string;
    entityName: string;
    response: AgentResponse;
  }>;
  environmentChanged: boolean;
}

Field	Type	Description
`affected`	`Array<{ entityId, entityName, response }>`	Entities affected by the event with their emotion responses
`environmentChanged`	`boolean`	Whether the event caused an environment change

Example:

const result = await world.event({
  type: 'earthquake',
  appraisal: {
    goal_relevance: 0.9,
    goal_congruence: -0.8,
    expectedness: 0.1,
    controllability: 0.0,
    agency: -1,
    norm_compatibility: 0,
  },
});

for (const a of result.affected) {
  console.log(`${a.entityName}: ${a.response.emotion.discrete.primary}`);
  // "Sera: fear"
  // "Mika: surprise"
}

TickResult

Result of a tick or time jump operation.

interface TickResult {
  elapsedSeconds: number;
  pendingEventsProcessed: number;
  phaseChanged?: {
    from: string;
    to: string;
    triggerId: string;
  };
}

Field	Type	Description
`elapsedSeconds`	`number`	Number of seconds that were advanced
`pendingEventsProcessed`	`number`	Number of pending events that were processed during the tick
`phaseChanged`	`object?`	Present only if a phase transition occurred
`phaseChanged.from`	`string`	Previous phase name
`phaseChanged.to`	`string`	New phase name
`phaseChanged.triggerId`	`string`	ID of the trigger that caused the transition

Example:

const result = await world.tick(300);
console.log(result.elapsedSeconds);          // 300
console.log(result.pendingEventsProcessed);  // 2

if (result.phaseChanged) {
  console.log(`Phase: ${result.phaseChanged.from} -> ${result.phaseChanged.to}`);
}

QueryData

Result of a world state query via world.query().

interface QueryData {
  entities?: Array<{
    id: string;
    name: string;
    type: EntityType;
    spaceId: string;
    profile?: UserProfile;
    hasAgent: boolean;
  }>;
  spaces?: Space[];
  environment?: Environment;
  definition?: Partial<WorldDefinitionInput>;
  currentPhase?: string;
}

Field	Type	Included When
`entities`	`Array<{ id, name, type, spaceId, profile?, hasAgent }>`	`include` contains `'entities'`
`spaces`	`Space[]`	`include` contains `'spaces'`
`environment`	`Environment`	`include` contains `'environment'`
`definition`	`WorldDefinitionInput`	`include` contains `'definition'`
`currentPhase`	`string?`	`include` contains `'phase'`

Example:

const data = await world.query(['entities', 'environment', 'phase']);

for (const entity of data.entities ?? []) {
  console.log(`${entity.name} (${entity.type}) in ${entity.spaceId}`);
}

console.log(data.environment?.weather);  // 'sunny'
console.log(data.currentPhase);          // 'chapter_1'

MutateResult

Result of a world.mutate() operation.

interface MutateResult {
  results: MutateOpResult[];
}

MutateOpResult

interface MutateOpResult {
  op: string;
  ok: boolean;
  data?: unknown;
  error?: string;
}

Field	Type	Description
`op`	`string`	The operation type (e.g., `'add_entity'`, `'move_entity'`)
`ok`	`boolean`	Whether the operation succeeded
`data`	`unknown?`	Optional data returned by the operation (e.g., entity ID for `add_entity`)
`error`	`string?`	Error message if the operation failed

Example:

const result = await world.mutate([
  { op: 'add_entity', name: 'Kai', type: 'persona' },
  { op: 'move_entity', target: 'Kai', toSpace: 'courtyard' },
]);

for (const r of result.results) {
  if (r.ok) {
    console.log(`${r.op}: success`, r.data);
  } else {
    console.log(`${r.op}: failed - ${r.error}`);
  }
}

WorldSnapshot

Complete serialized state of a world instance. Can be saved to external storage and restored later.

interface WorldSnapshot {
  id: string;
  definition?: Partial<WorldDefinitionInput>;
  entities: Array<{
    id: string;
    type: EntityType;
    name: string;
    spaceId: string;
    profile?: UserProfile;
    personaSnapshot?: PersonaSnapshot;
    relationships: Array<{
      targetId: string;
      relationship: WorldRelationship;
    }>;
  }>;
  spaces: Space[];
  environment: Environment;
  createdAt: number;
  knowledge?: {
    facts: Fact[];
    defaultVisibility: string;
  };
  progression?: {
    currentPhase: string;
    elapsedTime: number;
    eventCounts: Record<string, number>;
    phaseHistory: Array<{
      from: string;
      to: string;
      timestamp: number;
      triggerId: string;
    }>;
    firedTriggerIds: string[];
    triggers: ProgressionTrigger[];
  };
  recentEvents?: WorldEvent[];
}

Field	Type	Description
`id`	`string`	World ID
`definition`	`WorldDefinitionInput`	World definition
`entities`	`Array<...>`	All entities with persona snapshots and relationships
`spaces`	`Space[]`	All spaces
`environment`	`Environment`	Current environment
`createdAt`	`number`	Snapshot creation timestamp (epoch ms)
`knowledge`	`object?`	Facts and default visibility
`progression`	`object?`	Phase progression state, history, triggers, event counts
`recentEvents`	`WorldEvent[]`	Recent world events

Each entity in the snapshot includes:

personaSnapshot -- full internal state (PersonaSnapshot) for persona-type entities
relationships -- all relationships with other entities as { targetId, relationship: WorldRelationship }

WorldSummary

Summary of a world, returned by MolrooWorld.listWorlds().

interface WorldSummary {
  id: string;
  tenantId: string;
  definition: WorldDefinitionInput;
  engineVersion: string;
  createdAt: string;
}

Field	Type	Description
`id`	`string`	World ID
`tenantId`	`string`	Tenant (API key owner) ID
`definition`	`WorldDefinitionInput`	World definition
`engineVersion`	`string`	Engine version used by this world
`createdAt`	`string`	ISO timestamp of world creation

Result Types

On this page