supernpc 0.1.0

AI-Powered NPCs for Games - Local LLM NPCs with memory and emotions

Super NPC

AI-Powered NPCs for Games - Local LLM NPCs with Memory and Emotions

Super NPC is a universal AI NPC system for games. Add intelligent, emotional NPCs with persistent memory to any game with just a few lines of code. Runs entirely locally using your player's hardware.

✨ Features

• 🧠 Persistent Memory: NPCs remember conversations, events, and relationships across game sessions
• 😊 Emotional Intelligence: NPCs have dynamic emotions that affect their behavior and responses
• 👥 Personality System: Big Five personality traits make each NPC unique
• 🤝 Relationship Tracking: NPCs build trust/familiarity with players over time
• 💬 Natural Dialogue: LLM-powered conversations (Ollama, OpenAI, Anthropic)
• 🔄 Universal Integration: REST API, Python library, Unity/Godot plugins
• 💾 State Persistence: JSON serialization for saving/loading NPC states
• 🚀 Performance Optimized: Handles 100+ concurrent NPCs efficiently

🚀 Quick Start

Python Library

from supernpc import NPCAgent

# Create an intelligent NPC
npc = NPCAgent(
    name="Elara",
    role="blacksmith",
    personality="friendly",
    backstory=["I've forged weapons for 20 years"]
)

# Chat with the NPC
response = npc.chat("Player", "Do you have any swords for sale?")
print(f"Elara: {response}")

# NPC remembers and emotions change
npc.save_state("elara.json")

REST API Server

# Install and run
pip install supernpc[server]
supernpc-server --port 8080 --model qwen2.5:1.5b

# Any game can integrate
curl -X POST http://localhost:8080/chat \
  -d '{"npc_id": "merchant", "player": "hero", "message": "What do you sell?"}'

🎮 Engine Integrations

Unity (C#)

using SuperNPC.Unity;

NPCAgent npc = new NPCAgent("Guard");
string response = npc.Chat("Player", "Can I enter the castle?");

Godot (GDScript)

extends SuperNPC

func _ready():
    npc_id = "villager"
    personality = "curious"

func _on_player_interact(message):
    var response = chat("Player", message)
    show_dialogue(response)

📦 Installation

pip install supernpc

# For development
git clone https://github.com/supernpc/npcs
cd supernpc-sdk
pip install -e .

🏗️ Architecture

supernpc/
├── agent.py          # Main NPCAgent class
├── memory.py         # Memory storage & retrieval
├── emotions.py       # Emotional state management
├── personality.py    # Big Five personality traits
├── relationships.py  # Trust & familiarity tracking
├── dialogue.py       # LLM integration (Ollama/OpenAI/Anthropic)
└── __init__.py       # Package exports

🤖 LLM Support

• Ollama (Local): qwen2.5:1.5b, llama2:7b, etc.
• OpenAI: GPT-4, GPT-3.5-turbo
• Anthropic: Claude models
• Custom: Extend for any API

📊 Example NPC States

{
  "name": "Elara",
  "role": "blacksmith",
  "emotions": {"happiness": 0.7, "anger": 0.1},
  "memories": [
    {"content": "Player bought a sword", "importance": 0.6},
    {"content": "Player asked about apprentice", "importance": 0.8}
  ],
  "relationships": {
    "Player": {"trust": 0.75, "familiarity": 0.9}
  }
}

🎯 Use Cases

• RPGs: Shopkeepers who remember your purchases
• Adventure Games: NPCs with emotional arcs
• MMOs: Persistent NPC relationships across sessions
• Visual Novels: Dynamic character development
• Simulation Games: AI characters with realistic social behavior

🔧 API Reference

NPCAgent

class NPCAgent:
    def __init__(self, name, role="villager", personality=None, backstory=None)
    def chat(self, player_name, message) -> str
    def get_status(self, player_name) -> dict
    def save_state(self, filepath)
    def load_state(self, filepath)

Memory System

memory_store = MemoryStore(max_memories=100)
memory_store.add(Memory("Player helped me", importance=0.8))
relevant = memory_store.retrieve("help", limit=5)

🤝 Contributing

We welcome contributions! See our Contributing Guide.

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

📄 License

MIT License - see LICENSE file.

🌟 Roadmap

• Unity Asset Store package
• Godot Asset Library plugin
• Docker container with pre-configured models
• Voice synthesis integration
• Multi-language support
• WebSocket real-time dialogue
• Mobile game optimizations

📞 Contact & Support

Get Help

• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Issues
• 💬 General Discussion: GitHub Discussions
• 📖 Documentation: docs.supernpc.ai

Community

• Discord: Join our community
• Twitter/X: @supernpc
• GitHub: Super NPC Organization

Commercial Support

For enterprise support, custom integrations, or priority assistance:

• Email: [e-mail] (coming soon)
• GitHub Sponsors: Support ongoing development

---

Made with ❤️ for game developers who want smarter NPCs

📊 Current Status

✅ Completed (Phase 1)

• Extract core AI from Pygame dependencies
• Create standalone supernpc package
• Add multiple LLM backend support (Ollama, OpenAI, Anthropic)
• JSON state serialization for any game
• Python library API
• REST API server implementation
• Comprehensive test suite

🚧 In Progress (Phase 2)

• Unity C# bindings
• Godot GDScript integration
• Docker containerization
• Performance optimization for 100+ NPCs

📋 Roadmap (Phase 3+)

• WebSocket real-time dialogue
• Voice synthesis integration
• Multi-language support
• Unity Asset Store package
• Godot Asset Library plugin