Entity, Space, Environment, WorldContext, WorldEvent, and world structure types.

World Types

Types representing world structure -- entities, spaces, environment, events, relationships, and spatial connections.

import type {
  Entity,
  EntityType,
  Space,
  SpaceType,
  Environment,
  WorldContext,
  WorldEvent,
  Relationship,
  WorldRelationship,
  SpaceConnection,
  Fact,
  ProgressionTrigger,
} from '@molroo-ai/sdk';

EntityType

type EntityType = 'persona' | 'user' | 'secondary';

Type	Description
`'persona'`	AI character with full emotion engine (personality, goals, memory, soul stages)
`'user'`	Human player/user. Every world should have at least one user entity
`'secondary'`	Background character without a full persona agent

SpaceType

type SpaceType = 'physical' | 'virtual' | 'abstract';

Type	Description
`'physical'`	A real-world location (room, building, outdoor area)
`'virtual'`	A digital space (chatroom, virtual world)
`'abstract'`	A conceptual space (dream, memory, thought)

Entity

An entity in the world.

interface Entity {
  id: string;
  name: string;
  type: EntityType;
  spaceId: string;
  profile?: UserProfile;
}

Field	Type	Description
`id`	`string`	Unique entity ID (auto-generated)
`name`	`string`	Entity name (unique within the world)
`type`	`EntityType`	Entity type
`spaceId`	`string`	ID of the space this entity is currently in
`profile`	`UserProfile`	Optional profile data

Space

A spatial container within the world.

interface Space {
  id: string;
  name: string;
  type: SpaceType;
  capacity: number;
}

Field	Type	Description
`id`	`string`	Unique space ID
`name`	`string`	Space name
`type`	`SpaceType`	Space type
`capacity`	`number`	Maximum number of entities

Environment

Current world environment state.

interface Environment {
  weather: string;
  location: string;
  ambiance: string;
}

Field	Type	Description
`weather`	`string`	Current weather (e.g., `'sunny'`, `'rainy'`)
`location`	`string`	Location description
`ambiance`	`string`	Ambient mood/atmosphere

WorldContext

World context from the perspective of a specific entity. Returned by world.getContext(). Used internally by the SDK to build LLM system prompts.

interface WorldContext {
  whoAmI: string;
  whereAmI: string;
  whoIsHere: string[];
  whatHappened: WorldEvent[];
  adjacentSpaces?: string[];
  worldIdentity?: {
    name: string;
    [key: string]: unknown;
  };
  worldCulture?: {
    coreValues: string[];
    socialProtocol?: {
      greetingStyle?: string;
      addressSystem?: string;
      tabooTopics?: string[];
    };
  };
  knownFacts?: Array<{ id: string; content: string; visibility: string }>;
  currentPhase?: string;
}

Field	Type	Description
`whoAmI`	`string`	The entity's name
`whereAmI`	`string`	The entity's current space name
`whoIsHere`	`string[]`	Names of other entities in the same space
`whatHappened`	`WorldEvent[]`	Recent events visible to this entity
`adjacentSpaces`	`string[]?`	Names of connected spaces
`worldIdentity`	`object?`	World identity data (name, genre, tone, era, lore)
`worldCulture`	`object?`	World culture data (core values, social protocol)
`knownFacts`	`Array<{ id, content, visibility }>?`	Facts known to this entity
`currentPhase`	`string?`	Current progression phase

Example:

const ctx = await world.getContext('Sera');
// {
//   whoAmI: 'Sera',
//   whereAmI: 'Main Cafe',
//   whoIsHere: ['user', 'Mika'],
//   whatHappened: [
//     { type: 'chat', sourceEntity: 'user', payload: { message: 'Hello!' }, ... },
//   ],
//   adjacentSpaces: ['Kitchen', 'Patio'],
//   worldIdentity: { name: 'Cafe World', genre: 'slice-of-life', tone: 'warm' },
//   currentPhase: 'morning_rush',
// }

WorldEvent

An event that occurred in the world. Returned in WorldContext.whatHappened and WorldSnapshot.recentEvents.

interface WorldEvent {
  type: string;
  spaceId: string;
  timestamp: number;
  sourceEntity?: string;
  targetEntity?: string;
  payload: Record<string, unknown>;
  appraisal?: AppraisalVector;
}

Field	Type	Description
`type`	`string`	Event type (e.g., `'chat'`, `'chat_observed'`, `'earthquake'`)
`spaceId`	`string`	Space where the event occurred
`timestamp`	`number`	Epoch milliseconds
`sourceEntity`	`string?`	Entity that initiated the event
`targetEntity`	`string?`	Entity targeted by the event
`payload`	`Record<string, unknown>`	Event-specific data
`appraisal`	`AppraisalVector`	Optional appraisal attached to the event

Relationship

Persona-level relationship data. Found in PersonaSnapshot.relationships.

interface Relationship {
  entityId: string;
  trust: number;
  intimacy: number;
  interactionCount: number;
  attachmentStyle?: string;
  lastInteraction?: number;
}

Field	Type	Description
`entityId`	`string`	ID of the related entity
`trust`	`number`	Trust level (0 to 1)
`intimacy`	`number`	Intimacy level (0 to 1)
`interactionCount`	`number`	Total number of interactions
`attachmentStyle`	`string?`	Attachment style label
`lastInteraction`	`number?`	Timestamp of last interaction

WorldRelationship

World-level relationship data. Found in WorldSnapshot entity relationship arrays.

interface WorldRelationship {
  type: string;
  strength: number;
  trust: number;
}

Field	Type	Description
`type`	`string`	Relationship type label (e.g., `'friend'`, `'rival'`, `'mentor'`)
`strength`	`number`	Relationship strength
`trust`	`number`	Trust level

SpaceConnection

A spatial connection between two spaces. Used in WorldDefinitionInput.topology.

interface SpaceConnection {
  from: string;
  to: string;
  distance?: number;
  traversalTime?: number;
  accessibility?: string;
  bidirectional?: boolean;
}

Field	Type	Default	Description
`from`	`string`	--	Source space name or ID
`to`	`string`	--	Destination space name or ID
`distance`	`number?`	--	Distance between spaces
`traversalTime`	`number?`	--	Time (seconds) to travel between spaces
`accessibility`	`string?`	--	Access restriction (e.g., `'open'`, `'locked'`, `'hidden'`)
`bidirectional`	`boolean?`	`true`	Whether the connection works both ways

Example:

const topology = {
  connections: [
    { from: 'cafe', to: 'kitchen', bidirectional: true },
    { from: 'cafe', to: 'patio', distance: 10, traversalTime: 5 },
    { from: 'kitchen', to: 'storeroom', accessibility: 'staff_only' },
  ],
};

Fact

A piece of knowledge in the world. Facts have visibility levels and can be revealed to or hidden from specific entities.

interface Fact {
  id: string;
  content: string;
  visibility: 'public' | 'secret' | 'rumor';
  knownBy: string[];
}

Field	Type	Description
`id`	`string`	Unique fact ID
`content`	`string`	The fact content text
`visibility`	`'public' \| 'secret' \| 'rumor'`	Visibility level
`knownBy`	`string[]`	Entity names that know this fact

Example:

const facts: Fact[] = [
  { id: 'f1', content: 'The cafe was founded in 1985', visibility: 'public', knownBy: [] },
  { id: 'f2', content: 'Sera is planning a surprise party', visibility: 'secret', knownBy: ['Sera', 'Mika'] },
  { id: 'f3', content: 'Someone saw a ghost in the storeroom', visibility: 'rumor', knownBy: ['Mika'] },
];

ProgressionTrigger

A condition that triggers a phase transition in the world's progression system.

interface ProgressionTrigger {
  id: string;
  condition:
    | { type: 'event_count'; eventType: string; threshold: number }
    | { type: 'time_elapsed'; seconds: number }
    | { type: 'relationship'; entityA: string; entityB: string; field?: 'strength' | 'trust'; above?: number; below?: number }
    | { type: 'persona_emotion'; entity: string; dimension: 'V' | 'A' | 'D'; above?: number; below?: number };
  targetPhase: string;
  oneShot?: boolean;
}

Field	Type	Description
`id`	`string`	Unique trigger ID
`condition`	`object`	Condition that must be met (see condition types below)
`targetPhase`	`string`	Phase to transition to when triggered
`oneShot`	`boolean?`	If true, trigger fires only once

Condition Types

event_count -- fires when a specific event type has occurred N times:

{ type: 'event_count', eventType: 'chat', threshold: 10 }

time_elapsed -- fires after N seconds have passed:

{ type: 'time_elapsed', seconds: 3600 }

relationship -- fires when a relationship field crosses a threshold:

{ type: 'relationship', entityA: 'Sera', entityB: 'user', field: 'trust', above: 0.8 }

persona_emotion -- fires when an entity's emotion dimension crosses a threshold:

{ type: 'persona_emotion', entity: 'Sera', dimension: 'V', below: -0.5 }

Example:

const triggers: ProgressionTrigger[] = [
  {
    id: 'to-chapter2',
    condition: { type: 'event_count', eventType: 'chat', threshold: 20 },
    targetPhase: 'chapter_2',
    oneShot: true,
  },
  {
    id: 'crisis',
    condition: { type: 'persona_emotion', entity: 'Sera', dimension: 'V', below: -0.7 },
    targetPhase: 'crisis',
  },
  {
    id: 'friendship-arc',
    condition: { type: 'relationship', entityA: 'Sera', entityB: 'user', field: 'trust', above: 0.9 },
    targetPhase: 'deep_friendship',
    oneShot: true,
  },
];

World Types

On this page