Horadric Tools para Diablo II: Resurrected

👁 Tests
👁 Python 3.11+
👁 License: MIT
👁 Platform: Linux

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 .d2s offline 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 extract

Si 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 ExamplePaladin

Compí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 ExamplePaladin

YAML 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: 40

Consulta chars/ExamplePaladin.yaml para ver un ejemplo más completo.

Nombres de clase admitidos:

amazon, sorceress, necromancer, paladin, barbarian, druid, assassin, warlock

Ranuras de equipo comunes:

helm, body, weapon, shield, hands, belt, feet, neck, ring_right, ring_left,
weapon_switch, shield_switch

Referencia 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 update

Superposiciones 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 mcp

Inícialo con:

python3 -m d2r_mcp

Claude Code:

claude mcp add d2r-tools --transport stdio --scope user -- python3 -m d2r_mcp

Configuració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:

1. Comienza desde una plantilla .d2s válida existente siempre que sea posible.

2. Escribe los cambios en un archivo temporal o de pruebas (staging).

3. Recalcula el tamaño y la suma de comprobación (checksum).

4. Ejecuta d2r-chargen scan <nombre>.

5. 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 skills

Compatibilidad de plataforma

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.py

Licencia

MIT

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• d2r_chargen_buildA
• d2r_chargen_importA
• d2r_chargen_listA
• d2r_chargen_validateB
• d2r_lookup_item_baseA
• d2r_lookup_runewordA
• d2r_lookup_set_itemA
• d2r_lookup_skillA