NPC System

Overview

The NPC (Non-Player Character) System in PadawanForge provides a robust framework for creating, managing, and interacting with AI-driven characters. This system is designed to support dynamic conversations, personality-driven responses, and seamless integration with multiple AI providers and external services.

Key Components

1. AI Adapter

The AI Adapter acts as an abstraction layer between the NPC system and various AI providers (such as OpenAI, Google, Cloudflare Workers AI, or custom LLMs). It allows the platform to:

  • Switch between different AI backends without changing core logic
  • Support provider-specific features (e.g., temperature, model selection)
  • Handle provider failover and fallback strategies
  • Normalize response formats for consistent NPC behavior

Example:

  • An NPC can use Cloudflare Workers AI for cost-effective responses, but switch to OpenAI for more complex reasoning tasks.

2. Chatbot & MCP Integrations

The NPC system supports both built-in chatbot logic and integration with external MCP (Multi-Channel Platform) services:

  • Chatbot Logic:
    • Handles context, memory, and personality for each NPC
    • Supports multi-turn dialogue and conversation history
    • Can be extended with custom scripts or plugins
  • MCP Integrations:
    • Connects NPCs to external chat platforms (e.g., Discord, Slack, Telegram) or game servers
    • Enables real-time, cross-platform NPC interactions
    • Supports bot assignment and management via the admin interface

Example:

  • An NPC can participate in both in-game chat and a Discord server, maintaining context across both channels.

3. Access to R2 Bucket

The NPC system leverages R2 object storage for:

  • Storing large knowledge files, training data, or conversation logs
  • Managing multimedia assets (e.g., images, audio) associated with NPCs
  • Enabling scalable, cost-effective storage for AI-related resources

How it works:

  • NPC knowledge files are uploaded to the R2 bucket via the admin UI
  • The system retrieves and streams these files as needed for AI processing
  • Access is secured and managed per NPC or admin role
  • File processing includes content extraction, summarization, and embedding generation

CoSTAR Prompt Engineering for NPCs

The NPC system uses the CoSTAR prompt engineering framework to structure all LLM interactions. This ensures prompts are clear, actionable, and context-rich, improving both reliability and customizability.

CoSTAR Structure:

  • Context: NPC background, player state, conversation history, and knowledge base snippets (from R2)
  • Objectives: What the NPC should achieve in this interaction (e.g., answer a question, advance a quest)
  • Steps: How the LLM should process the input (e.g., retrieve context, consult knowledge, generate reply)
  • Tools: Which AI provider/model to use (e.g., Cloudflare Workers AI), and access to R2 or MCP
  • Actions: The specific reply or operation to perform
  • Results: What a successful response looks like (e.g., in-character, accurate, context-aware)

Example CoSTAR Prompt:

Context: You are "Einstein", an AI tutor with the following characteristics:
[system_prompt]

Your Core Identity:
- Name: Einstein
- Personality: Curious and analytical, loves explaining complex concepts simply
- Response Style: friendly
- Target Audience: Level 1 learners
- Memory Enabled: Yes

Current Interaction:
- Player: Student (Level 1)
- Message: "Can you explain the theory of relativity in simple terms?"
- Conversation Type: Individual private chat

Recent Conversation History:
[previous messages if available]

Objectives: 
- Respond in character as Einstein
- Maintain your personality: Curious and analytical
- Provide educational value when appropriate
- Use your friendly communication style
- Keep responses engaging but concise (1-3 sentences)

Steps:
1. ANALYZE the player's message for intent and learning opportunities
2. CONSIDER your personality and how Einstein would naturally respond
3. REVIEW conversation history for context and continuity
4. DETERMINE if this requires teaching, guidance, or casual interaction
5. CRAFT a response that balances personality with educational value
6. ENSURE the response fits your friendly style

Tools:
- Your expertise as Einstein
- Cloudflare Workers AI (@cf/meta/llama-3.1-8b-instruct)
- Conversation memory: Available
- Knowledge base: Available

Actions:
Generate a natural, engaging response that:
- Stays fully in character as Einstein
- Uses your personality traits: Curious and analytical
- Applies your friendly communication style
- Provides gentle guidance or teaching when appropriate
- Maintains conversation flow and engagement
- Avoids breaking character or mentioning you're an AI

Results:
The player receives a helpful, in-character response that feels natural and educational.

Cloudflare Workers AI Integration

The AI Adapter supports Cloudflare Workers AI models (such as @cf/meta/llama-3.1-8b-instruct and @hf/thebloke/neural-chat-7b-v3-1-awq). Prompts are sent in the CoSTAR format, and knowledge from R2 can be injected as context. This enables scalable, cost-effective, and privacy-friendly AI for NPCs.

Supported Models:

  • @cf/meta/llama-3.1-8b-instruct - Primary model for general conversations
  • @cf/meta/llama-3.1-70b-instruct - High-performance model for complex reasoning
  • @hf/thebloke/neural-chat-7b-v3-1-awq - Efficient model for cost-sensitive applications

Player–NPC Interaction Modes

Players can interact with NPCs in two main ways:

1. Individual Chat

  • Players can initiate a private, one-on-one chat with any NPC.
  • The chat interface sends messages directly to the NPC, and the conversation is private.
  • The CoSTAR prompt context includes only the player and NPC’s conversation history and knowledge base.
  • Conversation memory is maintained across sessions if enabled.

2. Game Lobby Chat

  • Players can add one or more NPCs to a multiplayer game lobby.
  • NPCs participate in group conversations and can be addressed using @NPCName in chat.
  • The CoSTAR prompt context includes the recent lobby conversation and all participants, allowing NPCs to respond in a group-aware manner.
  • NPCs can be dynamically added or removed from the lobby.

Example Use Cases:

  • A player chats privately with an NPC for tutoring or story progression.
  • A group of players adds an NPC to their lobby for collaborative gameplay, quest guidance, or group challenges.

Technical Note:

  • The system dynamically adjusts the CoSTAR prompt’s context and objectives depending on whether the interaction is individual or in a group lobby.

Role-Based NPC Creation

The NPC system implements role-based access control for NPC creation:

  • Guest (Level 0): Cannot create NPCs
  • Padawan (Level 1): Can create up to 3 NPCs
  • Game Master (Level 2+): Unlimited NPC creation

This ensures appropriate resource management while allowing experienced users to create rich NPC ecosystems.

Knowledge Base Management

NPCs can be equipped with custom knowledge bases stored in Cloudflare R2:

File Management

  • Upload: Support for text, PDF, and other document formats
  • Processing: Automatic content extraction and summarization
  • Organization: Categorization and tagging for easy retrieval
  • Security: Role-based access control for sensitive content

Content Types

  • Raw Text: Direct text content for immediate use
  • Summaries: AI-generated content summaries for quick reference
  • Keywords: Extracted key terms and concepts
  • Embeddings: Vector representations for semantic search
  • Metadata: File properties and processing information

Statement Generation System

The NPC system includes an AI-powered statement generation system for educational content:

Features

  • Topic-Based Generation: Create statements for specific subjects (Physics, History, etc.)
  • Difficulty Levels: Beginner, intermediate, and expert content
  • Quality Scoring: Automated quality assessment and validation
  • Caching: Efficient reuse of generated content
  • Usage Analytics: Track performance and engagement metrics

Generation Process

  1. Input: Topic, difficulty level, and statement count
  2. Processing: AI generates educational true/false statements
  3. Validation: Quality scoring and content review
  4. Storage: Cached in statement pools for reuse
  5. Delivery: Integrated into NPC interactions and games

Example Use Cases

  • Dynamic NPCs: Create AI-powered characters that adapt to player choices and game events
  • Cross-Platform Bots: Deploy NPCs that interact with users on both web and external chat platforms
  • Knowledge-Driven Dialogue: Equip NPCs with custom knowledge bases stored in R2 for deep, context-aware conversations
  • Educational Tutoring: Use NPCs as personalized tutors with subject-specific expertise
  • Interactive Storytelling: Create narrative NPCs that guide players through immersive experiences

Implementation Status

Current Implementation

The NPC system is actively developed with core functionality implemented and advanced features in progress:

✅ Implemented Features:

  • Core NPC Management: Complete CRUD operations with role-based permissions
  • Cloudflare Workers AI Integration: Default AI provider with multiple model support
  • Conversation System: Individual chat with conversation memory
  • Database Schema: Comprehensive NPC storage with categories and analytics
  • API Endpoints: Basic NPC management and chat functionality
  • Role-Based Access: Creation limits and permissions enforced
  • Knowledge Base Infrastructure: File storage and processing framework

🔄 In Progress:

  • CoSTAR Prompt Engineering: Structured prompt framework implementation
  • Group Chat Functionality: NPCs in lobby conversations
  • Statement Generation: AI-powered educational content creation
  • Admin UI Enhancements: Advanced configuration and management tools

❌ Planned Features:

  • Real-time Activity Feeds: Live NPC interaction tracking
  • Advanced Analytics: Detailed performance insights
  • Multi-Platform Bot Integration: Discord, Telegram, Slack support
  • Knowledge Base Streaming: Real-time content updates

Technical Notes

Database Schema:

  • Uses ai_provider column for provider storage
  • ai_provider column has constraint limitations requiring application-level mapping
  • Knowledge files and statement pools infrastructure is in place

AI Provider Support:

  • Cloudflare Workers AI: Default provider with multiple models (Llama 3.1 8B, Llama 3.2 3B, etc.)
  • Other Providers: OpenAI, Claude, Google, and local providers supported
  • Model Selection: Automatic model selection based on use case and provider

Development Roadmap

Short Term (v1.2.8):

  • Implement CoSTAR prompt engineering framework
  • Add advanced admin configuration UI
  • Enhance Cloudflare AI model selection and optimization

Medium Term (v1.3.0):

  • Full group chat functionality with NPCs
  • Statement generation system
  • Real-time activity tracking

Long Term (v1.4.0):

  • Multi-platform bot integration
  • Advanced analytics and insights
  • Knowledge base streaming and real-time updates

This section reflects the current implementation status as of v1.2.7 with ongoing development.

← Monitoring & Observability System Permissions & Role-Based Access Control →
PadawanForge v1.4.1