Skip to content
exsiliumPublic

About

Squeezing the Devil and the Hell into a small retro handheld (n3DS).

Resources

Contributing

Stars

17 stars

Watchers

0 watching

Forks

Repository files navigation

3ds-d2

Diablo II: Lord of Destruction 1.14d on the New 3DS.

Diablo II on a New 3DS XL: the Rogue Encampment on the top screen, the town automap on the bottom screen

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.

Requirements

  • 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).

Setup

1. Copy the game files to the SD card

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.

2. Dump the DSP firmware (for sound)

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:

  1. Get DSP1 (DSP1.3dsx, by zoogie) and copy it to /3ds/ on the SD card.
  2. Start the Homebrew Launcher (on Luma3DS, through the Rosalina menu) and run DSP1.
  3. It writes /3ds/dspfirm.cdc and 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.

3. Install the app

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.

4. Play

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.

Problem reports

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.

Building the CIA

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.

  1. 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-d2

    For a copy cloned without --recursive, run git submodule update --init first.

    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 .gitattributes keeps 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
  2. Build the toolchain images, once. This downloads and builds the pinned tools, and takes a few minutes the first time:

    scripts/docker.sh image
  3. 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:

References

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

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.

Legal

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.

About

Squeezing the Devil and the Hell into a small retro handheld (n3DS).

Resources

Contributing

Stars

17 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages