Creating Auto DM (Anansi)

I began creating Auto DM(Anansi) 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: /projects/auto-dm/
   • 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: /projects/auto-dm/
   • 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: /projects/auto-dm/
   • 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: /projects/auto-dm/
   • 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.