crabsmadethis/d2r-horadric-tools
Horadric Tools para Diablo II: Resurrected
Horadric Tools es un kit de herramientas de Python para la modificación offline de Diablo II: Resurrected y flujos de trabajo de archivos de guardado. Convierte YAML en personajes .d2s, compila mods de datos a partir de parches declarativos, inspecciona archivos de guardado antes de cargarlos y expone las mismas herramientas a través de un servidor MCP para Claude Code, Codex, Cursor y otros clientes de agentes.
El proyecto está diseñado principalmente para Linux / Steam Deck, con detección de rutas de Windows incluida pero no probada exhaustivamente. No incluye datos del juego de Blizzard, archivos de guardado privados ni automatización de Battle.net.
Qué hace
Compila personajes
.d2soffline a partir de YAML.Codifica equipo, palabras rúnicas, amuletos, estadísticas, habilidades, equipo de mercenarios, Golems de hierro y demonios vinculados derivados de plantillas experimentales.
Escanea archivos de guardado en busca de problemas estructurales antes de probarlos en el juego.
Extrae datos locales de D2R en tablas de búsqueda de Python generadas.
Compila y despliega mods de datos a partir de superposiciones YAML y parches de cadenas JSON.
Proporciona 23 herramientas MCP para búsqueda de datos del juego, inspección de guardados, creación de personajes y automatización de la canalización de mods.
Related MCP server: LoreKeeper MCP
Qué no es
No es una herramienta para jugar online.
No es un entrenador, bot, maphack o editor de memoria.
No es un paquete de datos extraídos de D2R.
No es una garantía de que cada guardado generado sea seguro de cargar sin escanear.
Para el trabajo con archivos de guardado, la regla principal es simple: compila o edita en el entorno de pruebas (staging), escanea el resultado y luego promuévelo solo si pasa la validación.
Inicio rápido
git clone https://github.com/crabsmadethis/d2r-horadric-tools.git
cd d2r-horadric-tools
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"Genera datos de búsqueda locales desde tu instalación de D2R:
d2r-mod extractSi la instalación no se detecta automáticamente:
d2r-mod extract --game-dir "/path/to/Diablo II Resurrected"Valida el personaje de ejemplo incluido:
d2r-chargen validate ExamplePaladinCompílalo solo cuando tu directorio de guardado esté configurado y estés listo para escribir el guardado generado:
d2r-chargen build ExamplePaladin --force
d2r-chargen scan ExamplePaladinYAML de personaje
Los personajes residen en chars/*.yaml. Una definición de personaje pequeña se ve así:
schema_version: 1
name: ExamplePaladin
class: paladin
level: 85
progression: hell_complete
stats:
strength: 156
dexterity: 125
vitality: 250
energy: 25
skills:
Blessed Hammer: 20
Concentration: 20
Vigor: 20
equipment:
- slot: helm
unique: Harlequin Crest
- slot: body
runeword: Enigma
base: utp
- slot: weapon
runeword: Heart of the Oak
base: fla
inventory:
charms:
- magic_grand_charm:
count: 8
properties:
skill_tab: [1, 15]
life: 40Consulta chars/ExamplePaladin.yaml para ver un ejemplo más completo.
Nombres de clase admitidos:
amazon, sorceress, necromancer, paladin, barbarian, druid, assassin, warlockRanuras de equipo comunes:
helm, body, weapon, shield, hands, belt, feet, neck, ring_right, ring_left,
weapon_switch, shield_switchReferencia de CLI
d2r-chargen
d2r-chargen list
d2r-chargen validate <name> [--yaml-only]
d2r-chargen build <name> [--phase N] [--force]
d2r-chargen scan <name>
d2r-chargen import <name> [--force]
d2r-chargen diff <file1> <file2>d2r-mod
d2r-mod extract [--game-dir PATH]
d2r-mod build [--no-regen]
d2r-mod deploy [--force] [--no-casc]
d2r-mod undeploy
d2r-mod diff [--summary]
d2r-mod inject [--from-dir PATH]
d2r-mod audit [--skills] [--items]
d2r-mod clean
d2r-mod updateSuperposiciones de mods de datos
Las superposiciones modifican las tablas de datos de D2R de forma declarativa. Coloca los archivos de superposición en overlays/ y ejecuta d2r-mod build.
target: data/global/excel/UniqueItems.txt
changes:
- row: {index: "The Gnasher"}
set:
prop4: "dmg%"
min4: "50"
max4: "50"
comment: "Buff The Gnasher with +50% Enhanced Damage"Si no existe un directorio overlays/, la compilación continúa solo con los datos originales (vanilla). Consulta examples/sample_overlay.yaml para ver un ejemplo completo.
Parches de cadenas JSON
D2R lee la mayoría de las cadenas de objetos, mercenarios e interfaz de usuario desde archivos JSON en data/local/lng/strings/. Coloca las especificaciones YAML en patches/json_strings/ para añadir o sobrescribir cadenas:
description: "Rename a few potions"
target: item-names.json
entries:
- key: "vps"
value: "Wild Rice Cake"
- key: "MyCustomItem"
value: "Heart of the Mountain"Después de d2r-mod build, los JSON parcheados se ubican en build/data/local/lng/strings/. D2R almacena las cadenas en caché al iniciarse, así que sal completamente y reinicia para ver los cambios.
Servidor MCP
Horadric Tools incluye un servidor MCP para clientes de agentes. Expone búsquedas de datos del juego, inspección de guardados, generación de personajes y comandos de canalización de mods como herramientas tipadas.
Instala el SDK de MCP antes de iniciar el servidor:
pip install mcpInícialo con:
python3 -m d2r_mcpClaude Code:
claude mcp add d2r-tools --transport stdio --scope user -- python3 -m d2r_mcpConfiguración genérica de MCP:
{
"mcpServers": {
"d2r-tools": {
"command": "python3",
"args": ["-m", "d2r_mcp"],
"env": {}
}
}
}Consulta d2r_mcp/README.md para ver el catálogo completo de herramientas.
Modelo de seguridad
El flujo de trabajo de archivos de guardado es intencionalmente conservador:
Comienza desde una plantilla
.d2sválida existente siempre que sea posible.Escribe los cambios en un archivo temporal o de pruebas (staging).
Recalcula el tamaño y la suma de comprobación (checksum).
Ejecuta
d2r-chargen scan <nombre>.Promueve solo los archivos limpios según el escáner.
Los errores graves del escáner se tratan como bloqueadores de despliegue a menos que haya evidencia a nivel de bit de que el escáner está equivocado. Las notas detalladas sobre el formato de guardado se encuentran en docs/d2s_format.md.
Mapa del repositorio
d2r_chargen/ YAML character builder, save writer, scanner, import/diff tools
d2r_mod/ Data extraction, overlays, CASC read/write, deploy pipeline
d2r_mcp/ MCP server and tool definitions
chars/ Example character YAML files
examples/ Overlay examples
docs/ Save-format notes and manual validation guidance
tools/ Standalone diagnostics and hygiene checks
plugin/ Optional Claude Code plugin commands and skillsCompatibilidad de plataforma
Plataforma | Estado |
Linux / Steam Deck (Proton) | Compatible, probado |
Windows | Detección de rutas incluida, necesita más pruebas |
macOS | No compatible para jugar D2R; útil solo para documentación y trabajo de código |
Requisitos
Python 3.11+
PyYAML
Diablo II: Resurrected para la extracción de datos
SDK de MCP para la integración de agentes (
pip install mcp)
Contribución
Comienza con CONTRIBUTING.md. Antes de abrir un PR, ejecuta:
python tools/public_hygiene_check.py
ruff check .
pytest tests/ -v --timeout=60 \
-m "not integration and not slow and not e2e and not smoke" \
--ignore=tests/fixtures/ \
--ignore=tests/test_chargen.py \
--ignore=tests/test_decoder.py \
--ignore=tests/test_fixtures.py \
--ignore=tests/test_importer.pyLicencia
MIT
Available Tools
23 toolsd2r_chargen_buildA
Build and deploy a character to the live saves directory.
Structurally enforces CLAUDE.md rules #3, #4, #10, #17: backs up the live save, builds to a temp file, runs the scanner on the temp, and only promotes the temp to the live save if the scanner passes. Live save is untouched on scanner failure.
Args: name: Character name (chars/.yaml must exist). phase: Deploy through phase (1-4). Default: full deploy (4). force: Skip the freshness gate (discards server progress). Avoid unless intentional.
Inputs: name (required), phase, force.
d2r_chargen_importA
Import a server-synced .d2s save into chars/.yaml.
Args: name: Character name (reads live save at /.d2s). force: Overwrite an existing chars/.yaml.
Inputs: name (required), force.
d2r_chargen_listA
List character names defined in chars/*.yaml.
Inputs: no named parameters.
d2r_chargen_validateB
Validate a character YAML and optionally run a dry-run binary build.
Args: name: Character name (resolves to chars/.yaml). yaml_only: Skip the dry-run binary build + scanner pass.
Inputs: name (required), yaml_only.
d2r_lookup_item_baseA
Look up a D2R base item by 3-char code or name.
Searches item_bases.py data. Returns dimensions, requirements, sockets. Supports substring matching on names.
Args: query: 3-character item code (e.g. "hax") or item name
Inputs: query (required). Returns: result
d2r_lookup_runewordA
Look up a D2R runeword by name or numeric ID.
Searches runewords.py data. Returns runes, valid bases, stats. Supports substring matching.
Args: query: Runeword name (or substring) or numeric runeword ID
Inputs: query (required). Returns: result
d2r_lookup_set_itemA
Look up a D2R set item by name or numeric ID.
Searches set_items.py data. Returns item info + set membership. Supports substring matching.
Args: query: Item name (or substring) or numeric set item ID
Inputs: query (required). Returns: result
d2r_lookup_skillA
Look up a D2R skill by name or numeric ID.
Searches skills.py data. Returns skill ID and class. Supports substring matching.
Args: query: Skill name (or substring) or numeric skill ID
Inputs: query (required). Returns: result
d2r_lookup_statA
Look up a D2R stat by ID, canonical name, or YAML alias.
Searches item_stat_cost.py data. Returns encoding info (save bits, save add, param bits, value shift) needed for binary stat encoding.
Args: query: Stat ID, canonical name (e.g. "fireresist"), or alias (e.g. "fcr")
Inputs: query (required). Returns: result
d2r_lookup_uniqueA
Look up a D2R unique item by name or numeric UID.
Searches unique_items.py data. Returns item info + stats. Supports substring matching (e.g. "harlequin" finds Harlequin Crest).
Args: query: Item name (or substring) or numeric UID
Inputs: query (required). Returns: result
d2r_mod_auditB
Audit vanilla skills and items; write markdown reports.
Args: skills: Run skills audit. items: Run items audit. audit_all: Run both audits (overrides skills/items). output_dir: Directory to write reports into. Default: docs/audit.
Inputs: skills, items, audit_all, output_dir.
d2r_mod_buildC
Build mod from vanilla + overlays + scripts into build/.
Inputs: warn_conflicts, no_regen, game_dir.
d2r_mod_cleanA
Wipe the local mod build artifacts to start from a clean slate.
Deletes the build/ directory and resets generated chargen data files. Does NOT touch the deployed D2R install; run d2r_mod_undeploy first if you also want to revert the running game.
Inputs: no named parameters.
d2r_mod_deployC
Build + deploy mod to the game mod folder (runs CASC injection by default).
Inputs: force, no_casc, no_build, warn_conflicts, +2 more.
d2r_mod_diffC
Compare vanilla/ vs build/ tables. Returns list of changed files.
Inputs: file, summary.
d2r_mod_extractC
Extract vanilla data from CASC archive into vanilla/.
Inputs: game_dir.
d2r_mod_undeployA
Revert the deployed D2R mod, restoring the vanilla game state.
Removes the mod directory from the D2R install (or keeps it on disk with keep_mod=True) and unregisters the launch options. Use this to roll back a deploy without rebuilding, or before switching to a different mod.
Args: keep_mod: If True, leave the built mod directory in place on disk. game_dir: Override the auto-detected D2R install path.
Inputs: keep_mod, game_dir.
d2r_mod_updateC
Full recovery pipeline: extract → build → deploy.
Inputs: warn_conflicts, no_regen, game_dir.
d2r_save_diffC
Compare two .d2s files and return structural differences.
Args: path_a: First save (treated as "before"). path_b: Second save (treated as "after").
Inputs: path_a (required), path_b (required).
d2r_save_inspectA
Summarize a .d2s save: class, level, stats, progression, merc.
No scanner pass — use d2r_save_scan for validation.
Args: path: Absolute path to .d2s file, or bare character name.
Inputs: path (required).
d2r_save_list_itemsA
List items on disk in a .d2s save, optionally filtered by location.
Args: path: Absolute path to .d2s file, or bare character name. location: Filter: equipped, inventory, cube, stash, merc_equipped, or None for all.
Inputs: path (required), location.
d2r_save_scanA
Run d2rdoctor scanner on a .d2s save file.
Returns a structured result with checksum/size status, item counts, and any scanner errors or warnings. status == "error" iff errors is non-empty. Deployment-blocker rule: never deploy a save that this tool flags as error (see CLAUDE.md Rule #17).
Args: path: Absolute path to .d2s file, or bare character name (resolved against Steam saves dir).
Inputs: path (required).
d2r_searchA
Search across ALL D2R item types: uniques, sets, runewords, bases.
Use this when you don't know what type of item you're looking for. Returns up to 20 results tagged by type.
Args: query: Search term (substring match across all item names)
Inputs: query (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Each tool has a clear, distinct purpose. The naming with category prefixes (chargen, lookup, mod, save) and specific actions prevents ambiguity. For example, d2r_chargen_build and d2r_save_inspect operate on different resources, and lookups are split by item type.
All tools follow the consistent pattern 'd2r_<category>_<action>', using snake_case uniformly. There are no mixed conventions (e.g., camelCase) or irregular formats.
23 tools cover the full modding lifecycle—character generation, lookups, mod building/deploying, and save file inspection—without being excessive. Each tool seems justified for its role.
The tool set covers the main workflows: chargen (build, import, validate), lookups (all item types), mod management (extract, build, deploy, clean, update, diff, audit), and save operations (inspect, scan, diff, list items). No obvious gaps for the intended domain.
Maintenance
Related MCP Connectors
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Build, run and publish 3D games in the Zero engine from Claude Code, Cursor or Codex, over MCP.
MCP Server for Slima - AI Writing IDE for Novel Authors with AI Beta Reader.
Self-hosted MCP server: 26 deterministic dev, security, and EVM tools.
Related MCP Servers
- AlicenseBqualityNot gradedmaintenanceEnables complete RPG Maker MZ game development through MCP tools, including autonomous game creation from concepts, AI-generated assets using Gemini 2.5 Flash, and programmatic control over maps, events, characters, and databases. Supports full game creation workflow from a single command with automatic story, asset, and implementation generation.3225-
- AlicenseAqualityDmaintenanceProvides fast, cached access to comprehensive Dungeons & Dragons 5th Edition data including spells, monsters, classes, races, equipment, and rules through Open5e and D\&D 5e APIs.72MIT
- AlicenseAqualityFmaintenanceProvides real-time access to Path of Exile 2 game data including currency exchange rates, item prices, and ladder meta-build statistics. It also enables LLMs to search the community wiki and retrieve datamined game information from public APIs.285MIT
- AlicenseNot gradedqualityBmaintenanceA Linux-native MCP server that gives AI assistants direct access to DMA-based memory operations for memory inspection, process analysis, reverse engineering, and game engine SDK extraction via natural language.13AGPL 3.0