Creating Auto DM (Anansi)

Written By Jerry Gaines

I began creating it Auto DM when my normal D&D group had trouble meeting up. I came up with the idea since we didn’t want to continue our main campaign if everyone could not show up. I envisioned a tool that could first help dungeon masters spin up a scenario and create small campaigns. Then I realized why stop there? Being a DM is fun but NO ONE wants to be a forever DM. Why not make it so it offloads this responsibility to AI who can then be the narrator!
I started to imagine groups of players coming together jumping in and out of unique worlds. A design that allows for busy everyday people who would not be able to carve out hours to play to now be able to play at their own pace. A tool that can allow for flexibility to all types of players, min-maxers who would like to decimate, people looking for a journey of a century, those who want to make a name for themselves, and those who just want to goof around.
I fired up a chat window and began “Vibe coding” the prototype of the project only took me 2 days to complete I learned all the technologies what their purpose is and how to configure each application. I have been slowly refining it and believe it will soon be a marketable product.

Tech stack MUMBO JUMBO:


Below is a comprehensive technical document detailing Auto Dungeon Master (DM) web application project, covering the gameplay experience, underlying mechanics, system architecture, technology stack, deployment considerations, and potential future enhancements.

D&D DM Web Application Technical Documentation

1. Project Overview

This project is an interactive Dungeons & Dragons DM web application that leverages AI-driven dynamic narrative responses. Players set up a custom adventure scenario, create characters (with a separation between their login username and their in-game character name), and interact with the DM through chat. The DM, generates immersive story updates in real time that follow a style reminiscent of popular DMs, Persistent data is stored in AWS S3.

2. Gameplay and Mechanics

2.1. User Flow & Game Play

  1. Login Screen:

    • URL: https://www.shaboobala.com/login

    • Inputs: Username and world code.

    • Logic:

      • The system verifies whether the world (scenario) exists.

      • If the world is new, the user is directed to the Scenario Setup page.

      • If the world exists, the system checks for the existence of the character corresponding to the logged‑in username.

      • Depending on the result, the user is redirected either to character creation or to the Chat screen.

  2. Scenario Setup:

    • URL: https://www.shaboobala.com/scenario

    • Purpose: For a new world, the user defines the adventure scenario.

    • Inputs:

      • Setting (e.g., "Ancient Ruins in a Forgotten Jungle")

      • Theme (e.g., "Mystery and Exploration with hints of dark magic")

      • Challenge level (e.g., "Moderate", "High")

    • Outcome:

      • The scenario is stored persistently (in S3) and an initial story file is created.

      • Once saved, the user is then redirected to the Character Creation screen.

  3. Character Creation:

    • URL: https://www.shaboobala.com/character

    • Purpose: To create a new character for an existing world.

    • Inputs:

      • Character Name (in-game name; separate from the login username)

      • Race

      • Class

      • Level

      • Additional details (stats, abilities, background)

    • Ability Scores:

      • The form provides a section for the six abilities (STR, DEX, CON, INT, WIS, CHA) arranged in two rows of three small, read-only input fields.

      • Two dice-rolling mechanisms are available:

        • Roll Stats: Rolls 4d6 dropping the lowest for all abilities at once.

        • Roll for a Single Ability: Lets the user choose one ability and roll 4d6, displaying the individual dice results and the dropped die for transparency.

    • Persistence:

      • Character data is stored in a JSON file on S3

    • DM Greeting:

      • If the world already exists, a DM greeting message is automatically appended to the story log, welcoming the new character and providing narrative context.

  4. Chat Room:

    • URL: https://www.shaboobala.com/chat

    • Purpose: The interactive chat interface where players and the DM interact.

    • Features:

      • Chat History:

        • Loads previously saved messages (player messages, DM responses, dice rolls) in chronological order.

        • Each message contains a timestamp.

        • Users can scroll through the conversation without auto-scrolling if they are viewing older messages.

      • Message Submission:

        • Players type messages which are persisted to S3 via the backend.

        • A toggle option allows players to direct messages to the DM (indicated by an asterisk next to their name) which then trigger a AI-generated narrative from the DM.

      • Dice Roller:

        • A built-in dice roller allows users to roll dice for game actions (e.g., d4, d8, d10, d12, d20, d100).

        • The results of the dice roll (including individual dice values, the total, etc.) are appended as chat messages and persisted.

3. System Architecture

3.1. Components

  • Frontend (Squarespace Hosted):
    Custom pages are embedded in Squarespace using HTML, CSS, and JavaScript. The front-end code:

    • Displays the login form, scenario setup form, character creation form, and chat interface.

    • Makes API calls (via fetch) to the backend endpoints.

    • Uses localStorage to store temporary session data (username, world code).

  • Backend (AWS Lambda via Flask):
    The Flask application provides RESTful endpoints for:

    • Checking if a scenario or character exists.

    • Creating or updating scenarios, characters, chat messages, and generating DM responses.

    • The code is deployed using Zappa as a serverless application on AWS Lambda.

    • The backend accesses persistent data via Amazon S3.

  • Persistent Storage (Amazon S3):
    Two S3 buckets are in use:

    • One for deployment.

    • A dedicated persistence bucket for storing all game data.

3.2. Data Flow Overview

  1. User Interaction:

    • Users interact with the front end hosted on Squarespace.

    • The application uses localStorage to retain session context.

  2. API Communication:

    • The frontend communicates with API endpoints deployed on AWS Lambda (public API Gateway URL).

    • These endpoints handle creation, updating, and retrieval of game data.

  3. S3 for Data Persistence:

    • All game-related data is stored as text or JSON files in S3.

    • Periodic polling on the front end reads the chat file from S3 and updates the chat area.

  4. DM Integration via LLM API:

    • When messages are directed to DM (via the DM toggle), the backend calls API.

    • The DM endpoint uses the API prompt with the current story context and character data.

    • The generated narrative is then appended to logs in S3.

4. Technology Stack

  • Frontend:

    • HTML/CSS/JavaScript: Custom code blocks embedded within Squarespace pages.

    • LocalStorage: To store temporary session data (username, world code).

  • Backend:

    • Python (Flask): RESTful API development.

    • Flask-CORS: For handling cross-origin requests.

    • AI API: For generating DM narrative responses.

    • Boto3: For interacting with AWS S3.

  • Deployment/Serverless:

    • AWS Lambda: For running the Flask app serverlessly.

    • API Gateway: To expose Lambda functions as HTTP endpoints.

    • Zappa: To package and deploy the Flask app to AWS Lambda.

    • AWS S3: For persistent storage of game files.

    • AWS Certificate Manager (ACM): For HTTPS support on a custom domain.

5. API Endpoints

5.1. Scenario and World Management

  • GET /check_scenario
    Checks if a scenario exists for the given world code.

  • POST /set_scenario
    Creates a new scenario and initial story log for a world.

5.2. Character Management

  • GET /check_character
    Checks if a character file exists for a given world and username.

  • POST /create_character
    Creates a new character file in JSON format using the logged‑in username (for file naming) and a separate character name (for in-game display). Also appends a DM greeting if the world already exists.

  • POST /update_character
    Allows for updating character details (equipment, money, etc.).

5.3. Chat and DM Interaction

  • POST /submit_message
    Persists a chat message with a timestamp.

  • GET /get_chat
    Retrieves the persistent chat history.

  • POST /dm_response
    Generates a DM narrative response via the OpenAI API, appends it (with a timestamp) to both the story and chat logs, and returns the narrative.

6. Frontend Pages

6.1. Login (login.html)

  • Users enter a username and world code.

  • The page checks via API calls if the world and character exist and routes the user to:

    • Scenario Setup if the world is new.

    • Character Creation if the character for the logged‑in username is missing.

    • Chat if both exist.

6.2. Scenario Setup (scenario.html)

  • Users input details about the new world (setting, theme, challenge).

  • The data is sent to the backend to create a scenario file and initial story log on S3.

  • Upon success, the user is redirected to character creation.

6.3. Character Creation (character.html)

  • Users provide in-game character name, race, class, level, and additional details.

  • Includes a full ability score section with:

    • A “Roll Stats” button to roll for all abilities.

    • A single ability roller for rolling for one specific ability.

  • Rolls use the 4d6 dropping the lowest mechanic.

  • The form submits data so that the character file is saved as <worldCode>_<username>.json in S3, even though the character name is separate.

  • After submission, the user is redirected to the Chat page.

6.4. Chat (chat.html)

  • Displays chat history by polling the /get_chat endpoint every 5 seconds.

  • Messages include timestamps and are stored in chronological order.

  • Provides message submission with a DM toggle:

    • When on, messages are sent to the DM endpoint for narrative responses.

  • Includes a dice roller that allows players to roll dice (d4, d8, d10, d12, d20, d100) with results saved to the chat.

  • Auto-scroll behavior has been disabled, so the user’s scroll position is preserved.

7. Deployment and Future Enhancements

7.1. Deployment

  • Local Development:
    Use a virtual environment with Python 3.10 (or 3.9/3.11) for local development.

  • Zappa & AWS Lambda:
    Package your Flask application with Zappa.
    Update your zappa_settings.json with the proper runtime (python3.10), region, S3 bucket for deployment, and environment variables.

  • Custom Domain & HTTPS (Optional):
    Optionally set up an SSL certificate with AWS Certificate Manager and configure API Gateway custom domain mapping for a branded URL (e.g., api.shaboobala.com).

7.2. Future Enhancements

  • Real-Time Updates:
    Implementing a WebSocket-based solution (via AWS API Gateway WebSocket support) for true real-time chat updates instead of polling.

  • Enhanced Data Persistence:
    Evaluate using a database (e.g., DynamoDB) for storing game data and chat history to enable more sophisticated querying and handling of large volumes of data.

  • Improved DM Prompts:
    Refine the DM narrative prompts by integrating more contextual data.

  • User Authentication & Session Management:
    integrate a user authentication system for a more secure login and session management across devices.

Conclusion

This document outlines the project’s functionality, architecture, and the technical choices made in building an auto DM web application for D&D. The application integrates a AI-driven DM with dynamic scenario creation, character creation (with dice-rolling mechanics), and a chat interface that uses AWS Lambda, API Gateway, and S3 for persistence. With planned future enhancements, this project can scale to provide a rich interactive D&D experience for players around the globe.

Jerry Gaines
Next

Getting it together: my first post