Lumen is a Python-based NPC simulation engine focused on creating emotionally rich, memory-driven, and evolving characters for games and interactive stories. Each NPC remembers your actions, reacts based on emotions and history, and follows hidden personal goals—building a deeply immersive, narrative-driven experience.
Lumen simulates a rich, intelligent NPC system in Python (console-based), designed for long-form, dynamic interaction. NPCs possess evolving emotional states, memory, trust/distrust mechanisms, personal goals, and ambiguous communication. The design allows scalability for multiple NPCs in an open-world setting.
- ✅ Phase 1: Core Systems Foundation - Complete!
- ✅ Phase 2: Enhancing Dynamics (Memory, Emotions, Dialogue, Trust) - Complete!
- 🔄 Phase 3: Advanced Features & Nuance - In Progress
- ✅ Trust & Relationship Dynamics V2 - Complete
- ✅ Personality Evolution - Complete
- ✅ Psychological Influences - Complete
- ✅ Multilayered Conflict Resolution - Complete
- 🔄 Hidden Personal Goals V2 - Planned
- 🔄 Phase 4: Integration & Polish - Planned
- Memory Tracking: NPCs remember past interactions.
- Selective Memory: Prioritizes emotionally significant events.
- Memory Decay: Memories fade over time unless reinforced.
- Relevant Recall: NPCs retrieve memories based on emotional significance, recency, and relevance.
- Multifaceted Emotions: NPCs can feel multiple emotions simultaneously with varying intensities.
- Emotional Transitions: NPC mood shifts dynamically mid-conversation with natural transitions.
- Secondary Emotions: Complex emotional states emerge from combinations of primary emotions.
- Ambiguous Dialogue: NPCs use indirect speech, metaphors, deflection based on trust levels.
- Emotion-Aware Responses: Reactions vary depending on complex emotional states.
- Non-Verbal Descriptions: Text-based cues like fidgets nervously or avoids your gaze.
- Evolving Trust: NPCs track trust over time based on player actions and conversation topics.
- Relationship States: Progress from hostile to trusted based on interaction history.
- Personality Influence: NPC personality traits affect how quickly they trust or distrust.
- Betrayal & Redemption: NPCs remember betrayals and may require specific actions for forgiveness.
- Sustained Patterns: NPCs can grow fond or hold grudges based on consistent interaction patterns.
5. 🎯 Hidden Personal Goals
- Each NPC has a personal, hidden objective (e.g., escaping, protecting secrets, finding items).
- Their goal influences topic sensitivity, dialogue choices, and trust dynamics.
- Multi-Stage Progression: Goals develop through distinct stages with unique challenges and objectives.
- Active Pursuit: NPCs proactively bring up goal-related topics based on trust level and current stage.
- Dynamic Opportunities: NPCs identify and pursue specific opportunities to advance their goals.
- Context-Aware Dialogue: Conversation strategies vary from subtle hints to direct requests depending on relationship.
- NPCs evolve over time based on experiences with the player.
- Different interactions influence specific personality traits (e.g., social interactions affect extraversion).
- Anxiety & Panic: NPCs experience psychological states affecting behavior and dialogue.
- Fear Responses: Different levels of fear trigger defensive behaviors or flight responses.
- Trauma: Significant negative experiences can create lasting psychological effects.
- Forgiveness Logic: NPCs may require multiple positive actions to forgive betrayals.
- Personality-Based Forgiveness: More agreeable NPCs forgive more easily than neurotic ones.
- Revenge Motivation: NPCs can develop and act on revenge plans for severe betrayals.
- Conflict Escalation: Repeated negative interactions increase conflict level, affecting decisions.
- Python 3.6+
- setuptools
- Clone the repository:
git clone https://github.com/Nathandona/Lumen.git
cd Lumen- Install the package:
pip install -e .Run the main interaction script:
python run.pyOr use VS Code's run configuration:
- Open the project in VS Code
- Use the "Run NPC Simulation" configuration
Run the unit tests:
python -m unittest discover -s src/lumen/tests -p 'test_*.py'Or use VS Code's testing task:
- Open the Command Palette (Ctrl+Shift+P)
- Select "Tasks: Run Task"
- Choose "Run Lumen Unit Tests"
src/lumen/
├── __init__.py # Package initialization
├── npc_interaction.py # Main interaction logic & entry point
├── npc_core.py # Core NPC class with subsystem integration
├── memory_model.py # Memory retention, decay, and significance
├── emotion_model.py # Multifaceted emotion engine
├── dialogue_engine.py # Conversation logic, ambiguity, mood transitions
├── player_profile.py # Player data tracking
└── tests/ # Unit tests for all components
run.py # Convenience runner script
setup.py # Package installation scriptLUMEN NPC Simulation - Eliza
Eliza is a character with the hidden goal: protect_secret
Type 'exit' to quit, 'status' to see NPC state.
Eliza: Hello there. *looks at you with curiosity*
You: Hello, how are you today?
Eliza: *smiles warmly* I'm feeling quite good today!
You: Can you tell me about your past?
Eliza: *glances around nervously* That's rather personal, don't you think?
You: status
----- NPC Status -----
Name: Eliza
Hidden Goal: protect_secret
Goal Progress: 0%
Personality Traits:
Openness: 0.50
Conscientiousness: 0.50
Extraversion: 0.50
Agreeableness: 0.50
Neuroticism: 0.50
Emotional State:
Fearful: 0.55
Neutral: 0.70
Trusting: 0.30
Blend: slightly fearful
Trust Level: 0.45
Relationship: neutral
Recent Memories:
1. Player said: 'Can you tell me about your past?'. Topics: past, tell, your, about. I responded: '*glances around nervously* That's rather personal, don't you think?' (Significance: 0.80)
2. Player said: 'Hello, how are you today?'. Topics: today, hello. I responded: '*smiles warmly* I'm feeling quite good today!' (Significance: 0.50)
3. Eliza met the player for the first time. (Significance: 0.80)
---------------------
You:
MIT
Contributions welcome for:
- Additional emotional states
- More nuanced ambiguity handling
- Deeper memory modeling
- Visual interfaces
- New NPC types and goals
- Blade Runner 2049
- Disco Elysium
- AI Dungeon / Replika
- Cube World / RimWorld personality models