Project Infinity

A text-based RPG where an AI acts as your Dungeon Master — with real dice rolls, real character tracking, and real D&D 5e rules (based on the SRD 5.1). No hallucinated stats. No forgotten inventory. The AI rolls fairly, tracks your HP, and levels you up automatically.

Running on deepseek-v4-pro:cloud:

What Makes This Different?

Most AI RPGs let the language model make up numbers. Project Infinity doesn't. Every dice roll, every stat change, every level-up goes through an external game engine that the AI can read but not fake. The result is a Dungeon Master that actually plays by the rules.

• Fair Dice — All rolls are performed by a dedicated server and verified. The AI sees the results, it doesn't generate them.
• Persistent Character — Your stats, inventory, gold, and spell slots live in a real database that updates in real time. No "forgetting" that you used your last potion.
• SRD 5.1 Rules — Leveling up, spell slot recovery, proficiency bonuses — all handled automatically by the engine.
• Combat Resolution — Weapon attacks, spell attacks, saving throws, cantrip scaling, upcasting, spell slot consumption, crits, kill detection, and XP awards are all resolved mechanically in a single tool call. The AI cannot fudge damage or forget to deduct a slot.
• In-Game Commands — Check your stats, save your character sheet, force a database sync, or get help without leaving the game.

---

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, and spell slots
/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

---

How It Works

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

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).
• Healing & HP Pools — Healing spells restore HP. HP pool spells (e.g. Sleep, Color Spray) roll a total HP pool against the target's HP.
• 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.

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, 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