molroo docs
SDK ReferenceTypes

Configuration Types

MolrooWorldConfig, CreateWorldInput, WorldDefinitionInput, and related setup types.

Configuration Types

Types used when creating and configuring molroo worlds.

import type {
  MolrooWorldConfig,
  CreateWorldInput,
  WorldDefinitionInput,
  EntityInput,
  SpaceInput,
  EnvironmentInput,
  WorldInteractionOptions,
  PersonaConfigData,
  UserProfile,
} from '@molroo-ai/sdk';

MolrooWorldConfig

Configuration for connecting to a molroo world instance.

interface MolrooWorldConfig {
  baseUrl: string;
  apiKey: string;
  worldId?: string;
}
FieldTypeDescription
baseUrlstringBase URL of the molroo API (e.g., 'https://api.molroo.io')
apiKeystringAPI key for authentication
worldIdstring?World instance ID. Set automatically by MolrooWorld.create()

The full config passed to MolrooWorld.create() and MolrooWorld.connect() extends this with optional adapters:

{
  baseUrl: string;
  apiKey: string;
  llm?: LLMAdapter;       // LLM adapter for generating responses
  storage?: StorageAdapter; // Storage adapter for snapshot backup
  memory?: MemoryAdapter;   // Memory adapter for episode persistence
  events?: EventAdapter;    // Event adapter for SDK-level event emission
}

CreateWorldInput

Input for creating a new world via MolrooWorld.create().

interface CreateWorldInput {
  definition: WorldDefinitionInput;
  entities: EntityInput[];
  spaces?: SpaceInput[];
  environment?: Partial<EnvironmentInput>;
  personaConfigs: Record<string, Record<string, unknown>>;
  interaction?: WorldInteractionOptions;
}
FieldTypeRequiredDescription
definitionWorldDefinitionInputYesWorld identity, rules, culture, topology, knowledge, progression
entitiesEntityInput[]YesInitial entities (personas, users, secondary characters)
spacesSpaceInput[]NoInitial spaces. If omitted, a default space is created
environmentEnvironmentInputNoInitial environment (weather, location, ambiance)
personaConfigsRecord<string, Record<string, unknown>>YesPersona configs keyed by entity name
interactionWorldInteractionOptionsNoGroup awareness, emotional contagion, propagation settings

Example:

const setup: CreateWorldInput = {
  definition: {
    identity: { name: 'Moonlight Academy', genre: 'school', tone: 'dramatic' },
    rules: {
      social: { norms: ['respect seniors', 'no fighting in hallways'] },
      narrative: { consequenceSpeed: 'moderate' },
    },
    culture: {
      coreValues: ['honor', 'friendship', 'growth'],
    },
  },
  entities: [
    { name: 'user', type: 'user' },
    { name: 'Sera', type: 'persona', spaceId: 'classroom' },
    { name: 'Mika', type: 'persona', spaceId: 'library' },
  ],
  spaces: [
    { name: 'classroom', type: 'physical', capacity: 30 },
    { name: 'library', type: 'physical', capacity: 20 },
    { name: 'courtyard', type: 'physical', capacity: 50 },
  ],
  environment: { weather: 'sunny', location: 'hilltop campus', ambiance: 'cheerful' },
  personaConfigs: {
    Sera: {
      identity: { name: 'Sera', role: 'student council president' },
      personality: { O: 0.7, C: 0.8, E: 0.6, A: 0.9, N: 0.3, H: 0.8 },
    },
    Mika: {
      identity: { name: 'Mika', role: 'quiet bookworm' },
      personality: { O: 0.9, C: 0.5, E: 0.3, A: 0.7, N: 0.6, H: 0.7 },
    },
  },
  interaction: {
    groupAwareness: true,
    emotionalContagion: true,
    propagation: 'same-space',
  },
};

WorldDefinitionInput

Describes the world's identity, rules, culture, spatial topology, knowledge system, and progression phases.

interface WorldDefinitionInput {
  identity?: {
    name: string;
    genre?: string;
    era?: string;
    tone?: string;
    lore?: string;
  };
  rules?: {
    physics?: {
      canFly?: boolean;
      canTeleport?: boolean;
      deathIsPermanent?: boolean;
      magicExists?: boolean;
    };
    social?: {
      norms?: string[];
      taboos?: string[];
      hierarchies?: string[];
    };
    narrative?: {
      tone?: string;
      violenceLevel?: string;
      romanceLevel?: string;
      consequenceSpeed?: string;
    };
  };
  culture?: {
    coreValues?: string[];
    normMap?: Record<string, number>;
    socialProtocol?: {
      greetingStyle?: string;
      addressSystem?: string;
      tabooTopics?: string[];
    };
  };
  topology?: {
    connections?: SpaceConnection[];
  };
  time?: Record<string, unknown>;
  knowledge?: {
    facts?: Fact[];
    defaultVisibility?: string;
  };
  progression?: {
    initialPhase?: string;
    phases?: Record<string, { description?: string; normMapOverride?: Record<string, number> }>;
    triggers?: ProgressionTrigger[];
  };
}

identity

FieldTypeDescription
namestringWorld name (required)
genrestring?Genre label (e.g., 'slice-of-life', 'fantasy', 'school')
erastring?Time period (e.g., 'modern', 'medieval')
tonestring?Overall tone (e.g., 'warm', 'dark', 'dramatic')
lorestring?Background lore text

rules.physics

FieldTypeDescription
canFlyboolean?Whether entities can fly
canTeleportboolean?Whether teleportation is possible
deathIsPermanentboolean?Whether death is permanent
magicExistsboolean?Whether magic exists in the world

rules.social

FieldTypeDescription
normsstring[]?Social norms (e.g., ['respect elders'])
taboosstring[]?Social taboos
hierarchiesstring[]?Social hierarchies

rules.narrative

FieldTypeDescription
tonestring?Narrative tone
violenceLevelstring?Violence level (e.g., 'none', 'mild', 'high')
romanceLevelstring?Romance level
consequenceSpeedstring?How fast consequences materialize (e.g., 'immediate', 'moderate', 'slow')

culture

FieldTypeDescription
coreValuesstring[]?World's core values
normMapRecord<string, number>?Norm weights (keys are norm names, values are importance 0-1)
socialProtocol.greetingStylestring?How entities greet each other
socialProtocol.addressSystemstring?How entities address each other
socialProtocol.tabooTopicsstring[]?Topics that are taboo in this culture

topology

FieldTypeDescription
connectionsSpaceConnection[]Spatial connections between spaces

knowledge

FieldTypeDescription
factsFact[]Initial facts in the world
defaultVisibilitystring?Default fact visibility ('public', 'secret', 'rumor')

progression

FieldTypeDescription
initialPhasestring?Starting phase name
phasesRecord<string, { description?, normMapOverride? }>Phase definitions
triggersProgressionTrigger[]Conditions that trigger phase transitions

EntityInput

Input for creating an entity.

interface EntityInput {
  name: string;
  type: EntityType;   // 'persona' | 'user' | 'secondary'
  profile?: UserProfile;
  spaceId?: string;
}
FieldTypeRequiredDescription
namestringYesEntity name (must be unique within the world)
typeEntityTypeYes'persona', 'user', or 'secondary'
profileUserProfileNoOptional profile data
spaceIdstring?NoInitial space. If omitted, placed in default space

SpaceInput

Input for creating a space.

interface SpaceInput {
  name: string;
  type?: SpaceType;    // 'physical' | 'virtual' | 'abstract'
  capacity?: number;
}
FieldTypeDefaultDescription
namestring--Space name (required)
typeSpaceType'physical'Space type
capacitynumber?--Maximum entities the space can hold

EnvironmentInput

Input for setting or updating the world environment.

interface EnvironmentInput {
  weather?: string;
  location?: string;
  ambiance?: string;
  [key: string]: unknown;  // Extensible
}
FieldTypeDescription
weatherstring?Current weather (e.g., 'sunny', 'rainy', 'thunderstorm')
locationstring?Location description
ambiancestring?Ambient mood/atmosphere description
[key]unknownAdditional custom environment fields

WorldInteractionOptions

World-level interaction settings that control how entities affect each other.

interface WorldInteractionOptions {
  groupAwareness?: boolean;
  emotionalContagion?: boolean;
  propagation?: 'none' | 'same-space' | 'adjacent';
}
FieldTypeDefaultDescription
groupAwarenessboolean?falseEntities in the same space are aware of each other's interactions
emotionalContagionboolean?falseStrong emotions spread to nearby entities
propagationstring?'none'Event propagation radius: 'none', 'same-space', or 'adjacent'

PersonaConfigData

Persona configuration data. See MolrooPersona for full details.

interface PersonaConfigData {
  personality?: Record<string, number>;   // HEXACO: { O, C, E, A, N, H }
  identity?: Record<string, unknown>;     // name, role, speakingStyle, coreValues
  goals?: Array<Record<string, unknown>>; // { id, content, priority, status, mutable }
  [key: string]: unknown;                 // Extensible
}

UserProfile

Optional profile data for user-type entities.

interface UserProfile {
  displayName?: string;
  role?: string;
  description?: string;
  personalityHints?: string;
}
FieldTypeDescription
displayNamestring?Display name for the user
rolestring?User's role in the world
descriptionstring?Brief description
personalityHintsstring?Hints about the user's personality (for LLM context)

On this page