d2animdata is a command-line program for editing AnimData.D2. AnimData.D2 is a propriety file format used by Diablo 2 to store animation metadata for characters and monsters.
d2animdata can decompile AnimData.D2 to text-based file formats, such as tabbed text and JSON (see Supported File Formats for more info). Modders can edit these files to add new animations or modify existing ones. After editing, d2animdata can compile it back to a new AnimData.D2 file.
d2animdata is written in Python. It supports Python 3.6 and above, and has been tested on Windows 10 and Ubuntu Linux.
⚠ This project is very much in Alpha. There may be several bugs. Always back up your AnimData.D2 file before using d2animdata.
To use d2animdata, you must install Python 3. Then, open a command-line shell (e.g. cmd.exe) and enter:
pip install d2animdataThis will install d2animdata on your computer.
To view help for a command, enter:
d2animdata <command> --help
Decompiles an AnimData.D2 file to tabbed text or JSON file.
$ d2animdata decompile --help
usage: d2animdata decompile [-h] [--dedupe] [--sort] (--json | --txt)
animdata_d2 target
positional arguments:
animdata_d2 AnimData.D2 file to decompile
target JSON or tabbed text file to save to
optional arguments:
-h, --help show this help message and exit
--dedupe Remove records with duplicate COF names
--sort Sort the records alphabetically before saving
--json Decompile to JSON
--txt Decompile to tabbed text (TXT)Example: Decompile path/to/AnimData.D2 to a JSON file.
d2animdata decompile --json path/to/AnimData.D2 path/to/my-animdata.json
Example: Decompile path/to/AnimData.D2 to a tabbed text file.
d2animdata decompile --txt path/to/AnimData.D2 path/to/my-animdata.txt
Compiles a tabbed text or JSON file to AnimData.D2 file.
$ d2animdata compile --help
usage: d2animdata compile [-h] [--dedupe] [--sort] (--json | --txt)
source animdata_d2
positional arguments:
source JSON or tabbed text file to compile
animdata_d2 AnimData.D2 file to save to
optional arguments:
-h, --help show this help message and exit
--dedupe Remove records with duplicate COF names
--sort Sort the records alphabetically before saving
--json Compile JSON
--txt Compile tabbed text (TXT)Example: Compile a JSON file to path/to/AnimData-result.D2.
d2animdata compile --json path/to/my-animdata.json path/to/AnimData-result.D2
Example: Compile a tabbed text file to path/to/AnimData-result.D2.
d2animdata compile --txt path/to/my-animdata.txt path/to/AnimData-result.D2
d2animdata supports two file formats: tabbed text (.txt) and JSON (.json).
Tabbed text files (.txt) can be edited with a spreadsheet program (e.g. Excel, AFJ Sheet Edit). Diablo 2 modders should already be familiar with these files, as Diablo 2 uses tabbed text files extensively to control various aspects of the game.
d2animdata is compatible with Paul Siramy's excellent animdata_edit program, which is another popular tool for (de)compiling AnimData.D2 to tabbed text.
JSON files (.json) can be edited with any text editor (e.g. Notepad), though I recommend using one with syntax highlighting support (e.g. Notepad++, Visual Studio Code).
JSON has several advantages over tabbed text:
-
JSON files can be added to a version control system (VCS), such as Git. This allows you to keep track of changes made to a file. You can compare changes across time and revert unwanted changes.
Tabbed text files and AnimData.D2 can also be added to a VCS. However, tabbed text files are tricky to deal with, because they don't produce nice-looking diff logs when compared. Binary files, such as AnimData.D2, cannot be compared at all. On the other hand, JSON files create diff logs that are easy to read.
-
JSON files are easier to handle in several programming languages.
-
Unlike tabbed text, JSON does not suffer from tricky whitespace issues.
d2animdata can also be imported from a Python script to load, edit, and save AnimData.D2.
Example:
from d2animdata import load, dump
# Load an AnimData.D2 file
with open('AnimData.D2', mode='rb') as animdata_file:
animdata = load(animdata_file)
# animdata now contains a list of Record objects.
# Iterate through each record, printing its information
for record in animdata:
print('COF name:', record.cof_name)
print('Frames per direction:', record.frames_per_direction)
print('Animation speed:', record.animation_speed)
print('Trigger frames:', record.triggers)
# Let's find a record named '0DNUHTH' and edit it
for record in animdata:
if record.cof_name == '0DNUHTH':
record.animation_speed = 192
# Erase all trigger frames previously set on this record.
record.triggers.clear()
# Set the trigger code of frame #10 to 1
# Since frame indices begin at 0, we're actually modifying the 11th frame.
record.triggers[10] = 1
break
# Save the records to AnimData.D2
with open('AnimData.D2', mode='wb') as animdata_file:
dump(animdata, animdata_file)See the API docs for a complete reference of available functions and classes.
To develop d2animdata, you will want a good Python editor. I recommend Visual Studio Code with the Microsoft Python extension.
To develop d2animdata, clone this repository and create a virtual environment. Then run the following commands to install the project locally for development:
# For Windows
python -m pip install -r requirements-dev.txt
flit install --pth-file
# For non-Windows
pip install -r requirements-dev.txt
flit installd2animdata uses:
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent