Project Infinity

A text-based RPG where an AI Dungeon Master runs real D&D 5e — with mechanical rolls, persistent state, and SRD 5.1 rules enforced by a dedicated game engine.

Running on deepseek-v4-pro:cloud

---

What Makes This Different

Most AI RPGs let the language model make up numbers. Project Infinity runs every dice roll, every stat change, and every combat action through an external game engine the AI can read but not invent. The result is a Dungeon Master that actually plays by the rules.

• Fair Dice — All rolls performed by a dedicated server. The AI sees results, it doesn't generate them.
• Persistent Character — Stats, inventory, gold, spell slots, and reputation live in a real database. No forgetting.
• Full Combat Resolution — Weapon attacks, spell attacks, saving throws, cantrip scaling, upcasting, spell slot consumption, crits, kill detection, and XP awards in a single tool call.
• Multi-Target AoE — Fireball, Sleep, and all area spells resolve every target in one call. Per-target saves, HP pool exhaustion, one slot consumed.
• Temporary Hit Points — False Life, Armor of Agathys, and Heroism auto-apply and auto-expire. NPC attacks drain THP before real HP.
• Reputation System — Faction standing persists between sessions. Heroic deeds and crimes tracked, visible via /stats.
• Saving Throw Spells — Hold Person, Charm, Banishment, and 50+ others roll saves with full dice disclosure.
• Active Buffs — Shield, Mage Armor, Longstrider auto-modify stats and auto-revert on removal.
• Scroll Casting — Cast from scrolls without slots. Ability checks for scrolls above your level.
• Rest & Recovery — Short and long rests auto-apply hit dice, slot recovery, Arcane Recovery, and effect clearing per SRD 5.1.
• Leveling Up — XP thresholds auto-trigger HP, proficiency, hit dice, and spell slot progression.
• Combat Registry — GM registers all combatants once per battle. Initiative auto-rolled for everyone. The engine tracks every combatant's HP across attacks.
• In-Game Commands — /stats, /save, /sync, /quit from within the game.

Read on for quick start, gameplay hints, and the full engine overview under How It Works.

---

Quick Start

1. Prerequisites

• Python 3.11 or newer
• One AI backend (pick one):
  • Ollama — cloud-based, free and paid
  • OpenAI — cloud-based, requires a paid API key
  • Gemini — cloud-based, requires a paid API key
  • Claude — cloud-based, requires a paid API key

2. Install

git clone <repo-url>
cd Project_Infinity
python3 -m venv venv
source venv/bin/activate      # Linux/macOS
# venv\Scripts\activate       # Windows
pip install -r requirements.txt

3. Choose Your AI Backend

Backend	Requirements	Supported Models	Play Command
Ollama	Install Ollama, pull your model	kimi-k2.6:cloud, deepseek-v4-flash:cloud, deepseek-v4-pro:cloud	python3 play.py
OpenAI	export OPENAI_API_KEY=your-api-key	gpt-5.5-pro, gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.4-nano	python3 play_with_gpt.py
Gemini	export GEMINI_API_KEY=your-api-key	gemini-3.1-pro-preview, gemini-3-flash-preview, gemini-2.5-pro	python3 play_with_gemini.py
Claude	export ANTHROPIC_API_KEY=your-api-key	claude-opus-4-7, claude-opus-4-6	python3 play_with_claude.py

Note: The Gemini preview models have known issues. See Known Issues for details.

4. Create Your World

Before you can play, you need to create a character and generate a world. The World Forge walks you through picking a race, class, background, distributing stats, choosing equipment, and more — all following SRD 5.1 rules.

python3 main.py

This generates two files in the output/ directory:

• yourcharacter_weave.wwf — the world data (kingdoms, NPCs, guilds, history)
• yourcharacter_weave.player — your character's stats and inventory

5. Play!

Launch the game with the script that matches your backend:

Backend	Command
Ollama	python3 play.py
OpenAI	python3 play_with_gpt.py
Gemini	python3 play_with_gemini.py
Claude	python3 play_with_claude.py

You'll be prompted to:

1. Select a model — pick from the list of supported models
2. Select a world file — pick the .wwf file you generated in Step 4

Then the Game Master awakens and your adventure begins. Type actions in plain English. The GM handles the rest.

---

In-Game Commands

Command	Description
/help	Show available commands
/stats	Display your current character stats, inventory, spell slots, active effects, temporary HP, and reputation
/save	Overwrite your .player file with your current character sheet (active effects are cleared/reverted)
/sync	Force a database sync to make sure the GM's memory matches your actual state
/quit	Exit the game

---

Gameplay Hints

Play in Verbose Mode

Run the game with --verbose (or -v) to see every tool call and its result behind the scenes:

python3 play.py --verbose

This lets you watch the GM roll dice, consume spell slots, track HP, and update your inventory in real time. It is the best way to catch missed mechanical updates before they go unnoticed.

When the GM Forgets Something

The GM is an AI — it can forget to award quest XP, apply gold payments, or remove an item from your inventory. If you notice a missing update:

1. Try /sync first — This forces a full database refresh. The GM reviews your current state and may self-correct.

2. If that doesn't work, address the GM directly — Speak to the GameMaster in plain language, exactly as you would to a human DM. Be specific about what was missed.

Example from a real session:

The player completed a quest and received 50 gold, but no XP was awarded.

Player: GameMaster I finished a quest and you didn't award me XP.

GM: "Fair call. The vault infiltration and log delivery to Pippa was a completed contract — that's worth experience, not just coin." — and awarded +50 XP.

The GM will review the conversation, verify the omission, and apply the correction via a tool call. This works for any forgotten mechanic: gold, inventory changes, spell slot recovery, hit dice, conditions, or items.

Between Sessions

/save writes your character sheet — stats, gold, inventory, spell slots — to the .player file so you can pick up where you left off. The story itself is not saved; each session is a fresh narrative with the same character.

The reputation system offers a bridge between sessions. Your standing with every guild in every kingdom is stored in the reputation dictionary inside the .player file. The GM records your deeds as title: description entries.

When you start a new session, these reputation entries persist — the GM sees them during the database dump and can reference them in the opening scene and throughout play. Use /stats at any time to review your current standing.

Save after a long rest — that way your .player file reflects full HP and recovered spell slots, giving you the best starting point for your next session.

---

How It Works

If you're curious about what's happening under the hood, here's a high-level overview.

Session Startup

When you launch the game, a four-step bootstrap brings the world to life:

1. System Prompt — GameMaster_MCP.md is loaded as the system prompt. It defines the GM's entire personality, the phased resolution protocol, combat rules, and all mechanical constraints.

2. World Injection — Your selected .wwf file is sent to the GM. This contains all kingdoms, rulers, guilds, NPCs, and world history generated by the World Forge.

3. Database Dump — The GM calls dump_player_db to read your character from the in-memory SQLite database — your stats, inventory, gold, spell slots, hit points.

4. Opening Scene — Only after all world data and character state are loaded does the GM produce the opening scene narrative. Your adventure begins.

MCP Tool Server

The game engine runs as a local MCP (Model Context Protocol) server with an in-memory SQLite database initialized from your .player file at startup. The AI cannot invent rolls, stats, or outcomes — every mechanical action is a verified tool call that returns a narrative_format string the GM must include verbatim.

Checks & Generic Rolls

• Skill Checks & Saves — perform_check rolls d20 + modifier vs DC with native Critical Success/Failure on natural 20/1. Every result is formatted for direct inclusion in the narrative.
• Damage, Healing & Quantity — roll_dice supports any standard notation (e.g. 3d6+2). The AI must use this for all random magnitudes; it cannot make up damage numbers.

Weapon & Unarmed Combat

resolve_attack handles the full attack sequence in a single call:

• Attack roll vs AC. Supports Advantage (roll twice, take higher) and forced crits (unconscious targets within 5 feet).
• Critical hits double primary damage dice but not extra damage dice (e.g. elemental riders).
• Automatic HP application, kill detection, and XP award using the 5e CR/XP table.
• Works for player-vs-NPC, NPC-vs-player, and NPC-vs-NPC.

Spell Combat

resolve_magic resolves all spell resolution in one call:

• Spell Database — Properties are looked up from config/spells.yml. Custom spells can be cast with override parameters.
• Automatic Spell Slot Management — Validates slot availability before rolling; consumes the slot automatically. Rejects under-level slots or empty slots with a clear error.
• Cantrip Scaling — Automatically scales base dice at levels 5, 11, and 17.
• Upcasting — Damage and healing scale automatically when a spell is cast in a higher-level slot (per the spell's higher_levels field).
• Attack Types — Supports attack_roll (vs AC), saving_throw (half damage on save if save_half), and automatic (always hits).
• Multi-Target AoE — For spells that affect an area (Fireball, Sleep, Lightning Bolt, Cone of Cold), pass a targets list. Damage is rolled once per spell, individual saves rolled per target with per-target modifiers, XP auto-awarded per kill — all in a single call consuming one slot.
• HP Pool Spells — Sleep and Color Spray accept a targets list, sort creatures by HP per D&D 5e RAW, and drain the pool until it's exhausted. The response identifies which targets are affected and which are not.
• Healing & Temporary Hit Points — Healing spells restore HP. False Life and Armor of Agathys auto-roll and apply temporary HP to the database. NPC attacks drain THP before real HP in all combat paths. When THP reaches zero, the source spell is auto-removed from active effects and the GM is notified.
• Conditions & Concentration — Applies conditions with duration and concentration flags. Supports instant-kill spells (Power Word-style HP threshold checks).
• Active Buff Tracking — Spells that modify stats (AC, speed, etc.) are tracked via active_effects and _active_buff_data. Recasting a duplicate is rejected before the slot is consumed. Removing an effect via update_player_list automatically reverts the stat changes. All active effects are visible in the /stats command display.
• Kill Detection & XP — Identical to weapon attacks: NPC deaths award XP automatically.
• Scroll Casting — Cast from scrolls without consuming a slot. Scrolls above the character's level trigger an ability check per D&D 5e (DMG p.200).

Combat Registry

When combat begins, the GM calls register_combatants once with all NPC participants:

• The player is auto-registered from the database — name, HP, AC, and DEX modifier are read automatically.
• Initiative is rolled for everyone (d20 + initiative_modifier) and returned in sorted turn order.
• Each combatant's HP, AC, save modifier, and challenge rating are stored in an in-memory registry.

Once the registry is active, resolve_attack and resolve_magic auto-lookup target HP by name — no need to pass target_current_hp on every call. When multiple combatants attack the same target in the same round, the engine automatically carries forward the reduced HP from each hit. Kill detection uses the correct remaining HP, not the original value.

Calling register_combatants again overwrites the registry — no separate clear step needed. When the player launches a surprise attack (Magic Missile at a guard, crossbow from hiding), the protocol requires register_combatants to be called first, so the registry is active before the attack resolves. For mid-combat reinforcements or forgotten combatants, call register_combatants(combatants=[...], add_to_existing=True). This adds NPCs to the existing registry without wiping it — existing HP states are preserved, and no initiative rolls are made for the new arrivals.

Rest & Recovery

The rest tool auto-applies all rest mechanics per SRD 5.1 — the GM doesn't need to track dice math manually.

• Short Rest (1 hour): Automatically spends hit dice one-by-one until HP is full or no dice remain, rolling 1d<hit_dice_size> + CON mod per die (minimum 0). Warlocks regain all Pact Magic slots. Wizards get Arcane Recovery auto-applied (recovers up to ceil(level/2) combined slot levels, greedily from lowest expended slots).
• Long Rest (8 hours): Full HP restore. Regain max(level//2, 1) spent hit dice (capped at level). All spell slots fully restored from class slot tables. All active effects cleared with stat deltas auto-reverted. Prepared casters can optionally provide a full replacement list of prepared spells, validated against max capacity and (for Wizards) spellbook content.
• Rejects long rest if the character is at 0 HP (must be stabilized first).
• Returns class-specific hints for manual feature recharges (Second Wind, Channel Divinity, Bardic Inspiration, etc.).

State Authority

Your character lives in an in-memory SQLite database that the AI updates through tool calls. Your HP, gold, inventory, spell slots — all of it is tracked precisely.

• Numeric State — modify_player_numeric handles everything from gold to XP. Crossing a level threshold triggers automatic level-up (HP, proficiency bonus, hit dice, spell slots, DC, attack modifier). The AI must manually apply class features, new spells, ASIs, and subclass features.
• List State — update_player_list manages inventory, reputation, known/prepared spells (capacity enforced for prepared casters), features, skills, proficiencies, and languages.
• HP Clamping — HP is bounded to [0, max_HP]. Hitting 0 returns an "Unconscious" status tag, triggers death saves, and clamps all damage to 0.
• HP Status Tags — Every HP change returns a structured status: Healthy, Wounded, Bloodied, Critical, or Unconscious.
• The AI is required to update state immediately when changes happen.
• You can force a full database sync at any time with /sync.

Phased Resolution

To prevent the AI from "collapsing" on complex turns (trying to narrate and calculate at the same time), the engine uses a two-phase protocol:

1. Mechanical Phase — The AI resolves all dice rolls and state updates first, pausing with a sync token.
2. Narrative Phase — Only after all mechanics are verified does the AI produce its story output.

This means you always get mechanically accurate results before the narrative.

Transparency

Every roll is shown in a standard format:

Guard Attack: 17 vs AC 15 (Success) (15 + 2)
TestHero Fireball: 28 vs DEX Save DC 15 (Failure) (3 + 2 + 6 + 5 + 5 + 7)

---

Advanced Options

All play scripts accept the following flags:

Flag	Description
--verbose, -v	Show all tool calls and their results behind the scenes
--debug, -d	Show raw AI responses including internal reasoning (also enables --verbose)
--temperature, -t	Set sampling temperature (Ollama/OpenAI/Claude default: 0.0, Gemini default: 1.0). Ignored for GPT-5.5 and Claude Opus 4.7 models (temperature is deprecated).
--think	Enable thinking/reasoning for the model as a boolean toggle (Ollama only)
--thinking-level	Enable structured AI reasoning with effort level: LOW, MEDIUM, HIGH, XHIGH. XHIGH is exclusive to Pro/Enterprise-tier models. See Known Issues.
--verbosity	Control output verbosity for GPT-5.5 models: low, medium, high (default: medium). Ignored by other backends.
--max-output-tokens	Maximum output tokens for GPT-5.5 and Claude models (default: 16384). Includes thinking tokens. Ignored by other backends.

Examples:

python3 play.py --temperature 0.6 --think
python3 play_with_gemini.py --temperature 0.7
python3 play_with_gpt.py --debug
python3 play_with_claude.py --thinking-level MEDIUM
python3 play_with_gpt.py --thinking-level HIGH --verbosity low
python3 play_with_gpt.py --thinking-level XHIGH --max-output-tokens 32000
python3 play.py --thinking-level MEDIUM --verbose
python3 play_with_gemini.py --thinking-level MEDIUM --verbose

Debug Mode

When the game is running with --debug, the engine logs:

• Every tool call and response (same as --verbose)
• Raw JSON responses from the AI model
• AI thinking/reasoning panels (when available)
• Automatic retry messages for empty or malformed responses

---

Known Issues

GPT-5.5 Models (Responses API)

GPT-5.5 models consume "thinking tokens" from the total --max-output-tokens budget. If this is set too low, the model may run out of space before finishing its reasoning, leading to truncated responses. Increase --max-output-tokens if you see incomplete output.

Temperature is deprecated for GPT-5.5 models (internally locked to 1.0). Use --thinking-level and --verbosity to control behavior instead.

GPT-5.4 Models (Legacy)

GPT-5.4 models sometimes return completely empty responses (no text, no tool calls). The engine automatically detects this and re-sends your last action as a new message, up to 3 times. If retries are exhausted, the empty response is shown as-is.

Gemini Preview Models

gemini-3.1-pro-preview and gemini-3-flash-preview have bugs with function calling:

• Malformed tool calls — These models intermittently send broken function calls. The engine retries with corrective messages to guide the model back on track.
• Thinking leakage (3.1-pro only) — The model may output its internal reasoning as visible text in the game narrative. There is currently no workaround.
• Thinking-only responses — When --thinking-level is enabled, the model may think without producing any output. The engine auto-injects "Continue" to prompt a response.

The default temperature for Gemini is set to 1.0 (instead of the usual 0.0) because this significantly reduces malformed call rates. You can override this with --temperature.

---

Technology Stack

Component	Technology
Language	Python 3.11+
Game Engine	MCP (Model Context Protocol) server + SQLite
Terminal UI	Rich + prompt_toolkit
Data Validation	Pydantic
Config	YAML
AI Backends	Ollama, OpenAI, Google Gemini, Anthropic Claude

---

Licensing & Legal

This project has a dual-license structure to comply with copyright law and Wizards of the Coast's intellectual property rights.

Source Code — MIT License

All original source code in this project (the game engine, TUI, MCP server, dice server, world forge, and all .py source files) is licensed under the MIT License. See LICENSE for the full terms.

D&D 5e Rules Content — CC-BY-4.0 (via SRD 5.1)

All embedded D&D 5e rules data — including spell descriptions, class features, racial traits, background features, weapon statistics, and game mechanics found in config/ files — is derived from the System Reference Document 5.1 (SRD 5.1), published by Wizards of the Coast LLC under the Creative Commons Attribution 4.0 International License (CC-BY-4.0).

This content is NOT covered by the MIT license. It is used under a separate open license that permits public use with proper attribution. See SRD_LICENSE.txt for the full attribution text and additional details.

Required SRD Attribution

"This work includes material taken from the System Reference Document 5.1 ("SRD 5.1") by Wizards of the Coast LLC, available at https://dnd.wizards.com/resources/systems-reference-document. The SRD 5.1 is licensed under the Creative Commons Attribution 4.0 International License available at https://creativecommons.org/licenses/by/4.0/legalcode."

What Is NOT Included

To maintain legal compliance, this project has been audited to exclude all non-SRD content from its distributed files. Specifically:

• Product Identity (Beholders, Mind Flayers, Displacer Beasts, Carrion Crawlers, Githyanki, Githzerai, Kuo-Toa, Slaadi, etc.)
• Named Characters (Strahd, Bigby, Mordenkainen, Tasha, Drizzt, etc.)
• Non-SRD Spells (Booming Blade, Green-Flame Blade, Absorb Elements, Toll the Dead, Chaos Bolt, etc.)
• Non-SRD Races/Subraces (Drow, Stout Halfling, etc.)
• Non-SRD Classes (Artificer)
• Proprietary Setting Lore (Forgotten Realms geography, unique deities, faction names)

AI-Generated Content at Runtime

The AI Game Master operates on general-purpose models that may have been trained on the broader D&D corpus. Despite prompt-level restrictions instructing the GM to adhere strictly to SRD content, the project cannot guarantee that AI-generated narrative will never reference non-SRD material at runtime. This is a known limitation of AI-powered applications and is explicitly disclosed.

Not Affiliated with Wizards of the Coast

This project is not affiliated with, endorsed by, sponsored by, or connected to Wizards of the Coast LLC in any way. Dungeons & Dragons and D&D are trademarks of Wizards of the Coast LLC in the USA and other countries.

---

License

• Original source code: MIT License
• D&D 5e rules data (config files): Creative Commons Attribution 4.0 International, via the D&D SRD 5.1