D2R Modding Universal Guide: Iron Rules from a Decade of Pitfalls

Why This Guide Exists

D2R modding looks deceptively simple — just edit a few JSON files. But beneath the surface lurk countless traps:

• Changed an item name → game still shows the original 😤
• Added colorful loot abbreviations → unique names turn yellow 🤔
• Restart the game → stuck on “Loading…” for 4+ minutes 💀
• ~20 seconds after launch → instant crash, no log 🫠
• Special characters all become blank squares □

This guide solidifies personally verified patterns into iron rules — 9 chapters + tools.

The Three Most Important Rules

Before touching a single file, memorize these. They prevent 80% of wasted troubleshooting:

1. Edit the right file: The CN client reads different content from different files — names may come from bnet.json, descriptions from item-modifiers.json, the rest from item-names.json. Wrong file = invisible changes.
2. Never guess codes/IDs: Item codes are counterintuitive (e.g., flawless gems are mostly gl*, not gz*). Missing id field = crash ~20s after launch with zero logs. Always grep from authoritative sources.
3. Every string needs id, simplified Chinese uses zhCN: The myth that “CN client reads sgCN/bnCN, not zhCN” has been empirically debunked. Original CN game data contains zero sgCN/bnCN fields.

Chapter Overview

01 · Mod Anatomy

Understand any D2R mod’s complete content. Mods have a four-layer structure:

Critical insight: The mod’s <name>.mpq is a folder, not an archive. Edits take effect without repacking — just fully restart the client.

02 · Golden Rules

Hard rules that cause failure when violated:

• CN client reads differently than intuitive: quality labels and some gem names get display-overridden by bnet.json. When item-nameaffixes changes don’t show, check bnet.json.
• zhCN is the correct locale field: The sgCN/bnCN myth originated from SU mod’s defensive fields. Three production mods running on CN server have zero sgCN/bnCN entries.
• Three crash modes: Missing id field (~20s crash), texture_desc_cache.json (4+ min loading freeze), referencing CN-harmonized art assets (DX12 DeviceLost).

03 · Standard Data Procedure

Never write item codes from memory. Comprehensive reference including:

• Complete item code/ID lookup tables
• Standard grep-based extraction from .txt files
• Counterintuitive quirks documented

04 · Colors & Safe Symbols

Complete D2R text color control codes (ÿc0 ~ ÿcM, including DLC additions), plus:

• Color semantic conventions (orange for runes, green for set items, gold for uniques…)
• Font-safe symbol whitelist — not all Unicode renders in D2R’s bundled AR font
• Reusable loot coloring patterns
• Multi-line color bleed fix: each line starts with its own color code + ends with ÿc0 terminator

05 · Reign of the Warlock DLC Reference

2026 DLC systemic changes: new Warlock class, runewords, Codex system, new item categories, version compatibility notes.

06 · China Server Complete Guide (Most Critical Chapter)

Every pitfall of CN server modding:

• Three crash modes with precise attribution
• Debunked myths: full sgCN/bnCN reversal with evidence chain
• CN censorship mechanism: runtime string-key interception, not data-layer
• File safety table: what you can modify, what will crash
• International → CN conversion SOP

07 · UI Manual

Panels, HUD, buttons, message routing:

• Panel registration truth: _profilehd.json is the master panel registry
• Message routing mechanism
• Widget vs Panel distinction
• Overlay effects and multi-mod compatibility

08 · New Mod Skeleton

Minimum viable mod that loads, doesn’t crash, and displays Chinese correctly. Complete directory structure, modinfo.json template, launch parameters, auto-registration, and validation checklist. Build in 15 minutes.

09 · Game Mechanics Reference

FCR/FHR breakpoint tables, socket rules, superior item mechanics, CB/DS/Break probabilities — the data foundation for loot coloring and balancing decisions.

Write Discipline (Anti-Echo-Chamber)

This guide has suffered two “unverified conclusion treated as iron rule” incidents and now enforces strict sourcing:

• Every iron rule must cite original evidence: screenshot or vanilla extract. No evidence = mark “unverified”.
• Community resources are only reliable for numeric codes; letter codes and new-version features require in-game verification.
• Reference mods ≠ vanilla: must verify against CASC original extracts before citing as “official.”
• Evidence levels: ✅ In-game verified / 🔬 Production confirmed / 📐 Structural fact / ⚠️ Unverified (banned).

Scope

• D2R CN (NetEase/bnCN) + International client, with emphasis on CN specifics
• Knowledge from real-world verification (through 2026-06), D2R version includes 3.x Reign of the Warlock
• Generic knowledge only — no machine paths or private info, ready to sync and share

Get the Full Knowledge Base

9 chapters + tool scripts, forever free and open source:

→ GitHub: d2r-modding-guide

Whether you donate or not, filing Issues / PRs to help complete this knowledge base — leaving your own pitfalls documented for the next person — is the best way to give back.