npcsts

NPCsTS — Social Engine for NPC Interactions

A TypeScript social engine for creating NPCs with personality, moods, relationships, and dialogue templates. Designed for games, virtual worlds, and interactive narratives.

• Zero runtime dependencies — pure TypeScript
• Modular architecture — import only what you need
• Extensible — custom interaction strategies, trait-to-interaction mappings, locale support
• Seeded randomness — deterministic rolls for testing

Installation

npm install npcsts

Quick Start

import {
  Character,
  InteractionEngine,
  TemplateManager,
  GreetStrategy,
  BoastStrategy,
  STAT_PRESETS,
} from 'npcsts';

// 1. Create characters
const alice = new Character({
  id: 'alice',
  name: 'Alice',
  personality: 'lively',
  traits: ['chatty'],
  stats: STAT_PRESETS.CHARISMATIC,
});

const bob = new Character({
  id: 'bob',
  name: 'Bob',
  personality: 'thoughtful',
  traits: ['kind'],
  stats: STAT_PRESETS.FRIENDLY,
});

// 2. Establish relationships
alice.meet(bob.id);
bob.meet(alice.id);

// 3. Set up the engine
const engine = new InteractionEngine({ seed: 42 });
engine.registerStrategy('greet', new GreetStrategy());
engine.registerStrategy('boast', new BoastStrategy());

// 4. Run an interaction
const result = engine.interact(alice, bob, 'greet');
console.log(result.dialogue.opener); // "Hey there, Bob!"
console.log(result.tone);            // "positive"
console.log(result.logs);            // Roll breakdown

API Overview

Module	Exports	Purpose
Character	Character class	NPC with stats, mood, relationships, inventory
InteractionEngine	InteractionEngine	Orchestrates interactions, cooldowns, seeded rolls
GreetStrategy, JokeStrategy, ComplimentStrategy, BoastStrategy, IdleThoughtStrategy	Strategy classes	Built-in interaction types
TemplateManager	TemplateManager	Dialogue template loading, variable substitution
MemoryManager	MemoryManager	Character memory storage, decay, and recall
PreferenceManager	PreferenceManager	Likes/dislikes across categories
PropManager	PropManager, generatePropComment	Object interactions and prop comments
WorldEventManager	WorldEventManager, getEventReaction	World events with decay and character reactions
LocaleManager / TranslationManager	LocaleManager, TranslationManager	i18n with pluralization and gender agreement
Types	InteractionResult, Stats, PronounSet, Trait, MoodTier, RelationshipTier, etc.	Core type definitions

Built-in Strategies

• Greet — Basic greeting with mood/relationship modifiers
• Joke — Humor-based interaction (stat-dependent)
• Compliment — Flattery with relationship bonuses
• Boast — Self-promotion (AUTH-based, can backfire)
• IdleThought — Monologue-style observation (CHAR-based)

Stats System

Characters have three stats that sum to 10:

Stat	Meaning
CHAR	Charisma — social charm and wit
AUTH	Authority — commanding presence
RAPP	Rapport — empathy and connection

Use STAT_PRESETS for quick setups (CHARISMATIC, AUTHORITATIVE, FRIENDLY, BALANCED, etc.).

Mood System

Mood ranges from 0–4 and affects interaction outcomes:

Value	Tier	Modifier
3–4	Happy	+3
2–2.99	Content	+1
1–1.99	Stressed	-1
0–0.99	Depressed	-3

Depressed characters cannot joke, boast, or compliment.

Relationships

Relationship scores range 0–100 and are tiered:

Score	Tier	Modifier
0–30	Enemy	Negative
31–70	Acquaintance	Neutral
71–100	Friend	Positive

Localization

import { LocaleManager, TranslationManager } from 'npcsts';

const lm = new LocaleManager('en-US');
lm.loadTranslations({
  locale: 'es-ES',
  translations: { 'greeting': '¡Hola, {name}!' },
});

const tm = new TranslationManager(lm);
const result = tm.translate('greeting', {
  locale: 'es-ES',
  variables: { name: 'Alice' },
});
console.log(result.text); // "¡Hola, Alice!"

Custom Interaction Strategies

import type { Character, InteractionStrategy, Tone, InteractionResult } from 'npcsts';

class DanceStrategy implements InteractionStrategy {
  calculateBaseScore(actor: Character, target: Character): number {
    return (actor.stats.CHAR + target.stats.RAPP) / 2;
  }
  getSpecificModifier(actor: Character, target: Character): number {
    return 0;
  }
  getRandomFactor(random: () => number): number {
    return (random() - 0.5) * 4;
  }
  calculateDeltas(actor: Character, target: Character, tone: Tone, score: number, logs: string[]): InteractionResult['deltas'] {
    const mood = tone === 'positive' ? 1 : tone === 'negative' ? -1 : 0;
    return { actor: { mood }, target: { mood } };
  }
}

engine.registerStrategy('dance', new DanceStrategy());

Repository Structure

NPCsTS/
├── package.json           # npm package config
├── tsconfig.json          # TypeScript config
├── vitest.config.ts       # Test config
├── .gitignore
├── README.md              # This file
├── docs/
│   ├── AI_SKILL.md        # AI agent skill reference
│   └── api/               # TypeDoc-generated API reference
└── src/
    ├── index.ts           # Barrel export
    ├── types.ts           # Core types + constants
    ├── character.ts       # Character class
    ├── stats.ts           # Stat utilities
    ├── mood.ts            # Mood utilities
    ├── relationships.ts   # Relationship utilities
    ├── memory.ts          # MemoryManager
    ├── preferences.ts     # PreferenceManager
    ├── props.ts           # PropManager
    ├── world-events.ts    # WorldEventManager
    ├── localization.ts    # LocaleManager + TranslationManager
    ├── templates/         # TemplateManager
    └── interactions/      # Strategies + InteractionEngine

Development

# Build
npm run build

# Test
npm test

# Generate API docs
npm run docs

# Serve docs
npm run docs:serve

License

MIT