Skip to content

Developer Wiki

Jump to bottom
Dustin Spencer edited this page Oct 9, 2024 · 2 revisions

Welcome to the UnscriptedAdventures development wiki! This page will guide developers through the project’s structure, core components, and architecture, helping you understand how the system works and how to contribute effectively.

Table of Contents

  1. Overview
  2. System Architecture
  3. Core Components
    • Character Creation System
    • Campaign Creation System
    • Gameplay System
    • Sourcebook Integration
  4. Memory and Knowledge Management
  5. Development Guidelines
    • Setting up the Environment
    • Working with LLM Agents
    • Sourcebook Integration
  6. Best Practices
  7. Contributing

Overview

UnscriptedAdventures is a text-based RPG game powered by Large Language Model (LLM) agents that serve as the Game Master (GM), NPCs, and world controllers. The system dynamically adapts to player input, offering immersive storytelling that is personalized based on real-time decisions.

This wiki covers the project's structure and details how each component interacts to deliver a seamless RPG experience. Developers will learn about the character creation process, how campaigns are built and managed, and how gameplay is conducted using LLM agents.

System Architecture

The system is divided into three primary systems:

  1. Character Creation System: Handles all aspects of character creation, allowing players to customize their characters.
  2. Campaign Creation System: Allows the DM or system to create rich worlds and storylines before the game starts.
  3. Gameplay System: Runs the active game, managing interactions between the player, NPCs, and the world.

Each system interacts with a shared Knowledge and Memory Management System, which ensures that information is persistent and accessible across sessions. This structure also includes integration with D&D sourcebooks for referencing rules, mechanics, and prebuilt stories.

Core Components

1. Character Creation System

  • Purpose: To allow players to create characters with custom traits, abilities, and backgrounds.
  • Key Components:
    • Character Creation Proxy Agent: Manages player interactions during character creation.
    • Character Creation Agent: Guides the player through the process, including race, class, and ability selection.
    • Mechanics Agent: Enforces game rules (e.g., ability score limits, class restrictions) during character creation.
    • PDF Parsing Layer: Accesses the D&D Player’s Handbook to reference official rules and mechanics.

Once a character is finalized, it is saved to the Character Knowledge Store (CKS) and is available for loading into the campaign.

2. Campaign Creation System

  • Purpose: To allow the creation of campaigns, including story arcs, settings, and NPCs.
  • Key Components:
    • Campaign Creation Proxy Agent: Manages the interaction for building a campaign.
    • Narrative Agent (DM): Creates plotlines, events, and NPC interactions.
    • Environment Agent: Builds the game world and dynamically generates locations.

The campaign data is stored in the Campaign Knowledge Store (CKS) and can be loaded during gameplay.

3. Gameplay System

  • Purpose: To run the actual game session, managing player actions and story progression.
  • Key Components:
    • Gameplay Proxy Agent: Handles real-time interaction between the player and system.
    • Narrative Agent (DM): Progresses the story, interprets player decisions, and manages NPC behavior.
    • Character Agent: Loads and controls the player’s character during the game.
    • Mechanics Agent: Enforces game mechanics like combat, skill checks, and spell casting.
    • Environment Agent: Generates and updates the environment dynamically.

This system ensures continuity across sessions using the Gameplay Knowledge Store (GKS) and Memory Management.

Memory and Knowledge Management

The memory system is critical to preserving the player’s progress across character creation, campaign creation, and gameplay. It is broken down into:

  • Short-Term Memory (STM): Stores temporary, session-specific data such as actions or events.
  • Long-Term Memory (LTM): Persists important information (e.g., character stats, quest progress) for continuity across multiple sessions.

Each of the three systems—Character Creation, Campaign Creation, and Gameplay—accesses these memory stores as follows:

  • Character Knowledge Store (CKS): Stores character profiles and attributes.
  • Campaign Knowledge Store (CKS): Stores campaign settings, NPCs, and plots.
  • Gameplay Knowledge Store (GKS): Stores active game states and story progression.

Agents query these stores in real-time to ensure consistency in the player’s experience.

Development Guidelines

Setting up the Environment

  1. Install Prerequisites:

    • Python 3.7+ is required.
    • Flask is used as the web framework for the game’s interface.

  2. Cloning the Repository:

    git clone https://github.com/dspencej/UnscriptedAdventures.git
cd UnscriptedAdventures

  3. Set up a Virtual Environment:

    python -m venv .venv
source .venv/bin/activate

  4. Install Dependencies:

    pip install -r requirements.txt

Working with LLM Agents

  • LLM Agents drive the story and gameplay. Developers should ensure that the Narrative Agent is aligned with the core game loop, interpreting player input and outputting consistent narrative actions.
  • Mechanics Agent integrates the game mechanics with Python functions (like dice rolls, stat checks, etc.). It references core rulebooks to enforce accurate mechanics.

Sourcebook Integration

  • PDF Parsing Layer: This layer extracts relevant rules, spells, and mechanics from the core D&D PDFs.
  • Example:
    • If a player casts a spell, the Mechanics Agent can query the Player's Handbook to retrieve the spell's effects.

Best Practices

  1. Modularity: Keep components decoupled. Character creation, campaign creation, and gameplay should remain separate systems to maintain flexibility.
  2. Memory Consistency: Always ensure that STM and LTM updates are correctly synchronized to prevent loss of data between sessions.
  3. Error Handling: Implement robust error handling in agents, especially in the Mechanics Agent, as it enforces game-critical rules.
  4. Sourcebook References: Use the PDF Parsing Layer for accurate referencing. Avoid hardcoding rules to keep the system flexible as new sourcebooks are introduced.

Contributing

We welcome contributions from the community! Follow these steps to contribute:

  1. Fork the repository and clone it locally.
  2. Create a new branch for your feature or bug fix.
  3. Make your changes, ensuring to adhere to coding standards and practices.
  4. Submit a Pull Request with a clear explanation of your changes.

Feel free to join the discussion on new features or issues via the Discussion Board or open a new issue on GitHub.

Thank you for contributing to UnscriptedAdventures! Let’s continue creating immersive, unscripted adventures together!

Clone this wiki locally