Diablo II: Lord of Destruction 1.14d on the New 3DS.
3ds-d2 runs the unmodified Windows Game.exe of Diablo II 1.14d on a New 3DS. The x86 code runs through an ARMv6 port of the Box86 dynamic recompiler (from the WinVita engine). The Windows APIs the game calls come from 3ds-d2's own runtime. The hottest drawing routines run as native ARM code. The game itself is not included: you need your own copy of Diablo II and Lord of Destruction, patched to 1.14d.
- A New 3DS, New 3DS XL or New 2DS XL. The original 3DS and 2DS do not have enough memory or CPU.
- Luma3DS custom firmware.
- FBI (or another CIA installer).
- About 2 GB free on the SD card for the game files.
- Your own Diablo II + Lord of Destruction, patched to 1.14d. The current Blizzard installers for Diablo II and Lord of Destruction install 1.14c, not 1.14d, so patch the installed game before copying its files: update it to 1.14d through Battle.net (Blizzard support), or apply the offline 1.14d patch. The app refuses any other
Game.exe(see step 1). - For sound: a DSP firmware dump at
sdmc:/3ds/dspfirm.cdc(see step 2).
Create the folder /3ds/3ds-d2/game/ on the SD card. Copy these 12 files from your Diablo II installation folder into it, with these names:
| File | Size | Contents |
|---|---|---|
Game.exe |
3.6 MB | the game, version 1.14d |
d2char.mpq |
266 MB | character graphics |
d2data.mpq |
269 MB | game data |
d2exp.mpq |
250 MB | Lord of Destruction data |
d2music.mpq |
348 MB | music |
d2sfx.mpq |
49 MB | sound effects |
d2speech.mpq |
163 MB | speech |
d2video.mpq |
442 MB | cinematics |
d2xmusic.mpq |
55 MB | Lord of Destruction music |
d2xtalk.mpq |
60 MB | Lord of Destruction speech |
d2xvideo.mpq |
111 MB | Lord of Destruction cinematics |
patch_d2.mpq |
5.7 MB | the 1.14d patch data |
That is about 1.9 GB in total. The game checks for every one of these files at startup, so copy all of them, cinematics included. The game needs no other files from the installation folder: since 1.14, Diablo II has no DLLs of its own.
The finished folder looks like this:
SD card
└── 3ds
├── dspfirm.cdc (for sound)
└── 3ds-d2
└── game
├── Game.exe
├── d2char.mpq
├── d2data.mpq
├── ...
└── patch_d2.mpq
The app creates save/ (characters and settings) and logs/ (game.log, stderr.txt) next to game/ the first time it runs.
To check that your Game.exe is the 1.14d build this project is tested with, its SHA-256 should be 631066c1649c4ea9ffe48bf97e24c00bca1f7a6759c21150f1a79982589adaaf. The app checks the Game.exe before starting it and refuses any other build, older 1.14 builds (1.14c from the current installers) and the small Game.exe of the versions before 1.14 included, with what to do on the top screen. It tells 1.14d by where the program starts (its entry point), not by the hash.
Homebrew apps can play sound only through the 3DS's DSP. Its firmware comes from your own console and can't be shipped with the app, so you dump it once:
- Get DSP1 (
DSP1.3dsx, by zoogie) and copy it to/3ds/on the SD card. - Start the Homebrew Launcher (on Luma3DS, through the Rosalina menu) and run DSP1.
- It writes
/3ds/dspfirm.cdcand tells you when it is done.
If you set up your console with the 3ds.hacks.guide, you may have done this already: check whether /3ds/dspfirm.cdc exists. The dump is needed only once, for every homebrew app. Without it 3ds-d2 still runs, but silently, and logs/game.log says ndspInit failed.
Build the CIA as described under Building the CIA, then install 3ds-d2-<version>-<build-id>.cia with FBI. Either copy it to the SD card and pick it in FBI under SD, or use FBI's Remote Install. The HOME menu then shows a 3ds-d2 icon (title ID 000400000D2D3D00).
The CIA holds only the app, about 2 MB. A new version is a quick reinstall over the old one, and the game files on the SD card stay where they are.
Start 3ds-d2 from the HOME menu. The game appears on the top screen. The bottom screen has tabs: the automap (MAP, with ? in its corner for a list of the controls), touch buttons for the hotkeys (KEYS), a 1:1 view around the cursor (ZOOM), and frame rate and memory use (INFO). When a panel opens, such as the inventory or the stash, the bottom screen shows it at full size, and you can tap items directly. On MAP and INFO the bottom screen works as a touchpad; the buttons under the map set its size and how often the markers of others refresh.
| Input | Action |
|---|---|
| Circle pad | Walk (in the game world); move the cursor (in menus and panels) |
| C-stick | Move the cursor |
| Touch screen | Touchpad: drag moves the cursor, a short tap clicks |
| A / B | Left / right mouse button |
| X | Inventory |
| Y | Show items on the ground (held); in a shop, sells the item under the cursor; with the inventory open, drops it |
| L | Stand still (held) |
| D-pad | Belt potions 1–4 |
| ZL | Weapon swap |
| Start | Game menu, close panels |
| Select | Top screen: whole frame ↔ 1:1 zoom for reading text |
| A, B, Start or a tap | During a cinematic: skip it |
| R + A / B / X / Y | Character screen / skill tree / automap / quests |
| ZR + A / B / Y / X | Skill hotkeys F1–F4 |
| R + D-pad | Skill hotkeys F1–F4 too |
| R + Start | Enter (confirm) |
| R + Select | On-screen keyboard |
| L + R + Select | Screenshot into the Camera album |
| Select + D-pad left / right | Previous / next bottom-screen tab |
| Select + D-pad up / down | Bottom screen: MAP / switch the map's size |
When the game asks for text, such as a character name, a keyboard opens on the bottom screen. Tap the keys. B deletes, Y is shift, Start confirms, Select closes it. R + Select opens the keyboard at any time. docs/controls.md has the full mapping.
If the app shows "Game.exe not found", check the folder name and that Game.exe is inside /3ds/3ds-d2/game/.
If the app shows "Game.exe ... is not Diablo II 1.14d" or "... is from a Diablo II before 1.14", the Game.exe on the SD card is another version: patch the game to 1.14d (requirements) and copy its Game.exe and patch_d2.mpq again.
If 3ds-d2 crashes (Luma3DS shows its exception screen), the next start keeps that session's game.log, stderr.txt and the Luma3DS crash dump in /3ds/3ds-d2/reports/<time>-<build>/ before anything is overwritten. The top screen then shows the report and asks whether to send it. It does the same after a session that ended on a fatal error, after a session in which you tapped report at the bottom of the INFO tab, and after a session with a profiler run (INFO's other button: a checklist of measurements to run, see docs/controls.md). The report is made only after the game has ended, never while you play.
The screen lists what would be sent:
- the whole
game.log(a four-hour session writes about 1 MiB; only past 32 MiB is the middle left out),stderr.txt, and the Luma3DS dumps saved during the session, gzip-compressed for the upload; - after a profiler run, the traces it wrote (
sprites.trc,files.trc), and which measurements ran; - the build ID, version, CIA or 3dsx, where the game files are read from, the console model, region, system version and kernel version;
- figures from the log: minutes played, frame rate in play, frames over 100 ms in play and the longest, memory peaks;
- your description, if you write one: press Y to type it with the system keyboard;
- screenshots, if you choose any: press L.
Save files and character names are never sent.
Screenshots. L lists the screenshot pairs that can go with the report, newest first, and shows the selected one on the bottom screen (Y switches between its top and bottom picture). A chooses a pair, up to 4; none is chosen unless you do. Two kinds are offered:
- the game's own (L + R + Select in the game, see docs/controls.md): its newest 16 pairs, whenever taken;
- Luma3DS's (its menu's Take screenshot, also usable while the game is suspended in the HOME Menu): all of them in
/luma/screenshots/, from any session.
The rest of the Camera album is never offered. A pair is sent as screenshot-<n>a-top.jpg and screenshot-<n>b-bot.jpg (named so Sentry lists the top first) (Luma3DS's BMPs as JPEGs), and the report says when each was taken and from which file. Pairs marked * were taken during the report's session (suspended time included).
In Sentry, reports are grouped by what happened, not by your description, so the same crash lands in one issue however it's described. The groups: a crash the app caught (the fault, and where in Game.exe); a Luma3DS dump (the crashed process and exception, and outside 3ds-d2 its address); a fatal error by its kind; a session that didn't end; a report you asked for, by its title. Your description goes with each report as its note.
A report you ask for (or a profiler run's) is titled by the version, which you can't change, and an optional topic you add with R: v0.4.0 alone, or v0.4.0 #24. Reports with the same title are one Sentry issue; the topic ignores case and extra spaces. The topic is remembered (/3ds/3ds-d2/report-topic.txt) for every later report until you change it, and goes with crash reports too, as the topic tag, without changing how they group. Builds not made from a release's tag carry -dev in their version (v0.4.0-dev), in the CIA's name and in Sentry, so testing never mixes with a release's reports.
On a report's screen:
- A sends it over Wi-Fi to the project's Sentry account. Sentry's ID for it is shown, and kept in the report's folder (
sent.txt). - Y writes or changes your description.
- R sets the topic: the title's own part for a report you asked for, a tag for a crash.
- L chooses screenshots to send with it.
- X marks it as not to be sent (A still sends it later).
- SELECT twice deletes the report and its files.
- B goes back to the list of reports.
Reports you don't send wait for later: playing without the internet (on a plane, say), each session's report stays on the SD card, and the next start with reports waiting shows the list of them. There, X sends every waiting report, oldest first, and A opens one to read, change, send or delete it; START goes on to the game. Hold SELECT while 3ds-d2 starts to open the list when nothing is waiting, for example to delete old reports.
Nothing is sent unless you press A or X. Up to 32 reports wait to be sent; of those sent or marked not to be sent, the newest 8 stay. The folders are on the SD card, so you can also attach one to a GitHub issue yourself. Builds made without a Sentry project (D2_REPORT_DSN=, see Building the CIA) never ask and never send; they only keep a crashed session's files.
Everything builds inside Docker containers with a pinned toolchain (devkitARM, libctru, makerom). The host needs only Docker and git: Docker Desktop on macOS (Apple Silicon or Intel) or Windows, or Docker Engine on Linux. You don't need the game files to build the app.
-
Get the source with its submodule. The CPU backend (WinVita, with Box86) is a git submodule, so clone recursively:
git clone --recursive https://github.com/exsilium/3ds-d2.git cd 3ds-d2For a copy cloned without
--recursive, rungit submodule update --initfirst.On Windows, run the commands below in Git Bash. Git for Windows checks text files out with CRLF line endings by default (
core.autocrlf=true), which breaks the scripts in the Linux build containers. The repository's.gitattributeskeeps its own files LF, but it does not reach the submodule, so clone with autocrlf off and keep it off in the submodule:git -c core.autocrlf=false clone --recursive https://github.com/exsilium/3ds-d2.git git -C 3ds-d2/third_party/winx86 config core.autocrlf false -
Build the toolchain images, once. This downloads and builds the pinned tools, and takes a few minutes the first time:
scripts/docker.sh image
-
Build the CIA.
scripts/docker.sh package-cia
On the first run this also builds the CIA tools image. It then compiles the CPU backend with this project's patches and the 3DS app, and packs the CIA. The last lines show the result:
cia: 3ds-d2-<version>-<build-id>.cia version: 0.4.0 sha256: ...
The output goes to dist/cia/:
3ds-d2-<version>-<build-id>.cia: the app to install (step 3 above).3ds-d2-<version>-<build-id>.elf: the same code with debug symbols, for reading crash dumps (tools/luma_dump.py).3ds-d2-<version>-<build-id>.cia.txt: version, size and SHA-256. To check that a copy on the SD card is intact, compare its SHA-256 with this file.
The build ID is a hash of everything that goes into the CIA, so the same sources always produce the same name, and any change gives a new one. Builds run without network access, and the game files never enter an image.
Two variants carry the game files inside the CIA itself instead of reading them from the SD card. Such a CIA is for your own console only:
scripts/docker.sh package-cia --full <game-dir>: all 12 files (~2 GB).scripts/docker.sh package-cia --slim <game-dir>: without music, speech and cinematics (~850 MB, no sound).
Every build, your own included, offers problem reports to the project's Sentry, whose DSN is in packaging/cia/report.dsn (a public key that can only send events). Each report's release is the version the session was played on (3ds-d2@<version>, with -dev unless the build was made from the release's tag v<version> with nothing uncommitted: scripts/version.sh), and its build ID is the release's dist and the build_id tag, so all builds of a version share one release in Sentry and reports from one build can still be filtered (dist:<build ID>). To send your reports to your own project instead, set its DSN when building: D2_REPORT_DSN=https://<key>@<org>.ingest.sentry.io/<project> scripts/docker.sh package-cia ... (SENTRY_AUTH_TOKEN=<token> scripts/sentry-setup.sh [<org> [<project>]] creates one and writes its DSN to that file). D2_REPORT_DSN= (empty) builds an app that never offers or sends anything. The console's own HTTPS cannot complete a handshake with Sentry's servers (they take only TLS 1.2 with SNI), so the app brings its own TLS: mbedTLS and the root certificates of Sentry's current and announced certificate authorities, built into a separate module (src/tls/, shipped as tls.bin in the RomFS). The module takes no memory during play. To send a report, the app loads it into executable memory (the way the JIT makes its code), sends over the console's sockets, and frees it again. scripts/docker.sh test tls loads the same module under qemu-arm and sends a test event to the project. An http:// DSN (a relay that forwards to Sentry) is sent without the module.
More documentation:
- docs/build-and-run.md: builds, tests and the Azahar emulator lanes.
- docs/hardware-test.md: installing, what the bottom screen shows, reading crash dumps.
- docs/architecture.md: how the pieces fit together.
Projects this one builds on, learned from or uses.
Built on
- WinVita (MIT): the Win32 engine for running Windows executables on a console: PE loader, import bridge, guest threads, and the Box86-based CPU backend and DirectSound emulation. It is the submodule
third_party/winx86, and this project's ARMv6 port is a patch series on top of it. - Box86 (MIT): the x86-to-ARM dynamic recompiler at the core of WinVita's CPU backend, ported here to the 3DS's ARMv6K.
Inspiration and reference
- D2Vita (GPL-3.0): Diablo II 1.14d on the PlayStation Vita, built on WinVita. It proved the approach on this exact executable. It was used only as a behavioural reference, for game facts such as memory addresses and the sprite-cache sizing, and for its control ideas. None of its code is in this project.
- DOSBox-3DS (GPL-2.0): read to confirm how a 3DS homebrew app makes JIT memory executable (
svcControlProcessMemory). None of its code is used. - DOSBox-X and M-HT/SR (static recompilation of DOS and Windows games): evaluated as alternative CPU approaches while planning.
3DS platform and tools
- devkitPro: devkitARM, libctru and citro3d, from the devkitPro Docker images.
- Project_CTR: makerom and ctrtool, to build and check CIAs.
- 3ds-bannertool: the HOME menu icon and banner.
- Azahar: the 3DS emulator used for testing.
- StormLib: MPQ archive library, used by the D2Vita reference build that served for measurements.
On the console
- Luma3DS: the custom firmware the app needs (its system calls make the JIT work on hardware).
- FBI: CIA installer.
- DSP1: dumps the DSP firmware for sound.
3ds-d2 is licensed under the BSD 2-Clause License (LICENSE). Third-party components and their licences are listed in THIRD_PARTY_NOTICES.md.
Diablo II and Lord of Destruction are trademarks of Blizzard Entertainment. This project is not affiliated with or endorsed by Blizzard, and it contains no game files or code. You need your own legally obtained copy of the game.
