Today, we're releasing a central building block used throughout Mikage: A package management solution for 3DS tools and homebrew development! conan-3ds takes care of setting up toolchains and development libraries, with support for side-by-side installation, semi-reproducible builds, and safe updates. While this is a tool for fellow homebrew and emulator developers, we figured it's a good opportunity to explain a bit more about its background and the problems it solves for Mikage development.

Background

During development of our 3DS emulator, we naturally work with a lot of 3DS homebrew for testing, so we rely heavily on various tools such as the devkitARM compiler toolchain, the ctrtool info tool, or the 3DS Homebrew Menu. To test hardware features in isolation, example projects such as the devkitPro ones come into play.

On top of the existing 3DS ecosystem of apps and tools, we also wrote a lot of our own utilities: From our automated hardware test suite, a title manager (similar to FBI), a sophisticated GPU debugging tool, and more. This is where the homebrew libraries libctru and citro3d come in, but also widely used C++ libraries like fmt or Catch2.

All of this is to say: There are a lot of components related to 3DS development when creating large, complex software such as Mikage. This opens up some interesting challenges:

• How do you organize all the tools, libraries, and applications on disk? How difficult is it to add new things into the mix?
• How do you ensure applications are built with the correct version of each library? How do you keep track of the required version lists in the first place?
• What do you do if one application requires libctru from 2024 but another won't built unless using the one from 2018?
• If you update a library with a breaking change, how do you avoid having to make changes to all projects that use it at once?
• What about external collaborators? How do you ensure their build setup is consistent with yours?
• How do you avoid all of this management overhead to blow up to a full-time job?

Enter package managers

Fellow software developers will already know the answer: A package manager!

A package manager or package-management system is a collection of software tools that automates the process of installing, upgrading, configuring, and removing computer programs for a computer in a consistent manner

We aren't the first to have this idea: devkitPro offer a similar setup for the 3DS based on pacman. Sadly it's not suited to address the problems listed in the beginning however, so we needed to come up with an alternative. After looking into existing options, we found a promising base for our work: Conan, a package manager for C and C++ developers.

While Pacman operates like a traditional system package manager in the Linux world, Conan is more like Python's pip. It allows applications to declare a list of dependencies with specific version ranges; it supports side-by-side installation of multiple versions of the same library; and it has fantastic integration into different build systems like CMake and Autotools. A perfect match!

What we added on top is a number of different 3DS-specific packages, and Conan extensions to facilitate setup of the compiler toolchain. The result: conan-3ds, a package repository that adds 3DS superpowers to Conan. While we want to focus this post on our motivation for writing this, here's a sneak preview:

This innocent-looking command conan install-3ds 3ds_examples will install the 3DS example projects, including all of the heavy-lifting that you didn't want to think about in the first place: It downloads the devkitARM toolchain and it builds the core dependencies libctru, citro2d, and citro3d. Even ImageMagick is compiled behind the scenes since some examples rely on it. You can also specify specific versions, such as 3ds_examples/20170714 --toolchain devkitarm49 to build older releases that wouldn't build with the latest library versions. Pretty cool, huh?

If you're intrigued, head over to our source repository for a full usage guide. For this post, let's continue with the problems this solves for us!

Within arm's reach: More than 1000 libraries

One main advantage of Conan is the huge number of C and C++ libraries that are already packaged for it: At the time of writing, 1737 packages are available! Need to add string formatting, unit testing, or file decompression to your project? No problem. Even the rather heavyweight Boost libraries work!

This is a massive upgrade compared to the set of previously available packages! Not only does Conan offer more than 30 times as many packages, but the various libraries are more up to date too: The extreme case here is SDL, previously limited to the 13-year-old version 1.2. conan-3ds ships the latest version 2.30, released in May of this year!

Of course, not all of the 1737 packages will be compatible with the 3DS due to platform specifics, but in our experience libraries without strong platform dependencies will just work. Additionally, some packages will work fine if specific platform-specific components are disabled. If you find anything that can easily be fixed, be sure to let us know so we can ship the right package settings by default!

The right match for a lone library version

How hard could it be to build old homebrew apps from 2018? In an ideal world, the libctru and citro3d libraries used by most 3DS homebrew would only ever add new features when releasing new versions. Old homebrew (written against old versions of these base libraries) would continue to compile fine even with newer versions then. In theory, a 3DS application that uses an old citro3d version for 3D graphics should be able to move to a newer core libctru library or a more recent devkitARM toolchain without a problem.

In practice, sadly the 3DS library ecosystem hasn't been so reliable. devkitARM, libctru, and citro3d are heavily intertwined with each other: If you update one of the three, you generally have to update all of them. Conversely if you're trying to build an older homebrew app, you will generally need to match up older versions as well - and with so many years passed, it's not easy to figure out which citro3d versions can be used with the ancient libctru 1.6.0!

conan-3ds addresses this by writing down the exact version ranges needed for libraries and their dependencies. Here's how citro3d declares its libctru dependencies:

def requirements(self):
    if self.version >= '1.7.0':
        self.requires("libctru/[>=2.1.0]")
    elif self.version >= '1.6.1':
        self.requires("libctru/[>=2.0.0 <2.1.0]")
    elif self.version >= '1.3.0':
        self.requires("libctru/[>=1.5.1 <2.0.0]")

Manually finding out the compatible ranges was rather painful, but now that it's done others won't have to repeat the effort. Thanks to this list, we can have confidence that when building old software, we'll always combine the right library versions.

Russian update roulette

It's one thing to take care of old, unmaintained apps, but other issues come up with actively developed software. Imagine you're working on a 3DS app and a new libctru version gets released with a cool new feature: You update the dependency, make some tweaks to your code, and it all works. That is, until you realize there was an API change that actually breaks all the other projects you've been working on. You either have to fix all your projects, or move back to the old libctru version.

Updating dependencies has been an all-or-nothing deal that 3DS homebrew developers are all too familiar with. While pacman made updating libraries easier, it made this problem worse since there is no option for downgrades (once you updated, you were stuck!). Due to the sheer number of projects we touched during Mikage development, this often led to days of unplanned follow-up work. Updates became a big, unpredictable, irreversible risk.

With Conan, we win a powerful feature to combat the problem: Side-by-side installation of multiple versions of the same library. When using multiple projects in parallel, each can use their own copy of libctru and other libraries as needed, allowing you to selectively opt into newer package versions individually. If something doesn't work out, you can just move back to the old version without affecting the other projects.

The best part? Since each homebrew app declares which library versions are required, all of this happens automatically. There's no need to juggle library versions yourself. This is how conan-3ds can build any of the 3DS homebrew examples from 2015 to 2024 against matching old versions of the base libraries without a sweat.

Frozen in time: Semi-reproducible builds

Ideally, app authors would eventually update their dependencies to the latest versions, but in practice that doesn't happen for various reasons. For Mikage, this posed a big problem when we tried debugging old homebrew applications: Building from source seemed impossible because the involved libctru versions were so old. But updating would've effectively required a rewrite of the app, at which point it wouldn't have been useful for debugging the original issue.

Once again, side-by-side installation comes to the rescue: All we need to figure out now is what libctru version an app was written against, and conan-3ds will ensure to combine it with the correct versions of other libraries. We also have version checks on devkitARM itself in place, since particularly ancient libctru versions won't build on more recent compiler versions.

As a stress test (and because we actually needed to test a very specific thing!), we went as far and checked out an ancient version of 3ds_examples from August 2015 along with one of the earliest libctru releases ever. The result? It works!

We refer to this as semi-reproducible builds. This plays on the practice of reproducible builds, which has much stronger bit-by-bit requirements that we don't currently aim for - but it's such a big step forward compared to the status quo that we think it's a suitable analogy.

The road ahead

conan-3ds has been in use in Mikage for longer than you might think. Over the years, we went through several iterations to add features and to make usage easier. We're finally at a point where we think the system is robust enough for others to experiment with. While we've had some help testing, this initial release is still anticipated to have rough edges. Contributions to make it even better than today are hence absolutely welcome!

Did you add more versions for recently released libraries? Did you get a new package from Conan Center working by tweaking a few settings? Did you try out conan-3ds in a homebrew app of yours? Are you interested in using Conan on the Nintendo Switch? We want to hear about your experience! And while we can't turn this side-project into a full-time job, by working together we can smoothen things out for everyone.

As far as Mikage is concerned, the next thing we're pushing to release is our graphics test suite, which makes heavy use of the Conan infrastructure and hence had to wait for this initial code drop. Stay tuned!

Credits

We'd like to thank a number of individuals without whom this undertaking would not have possible (listed in no particular order):

• leseratte, for kindly hosting an archive of prebuilt compiler toolchains and for giving us permission us to have conan-3ds fetch builds directly from their server
• The Conan team, for building a powerful package manager
• The Conan Center maintainers, for providing so many packages out-of-the-box
• The various people who kindly tested the project during development

Furthermore, thanks to our Sponsor-level supporters on Patreon, including:

• Francisco Garcia
• Mr. Madness
• Pretendo Network
• Thidguy

It's time for one of these again! We're seeing a lot of curiosity about what's taking so long to get Mikage out of the door. Let's clear up some dust of mystery that often surrounds emulator development: Many assume there's a straightforward path to bringing games from one platform to another. In practice, it's far from simple.

In this update, we wanted to highlight some of the seemingly mundane tasks that turn out to be anything but trivial to implement in an emulator. Being small in scope but immense in technical depth, these things don't make headlines: Yet they are the cornerstone of creating an emulator that doesn't merely work, but feels right.

We'll get back to big, flashy features and compatibility highlights another day. For a moment, let's put those aside and take a journey through the small, intricate puzzles that make up the backbone of 3DS emulation.

Bootstrapping a Virtual 3DS

Being focused on excellent compatibility right out of the box, Mikage requires a number of different system files that a real 3DS normally works with. For a long time, this involved a convoluted mix of dumping files from a console, decrypting them by hand, and putting them in the correct locations. Doing this from scratch would often take days. Clearly, that wasn't the user experience we intended for production.

During initial development, it wasn't clear which files were needed in the first place, and how the user should get this data in the first place. Making the wrong choices here means users won't be able to get the emulator working, or they would be bothered with adding new files after each update. Now that the emulator core has become sufficiently mature, we've settled for a good approach that has been working well in our experience so far. But implementing this smoother onboarding process would still require a mixture of new emulator features, additional interfaces in the frontend, and a well-integrated setup GUI.

The elephant in the room is decryption support: Virtually all 3DS system files are encrypted with one of 4 increasingly complicated schemes (called Secure1 - Secure4). We've based the cryptographic algorithms themselves on the powerful Crypto++ library to produce more reliable results with less work, however building an understanding of the encryption schemes themselves in face of lacking documentation about them took the most time here.

Another can of worms opens up if you consider decryption keys themselves. What format should the keys be stored in? Which of the over 50 keys do we need? What tools should we provide for dumping them? Luckily, just as we were about to tackle this, developer Steveice10 published a GodMode9 script for exactly this purpose. We tried it out: The dumping process is super easy for anyone with a hacked 3DS, and the dumped data includes everything we need for accurate 3DS emulation.

With crypto keys and decryption algorithms in place, we can load title installation files to set up 3DS system files. This requires implementing support for reading CIA files - a container format that's simple on its own but which wraps a set of other files in different formats. Implementing support for all of them wasn't terribly difficult, but in combination it adds up quickly, especially if you need to flesh out all the edge cases.

Now that we had all these tech-heavy things implemented, all that was left was to bundle it all up in a nice user interface that automates the process. Our new setup wizard will handle each of the steps above for you. If you hadn't read this blog post, you'd never guess how much is happening behind the scenes!

It's worth noting none of this was feasible back when we started work on Citra, which led to a really poor experience: Games wouldn't launch unless dumped with special tools we had to develop from scratch (braindump, later uncart); data from physical consoles (e.g. Miis) couldn't be imported; and many features were outright not available (Amiibos, system apps, ...). With the benefit of hindsight and easy methods for dumping the required keys, designing Mikage as decrypting-by-default yields a much better experience that supports all features you'll ever want to touch without needing to go through annoying extra setup.

Don't panic! Unless it's about Sound...

In the last progress update, we've been showing off our promising initial audio support. It has been moving forward well and has seen general optimizations since, notably a big speed-up to the "warm-up" required for the DSP emulator upon the first launch of a game. But all that aside, we want to highlight one issue in particular here, which is buggy audio emulation.

Imagine this scene: You've been eagerly playing your favorite 3DS game for hours at a time. You've just made it to the door leading to the final boss. You walk through the door in anticipation, and all of a sudden the sound in your earphones becomes... deafening. The audio is painfully loud and distorted beyond recognition. You rush to turn down the volume, but it's too late. With your ears still ringing, you're left wondering what just happened. What's clear though is this glitch was so intense that it ruined the entire experience for you. This almost happened to us during development:

While ideally we'd fix whatever underlying bugs cause this problem in the first place, emulator bugs are just a part of reality: We'll never be able to rule out that after 2 hours of gameplay some sort of subtle integer overflow will cause such issues. As far as we know, virtually all emulators take this as a fact and hence refer to a "Use at your own risk" disclaimer. Potentially causing lasting damage to your ears isn't what we're here for though, so instead we're going the extra mile and adding a layer of protection to detect cases were the audio engine clearly went off course. A "panic mode", so to speak, that immediately lowers all volume to prevent the worst.

Audio processing is a very specific field on its own, so we've been asking for help on Mastodon: Within just a day, plenty of people more knowledgeable in the field than us reached out to help us figure out how to approach this important problem. While we haven't gotten around actually implementing the panic mode itself, we've got it fairly well-mapped out now, making the effort much more predictable. For the time being, this allows us to keep improving the audio emulation itself again. Thanks again to everyone who contributed their knowledge to help us move forward here!

The Art of Displaying Pictures

Emulating the complex 3D graphics pipeline implemented in an embedded GPU like the PICA200 is a tremendous challenge with lots of side tasks. Even ignoring all this complexity, just getting rendered images to the screen ended up being a massive rabbit hole.

Think about it: Ideally emulation should run at roughly 60 FPS to match the refresh rate of a 3DS display, but in practice this isn't always the case. What happens if the monitor is configured for 144 Hz? What if the audio engine lags behind the core emulation, or if there are temporary frame drops? Handling any of these poorly will give you stuttery audio, frame lags, or desynchronized audio/video. While we've yet to solve the issue in a fully satisfying way, we put together a framework for asynchronous presentation that'll fix the most egregious types of problems while allowing for more fine-tuning later. There's a lot of unexplored territory here even among giants like Dolphin. If you're interested in technical details, the redream folks have outlined many useful ideas in far more detail than we could cover here.

In addition to this, we've restructured our Vulkan code behind the scenes to allow sharing rendering code between the emulator core and the frontend. Our goal was to avoid the immersion-breaking effect you have in most other emulators, where opening the GUI to change some emulator setting throws you into a completely different interface. Mikage's experience on the other hand feels much more streamlined thanks to the closer interplay between GUI and emulation. We're probably the first emulator for a modern console to do this, so stay tuned to see what this enables in practice.

Leave it as you found it

Every good thing comes to an end, including a good emulation session. But what does actually happen in an emulator when the user hits the stop button? This isn't a trivial matter if you consider the many emulated components running in parallel, each optimized to handle countless operations per second. But adding exit checks everywhere would add costly overhead for something that happens only once. Sometimes it's the only option, such as when the emulated GPU has already shut down while the Display subsystem was still waiting for new frames to arrive. Finding each of these dependencies was tricky enough on its own.

In the majority of cases, we're instead using C++ exceptions to exit out of hot loops without impacting emulation performance or requiring complex code refactorings. However we must be careful when throwing exceptions in a coroutine or from just-in-time compiled code (... or the latter running in the former), as these environments can't easily propagate exceptions to their parent. It can be done, but there's some fun trickery involved (look up std::exception_ptr if you're interested in technical details!).

With that in place, we've successfully stopped the emulator and are presented with the main user interface again. There's more problems to face once the user decides to play another game. The UI might still carry state about the emulation core that wasn't properly reset. This is relatively easy to fix but can be somewhat time-consuming. Fortunately, we've designed our emulator with a focus on localizing state and use C++'s resource management features extensively, so we don't have the same issues in our emulator core that many other projects often face.

Finally, there's quality-of-life issues to worry about: Emulator bugs are no fun for anyone, but at least we want to display a friendly popup and return to the UI instead of crashing the entire program. After all, there's no such thing as a bug-free emulator, so we'd like to counter an unpleasant surprise with a somewhat more comforting error message to tell the user what happened.

Big features next!

Many more things happened in 2023 that we'll outline in our next update, from new features, major compatibility improvements, and new developer tools. For this one, we wanted to do things a little bit different. It's easy to underestimate how seemingly little things blow up to fundamental problems that require extensive research work. This is a common pattern in emulation, but we're pleased with the solutions we've discovered, even if we can only implement so many of them with our time constraints.

Despite frequent request, we're not eager to release Mikage just for the sake of it. Most other 3DS emulator releases have been met with lukewarm responses. Simply dropping some code on GitHub doesn't automatically foster a community around the project. For us, this underlines how important defining a clear and practical value-add is.

We've been listening closely to community feedback to see where that value-add sits, and we're continuously putting in the effort to get there. Sadly, a small but vocal (and not always well-intentioned) part of our community has taken this extra-care as reason to question the project's purpose in general. As much as we appreciate the eagerness to try out Mikage, this kind of criticism is not constructive and does not help us improve the project. Other conversations have been much more fruitful. From other emulator developers, game programmers, content creators, homebrew people, 3DS enthusiasts, and others: The folks that truly care about the 3DS platform are those who inspire us, motivate us to keep going, and help us refine the gap Mikage is here to fill.

As usual, thanks for reading, and until next time!

Special thanks to the following people, who generously supported Mikage at Sponsor-level on Patreon:

• Francisco Garcia
• Mr. Madness
• Pretendo Network
• Rodrigo Copetti

How time flies! It's been over a year since our project reboot in 2022. We've been sending around occasional updates on Twitter/YouTube/Mastodon to log our progress, but after such a while we wanted to also write a more bigger-picture overview of what we've been up to.

Strap in, because 2022 has seen a wild mix of improvements, from compatibility fixes to major performance uplifts and more: Perhaps most important on the list are the PC port of Mikage and the beginnings of audio emulation. Without further ado, let's get into it!

It's time you listened...

... is what we'd say if there had been anything to listen to. Alas, Mikage has notoriously been silent due to not emulating the 3DS audio hardware. For good reason: It would have to be done eventually, but we knew it was going to take at least a few months of dedicated work.

In July 2022 we finally decided to tackle the issue with a first prototype: An audio backend based on Teakra, a low-level and accuracy-focused approach by former Citra developer wwylele. Lo and behold, in just a few days we turned complete silence to close-to-perfect audio output! The only issue? At 5 frames per second, this accuracy-focused library wasn't practical for real-time gameplay. Nevertheless, it provided us with a crucial reference point for DSP emulation.

The real challenge was to make it fast now, which led us to writing our own LLE DSP emulator. After more than 3 months of dedicated work, we finally got to a state fast enough for fullspeed emulation, all while matching the original Teakra prototype in compatibility. Along the journey, we found a lot of neat performance tricks and developed really cool DSP debugging tools to ensure great emulation accuracy. A whole blog post could be dedicated to this topic alone - which in fact we're planning to do! For now we'll just let the results speak for themselves. We're really glad the hard work paid off!

A sense of feeling at HOME

Mikage has always been about creating an authentic experience that fully preserves the 3DS: Not just the games, but the platform as a whole. Admittedly this vague idea was easy to shrug off as hot air, but in 2022 we could finally show what this authentic experience looks like:

That's right! The 3DS system interface ("HOME Menu") emulated in its full glory. And not just that, you can even run the initial system setup! How cool is it that your first run of Mikage is just like the first boot of a new console?

From Mikage's perspective, there is a lot of little elements that each required individual work. Whether it was launching games, entering the settings app, the software keyboard, mii selector applets, or one of so many other things: All these aspects added up to months of work, which we've collected in an exhaustive overview video. Almost every second, something really cool is happening under the hood. Perhaps most impressively, this shows off Mikage's capability for multi-process emulation: Each of Mii Maker, HOME Menu, Software Keyboard, and the Mii Selector are dedicated programs that run in parallel to each other!

We implemented support for somewhat rarely used 3DS controls as well: The 3D slider, the HOME button, and the Power button. (Yes, that's right: You can turn off your virtual 3DS.)

At the speed of light

As far as an authentic experience goes, one aspect that's so obvious it's rarely spoken out loud is performance. Emulating the HOME Menu with audio is cool and all, but it's nothing like the real console if you can count the frames as they show up on screen. Mikage's GPU emulation code hadn't received much optimization work to this point, being focused much more on getting things rendered correctly than fast. In fact the vast majority of the graphics pipeline was still implemented on the CPU-side, so it was time to move more parts of it to the host GPU.

Our first attack point was the 3DS vertex shader engine: It was an obvious waste of precious CPU time on a task that GPUs were practically made to process faster. But the latter can't easily be used without translating the low-level shader bytecode of the 3DS GPU to common shader languages like GLSL or SPIR-V. The big difficulty here is the somewhat esoteric control flow instructions used by the 3DS, which must be remapped to a convential control flow graph. If you're interested in the technical details, Mees Delzenne has actually written an entire Bachelor thesis on this topic!

For Mikage, we've independently built our own control flow analyzer, from which it's straightforward to build a GLSL/SPIR-V equivalent to the original 3DS shader. Since getting this right is critical, we also created a mighty debugging interface that allows showing the 3DS shader bytecode side-by-side to our reconstructed control-flow-graph and other representations. This has proven very useful, since these shaders can be mind-bogglingly complex!

One further nifty design trick is that we've strongly decoupled the control flow analysis from the actual shader generation. This helps us handle some corner cases of 3DS shaders that can't be emulated on the host GPU: Instead of falling back to an excruciatingly slow CPU interpreter path, we recompile these shaders to an internal bytecode representation that's designed to be fast to process on the CPU. Accurate control flow analysis was crucial for this to work, and thanks to it the worst 3DS shaders now won't have any noticeable impact on emulator performance. All this works without any platform-specific JIT code generation, so it equally benefits all devices (PC and Android)!

One other key optimization is flushless rendering, wherein Mikage avoids writing back rendered images to emulated memory and instead keeps them on the host GPU as long as possible. This saves unnecessary work caused by copying around data, enables the host CPU to process more non-graphics emulation work in parallel to the GPU rendering, and provides an efficient mechanism for handling changes in texture formats (format reinterpretation).

A similar approach is found in what Citra calls texture forwarding, though Mikage features a somewhat more sophisticated system that tracks ownership of each part of emulated memory. This ownership information allows us to omit any unnecessary data copying until the point where the owner changes (e.g. because the emulated game reads directly from a framebuffer). At the same time, it's a useful safety net that double-checks each GPU resource is in the exact state we expect it to be. This paid off quickly by catching important bugs just by investigating each time the tracking system was yelling at us. Going the extra mile to add validation code is an often underestimated yet highly effective approach to emulation!

These two major optimizations combined yielded impressive results: We've been able to run our evergreen testing game The Legend of Zelda: Ocarina of Time 3D consistently at full native frame rate! Further optimization work is ongoing for more complex games, but it's reassuring that we've now reached this milestone for such a popular title.

No one is left in the dark

Fragment lighting was a major blocker for most games to display anything. Some games don't care if you just don't emulate lights, but for most games this will leave all the objects fully black! The reason we didn't implement fragment lighting initially was that it's a highly complex hardware feature with tons of configurable knobs. Our plan is to get this right by writing hardware tests that verify all the different corner cases. But for the time being, just implementing a very minimal subset is enough to at least render some graphics:

Do you guys not have phones?

Anyone who's tried Android development before knows: It's kind of a pain. Iteration times are very slow, debugging is an awful experience, and mobile graphics drivers are royal bugfests. Hence despite Mikage being announced as an Android app, our primary development environment has always been on an internal PC version.

We never planned on releasing this internal PC build: There's hundreds of tasks we have to juggle simultaneously during development, so adding 3 more GPU drivers (AMD/Nvidia/Intel) and a new CPU architecture (x86) into the mix wouldn't have helped us get anything done. Making Mikage ready for PC wouldn't take egregious amounts of time, but other fires were simply more important.

Until one day, on a whimp we gave it a shot after all:

Hi there 😏 pic.twitter.com/xt1fLmOYzt

— Mikage (@MikageEmu) February 25, 2022

Most of the work that went into this was on the Vulkan renderer by going through all validation layer problems that cropped up on AMD/Intel GPUs. We also found a fun memory leak in the Steam Overlay that we added a workaround for. On the CPU side, we've added the excellent dynarmic recompiler as a backend for faster CPU emulation on x86.

We also added controller support - which even works on Android for both wired and bluetooth devices!

Finally, all this is bundled in a new GUI that we're going to show off in its full glory another day. We've chosen a powerful tech stack that is rather unique among emulators, so we'll have some very Mikage-exclusive features to offer. We'll have to ask for your imagination to guess the full potential from the small glimpses we've given so far, but we'll have more to show later :)

The time it takes to build Rome

With the bigger-picture issues like performance and audio support out of the way, we went through a couple of games in our library and made sure they don't just somewhat boot but actually run great in Mikage. Emulating some new minor configuration here, fixing a small but game-breaking bug there. Other than the already mentioned changes to the GPU core and the new audio support, practically all of Mikage's subsystems have received changes: From the ARM CPU emulation core, our kernel system call handling, the service HLE code, YUV video decoding, GPU DMAs, and the filesystem emulation.

Individually each of these changes had little effect overall. It's like the heads of a Hydra, where fixing one emulator bug makes you notice two others. But improving each game bit by bit, letting the work bake and add up over months, we could finally reap the fruit that made games suitable for presentation. We couldn't individually list all the changes we made (there's too many), but we're really proud that we can feature so many well-working games thanks to them!

A look ahead

That's all up to the beginning of 2023. We're really proud of the progress we've made: Countless hours, 400 git commits, and more than 25000 new lines of code. Of course these metrics must be taken with a grain of salt, but they do illustrate the scope of our work really well.

This new phase came with a shift in development philosophy: Our original plan when announcing the project in 2019 was to create a product that can sustain full-time development of a high-quality 3DS emulator. As history showed, that didn't work out. Ever since the reboot, development is driven by what sparks our passion instead: Working on advanced tech and cool emulator features while pursuing technical challenges that others shied away from. All bundled under the umbrella of a great emulator project.

Today Mikage is all about pushing the envelope, and it's really been a breath of fresh air. We can focus on the stuff that excites us without feeling the pressure to please everyone's expectations. Yet, our Patreon page has seen more support than ever. Seeing other people share the same enthusiasm as us is probably the biggest source of motivation there could be.

Thanks so much for your support. We can't wait to share what we've been up to since the start of 2023!

Despite continued progress, the signs were not good for Mikage in 2020: Our Patreon campaign wasn't running too well, various Android-builds of Citra pulled most attention away from us, and then there was that whole pandemic thing (woops). Even our biggest milestone to that point, Mikage running Super Mario 3D Land, couldn't change that people were (understandably) occupied with other matters. And thus we had to admit that continued development could not be funded in a sustainable way.

But forward to 2022 and the tables have turned: Citra's shortcomings have become more present in people's minds, and its various Android builds have not been as actively developed as many hoped. Is it time for another contender after all? Maybe! Canceling all the exciting work items that had been in the pipeline in 2020 never quite felt right anyway.

Which is why I'm happy to announce: Mikage development has resumed! We've silently (or not so silently for the Twitter folks) been picking things up again back in February and made big leaps forward already. Curious what's in store for you? Superboosted performance (allowing 60 FPS gameplay in many titles!) and a new port of the emulator to PC! Here's a sneak preview of the new shader recompiler and other goodies:

Of course we also worked on game compatibility, thus extending the set of compatible titles a lot compared to the limited selection supported previously! Here are just a few of them:

And all that is just the tip of the iceberg. In 2022, Mikage is going full in on preserving the full experience of the 3DS platform. There's so much to talk about, and you're probably asking yourself: What does it all lead up to? Right now we just wanted to say we're alive and kicking again, but we'll have more announcements for you in the future. To stay in the loop make sure to follow our progress on Twitter and YouTube, and spread the word that the 3DS emulation landscape is once again changing big time!

I'm sure some of you are getting ready to object; no sufficient demand for a 3DS emulator? Let me elaborate.

UPDATE: Since the release of this post, development has been picked up again. Expect more news in the future!

How did we get here?

Mikage's mission was simple: A high-quality emulator that "just works" with minimal configuration yet excellent performance, bundled in a pleasant-to-use interface. DraStic but for the 3DS. The core premise to enable all of this: Full-time funding of an experienced professional who previously worked on gold-standard projects such as Dolphin and PPSSPP.

How do you even approach this? One typical way is ads. Another one is microtransactions. And then there's rebundling existing projects (hello MMJ). While (regrettably) widely accepted in the community, it was important to me that Mikage would do without any such shady compromises.

Many criticized Mikage's Patreon approach, but the truth is: Nobody came up with something better. Even ignoring "Just do X"-esque suggestions that clearly didn't consider the numbers involved in the first place, proposals like "Just put it on the Play Store" or "Just use ads" weren't an option. Doing things ethically has been of upmost priority to me, culminating in a 7-digit investment offer I received from a VC company - which I declined.

If Mikage's success depended on breaking my ethical code, it wasn't really a success in my book. If the honest approach wasn't going to work out, then so be it.

And well, that's where we are: It would be a lie to claim the Patreon campaign brought in any significant income that enabled me to work on Mikage any longer than without. Frankly, considering all the marketing overhead it has been a negative investment. I've been working on 3DS emulation pro bono for several years now, and it's been enough.

A turning point

Since 2020, response to the various progress reports and other updates visibly declined, and so it became clear the Patreon route just wasn't going to cut it. Even the biggest milestone to that point, Super Mario 3D Land being functionally playable, brought in virtually no new supporters. Imagine spending a whole month on preparing such a big announcement, and all you get out of it is 100 bucks.

The truth is, everybody wants a great 3DS emulator, but the fewest are willing to contribute towards a mere promise, no matter how convincing the argument. It doesn't help that the Android market is diluted with so many cheap $1 apps (most developed in few weeks) that emulators frankly can't be sold at fair prices. No matter if Mikage had been priced at $15, $50, or $200 - you'll bet either of them would've triggered massive outcries.

Then, [vaguely waves hands around] happened, so Mikage development at least was a nice way to spend the whole social distancing thing. Much to the benefit of Mikage's performance: Optimizing its GPU core significantly yielded a 3x frame rate improvement in e.g. the Zelda games, which are actually fully playable at 60 FPS on PC hardware now. I also got a couple of new games running in a playable state, notably Animal Crossing: New Leaf.

But it's no use.

What's next?

Mikage is a closed chapter for me now. It was one of the most challenging projects I've tackled in my career, and I'm glad about all the lessons it taught me and the technologies I had a chance to pick up along the way. Ultimately though with the commercial prospects written off, the project has served its purpose as far as personal interests go.

Under the hood, Mikage is a genuine masterpiece of software engineering. This goes beyond the "my code is so nice and clean" you'll hear any excited developer say: Where Mikage really shines is the technical foresight about long-term problems and its sophisticated solutions to address them, resulting in a powerful infrastructure to find and debug emulation issues quickly, ultimately making for a better user experience due to fewer game bugs. Imagine your game is broken, but instead of spending weeks of debugging the problem, the emulator essentially tells you were the problem lies right away.

One of my long-term plans for Patreon had been to fund blog posts to actually talk about this infrastructure and other elements of Mikage's code architecture, similar to Dolphin's Progress Reports but on a more technical level. If I kept the Patreon running I could write one of these about every 3 months - let me know if that's something you'd be interested in seeing!

Before I close I do want to apologize for the late statement on this, particularly to my patrons who up to this very point have supported me despite the lack of updates in the last few weeks. I had written several versions of this article but just never quite found the right words. Since I obviously couldn't deliver on my promise, please shoot me a Patreon PM if you'd like your recent pledges refunded. Of course I wish there were a more satisfying outcome here, but that's the least I can do.

Meanwhile, I've moved on to my next journey: Open-source graphics drivers for Linux, the kind of thing I dreamed of doing as a teenager but never imagined would actually happen. I'm incredibly excited about this opportunity to improve the Linux gaming experience for gamers around the world.

It's been a fun ride, emulation community. Thanks for having me.

All the best!

March's big news: Mikage can now run Super Mario 3D Land! Perhaps you've already seen our gameplay video about it; what the video didn't show is just how much sophisticated work went into that title alone, so we figured it's a good time to show you the various steps of iteration from error messages over to garbled rendering to almost perfect game visuals.

In the Beginning, there was Nothing

The first sign of life Super Mario 3D Land showed in Mikage was back in July 2019: A title logo with just-kinda the right colors. One fix in the code that handles RGB565 framebuffer data transfers ("display transfers") later, it's rendering fine:

While this achievement looks simple on the surface, getting a game to draw anything is really the biggest hurdle from a development perspective: After all, how do you debug a game that simply doesn't do anything?

A Title Screen

Of course, a blocker was found quickly, and so the game didn't make it past the initial setup dialogs. There were some obvious and some not-so-obvious features not implemented in Mikage. Eventually though, we succeeded and got this beauty of a title screen:

All the rendering glitches notwithstanding, what's really cool about this picture is what's happening on the top screen behind the game logo: Look closely, it's actually rendering the 3D graphics properly! For instance the geometry of the block in the top right corner is completely fine.

Debugging issues with 3D geometry can be a royal pain, so seeing it just work meant that fixing the rendering for good was within close reach. But there was another roadblock that had to be dealt with first...

Command Processor Fixes

Shortly after entering the title screen, the game would randomly freeze up for no apparent reason. This hadn't always been the case, but at some point it just started doing so.

SM3DL likes to keep the 3DS GPU busy while doing processing on the CPU, and hence schedules a lot of work using command lists that call other command lists. Technically there's just one a primary list that calls smaller, secondary lists, which then return back to the primary one after processing. However,  since there's no equivalent of a call stack, all return offsets are hardcoded in the command lists themselves, and hence it's equivalently just one huge pile of nested command lists calls.

My first command processor implementation struggled with this: While handling secondary command lists using a C++ function call each worked for most games, for SM3DL it leads to such deep recursion that the game eventually ran out of stack space.

Luckily, this was the only thing that caused unpredictable crashes in the game - after fixing my implementation to use a non-recursive algorithm, the game was rock-solid!

Fast Forward

A couple of weeks later, many more fixes had landed, most notably the Render Target Cache Revamp. Some of the graphics fixes were fixed to the point you could recognize the 3D geometry better now:

Super cool! Somehow the geometry is missing colors though, and we somehow lost all environment graphics along the way. A couple of days later I at least managed to make the characters render properly:

Stencil Support

So what's up with the missing environment graphics? Luckily, I stumbled upon a Citra issue from back in the day that shows a screenshot resembling Mikage's output very closely. As the issue points out, the background will be rendered in grey unless a feature called stencil testing is implemented.

Adding support for stencil testing was a bit involved, taking a full day or two. But it is a good example of how one change can make the difference between almost nothing working at all and an essentially playable game:

Meanwhile, on the Bottom Screen

You'd think with the top screen graphics being essentially perfect at this point, the 2D bottom screen graphics would just work easily, but nope. Due to missing support for decoding textures in the RG8 format, the UI elements displayed in a weird overlaid fashion. After extending the texture decoder, the bottom screen renders fine too!

Applet Fixes

We're getting there; the title screen displays just fine, Mario is running across the screen, all the objects show up just fine. But then you press A to select a save file, and argh - the game freezes up for no apparent reason! What's worse, the prototyping branch of Mikage's source code worked just fine.

When your work-in-progress fixes things it wasn't meant to, ironically that often uncovers yet more work to do: What fixed the issue, and why? Is it a proper fix or did I just accidentally change emulation behavior? What's left for a proper solution? Granted, at least it gave me a starting point for debugging the lockups, and eventually I found the culprit: Emulation of Nintendo's applet system.

On the 3DS, the applet system manages the various applications that run on the system (primarily the active game, but also the Home Menu and the browser), and it also manages the transition from one to another (such as when Home Menu launches a title). Game emulation requires only a small subset of this system, but it turns out Mikage's early implementation was a bit too simple. Given this opportunity for sorting things out, I decided to move a full rewrite on the priority list to fully support applets.

... which wasn't such an easy task, it turned out: Info on the applet system is scattered among many different places, each of which only contains a piece of the picture: Between 3dbrew, libctru sources, and Citra, no source does a really good job of conveying the underlying ideas. Piecing it all together into a coherent architecture took a lot of work, but luckily also means that Mikage's implementation is rock-solid now and won't run into major issues anytime soon. Meanwhile, the applet system also paves the way for other exciting work I'll be addressing in a future Progress Report.

Unimplemented features

Of course, that wasn't all - at any point of progress, there's a "boring" period of watching Mikage try to run the game and fail quickly due to the game using a feature not yet implemented in the emulator. This happens a lot: Mikage tries really hard to detect "unexpected" configurations, and immediately errors out instead of "hoping for the best" like many other projects do.

So really, sometimes it's just all about running the game and implementing whatever feature Mikage is complaining about. If you look at the changelogs, many of the fixes listed there are about this. A missing system module interface, a graphics rendering configuration, or an unimplemented CPU instruction.

Granted, tackling these things one by one instead of implementing features all in one go usually doesn't make a difference in 90% of the games I test, but for the other 10% it easily saves days of debugging time. And it gives me confidence that the supported features are "correct enough", meaning there are no glaring issues that could require a major rewrite.

Of course, there's the occasional exception to ensure Mikage keeps visibly progressing, such as for purely cosmetic features like fragment lighting, as required by Super Mario 3D Land.

Success 🎉🎉🎉

Finally, we're done: The game is functionally playable! It's always a thrill to watch the intro cutscene, crossing fingers that the emulator doesn't hit yet another missing feature, and eventually make it through for good. This is the point where it's time to take a break, pat yourself on the back, and just enjoy the game for a moment.

Oh no, more Problems!

Of course, the job is never really done. While the game has been functional since January, not all is perfect:

... and then there's this hilarious problem with the ground geometry ...

... and let's just not talk about this one ...

Cliffhanger

Of course, I knew releasing a video with these glaring issues wouldn't be particularly impressive. Hence stay tuned for the next Progress Report to see how I fixed them ;)

I hope you enjoyed this little digression from the usual program. As usual, thanks for your support and stay safe!

Yes! You're reading that right: Super Mario 3D Land is now (functionally) playable on Android via Mikage :)

I'll publish a write-up of this exciting development progress next week, and I'll also push the next alpha release soon so you can try the game out for yourself.

Until then, stay safe!

It's been a while since I announced new titles that now work in Mikage, so I figured I'd make up for that by announcing a big one ;)

Super Mario 3D Land is now functionally playable! Yes, you read that right - it gets past the title screen, plays back the entire intro sequence, and you can actually play the game.

Suffice to say I'm extremely happy with this result. It was actually back in January that I realized how close the game was to getting ingame (bearing major artifacts), but then things improved bit by bit until eventually the game rendered almost perfectly!

Other than two small (but very important) bug fixes, all changes required to get this game into this state were about implementing new things (most notably stencil testing, but lots of minor stuff too). This is a good thing: Rather than spending my time fixing code I've already written, Mikage's solid foundation allows us to add more comprehensive emulation and progress towards broader game compatibility.

I'll prepare a video of Super Mario 3D Land in action over the weekend, but I figured I'd share the news here first :)

We have another update in store, this time with major optimization work going on and of course the obligatory compatibility improvements. Let's dive right in!

AArch64 JIT for super-fast CPU emulation

Every emulator project has to start somewhere, and in terms of CPU emulation that's usually an interpreter core: Easy to get early results from, with little complexity, and adaptable when surprising hardware behavior is discovered. The big weakness of interpreters is performance: Emulating every 3DS CPU instruction with a C++ function call flat out isn't going to run at great speeds.

A more performant solution is called Just-In-Time binary translation (commonly abbreviated to JIT in emulation circles), where you disassemble and recompile functions executed by an emulated game to equivalent binary code that can be executed on the target device (i.e. your phone). This method of CPU emulation can provide massive speedups (up to 10x) depending on the situation, so logically I assigned high priority to the JIT on Mikage's roadmap.

That said, writing a JIT is a complex undertaking, certainly not something you can pull off in a couple of days and immediately collect fruits of labor from. It takes dedicated experimentation and research over several weeks, and then there are still several components that need to be written independently. I announced my early tinkering with JITting back when the project was announced, having been working secretly on it until it was ready for a general showcase.

And finally, it's here: The first JIT-enabled Mikage release shipped in February! The translation process doesn't cover the entire ARM instruction set yet, so it will be another couple of weeks until all comercial games benefit from the JIT. But the potential is very visible in yeti3DS and Retro City Rampage DX - the former getting a mind-blowing 650% framerate improvement! See for yourself:

Of course, this JIT is just the basis to build on, and it will be refined and extended over the coming weeks to make sure the speedups translate to all other titles as well.

If you're curious about the inner workings of this new JIT, I shared a more technical overview in Development Update 9.

Interpreter speedups

In preparing the JIT, I had to rework the interpreter's instruction dispatcher so it could be used as a fallback by the JIT for instructions it doesn't cover yet. The new dispatcher replaces some ugly logic with a much neater approach that also happens to improve performance a little.

If you've seen my professional work, you'll know I'm a big proponent of applying C++ metaprogramming when a good chance comes about. In this case, going through the cumbersome process of decoding ARM instructions manually was very error-prone and led to unnecessary branching within the code that would lead to slow interpretation. There is now a simple table that describes the various ARM opcodes, and we have the C++ compiler conveniently generate a lookup table from that, which can be used to map a CPU instruction's binary encoding to the interpreter's instruction handler. Very convenient and fast :)

New challenger approaching: Steel Diver: Sub Wars

Steel Diver: Sub Wars now reaches the title screen! Other than many small fixes, I uncovered two major bugs:

• When emulating IPC requests, Mikage considered it an error when a game provided a zero-sized buffer. After all, if you're asking the system to do work, why would you request no data to be returned? Well, my educated guess is that it was just the easier thing to do in the game's source code, so the programmers just opted for leaving these seemingly pointless requests in. It took some creativity to find a clean way of supporting zero-sized buffers, but these games now won't error out anymore.
• During startup, Steel Diver requests a memory transfer ("DMA") from a seemingly unknown memory address. It turns out this was a bug in the GSP emulation, where DMAs were assumed to refer to memory with process-agnostic virtual-to-physical address mapping. By referring to the game's own memory space instead, the input memory address is recognized properly and hence the DMA runs through just fine now. Ironically, Citra got this wrong too: They implemented what was easiest (and correct, in the common case) and eventually concluded it was incorrect behavior, leaving a note in the source code suggesting to move to the wrong behavior in the future.

As you can guess, these issues by no means only affected Steel Diver. I'll have more news in the next Progress Report about other titles :)

Better graphics in Zelda OoT3D & others

The Legend of Zelda: Ocarina of Time 3D and Nano Assault EX got a nice update to their visuals: You might have noticed various objects to look a bit dull or boring compared to how they look on hardware. And indeed, this was because Mikage didn't implement a feature called texture combiner scalers!

Adding support for this feature luckily wasn't too difficult and the games now look fantastic. See for yourself:

What's next?

There's a big stream of reveals coming up, especially in terms of compatibility! Various new titles are just around the corner of being functionally playable in the next version. I'm also super excited to finally announce a feature that actually has been part of Mikage ever since its early days, but for which there had never been a good chance to show it off... until very recently ;)

Meanwhile, the optimization work continues, of course. More refinements to the JIT are in progress, and there's a lot of optimizations in the pipeline for the Vulkan renderer.

That's it for now though - stay tuned for next months! Be safe, and remember to wash your hands and stay inside ✌️

Compatibility improvements and fixed rendering glitches aside: What good is an emulator if everything is a slideshow? I promised to tackle the framerate issues a while ago, and the first major step towards doing so has now been completed: An AArch64 JIT.

This may come as a surprise, but I actually started focusing to work on this major feature back in December already, and quietly implemented feature by feature. A proper JIT requires a lot of infrastructure until it starts giving the desired speed benefits, and I didn't want to weaken the hype by announcing it in a preliminary state. Now that the pieces have fallen together, let's see what the JIT has in store for us!

IR Generator

At a whopping 2000 lines of code, this is the heart of the JIT: It turns ARM assembly code into an Intermediate Representation (IR) which is later compiled down to AArch64 code (or x86 on the internal development version). Mikage uses LLVM IR for this purpose, since that allows us to leverage all existing, industry-proven infrastructure around the LLVM project.

We are off to a good start: The instructions already covered by translation are the simple arithmetic ones (mov, add, ...), memory accesses (ldr, pop, ...), branches (bl, bx, ...), and some floating point operations (vneg, vmul, ...).

On top of that, there is a Thumb layer that takes care of converting Thumb instruction into something the IR generator understands. That saves us from having to translate two instruction sets at basically no cost!

There are many ARM instructions not yet supported by this IR generator, but luckily that need not prevent us from achieving good results.

Inline Interpreter Fallback

One critical metric for good JIT performance is the length of blocks, i.e. groups of instructions that are translated and later executed in one go. If your blocks are very short (few instructions), the overhead of translation and of the generated function prologues/epilogues will be larger than if you'd run the interpreter.

Considering the sparse set of instructions translated currently, this is a real problem, and I didn't want to delay the release of the JIT just because it'd run too slow without implementing the entire ARM instruction set.

There is a good solution though: Whenever the JIT hits an unknown instruction, a fallback to the interpreter core is emitted right inside the block. This allows translation to just continue afterwards without costly context switches!

A prerequisite for this approach is that the interpreter fallback may never do any control flow. Imagine the instruction branched to another address, yet what follows in the emitted block still refers to the old point of execution! So the compromise was to implement all control flow instructions in the JIT before this approach could be implemented, including lesser obvious ones such as `mov pc, r1` or `add pc, 40`. Luckily, that work has been done now and the interpreter fallback works superbly.

Analysis Prepass

Even with large JIT blocks, there is a big problem: Compilation latency. Each block is compiled individually, which for most games could lead to thousands of separate JIT invocations during bootup alone!

To avoid this issue, Mikage performs control flow analysis before invoking the JIT. It goes through all ARM instructions in the block it's about to translate, gathers a list of all branches to other blocks, and repeats the process for those blocks too. This gives the JIT gets a very clear picture about how blocks are connected and hence it can compile them all in one go. This is a massive improvement - instead of way too many separate translation processes, you'll just get a single one that compiles thousands of blocks at once.

This approach also has a few nice side benefits: For one, jumps from one block to another (such as loops, conditionals, etc) can now be translated into plain branches in the generated assembly code, where previously it needed to be an expensive function call. Furthermore, the backend can now perform control-flow optimizations such as inlining. The result of these two is the same: Much shorter and faster output assembly, and hence better performance!

Background compilation

Alas, while grouping blocks reduced total latency. It worsed perceived latency a lot: After all, compiling 8000 blocks at once takes a while! You wouldn't want to wait half a minute to even wait for the loading logo of your game. Something had to be done about this.

Luckily, Mikage already has a CPU engine that does not suffer from latency issues at all: The interpreter. Of course though, the whole reason I'm working on the JIT is that the interpreter is too slow. But maybe we can have the best of two worlds?

Indeed we can! When execution hits an uncompiled block, Mikage won't immediately translate it. Instead, it queues the block start address for translation on a background thread. It doesn't really care how long that thread needs to compile the block: It temporarily uses the interpreter until execution hits a block that has already been compiled. This allows execution to continue even though the JIT is still busy.

During bootup, this means you'll notice things running significantly slower, but it's much better than the complete standstill you'd have seen before. More importantly during gameplay, you can barely notice any compilation latency at all anymore.

Conditional Flags Management

The ARM instruction set supports conditionally executing functions based on the results of a previous operation. For instance, an error handling function might be conditionally called depending on whether an error code compares equal to 0 or not. Emulating this naively implied having to decode and re-encode the conditional execution flags ("NZCV") after every instruction that potentially touched them.

Suffice to say, this caused the generated assembly code to blow up quite a bit. Instead, each of the flags is managed by a dedicated IR variable now, all of which are initialized on function entry and encoded back to the NZCV flags on function exit.

Constant Read Optimization

Memory accesses are complicated: Due to virtual memory, you can't just translate data writes in the emulated CPU to writes in the generated assembly code. Implementing the entire virtual address translation logic in assembly would be very laborious, so instead Mikage's JIT replaces memory accesses with calls to a C++ function that deals with them.

That can be very slow though; each call to C++ is a costly context switch, where the host CPU state has to be saved to memory and restored after, since the JIT can't know which registers the C++ function might modify. This is doubly concerning considering that any access to constants requires a read from memory. To reduce the cost of this effect, ReadMemory32 calls are optimized in a post-processing phase: If the read address is known to be in read-only memory, the JIT can conveniently bake the value at that address right into the generated IR instead of emitting a full-blown ReadMemory32 function call.

First Results

The video above shows before/after footage for yeti3DS, my primary benchmark for the JIT work. This may be somewhat counter-intuitive: Why optimize simple homebrew applications when proper games struggle most? The reason is that yeti3DS specifically is a very CPU-intense application since its 3D graphics are rendered without the GPU. This means CPU-side speedups translate almost equivalently into speedups in the entire emulation, without the GPU slowing us down.

And it shows: yeti3DS used to be a slideshow, running at few frames per second. One 650% improvement later we are at 50-60!

Official games of course also see a speedup, but are quickly limited by GPU emulation now. Still, Retro City Rampage DX sees a significant framerate improvement of 60%.

Future Prospects

Hopefully this writeup gives you a good overview of the problems I've faced while working on the JIT. With the ground work we're in a good position for further speedups, which we'll see once the IR generator covers the ARM instruction set more comprehensively (especially in terms of floating point math).

Some elements, such as the background compilation, also give Mikage an edge over Citra: If you ever tried out any of the unofficial Citra builds with a JIT, you'll notice very heavy microstuttering. Background compilation eliminates that issue from the picture.

For the next month, I'm working on optimizing some of the bottlenecks in GPU emulation such as the texture cache. Stay tuned!

Hello again, it's been a while! I'm sure many of you wondered what we've been up to since there's been somewhat of a radio silence around Mikage. Suffice to say the project is alive and kicking, with hundreds of hours spent on development since last progress report, and clearly too few on marketing :)

So what have we been up to? We achieved lots of user-visible progress such as fixed rendering issues and new functional games, and more importantly we sorted out a number of critical technical challenges under the hood.

New games!

Let's get to the gist most of you will care about: What content did we manage to get running in Mikage? Among various titles reaching title screens or at least booting up, two games - Nano Assault EX and Cave Story 3D - make it past the openings and are functionally playable now! We've released gameplay videos for both of these, so make sure to give them a watch if you haven't already.

There wasn't any one individual, big fix that made this possible, but it's rather various big groundwork items being finished (such as the Render Target Cache revamp mentioned below) plus the accumulation of many small iterations and bug fixes, such as for instance:

• Implementing more configurations of the GPU's pixel pipeline, e.g. alpha blend modes or depth testing functions
• Implementing texture combiner features such as the texture combiner buffer
• Supporting more FS features such as reading the game icon via the SelfNCCH archive or copying file handles ("link files")
• Adding 3DS configuration blocks for parental controls and EULA version

In fact, bringing up new games is straightforward in Mikage: Start the game, check the logs to see what functionality is used, and implement what's not yet emulated. The typical hour-long debugging sessions other emulator developers go through is largely unnecessary, partly because the 3DS platform is rather well understood by now, but I also like to attribute this success to good design in Mikage's emulation core: Instead of blindly accepting "weird" states of emulation, it'll loudly complain as soon as anything smells fishy. While sometimes a bit tedious, this prevents small inaccuracies from trickling through layers over layers of abstraction and causing unretraceable butterfly effects, and instead makes nailing down critical issues straightforward. This approach easily saved tons of hours of debugging work and allows us to focus on improving the emulator instead of fixing old, unresolved bugs!

There has been progress on other titles too, notably Super Mario 3D Land. We're now reaching the title screen with the characters rendering just fine. The landscape still has some issues that I need to look at - my suspicion is that missing stencil support is the culprit. In fact, back in August I did have the landscape geometry rendered albeit in a corrupted framebuffer, so it's just a matter of getting it presented to the screen properly!

Another title that's showing signs of life is Bravely Default: We can boot the game and even start it; unfortunately playing the game won't be much fun quite yet since the top screen just stays black. I haven't had time to dig into this, so it will be interesting to figure out what exactly is going on here.

Finally, it's not always about the latest and shiny games, but there's also many homebrew applications Mikage needs to support. Most 3ds-examples are now supported, and even portal3ds makes it to the title screen:

Bug fixes

It's not always about getting new games to boot - often, fixing smaller bugs in games that already work uncovers subtle issues that would've been harder to debug in a game that outright refuses to render anything at all.

One issue that always bugged me out was the missing flame effect around the title screen logo of The Legend of Zelda: Ocarina of Time 3D. Thanks to Mikage's software renderer I knew the issue was with the Vulkan renderer. But it took me a rather lengthy debugging session to finally figure out the problem: The pixel shaders generated for the AddThenMultiply texture combiner operation were wrong! Instead of (min(255, (rgb_in1 + rgb_in2)) * rgb_in3, it said min(255, (rgb_in1 + rgb_in2) * rgb_in3) - note the misplaced parenthesis! The unmodified sum of rgb_in1 and rgb_in2 entered the multiplication instead of having it clamped first! With that issue fixed, I finally got to see the flame effect work just fine and, as a pleasant surprise, it also made the intro animation in Nano Assault EX show up!

Another fun glitch are the intro logos in Cubic Ninja, which are supposed to fade in smoothly upon starting the game, but just instantly popped up when ran in Mikage. This issue affected even the software renderer, making it even more puzzling what was going on. On the other hand, reproducing the issue in the software renderer allowed me to very closely inspect every step of the rendering pipeline. Things just didn't add up: The emulator rendered things just like it was supposed to! Eventually, this was one of the few cases where comparing against Citra actually helped - running both Mikage's and Citra's software renderer in lockstep for individual pixels allowed me to catch unexpected differences in the logo rendering. Eventually, I found the root cause: The GPU register definitions for two alpha blending where off!

RenderTargetCache revamp

Mikage's Render Target Cache is responsible for matching raw framebuffer configurations to render targets used on the phone GPU. Ideally such a system avoids unnecessary round trips from GPU memory to emulated 3DS RAM, and this sort of caching is critical for getting any performance benefits out of hardware (Vulkan) rendering over software. Meanwhile, getting it right is essential to bug-free emulation without rendering glitches. In fact, Citra's early hardware renderer was plagued by caching issues like this, so it was important to me to address this early on.

Thanks to the work I put into the testing framework (see below), it wasn’t too stressful to come up with a reliable rewrite of this component. As a result, not only is the RenderTargetCache itself much more readable, but I was also able to resolve various compatibility issues: Nano Assault picked up an old render target previously, causing it to crash shortly after due to an invalid viewport setup. The both_screens homebrew example now renders the bottom screen as you’d expect:

Finally, the RenderTargetCache revamp removes the need for many annoying workarounds that harmed performance. Of course, the bottleneck is still largely CPU emulation, so don't expect this to do miracles to your frame rate yet. But at least the GPU now won’t hold us back anymore either.

Testing an emulator

Testing emulators is particularly interesting: On the one hand you want to verify your emulator is doing what it's supposed to do, and you want to ensure already verified behavior doesn't unintentionally break in a future change. This aspect of testing is absolutely critical to ensure emulator development keeps moving forward. Without tests, you'll run into a state where any fix you make to get a game running breaks 5 others because things become unpredictable. On the other hand, you also want a research platform to run against physical 3DS consoles to make sure your understanding of the emulated system is correct in the first place. Mikage's testing framework serves both of these requirements.

Unfortunately there's not much to show of the tests themselves - after all, for a correct emulator the whole point of tests is to just run through silently and pass. But if they do fail, such as when you're researching how a particular hardware feature works, this is the kind of output you get:

As you'll imagine, this sort of information is very helpful during development: Quickly pinning down what line of the test sources caused an issue, including information such as C++ exception information, allows for quick iteration cycles and makes writing tests a smooth experience.

One case I applied this powerful framework on is Mikage's OpenLinkFile implementation: Link files are used to open a second "view" onto an already opened file on the 3DS. This is a feature many games - notably Bravely Default and Nano Assault - use internally, and they won't let you get past boot unless you implement it. But doing so posed a bit of a challenge: I didn’t know what things games were allowed to do with them specifically, and so supporting link files properly could’ve required either a minor adjustment or a costly rewrite. And I didn't want to just support the bare minimum required to boot games just to find another game that'll have me rewrite it all a month later!

And this is where the testing framework came to the rescue: The first thing I found was that link files only really are supported in the SelfNCCH archive (as opposed to e.g. save data or SD card contents), hence massively reducing the scope of things to test. SelfNCCH can easily be accessed from 3DS homebrew, so writing tests was straightforward in the case, and in the process I also ported the existing FS tests (which previously only checked save file archives) to cover SelfNCCH, too.

Long story short: Having tested link files on actual hardware, I can now confidently say that a simple tweak is enough to support them properly. Basing this on a scientific research process feels much better than taking a leap of faith and crossing fingers nothing will break because of it!

A new homebrew toolchain

3DS homebrew is a valuable tool for emulator development - not only is it really easy these days to write your own 3DS application to test your emulator with, but there already is a plethora of demos to check your emulator works with! In particular, the 3ds-examples project covers a lot of the elementary 3DS GPU features, from basic 3D rendering to fragment lighting, up to procedural textures. Unfortunately though, not all is perfect.

Let me tell you the story of when I tried to build the 3ds-examples project for testing:

• I went to GitHub, downloaded the sources, and typed make to build the library. It doesn't work: citro3d.h not found is what it says
• Turns out it now depends on the citro3d library: So I go to GitHub again, download citro3d, type in make to build that library, and luckily that works out fine
• Going back to 3ds-examples though, the make command still fails, now with errors related to citro3d: It turns out the project was written against an old version of citro3d, incompatible with the newer version I had just downloaded
• There's no mention about what version exactly was used, so I go back and make an educated guess; after downloading and attempting to compile the old version, well... it turns out the old citro3d version doesn't build with the latest 3DS toolchain

The bottom line is: To build 3ds-examples, you need to downgrade all your base libraries to versions nobody ever wrote down. It was at that point that I realized this system is too fragile to be used for Mikage!

Unfortunately, package management for C++ in general is rather meager: Every library may use its own build system, and there's no standardized way of declaring dependencies in a project. Luckily things are changing, and with Conan there is now a feasible candidate for a C++ package manager. It's already in use by Mikage to manage dependencies such as SDL and boost across Linux and Android with ease. So back in October I started an experiment: What if we could manage 3DS libraries using Conan?

Suffice to say it wasn't quite so easy; figuring out a good way to bootstrap the toolchain itself and bundle it as a Conan package wasn't quite as straightforward as I had hoped, because gcc and binutils expect to be installed in a well-defined, global location, whereas Conan uses its own paths in the user's home folder based on hashes of the package configuration. Still though, eventually I managed to get something functional, and built on top of that. Among others, there's now packages for:

• a cross-compiling gcc targeting the 3DS's ARM11 processor
• ctrulib, the base library for 3DS homebrew
• citro2d/citro3d to render using the GPU
• picasso, tex3ds, and other tools often used to build 3DS homebrew
• ctrtool, a program to inspect 3DS application images (CCI, CXI, etc)
• 3ds-examples, a suite of demo applications for 3DS functionality

For now this system is merely sitting on my hard disk for use in Mikage's internal 3DS tools, but these package recipes can be useful for 3DS homebrew development too; if there's sufficient community interest I'm definitely up for publishing those Conan packages in the future.

Open-sourcing Mikage's serialization framework

Serialization is the task of turning blocks of binary data into meaningful objects such as C++ structures, and vice-versa. This comes up when reading 3DS-specific file formats (such as CXI or CIA), when decoding parameters for high-level emulation of services, when interpreting command buffers for GPU emulation, and generally whenever the emulator core needs to access data structures contained in the emulated 3DS's memory.

Considering how common this task is, I grew tired of reinventing the wheel for every component it came up in. To automate all of this redundant work, I created blobify as part of Mikage. blobify uses advanced C++ techniques to automate serialization tasks as much as possible, and it has proven to be a very effective tool at that. To allow others to benefit from this, I decided to spend a couple of weeks on extracting blobify from Mikage's source code and turning it into a proper library that can be used in other projects, too.

I released the fruits of this work earlier today on GitHub. This reiterates my dedication to open-source development, and is a first (if small) step towards open-sourcing Mikage as a whole.

Stickers and 36c3

Hackers and security researchers gathered at the 36th Chaos Communication Congress (or 36c3 for short) at the end of December - and it's become somewhat of a tradition for emulator developers in Europe to meet up there too! It's been a blast to meet old and new friends alike, and I can't wait to go to 37c3 in 2020. If you haven't seen it in action yet, I definitely recommend trying it out! Plus, see what cool merch you're missing out on ;)

What's next?

Despite all this progress, there's lots of work left to be done! As usual, I'm planning on extending the set of supported games: With the bulk of the essential 3DS features emulated by now, bringing up new games has become a task of a few days rather than a few weeks, so compatibility will improve a lot over the next few months.

With that base line, improving performance has become an increasingly important target. Mikage's internal Linux build is already running games at 60 FPS, but performance on Android is far from playable at the moment. Luckily, my experiments with a Just-in-Time recompiling CPU emulator have concluded, and I'm planning on boosting GPU performance using optimizations to the texture cache and the shader processor (akin to what Citra is doing but with some special sauce).

And with that, stay tuned for future updates!

Until next time!

It's this time of the month again! If you haven't seen yet, I uploaded a new gameplay video showing off Cave Story 3D earlier this month. But of course I didn't stop there, and in fact this month we got another title working in Mikage.

Steel Diver: Sub Wars enters its title screen

Steel Diver: Sub Wars now reaches the title screen! Other than many small fixes, I uncovered two major bugs:

• When emulating IPC requests, Mikage considered it an error when a game provided a zero-sized buffer. After all, if you're asking the system to do work, why would you request no data to be returned? Well, it turns out game programmers sometimes just don't mind, so that's precisely what they did. It took some creativity to find a clean way of supporting zero-sized buffers, but these games now won't error out anymore.
• During startup, Steel Diver requests a memory transfer ("DMA") from a seemingly unknown memory address. It turns out this was a bug in the GSP emulation, where DMAs were assumed to refer to memory with process-agnostic virtual-to-physical address mapping. By referring to the game's own memory space instead, the input memory address is recognized properly and hence the DMA runs through just fine now. Ironically, Citra got this wrong too: They implemented what was easiest and eventually concluded it was incorrect behavior, leaving a note in the source code suggesting to move to the wrong behavior in the future.

As you can guess, these issues by no means only affected Steel Diver. I'll have more news next month about other titles :)

GPU texture combiner scalers

The Legend of Zelda: Ocarina of Time 3D and Nano Assault EX got a nice update to their visuals: You might have noticed various objects to look a bit dull or boring compared to how they look on hardware. And indeed, this was because Mikage didn't implement a feature called texture combiner scalers!

Adding support for this feature luckily wasn't too difficult and the games now look fantastic. See for yourself:

New CPU Interpreter dispatcher

This is actually the preparation for another big feature, but implementing it went hand-in-hand with replacing some ugly logic with a much neater approach that also happens to improve performance a little.

C++ metaprogramming comes in handy again: Instead of going through the cumbersome process of decoding ARM instructions manually, there is now a simple table that describes the various ARM opcodes, and we have the C++ compiler conveniently generate a lookup table from that:

A quick benchmark on the CPU-heavy yeti3DS application yielded a 19% framerate improvement, which is a nice side effect for a change that wasn't even geared towards optimization!

USAT emulation fix

While working on the new dispatcher, I stumbled upon the cause of a long-standing bug that had been haunting me for a while: The incorrect rendering of the walls in yeti3DS!

It turns out the interpreter decoded the argument to the USAT instruction incorrectly. It's one of those things that's super easy to overlook when glancing over the source code - until you double-check against the ARM manuals and realize the decoding logic has been wrong all along.

Looking forward

With all the fixes recently and so many new games being close to fully functional, it's finally time to make Mikage produce more than just a beautiful slide-show. I'll been working on this behind the scenes for a while now, and you'll see the first fruits of that work next month.

Stay tuned ;)

Hey folks!

First of all - happy new year! Mikage has kicked off 2020 with some really cool progress, but more on that later this month ;)

As for today, I figured it's time for another video, and I already teased Cave Story 3D back in Development Update 7 so why not? Here you can see me playing the game (well, trying to) to show off what's now possible with December's emulation fixes.

There'll be more things to come in January - notably a new alpha release and, of course, another Development Update. Until then!

Another month, another update - let's see what December had in it for us :)

New Games!

The big news comes first: Mikage runs another game, Cave Story 3D! Turns out after a couple of small additions and the fixes mentioned later, this game pretty much just worked out of the box. And for what it's worth, both the original Cave Story and Cave Story 3D are supported ;)

I've also given an old homebrew release a shot, smea's portal3DS. A couple of GPU features are missing to make it playable, but the menu screen is rendering mostly fine so far!

Fixing all the things: Onto Perfect Graphics!

It's not always about getting new games to boot - often, fixing smaller bugs in games that already work uncovers subtle issues that would've been harder to debug in a game that outright refuses to render anything at all.

Cubic Ninja is a good example of this: It was one of the first games supported in Mikage back in July 2019, but its opening screen would instantly pop up rather than smoothly fading in. I decided to look into the issue, and found this:

Turns out I mixed up the GPU register definition for some of the alpha blend modes! Having fixed that issue, Cubic Ninja's intro now plays just fine:

A similarly subtle, but ultimately really simple issue to fix was the intro logo rendering in Nano Assault EX: I had misplaced some parentheses in the shader generated when rendering this effect, leading the computation of the AddThenMultiply texture combiner operation to return the wrong result. Voila, we finally know who created the game!

Meanwhile, remember the flame effect on the title screen of The Legend of Zelda OoT 3D that was working just fine in the software renderer? The Nano Assault fix made this flame effect work in Vulkan too! A great example of how fixing a bug in one game can resolve seemingly unrelated issues in other games in one go.

Happy Holidays!

That's it, folks - plenty of good progress! I'm planning on having the next alpha release in January, but I'll upload another gameplay video soon to make the waiting a bit easier on you. Until then, enjoy your holidays and have a great start into the new year! :)

This post was originally posted on 11 December 2019 for patrons, and released publicly on 16 January 2020.

As a followup to yesterday's Development Update, I recorded some gameplay footage to show off in more detail how great Nano Assault already runs in Mikage.

Like I mentioned before, I'm super happy to have a game with such complex graphics work in the emulator already. Hope you enjoy :)