Core Concepts

This guide explains the fundamental building blocks of molroo. Understanding these concepts is essential for designing expressive, emotionally authentic worlds.

World

A World is the top-level container that holds everything together: entities, spaces, rules, knowledge, and progression. Each world runs as an isolated instance on the server (backed by a Durable Object), so worlds never interfere with each other.

A world has:

• Identity -- name, genre, era, tone, lore
• Culture -- shared values, taboos, social norms
• Knowledge -- facts with visibility rules (public, secret, rumor)
• Progression -- phase system for story arcs with triggers

const world = await MolrooWorld.create(clientConfig, {
  definition: {
    identity: {
      name: 'Moonlight Academy',
      genre: 'fantasy',
      era: 'modern',
      tone: 'mysterious',
      lore: 'A prestigious academy where students discover hidden magical talents.',
    },
  },
  // ...entities, spaces, etc.
});

Entity

An Entity is anything that exists in a world. There are three types:

Every world needs at least one user entity (the default from for chat() calls) and one persona entity to interact with.

entities: [
  { name: 'user', type: 'user' },
  { name: 'Sera', type: 'persona' },
  { name: 'Townsperson', type: 'secondary' },
],

Persona

A Persona is an entity with a full emotion engine. It is the core unit of emotional simulation in molroo. Each persona has:

• Identity -- name, role, backstory, speaking style
• Personality -- HEXACO 6-factor model with 24 facets
• Soul Stages -- 15 levels tracking psychological resilience (higher = more volatility)
• Needs -- autonomy, competence, relatedness (self-determination theory)
• Goals -- active objectives that influence appraisal
• Relationships -- trust, familiarity, and affiliation with other entities
• Mood -- slow-moving emotional baseline
• Somatic Markers -- physiological signals tied to emotion (e.g., racing heart, sweaty palms)

personaConfigs: {
  Sera: {
    identity: {
      name: 'Sera',
      role: 'friendly barista',
      backstory: 'Grew up in a small coastal town...',
      speakingStyle: 'warm and casual, uses food metaphors',
    },
    personality: { O: 0.7, C: 0.6, E: 0.8, A: 0.9, N: 0.3, H: 0.8 },
  },
},

HEXACO personality model

molroo uses the HEXACO-PI-R 6-factor personality model. Each factor ranges from 0 to 1:

VAD (Valence-Arousal-Dominance)

VAD is the 3-dimensional coordinate system that represents emotional state. Every emotion maps to a point in this space.

Examples of emotions in VAD space:

The emotion engine operates natively in VAD space. Discrete emotion labels (joy, anger, sadness, etc.) are derived from the VAD coordinates as a convenience.

Space

A Space is a location within a world. Entities exist in exactly one space at any given time. Spaces can connect to each other with distance and traversal properties.

Three types of spaces:

spaces: [
  {
    name: 'Main Hall',
    type: 'physical',
    description: 'The central gathering place.',
    connections: [
      { target: 'Garden', distance: 50, traversalTime: 30 },
    ],
  },
  {
    name: 'Garden',
    type: 'physical',
    description: 'A peaceful garden with a fountain.',
  },
],

Spaces influence emotional interactions: entities in the same space can observe each other's emotional states, and events can propagate spatially.

Appraisal

Appraisal is how a persona evaluates an incoming stimulus (message, event, or action). It is the entry point of the emotion pipeline. The appraisal is a 6-dimensional vector:

In normal operation, the LLM generates appraisal values automatically based on the persona's context. You can also provide manual appraisal in emotion-only mode.

Knowledge

Knowledge represents facts that exist in a world. Each piece of knowledge has a visibility level:

Knowledge influences how personas interpret events and generate responses. A persona who knows a secret will react differently than one who does not.

Progression

Progression is a phase system that enables story arcs. You define phases with triggers that advance the narrative:

Phases can change world rules, unlock spaces, reveal knowledge, and alter persona behavior -- enabling dynamic, evolving narratives.

Next steps