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;
}| Field | Type | Default | Description |
|---|---|---|---|
from | string? | 'user' | Sender entity name |
appraisal | AppraisalVector | -- | Manual appraisal values. If provided, skips LLM and uses emotion-only mode |
includeState | boolean? | false | Include full internal State in the result |
history | Array<{ role, content }>? | -- | Conversation history to include in the LLM prompt |
propagateToSpace | boolean? | -- | 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;
}| Field | Type | Description |
|---|---|---|
type | string | Event type name (e.g., 'battle_start', 'weather_change', 'compliment') |
target | string? | Target entity name. If omitted, broadcasts to the space |
from | string? | Source entity name |
payload | Record<string, unknown>? | Additional event data |
appraisal | AppraisalVector | Cognitive appraisal for this event |
stimulus | object? | Direct physiological/emotional manipulation (see below) |
propagateToAdjacent | boolean? | Whether to propagate this event to adjacent spaces |
stimulus
Direct manipulation of a persona's internal state. Bypasses the normal appraisal pipeline.
| Field | Type | Description |
|---|---|---|
bodyBudgetDelta | number? | Change to body budget (e.g., -0.1 for fatigue) |
vadOverride | Partial<VAD>? | Force-set emotion coordinates |
vadDelta | Partial<VAD>? | Add to current emotion coordinates |
needsDelta | Partial<NeedState>? | Change to SDT needs (autonomy, competence, relatedness) |
soulStageForce | number? | Force soul stage to a specific ID (1-15) |
catastropheAlphaDelta | number? | 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
| Operation | Description | Key Fields |
|---|---|---|
add_entity | Add a new entity | name, type, profile?, spaceId? |
add_agent | Add an entity with a full persona agent | name, config, spaceId? |
remove_entity | Remove an entity | target (name or ID) |
move_entity | Move entity to a space | target, toSpace |
set_emotion | Directly set emotion VAD | target, vad: Partial<VAD> |
set_relationship | Set relationship between entities | entityA, entityB, relationship |
add_space | Add a new space | name, spaceType?, capacity? |
add_connection | Connect two spaces | connection: SpaceConnection |
remove_connection | Remove a space connection | from, to |
update_connection | Update connection properties | from, to, updates |
update_environment | Update environment | environment: Partial<EnvironmentInput> |
add_fact | Add a fact to the knowledge system | fact: Fact |
reveal_fact | Reveal a fact to entities | factId, entities: string[] |
hide_fact | Hide a fact from entities | factId, entities: string[] |
set_phase | Force set the progression phase | phase: string |
add_trigger | Add a progression trigger | trigger: 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;
}| Field | Type | Description |
|---|---|---|
type | string | Relationship type label (e.g., 'friend', 'rival', 'mentor', 'stranger') |
strength | number? | Relationship strength (0 to 1) |
trust | number? | Trust level (0 to 1) |
TimeJumpInput
Input for a time jump operation.
interface TimeJumpInput {
seconds: number;
milestoneEvent?: Record<string, unknown>;
}| Field | Type | Description |
|---|---|---|
seconds | number | Number of seconds to jump forward |
milestoneEvent | Record<string, unknown>? | Optional event to inject at the destination time |
QueryInclude
Selectable data sections for world.query().
type QueryInclude = 'entities' | 'spaces' | 'environment' | 'definition' | 'phase';| Value | Returns |
|---|---|
'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']);