Skip to content
VibePorterPublic

About

Dishonored (Xbox 360) statically recompiled for the Nintendo Switch: native ARM code via ReXGlue and a Direct3D-level deko3d renderer, built from your own game files.

Topics

Resources

Contributing

Stars

8 stars

Watchers

1 watching

Forks

Latest commit

ย 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

Dunwall

Arkane's Dishonored (Xbox 360, with its title update), statically recompiled for the Nintendo Switch

Platform Renderer Game Status License

What it is ยท Known issues ยท Highlights ยท What we fixed ยท Screenshots ยท Editions ยท Install ยท Build ยท Controls ยท FAQ ยท Story ยท Docs ยท Credits


Important

No game files are included, and none may ever be added. Dunwall is made from your own Xbox 360 copy of Dishonored and its title update. The code generated from the game, the converted shaders and the finished NRO are all built on your computer from your files.

๐Ÿ—๏ธ What it is

Dunwall is the sister project of Lazarus (Mass Effect 2 for the Switch): the same tree, retargeted to another Unreal Engine 3 game on a newer XDK.

  • Static recompilation. The game's PowerPC program (default.xex + the title update's default.xexp) is translated to C++ by the ReXGlue code generator and compiled for the Switch's ARM CPU. No emulator runs at play time: the Xbox 360 kernel, file system, audio (Wwise on XMA) and input are provided by the SDK's runtime.
  • A Direct3D-level renderer on deko3d. Instead of emulating the Xenos GPU, Renut hooks the game's own Direct3D calls (draws, shaders, render targets, resolves) and replays them through plume on deko3d, the Switch's native graphics API. The game's ~49,500 shaders are converted ahead of time (Xenos microcode โ†’ SPIR-V โ†’ GLSL โ†’ DKSH).
  • Game-specific work on top: a CPU occlusion rasterizer that answers UE3's occlusion queries, size-based culling, native replacements for hot functions, PGO builds, Switch button prompts and a redrawn controller screen, a new control scheme, all DLC, and menu clean-ups for things a Switch does not have (see below).

It runs on a real Switch and in Ryujinx, and the same app builds for Windows for debugging. It is a work in progress: read known issues before you start a long playthrough.

๐Ÿšง Known issues at a glance

Warning

  • Not a locked 30. The busiest views drop to the low 20s: UE3's own render thread (one core) is the limit there.
  • Rainbow or black textures on distant objects can still appear now and then on the console and stay until the level is loaded again. Several causes were found and fixed; the last one is not confirmed gone.
  • You build it yourself. There is no download; the NRO and shader files are made from your own disc and title update, and the build chain has not yet been re-run from a fresh clone.
  • One edition tested: the Eastern European disc (English / Russian / Polish / Czech / Hungarian).
  • Picture trade-offs for speed: the world depth prepass and the sun's dynamic shadows of characters are not drawn, and small far props are culled earlier than on the Xbox. Each is one line in dishonored.toml.
  • No online: leaderboards and the DLC store are removed from the menus.

The full list: docs/known-issues.md.

โšก Highlights

Feature What it does
๐ŸŽจ Native deko3d renderer The game's Direct3D calls drawn by deko3d: no GPU emulation, no Vulkan driver in the NRO
๐Ÿ‘๏ธ CPU occlusion rasterizer UE3's occlusion queries are answered from the frame's own occluders on a worker core, without waiting for the GPU; hidden primitives are also dropped before UE3 draws them
โœ‚๏ธ Prepass skip and size culling The depth prepass (up to 45 % of the draws in heavy views) is not drawn; small far meshes are skipped by size
๐Ÿ”ฅ Hot natives + PGO Hand-written C++ for hot guest functions (each checked against the original), profile-guided LTO builds
๐Ÿงฉ Every shader ahead of time 49,514 shader containers found in the packages, including the ones the first scans missed
๐ŸŽฎ Switch button prompts The game's Xbox button prompts replaced, and the options' controller picture redrawn as a Switch
๐Ÿ” Control scheme "Type E" A new scheme in Options โ†’ Controls: Type A with the A and B actions exchanged
๐ŸŒ Language choice English, Russian, Polish, Czech or Hungarian from one disc (dh_language); by default English, or Russian on a console set to Russian
๐Ÿ“ฆ All DLC, as asset packs The game and each DLC package mounted from one pack file instead of thousands of SD card files
๐Ÿ’พ Switch user saves With the NSP forwarder the game saves into the chosen Switch user's save data, with real dates
๐Ÿงน Menus that fit a Switch No "install to hard drive" prompt, storage device row, DLC store button or leaderboards

๐Ÿ“Š Measured

Real Switch, handheld, 480p scene with a 720p HUD, GPU at its stock 460.8 MHz and the CPU at about 1323 MHz (the overlay in the screenshots below): 30 fps in the street, at Dunwall Tower and in the fight shown. From the console logs of the instrumented builds: about 25 fps over a 27-minute session, and 23-24 fps at the heaviest stationary spots (about 760-870 draws a frame, UE3's render thread at 88-90 % of its core). No long session of the release build has been logged yet. How to measure your own runs: docs/measuring.md.

๐Ÿ”ง What we fixed

Every row was found in a console or Ryujinx log, a RenderDoc capture or a crash stack. The longer story of each is in docs/porting-notes.md.

Problem Cause Result
๐ŸŸจ Flat yellow / grey frames The device-watch list was Mass Effect 2's: no draw's state was ever compared the title screen renders
๐ŸŽจ Wrong colours, then a green 3D picture on the Switch Resolve's slice argument read as a mip level; the 32x16 colour-grading target scaled with the scene; a 2D-array view made as one layer colours as on the Xbox 360
โœ๏ธ Thin bright outlines on every edge The texture fetch's exponent adjust was ignored (the game's FXAA reads one image at three scales) outlines gone
๐ŸŒช๏ธ Swirling, torn materials The shader translator linked vertex outputs to pixel inputs by register; UE3 packs them by semantic materials right
๐ŸŸฉ Green screen in Dark Vision, missing blink sphere Thousands of shaders were never extracted (four scanner bugs: slack bytes after LZX chunks, fully compressed packages, ...) +4,147 shaders, none missing
โฌ› Black screen on a sword hit The +5 exponent of 16-bit fixed-point resolves was dropped: three resolves at 1/32 each the blur shows (the combat screenshot)
๐Ÿ’ฅ "GPU timeout" crash at level loads The GPU channel's 2,048-entry command ring ran full while the CPU was far ahead the submit is retried: no crash
๐Ÿ€ 3-7 fps for minutes when rats arrive UE3's per-draw polygon offsets were part of the pipeline key: ~640 new pipelines every 10 s depth bias is dynamic state
๐Ÿง‘ Characters popping in and out Occlusion answers came from the GPU a frame late the CPU rasterizer answers in time
๐Ÿ‘ป Dark Vision showed nobody behind walls The primitive cull hid characters UE3 never queries only primitives with static meshes are culled
๐Ÿ“‰ HUD dropping to scene resolution after water A screen effect detoured the final pass through a small buffer the UI pass is kept
โฑ๏ธ 30 s on a black screen at every start 65,000 pipeline records loaded with a grow-and-free pattern containers reserved up front (console timing still to be checked)
๐Ÿ“… Saves dated 1970 The Switch's save data file system keeps no file times times kept beside the saves
๐Ÿ† Crash on the Dunwall City Trials leaderboard XUserReadStats returned success without results empty results; the leaderboards are hidden

๐Ÿ–ผ๏ธ Screenshots

Captured on a real Switch (handheld, 1280x720, GPU 460.8 MHz, CPU about 1323 MHz). The overlay in the corner shows the clocks and the frame rate.

Title screen A street in Dunwall
Title screen Dunwall, at 30 fps
Controls screen Dunwall Tower
Options โ†’ Controls: the Switch picture, Switch prompts and the new Type E scheme Dunwall Tower
Dark Vision Combat
Dark Vision, with a ZL prompt Combat: the game's blur around a sword fight, at 30 fps

โœ… Supported editions

Dunwall is built for the Xbox 360 release (title ID 425307E3) with its title update. The NRO must be built from the same default.xex + default.xexp you play with.

Edition Base default.xex With the title update Status
Eastern European disc (English, Russian, Polish, Czech, Hungarian) 0.0.0.17 0.0.3.17 โœ… played on console, in Ryujinx and on the PC build
Other discs, Game of the Year Edition, Games on Demand โ” not tested: another program means other addresses
Without the title update 0.0.0.17 โŒ not supported (every hook uses the updated addresses)

๐Ÿ“ฆ Install

The full guide, with the SD card layout, Ryujinx and the forwarder, is docs/install.md. In short:

  1. Build the NRO and its shader files from your game (building). There are no prebuilt downloads: every file that comes from the game has to be made from your own copy.
  2. Pack the game folder (tools/build_asset_pack.py) and copy it, the title update and the build to sdmc:/switch/dishonored/.
  3. Copy config/dishonored.toml next to the NRO.
  4. Start dishonored.nro with full memory (hold R while starting a game), or install the NSP forwarder, which also unlocks the 4th CPU core and Switch user saves.
sdmc:/switch/dishonored/
  โ”œโ”€โ”€ dishonored.nro                 โ† tools/nx/build_switch.sh
  โ”œโ”€โ”€ dishonored.toml                โ† config/dishonored.toml
  โ”œโ”€โ”€ deko3d_glsl.bin                โ† the game's shaders (from your game)
  โ”œโ”€โ”€ deko3d_shaders.bin (+ .idx)    โ† precompiled shader variants (from your game)
  โ”œโ”€โ”€ game_root.nxpack (+ .nxidx)    โ† your game, as one asset pack
  โ”œโ”€โ”€ update/                        โ† the title update: default.xexp and DishonoredGame/
  โ””โ”€โ”€ dlc/                           โ† (optional) one pack per DLC package

๐Ÿ› ๏ธ Building from source

The step-by-step guide is docs/building.md. The outline:

# 0. Source and the third-party libraries the repository does not carry
git clone https://github.com/VibePorter/Dunwall.git && cd Dunwall
python tools/fetch_thirdparty.py          # SDK libraries (ReXGlue v0.10.0 and its submodules)
python tools/fetch_app_thirdparty.py      # plume / XenosRecomp submodules (Vulkan headers, DXC, zstd, ...)

# 1. Windows: your game into assets/game_root, the title update into assets/update, the code generator,
#    the C++ of the game
powershell -File tools\codegen.ps1 -Flavor optimised

# 2. Windows + WSL: the game's shaders (Xenos -> SPIR-V -> GLSL / DKSH), see docs/building.md "Shaders"

# 3. WSL / Linux: the Switch NRO (devkitA64)
sudo bash tools/nx/setup_wsl.sh
SHADER_CACHE_CPP=... GLSL_DIR=... DKSH_DIR=... bash tools/nx/build_switch.sh

๐ŸŽฎ Controls

The game's Xbox layout maps to the Switch by letter for A and B and by position for X and Y, and the on-screen prompts follow:

Switch Xbox 360 pad Switch Xbox 360 pad
A / B A / B L / R LB / RB
Y (left) X (left) ZL / ZR LT / RT
X (top) Y (top) + / โˆ’ Start / Back

Options โ†’ Controls โ†’ Control Scheme has the game's four schemes and a fifth, Type E (Type A with the A and B actions exchanged). L + R + D-pad up opens the frame-rate overlay when ui_dev_overlays = true.

โ“ FAQ

Where is the download?

There is none, and there will not be one with game content in it. The NRO contains code translated from the game, and the shader files are made from the game's shaders, so you build both from your own copy (docs/building.md).

Does it run on an unmodified Switch?

No. It is homebrew: you need a console running Atmosphรจre. The NSP forwarder also needs sigpatches.

Can I use the PC, PS3 or Definitive Edition files?

No. Dunwall is the Xbox 360 program, and it needs the Xbox 360 disc and its title update. Other versions have different program code and data formats.

Does the DLC work?

Yes, from your own extracted packages (docs/install.md); seven packages were tested, including Dunwall City Trials. The Trials' online leaderboards are removed.

Which language will I get?

English, or Russian when the console is set to Russian. dh_language in dishonored.toml picks any language your disc has: the Switch itself has no Polish, Czech or Hungarian setting (docs/configuration.md).

Switch Lite / OLED / docked?

Any Switch that runs Atmosphรจre should work; it was tested on one console. Handheld renders the scene at 480p and docked at 540p, both with a 720p HUD. Docked play at 540p has not been measured yet.

Should I play in Ryujinx?

Ryujinx is for testing and debugging. It runs the port, but colours can be wrong there (an unimplemented shader instruction) and it needs one extra setting (docs/install.md).

๐Ÿ“œ How it came together

One week from the first line to a build that plays through. The full story: docs/timeline.md.

  • 8 Nov: the Lazarus tree cloned and retargeted: codegen, all 35 Direct3D hooks matched, the PC build at the 3D menu with sound; the first picture bugs fixed; the first Switch NRO.
  • 9 Nov: language choice, DLC, Ryujinx (green screen, the command-ring kickoff), optimised codegen, real occlusion queries, the first console run.
  • 10 Nov: device watch, natives, the CPU occlusion rasterizer, Switch button prompts, the rat-swarm slowdown, save dates, renderer ports from naruto-nx.
  • 11 Nov: the controller screen and Type E, menu clean-ups, prepass skip, primitive culling, the game's own quality and ini settings from the toml.
  • 12 Nov: every shader found ahead of time; Dark Vision; start-up and Press Start stalls; PGO capture.
  • 13 Nov: the "GPU timeout" crash traced to the command ring; the long rainbow-texture hunt; leaderboards.
  • 14 Nov: the release build (PGO + LTO), DLC as asset packs, the sword-hit blur, the frame-rate overlay.

๐Ÿ“š Documentation

Guide
install.md SD card layout, game files, DLC, Ryujinx
building.md Everything from your disc to the NRO
configuration.md dishonored.toml and the settings worth knowing
forwarder.md The HOME-menu NSP: 4th core, user saves
architecture.md How the port works, folder by folder
porting-notes.md What was found in the game and how each problem was solved
d3d-map.md The game's XDK Direct3D functions and device fields
pgo.md Profile-guided builds
debugging.md Logs, crash stacks, RenderDoc, Ryujinx
measuring.md The performance report and how to read it
known-issues.md What does not work yet
timeline.md How the port came together, day by day
lazarus-backports.md Fixes found here that also apply to Lazarus

๐Ÿ™ Credits

Dunwall stands on the work of many people. Licenses and the exact files each project contributed: THIRD_PARTY_NOTICES.md and UPSTREAM_SA2_NOTICES.md.

The ports this one grew from

  • Lazarus (Mass Effect 2): the tree Dunwall started from, and everything it carries from the projects below
  • mgr-nx-deko by tuancapoo: the deko3d build, Renut retargeted to another game, the tooling around it, and the device layout of this XDK
  • sa2-nx by ChanseyIsTheBest: the renderer integration, the application structure and most of the build and analysis scripts
  • banjo-nx by ChanseyIsTheBest (Banjo-Kazooie: Nuts & Bolts): Renut's deko3d tuning, plume's deko3d back end
  • reNut by masterspike52: the Direct3D-level renderer itself
  • masseffect-nx by NebadasSwifty: the Unreal Engine 3 recompilation base, the shader scanner, the CPU enhancement and native-function framework
  • nfsmw-nx by StevensND: the SDK's Horizon (Switch) layer, the profiling and PGO method, the toolchain file and several scripts
  • NFSMW Recompiled by madelrandel-blip: the recompilation project the ports above started from

Ports we learned from and borrowed fixes from

  • naruto-rise-of-a-ninja-nx by malinkin-s: the alpha test as a pipeline constant, the lock-free render queue, repeated clears, the draw fast path, critical-section spinning
  • Mass Effect Cinnamon by jvankooo: this README's layout
  • mk9-nx by Thorhax: performance ideas (heap and deko3d memory tuning)
  • ds2-nx by VasilkovND: XMA wake-up and thread yield fixes in the SDK
  • prototype-switch by fungalspores: the NSP forwarder packer and the codegen preparation step
  • Fruit Ninja NX: the asset pack format
  • sasrt-nx, futari-nx, peggle2-nx and UnleashedRecomp-NX: post-codegen passes, the frame latency probe, the HLSL front end and plume's Switch changes, as they reached us through sa2-nx and banjo-nx

Recompilation and runtime

  • ReXGlue SDK by Tom Clay and contributors: the code generator and runtime
  • Xenia by Ben Vanik and the Xenia contributors, and xenia-canary: the Xbox 360 kernel and GPU knowledge in the SDK
  • libnx (switchbrew) and devkitPro (devkitA64, newlib, the Switch portlibs)
  • FFmpeg: XMA audio decoding; libmspack by Stuart Caie: LZX decompression (the game's packages and its shader code cache)

Graphics and shaders

Libraries

Tools and know-how

  • Forwarder-Mod (nx-hbloader authors): the NSP forwarder's loader
  • Ryujinx: testing without a console; RenderDoc by Baldur Karlsson: frame captures on the PC build and in Ryujinx
  • Atmosphรจre: running homebrew on the console

โš–๏ธ Legal

Dunwall is an unofficial fan project, not affiliated with or endorsed by Arkane Studios, Bethesda Softworks, ZeniMax Media, Microsoft or Nintendo. Dishonored is a trademark of ZeniMax Media Inc. You need your own legally obtained copy of the game. The port's own code is GPL-3.0 (LICENSE); the SDK is BSD-3-Clause, and the third-party parts keep their licenses (THIRD_PARTY_NOTICES.md).

About

Dishonored (Xbox 360) statically recompiled for the Nintendo Switch: native ARM code via ReXGlue and a Direct3D-level deko3d renderer, built from your own game files.

Topics

Resources

Contributing

Stars

8 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages