DoomWorks (fork of GBADoom by doomhack)

Originally a port of prBoom to the GBA, then ported to the Numworks calculator.

Works on both simulator AND REAL DEVICE (only tested on N0110) !

vid.mp4

This project uses GbaWadUtil (by doomhack) from the original GBADoom repo to embed the chosen WAD into the app.

IMPORTANT:

This port is still very much a work in progress / proof of concept !!!

The biggest challenge when porting this was RAM usage, as a Numworks app only has about ~100KB of heap available, which is almost nothing when compared to the original PC recommandations (~4MB) and still less than half of the GBA's specs (~256KB).

The available storage space for a Numworks app was also a major constaint, as on my 25.2.0 Epsilon N0110 device, I could only install an app of about 2.4MB total.

As a result, most WADs (including the basic shareware WAD) either won't fit when installing the app on a regular stock Numworks device, or will take too much memory from the Zone allocator and quit.

RAM / Allocation issues:

Due to issues I have encountered when developping this project, mainly very unreliable memory allocations, the "Zone" allocation that is used to load almost all of the data is a static byte array of either 72KB (stable) or 96KB (unstable). This is temporary and I will change it later on.

To use the bigger memory, add USE_UNSTABLE_ZONE_HEAP_SIZE=1 when making the project for real device. Adding GBADOOM_ENABLE_STACK_REUSE=1 also helps a bit with memory usage.

Unfortunately, this bigger zone heap comes at the cost of the OS (Epsilon) crashing every single time I try to exit the app. I have no idea why this happens, if it only happens on newer OS versions, on my N0110, if is it because of a bug in my app... But, a static byte array of 72KB seems to be the upper limit before the OS becomes unstable upon exiting.

Thanks to the Upsilon bootloader, comming back from this crash is quick and painless, but I have no idea of what happens on models other than N0110, or even with the stock bootloader.

From what I have heard, N0120 models have a lot more RAM to work with. However, as I don't have this model, it is untested, and (for now) do not have a bigger zone allocation.

WAD size issues:

If your WAD is too big to fit on your device, here are some projects that can help you port your favorite WADs :

• Wadptr : A Doom WAD file compressor, almost necessary to port WADs to this project. (by fragglet)
• Miniwad : A (very) minimalist Doom IWAD, letting you use Wadptr to its full potential. (also by fragglet)

Miniwad + Wadptr = A tiny WAD that can (probably) fit into your Numworks.

In case you need even more space, you can use Nwagra (by yaya-cout), a tool letting you use up to 6MB to install apps (for N0110, N0115 and N0120) !

If you just want a small WAD to test out the engine, I recommand Squashware Doom (by fragglet). The silent 1-level version of this fits perfectly and runs at full-speed.

To do:

• Make a better zone allocation system (utilize the extra RAM of the N0120, use dynamic allocations)
• Fork GbaWadUtil to make an easier to use version that strips the music + SFX from the WADs (for now, Numworks calculators don't have speakers, but maybe in the future !)
• Optimize as much as possible !

Controls:

• UP, DOWN, LEFT, RIGHT : D-Pad
• A (Use, Sprint, Menu) : OK
• B (Shoot, Back in menus) : Back
• L (Strafe left) : Shift
• R (Strafe right) : Alpha
• Start (Open menu) : EXE
• Select (Automap) : Toolbox

Changing weapon is done with (Shift / Alpha) + OK.

Cheats (from the original GBADoom):

Chainsaw: L, UP, UP, LEFT, L, SELECT, SELECT, UP
God mode: UP, UP, DOWN, DOWN, LEFT, LEFT, RIGHT, RIGHT
Ammo & Keys: L, LEFT, R, RIGHT, SELECT,UP, SELECT, UP
Ammo: R, R, SELECT,R, SELECT,UP, UP, LEFT
No Clipping: UP, DOWN, LEFT, RIGHT, UP, DOWN, LEFT, RIGHT
Invincibility: A, B, L, R, L, R, SELECT, SELECT
Berserk: B, B, R, UP, A, A, R, B
Invisibility: A, A, SELECT,B, A, SELECT, L, B
Auto-map: L, SELECT,R, B, A, R, L, UP
Lite-Amp Goggles: DOWN,LEFT, R, LEFT, R, L, L, SELECT
Exit Level: LEFT,R, LEFT, L, B, LEFT, RIGHT, A
Enemy Rockets (Goldeneye): A, B, L, R, R, L, B, A
Toggle FPS counter: A, B, L, UP, DOWN, B, LEFT, LEFT

Building and running (current repo workflow):

This repository uses the top-level Makefile to build and run the NumWorks app.
GbaWadUtil (used to embed WADs into the project to save on RAM) is already wired in and is called automatically when embedding a WAD.

Requirements

• make
• A working C/C++ build environment for the NumWorks app toolchain used by numworks_app/
• epsilon.bin (Linux) or epsilon.app (macOS) in the repository root for simulator runs
• npx (for nwlink) if you want to install on a real device

Run on a NumWorks device

Embed the WAD in the app :

make PLATFORM=device run WAD=doom1.wad GBADOOM_ENABLE_STACK_REUSE=1 USE_UNSTABLE_ZONE_HEAP_SIZE=1 USE_EXTERNAL_IWAD=0 -j4

Notes:

• Embedded WAD source files are generated under source/iwad/ automatically.

Run on simulator

Build and run with a WAD:

make PLATFORM=simulator run WAD=doom1.wad -j4

Build only:

make PLATFORM=simulator build WAD=doom1.wad -j4

Clean:

make clean

For anyone reading the code :

WAD format terms used in this repo (non-official terminology)

The terms vanilla and compact are local project terms, not official Doom formats.

• Vanilla WAD: standard Doom map lumps as stored in IWAD / PWAD files (classic vertex / linedef / sidedef / seg layouts, sidedef textures as 8-char names).
• Compact WAD: a WAD processed by GbaWadUtil where map lumps are preconverted for this engine (for example, sidedef textures become texture indices, and map geometry lumps are expanded into runtime-oriented layouts).

Both represent the same map content. Compact format is a preprocessing / packing step for GBADoom and this port.