Doom-MCX port of popular Doom game to run on NXP MCX microcontrollers

A port of prBoom to NXP MCXN MCU running Zephyr RTOS

Table of Contents

1. Software
2. Hardware
3. Setup
4. Results
5. FAQs
6. Support
7. Release Notes
8. License

1. Software

• Zephyr 4.4.2
• Zephyr SDK version 1.0.1

2. Hardware

FRDM Development Board for MCX N947	LCD-PAR-S035 480x320 IPS LCD

Optional Joystick shield on FRDM-MCXN947 Arduino Header

3. Setup

Before getting started, make sure you have a proper Zephyr development environment. Follow the official Zephyr Getting Started Guide.

Note

DOOM-MCX has been tested on Zephyr SDK version 1.0.1. When installing the sdk it's recommended to specify the version using west sdk install --version 1.0.1

Initialization

The first step is to initialize the DOOM-MCX Zephyr workspace folder (doom-mcx-workspace) where doom-mcx and all Zephyr modules will be cloned. Run the following command:

# initialize  for the example-application (main branch)
west init -m https://github.com/nxphovergames/doom-mcx --mr main doom-mcx-workspace
# update Zephyr modules
cd doom-mcx-workspace
west update

The game data

The game data lives in wad/doom1.wad. It contains the game data of the Doom shareware episode converted with GbaWadUtil into the layout this engine reads (levels in the engine's native structures, sound lumps omitted), so a stock doom1.wad cannot be used directly; other IWADs (registered Doom, Doom II, Final Doom) can be converted with the same tool. It is not linked into the firmware; it is a separate binary that is flashed to the external QSPI flash at 0x90000000 and read in place from there. The game data is copyright id Software; see wad/doom-wad-shareware-license.txt and section 8.

Building

To build the application, run the following command:

cd doom-mcx
west build -p always -b frdm_mcxn947/mcxn947/cpu0

Besides the application, the build produces build/zephyr/doom1.hex, the IWAD converted to an Intel hex at the external flash address.

Set CONFIG_DOOM_SPLASH_TEXT to change the text of the startup splash.

Flashing

Note

NXP Linkserver v1.5.30 or newer has to be installed. See Zephyr LinkServer guide for more information.

Flashing takes two steps. Connect a USB-C cable to the "MCU-Link" USB-C port, then flash the application to the internal flash:

west flash

and the IWAD to the external flash at 0x90000000:

west flash --no-erase --hex-file build/zephyr/doom1.hex

--no-erase keeps the application that was just written; without it the runner mass erases the device first. The IWAD only has to be re-flashed when wad/doom1.wad changes.

4. Results

On a successful flash the display (LCD-PAR-S035) should turn and you can start playing the game.

5. FAQs

Doom-MCX Controls

Doom-MCX supports 2 types of control either through touchscreen or the Joystick shield.

Touchscreen controls

Open doors/start: Tap "Use Area"
Fire: Tap "Fire Area"
Wake & Strafe Tap and drag in the "Virtual Joystick Area"

Caution

When using the Funduino shield make sure the switch is in 3V3 mode, otherwise you will damage the board.

Joytick Shield controls

Fire: D
Use: C
Walk: Joystick Y-axis
Strafe: Joystick X-axis
Menu: A

6. Support

Questions regarding the content/correctness of this example can be entered as Issues within this GitHub repository.

Warning: For more general technical questions regarding NXP Microcontrollers and the difference in expected functionality, enter your questions on the NXP Community Forum

Simulation on PC

Zephyr RTOS also provides a native_posix target

To compile as native type:

west build -p always -b native_sim/native/64

To run type

cd doom-mcx
./build/zephyr/zephyr.exe --wad=wad/doom1.wad

--wad defaults to wad/doom1.wad, so a bare ./build/zephyr/zephyr.exe started from the repository root picks up the IWAD as well.

native_posix controls

Fire: CTRL
Use: Spacebar
Walk: Up-arrow & Down-arrow
Strafe: Left-arrow & Right-arrow
Menu: ESC

7. Release Notes

Version	Description / Update	Date
1.0	Initial release	September 12th 2026

8. License

This repository distributes source code and game data only; no firmware images are distributed. Building an image and flashing it to a board is done by the developer. The components that go into an image and their licenses are listed in SCR.txt.

• The game engine (prboom2/) is distributed under the GNU General Public License, version 2 or (at your option) any later version, as stated in the notices in its source files; see COPYING. It is derived from id Software's 1999 GPL release of the Doom source, PrBoom 2.5.0 and GBADoom. Files under prboom2/ that carry a "Copyright 2024 NXP" line were modified by NXP for this port; the changes are recorded in the git history.
• NXP's own files (src/, build and board files, scripts/) are available under Apache-2.0 OR GPL-2.0-or-later.
• A build links Zephyr RTOS (Apache-2.0), the NXP HAL (BSD-3-Clause), CMSIS (Apache-2.0), picolibc (BSD-3-Clause, MIT) and libgcc (GPL-3.0-or-later with the GCC Runtime Library Exception). See SCR.txt for the component register and LICENSES/ for the texts.
• wad/doom1.wad contains the game data of the Doom shareware episode, converted by the GBADoom project's tool GbaWadUtil into the layout this engine reads: levels in the engine's native structures, sound lumps omitted, plus the engine's own resource lumps from the GBADoom project. The game data is copyright id Software; the shareware license text that accompanies the shareware release is reproduced in wad/doom-wad-shareware-license.txt. The file is not part of the GPL-licensed engine and is flashed separately. An equivalent file can be generated from your own shareware or registered IWAD with GbaWadUtil.

Anyone who distributes a built image is responsible for determining and complying with the license terms that apply to that combination.

DOOM is a trademark of id Software LLC. This project is not affiliated with, sponsored by, or endorsed by id Software or ZeniMax Media. Zephyr is a trademark of The Linux Foundation.