Quick Start
Get started with molroo in 5 minutes.
Quick Start
Build an AI character with authentic emotions in under 5 minutes.
Prerequisites
- Node.js 18+ installed
- A molroo API key from the dashboard
- An LLM provider API key (OpenAI, Anthropic, etc.) if you want LLM-generated responses
Install
npm install @molroo-ai/sdk @molroo-ai/adapter-llmYou also need a Vercel AI SDK provider for your chosen LLM:
# Pick one (or more)
npm install @ai-sdk/openai
npm install @ai-sdk/anthropicCreate a world
A world is a container that holds entities (characters, players), spaces, and rules. Here we create a simple cafe world with one persona named Sera.
import { MolrooWorld } from '@molroo-ai/sdk';
import { VercelAIAdapter } from '@molroo-ai/adapter-llm';
import { openai } from '@ai-sdk/openai';
const llm = new VercelAIAdapter({ model: openai('gpt-4o-mini') });
const world = await MolrooWorld.create(
{ baseUrl: 'https://api.molroo.io', apiKey: 'your-api-key', llm },
{
definition: {
identity: { name: 'Cafe World', genre: 'slice-of-life', tone: 'warm' },
},
entities: [
{ name: 'user', type: 'user' },
{ name: 'Sera', type: 'persona' },
],
personaConfigs: {
Sera: {
identity: {
name: 'Sera',
role: 'friendly barista',
speakingStyle: 'warm and casual',
},
personality: { O: 0.7, C: 0.6, E: 0.8, A: 0.9, N: 0.3, H: 0.8 },
},
},
},
);The personality object uses HEXACO 6-factor notation: Openness, Conscientiousness, Extraversion, Agreeableness, Neuroticism, Honesty-Humility. Values range from 0 to 1.
Chat with a persona
Send a message and get back an emotion-aware response:
const result = await world.chat('Sera', 'Hi! What do you recommend today?');
console.log(result.response.text);
// "Oh hey! You've gotta try our new lavender latte — it's been flying off the shelf!"
console.log(result.response.emotion.discrete.primary);
// e.g. 'joy'The result contains the full emotion state, including VAD coordinates, discrete emotion labels, mood, and somatic markers.
Connect to an existing world
If you already created a world and want to reconnect later:
const world = await MolrooWorld.connect(
{ baseUrl: 'https://api.molroo.io', apiKey: 'your-api-key', llm },
'existing-world-id',
);Emotion-only mode (no LLM)
You can skip LLM integration entirely and provide manual appraisal values. This is useful for game engines or systems that already have their own dialogue generation:
const result = await world.chat('Sera', 'Hello', {
appraisal: {
goal_relevance: 0.5,
goal_congruence: 0.8,
expectedness: 0.6,
controllability: 0.5,
agency: 0,
norm_compatibility: 0.7,
},
});In emotion-only mode, the text field in the response will be empty. You get pure emotion computation without any LLM calls.