molroo docs
SDK ReferenceTypes

Input Types

ChatOptions, EventInput, MutateOp, RelationshipInput, and other operation input types.

Input Types

Types used as inputs to MolrooWorld operations.

import type {
  ChatOptions,
  ChatInput,
  EventInput,
  MutateOp,
  RelationshipInput,
  TimeJumpInput,
  QueryInclude,
} from '@molroo-ai/sdk';

ChatOptions

Options for world.chat().

interface ChatOptions {
  from?: string;
  appraisal?: AppraisalVector;
  includeState?: boolean;
  history?: Array<{ role: 'user' | 'assistant'; content: string }>;
  propagateToSpace?: boolean;
}
FieldTypeDefaultDescription
fromstring?'user'Sender entity name
appraisalAppraisalVector--Manual appraisal values. If provided, skips LLM and uses emotion-only mode
includeStateboolean?falseInclude full internal State in the result
historyArray<{ role, content }>?--Conversation history to include in the LLM prompt
propagateToSpaceboolean?--Override world-level groupAwareness for this chat. Set to false for a whisper (private message)

Example:

// With conversation history
const result = await world.chat('Sera', 'Do you remember what we talked about?', {
  history: [
    { role: 'user', content: 'I love coffee!' },
    { role: 'assistant', content: 'Oh really? What kind do you prefer?' },
  ],
});

// Whisper (no observers even if groupAwareness is on)
const result2 = await world.chat('Sera', 'Can I tell you a secret?', {
  propagateToSpace: false,
});

// Emotion-only mode with manual appraisal
const result3 = await world.chat('Sera', 'You look nice today', {
  appraisal: {
    goal_relevance: 0.4,
    goal_congruence: 0.7,
    expectedness: 0.5,
    controllability: 0.3,
    agency: -0.5,
    norm_compatibility: 0.8,
  },
});

ChatInput

Raw chat input sent to the API. Used internally by the SDK -- you typically use world.chat() instead.

interface ChatInput {
  from: string;
  to: string;
  message: string;
  appraisal?: AppraisalVector;
}

EventInput

Input for dispatching a world event via world.event().

Events can carry either an appraisal (cognitive evaluation) or a stimulus (direct physiological/emotional manipulation), or both.

interface EventInput {
  type: string;
  target?: string;
  from?: string;
  payload?: Record<string, unknown>;
  appraisal?: AppraisalVector;
  stimulus?: {
    bodyBudgetDelta?: number;
    vadOverride?: Partial<{ V: number; A: number; D: number }>;
    vadDelta?: Partial<{ V: number; A: number; D: number }>;
    needsDelta?: Partial<{ autonomy: number; competence: number; relatedness: number }>;
    soulStageForce?: number;
    catastropheAlphaDelta?: number;
  };
  propagateToAdjacent?: boolean;
}
FieldTypeDescription
typestringEvent type name (e.g., 'battle_start', 'weather_change', 'compliment')
targetstring?Target entity name. If omitted, broadcasts to the space
fromstring?Source entity name
payloadRecord<string, unknown>?Additional event data
appraisalAppraisalVectorCognitive appraisal for this event
stimulusobject?Direct physiological/emotional manipulation (see below)
propagateToAdjacentboolean?Whether to propagate this event to adjacent spaces

stimulus

Direct manipulation of a persona's internal state. Bypasses the normal appraisal pipeline.

FieldTypeDescription
bodyBudgetDeltanumber?Change to body budget (e.g., -0.1 for fatigue)
vadOverridePartial<VAD>?Force-set emotion coordinates
vadDeltaPartial<VAD>?Add to current emotion coordinates
needsDeltaPartial<NeedState>?Change to SDT needs (autonomy, competence, relatedness)
soulStageForcenumber?Force soul stage to a specific ID (1-15)
catastropheAlphaDeltanumber?Adjust the catastrophe model's asymmetry factor

Example (appraisal-based event):

await world.event({
  type: 'surprise_gift',
  target: 'Sera',
  from: 'user',
  payload: { item: 'flowers', description: 'A beautiful bouquet of roses' },
  appraisal: {
    goal_relevance: 0.6,
    goal_congruence: 0.9,
    expectedness: 0.2,
    controllability: 0.3,
    agency: -0.8,
    norm_compatibility: 0.9,
  },
});

Example (stimulus-based event):

// Exhaustion event — drains body budget and lowers arousal
await world.event({
  type: 'exhaustion',
  target: 'Sera',
  stimulus: {
    bodyBudgetDelta: -0.3,
    vadDelta: { A: -0.4, V: -0.1 },
    needsDelta: { competence: -0.2 },
  },
});

Example (broadcast to space):

// No target — affects all entities in the default space
await world.event({
  type: 'fire_alarm',
  payload: { severity: 'high' },
  appraisal: {
    goal_relevance: 0.9,
    goal_congruence: -0.8,
    expectedness: 0.1,
    controllability: 0.2,
    agency: -1,
    norm_compatibility: 0,
  },
  propagateToAdjacent: true,
});

MutateOp

Union type of all 16 supported mutation operations for world.mutate().

type MutateOp =
  | { op: 'add_entity'; name: string; type: EntityType; profile?: UserProfile; spaceId?: string }
  | { op: 'add_agent'; name: string; config: Record<string, unknown>; spaceId?: string }
  | { op: 'remove_entity'; target: string }
  | { op: 'move_entity'; target: string; toSpace: string }
  | { op: 'set_emotion'; target: string; vad: Partial<VAD> }
  | { op: 'set_relationship'; entityA: string; entityB: string; relationship: RelationshipInput }
  | { op: 'add_space'; name: string; spaceType?: SpaceType; capacity?: number }
  | { op: 'add_connection'; connection: SpaceConnection }
  | { op: 'remove_connection'; from: string; to: string }
  | { op: 'update_connection'; from: string; to: string; updates: { accessibility?: string } }
  | { op: 'update_environment'; environment: Partial<EnvironmentInput> }
  | { op: 'add_fact'; fact: Fact }
  | { op: 'reveal_fact'; factId: string; entities: string[] }
  | { op: 'hide_fact'; factId: string; entities: string[] }
  | { op: 'set_phase'; phase: string }
  | { op: 'add_trigger'; trigger: ProgressionTrigger }

Operation Reference

OperationDescriptionKey Fields
add_entityAdd a new entityname, type, profile?, spaceId?
add_agentAdd an entity with a full persona agentname, config, spaceId?
remove_entityRemove an entitytarget (name or ID)
move_entityMove entity to a spacetarget, toSpace
set_emotionDirectly set emotion VADtarget, vad: Partial<VAD>
set_relationshipSet relationship between entitiesentityA, entityB, relationship
add_spaceAdd a new spacename, spaceType?, capacity?
add_connectionConnect two spacesconnection: SpaceConnection
remove_connectionRemove a space connectionfrom, to
update_connectionUpdate connection propertiesfrom, to, updates
update_environmentUpdate environmentenvironment: Partial<EnvironmentInput>
add_factAdd a fact to the knowledge systemfact: Fact
reveal_factReveal a fact to entitiesfactId, entities: string[]
hide_factHide a fact from entitiesfactId, entities: string[]
set_phaseForce set the progression phasephase: string
add_triggerAdd a progression triggertrigger: ProgressionTrigger

Example (multiple operations):

await world.mutate([
  // Add a new character
  { op: 'add_entity', name: 'Kai', type: 'persona', spaceId: 'courtyard' },

  // Connect spaces
  { op: 'add_connection', connection: { from: 'courtyard', to: 'library', bidirectional: true } },

  // Add a secret fact
  {
    op: 'add_fact',
    fact: { id: 'secret-1', content: 'Kai is secretly a prince', visibility: 'secret', knownBy: ['Kai'] },
  },

  // Reveal the fact to Sera
  { op: 'reveal_fact', factId: 'secret-1', entities: ['Sera'] },

  // Set emotion directly
  { op: 'set_emotion', target: 'Sera', vad: { V: 0.5, A: 0.3 } },

  // Add a phase transition trigger
  {
    op: 'add_trigger',
    trigger: {
      id: 'reveal-arc',
      condition: { type: 'relationship', entityA: 'Kai', entityB: 'Sera', field: 'trust', above: 0.8 },
      targetPhase: 'truth_revealed',
      oneShot: true,
    },
  },
]);

RelationshipInput

Input for setting a relationship between two entities.

interface RelationshipInput {
  type: string;
  strength?: number;
  trust?: number;
}
FieldTypeDescription
typestringRelationship type label (e.g., 'friend', 'rival', 'mentor', 'stranger')
strengthnumber?Relationship strength (0 to 1)
trustnumber?Trust level (0 to 1)

TimeJumpInput

Input for a time jump operation.

interface TimeJumpInput {
  seconds: number;
  milestoneEvent?: Record<string, unknown>;
}
FieldTypeDescription
secondsnumberNumber of seconds to jump forward
milestoneEventRecord<string, unknown>?Optional event to inject at the destination time

QueryInclude

Selectable data sections for world.query().

type QueryInclude = 'entities' | 'spaces' | 'environment' | 'definition' | 'phase';
ValueReturns
'entities'All entities with ID, name, type, spaceId, profile, hasAgent
'spaces'All spaces with ID, name, type, capacity
'environment'Current environment (weather, location, ambiance)
'definition'World definition (identity, rules, culture, etc.)
'phase'Current progression phase name

Example:

// Get only entities and current phase
const { entities, currentPhase } = await world.query(['entities', 'phase']);

// Get everything
const all = await world.query();
// or equivalently:
const all2 = await world.query(['entities', 'spaces', 'environment', 'definition', 'phase']);

On this page