Configuration Types
MolrooWorldConfig, CreateWorldInput, WorldDefinitionInput, and related setup types.
Types used when creating and configuring molroo worlds.
import type {
MolrooWorldConfig,
CreateWorldInput,
WorldDefinitionInput,
EntityInput,
SpaceInput,
EnvironmentInput,
WorldInteractionOptions,
PersonaConfigData,
UserProfile,
} from '@molroo-ai/sdk';
Configuration for connecting to a molroo world instance.
interface MolrooWorldConfig {
baseUrl: string;
apiKey: string;
worldId?: string;
}
| Field | Type | Description |
|---|
baseUrl | string | Base URL of the molroo API (e.g., 'https://api.molroo.io') |
apiKey | string | API key for authentication |
worldId | string? | 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
}
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;
}
| Field | Type | Required | Description |
|---|
definition | WorldDefinitionInput | Yes | World identity, rules, culture, topology, knowledge, progression |
entities | EntityInput[] | Yes | Initial entities (personas, users, secondary characters) |
spaces | SpaceInput[] | No | Initial spaces. If omitted, a default space is created |
environment | EnvironmentInput | No | Initial environment (weather, location, ambiance) |
personaConfigs | Record<string, Record<string, unknown>> | Yes | Persona configs keyed by entity name |
interaction | WorldInteractionOptions | No | Group 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',
},
};
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[];
};
}
| Field | Type | Description |
|---|
name | string | World name (required) |
genre | string? | Genre label (e.g., 'slice-of-life', 'fantasy', 'school') |
era | string? | Time period (e.g., 'modern', 'medieval') |
tone | string? | Overall tone (e.g., 'warm', 'dark', 'dramatic') |
lore | string? | Background lore text |
| Field | Type | Description |
|---|
canFly | boolean? | Whether entities can fly |
canTeleport | boolean? | Whether teleportation is possible |
deathIsPermanent | boolean? | Whether death is permanent |
magicExists | boolean? | Whether magic exists in the world |
| Field | Type | Description |
|---|
norms | string[]? | Social norms (e.g., ['respect elders']) |
taboos | string[]? | Social taboos |
hierarchies | string[]? | Social hierarchies |
| Field | Type | Description |
|---|
tone | string? | Narrative tone |
violenceLevel | string? | Violence level (e.g., 'none', 'mild', 'high') |
romanceLevel | string? | Romance level |
consequenceSpeed | string? | How fast consequences materialize (e.g., 'immediate', 'moderate', 'slow') |
| Field | Type | Description |
|---|
coreValues | string[]? | World's core values |
normMap | Record<string, number>? | Norm weights (keys are norm names, values are importance 0-1) |
socialProtocol.greetingStyle | string? | How entities greet each other |
socialProtocol.addressSystem | string? | How entities address each other |
socialProtocol.tabooTopics | string[]? | Topics that are taboo in this culture |
| Field | Type | Description |
|---|
facts | Fact[] | Initial facts in the world |
defaultVisibility | string? | Default fact visibility ('public', 'secret', 'rumor') |
| Field | Type | Description |
|---|
initialPhase | string? | Starting phase name |
phases | Record<string, { description?, normMapOverride? }> | Phase definitions |
triggers | ProgressionTrigger[] | Conditions that trigger phase transitions |
Input for creating an entity.
interface EntityInput {
name: string;
type: EntityType; // 'persona' | 'user' | 'secondary'
profile?: UserProfile;
spaceId?: string;
}
| Field | Type | Required | Description |
|---|
name | string | Yes | Entity name (must be unique within the world) |
type | EntityType | Yes | 'persona', 'user', or 'secondary' |
profile | UserProfile | No | Optional profile data |
spaceId | string? | No | Initial space. If omitted, placed in default space |
Input for creating a space.
interface SpaceInput {
name: string;
type?: SpaceType; // 'physical' | 'virtual' | 'abstract'
capacity?: number;
}
| Field | Type | Default | Description |
|---|
name | string | -- | Space name (required) |
type | SpaceType | 'physical' | Space type |
capacity | number? | -- | Maximum entities the space can hold |
Input for setting or updating the world environment.
interface EnvironmentInput {
weather?: string;
location?: string;
ambiance?: string;
[key: string]: unknown; // Extensible
}
| Field | Type | Description |
|---|
weather | string? | Current weather (e.g., 'sunny', 'rainy', 'thunderstorm') |
location | string? | Location description |
ambiance | string? | Ambient mood/atmosphere description |
[key] | unknown | Additional custom environment fields |
World-level interaction settings that control how entities affect each other.
interface WorldInteractionOptions {
groupAwareness?: boolean;
emotionalContagion?: boolean;
propagation?: 'none' | 'same-space' | 'adjacent';
}
| Field | Type | Default | Description |
|---|
groupAwareness | boolean? | false | Entities in the same space are aware of each other's interactions |
emotionalContagion | boolean? | false | Strong emotions spread to nearby entities |
propagation | string? | 'none' | Event propagation radius: 'none', 'same-space', or 'adjacent' |
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
}
Optional profile data for user-type entities.
interface UserProfile {
displayName?: string;
role?: string;
description?: string;
personalityHints?: string;
}
| Field | Type | Description |
|---|
displayName | string? | Display name for the user |
role | string? | User's role in the world |
description | string? | Brief description |
personalityHints | string? | Hints about the user's personality (for LLM context) |