diff --git a/Documentation/applications/games/nxdoom/doom-on-sim.png b/Documentation/applications/games/nxdoom/doom-on-sim.png new file mode 100644 index 0000000000000..829575fb8e4cf Binary files /dev/null and b/Documentation/applications/games/nxdoom/doom-on-sim.png differ diff --git a/Documentation/applications/games/nxdoom/index.rst b/Documentation/applications/games/nxdoom/index.rst new file mode 100644 index 0000000000000..4129f89c7a7f2 --- /dev/null +++ b/Documentation/applications/games/nxdoom/index.rst @@ -0,0 +1,134 @@ +====== +NXDoom +====== + +This game is a port of the `Chocolate DOOM +`_ DOOM port to NuttX. The +original Chocolate DOOM port is highly featured, and also adheres well to the +vanilla DOOM experience. NXDoom is tailored instead for embedded devices and +will likely have to forego some features or sacrifice some vanilla DOOM +experience for better memory/CPU performance. + +NXDoom is maintained inside the NuttX source tree because it will diverge +heavily from the original Chocolate DOOM port in order to target embedded +devices. It is for this reason that we do not take the approach of downloading +Chocolate DOOM and apply patches (there would be too many large patches to +apply). + +.. figure:: doom-on-sim.png + :figwidth: 60% + :align: center + :alt: The shareware version of DOOM being played on the NuttX simulator + + The shareware version of DOOM being played on the NuttX simulator + +.. warning:: + + Not all features are implemented for NXDoom. There is currently no support + for game sounds or music, nor does any of the networked logic for multiplayer + games work. + + Some code was stripped during the initial port to simplify the port. If those + features are needed/desired later, they can be added back. This includes some + sound-library interfaces which are not available on NuttX, some input + options, etc. + + It is recommended that if you are making any significant changes to the + source code, you try compiling with and without the sound/networking feature + flags enabled to catch any possible errors. + +.. todo:: + + This port is a massive work in progress. Any contributions are welcome. Since + memory is the primary constraint for many of the embedded devices running + NuttX, memory optimizations are particularly welcome. + + Sound support, multiplayer support, support for any of the wide array of + input devices NuttX can provide are also highly welcomed. + +.. warning:: + + Currently, the only supported input device is keyboard input. However, + NuttX's keyboard codec is highly non-standard and therefore some things do + not work as intended. For instance, pressing CTRL to fire does nothing since + NuttX's codec has no concept of CTRL. The keyboard codec will need to be + amended before this works properly, but the port is upstreamed in the hopes + of encouraging those changes or getting more contributors to add different + input devices. The keyboard codec needs to be treated delicately since other + things in the kernel depend on it. + +Minimum requirements +-------------------- + +The minimum requirements for playing NXDoom are: + +* A device running NuttX +* A device with graphics output controlled via a frame buffer driver (320x240 + screen minimum resolution) +* Some way of getting sufficient input for up/down/left/right/fire controls + (limited out-of-the-box input support is available) +* A pretty good amount of memory (I haven't verified the total amount required + yet, but the original DOOM needed 4MB of RAM and NXDoom isn't much better + optimized) +* Non-volatile memory sufficiently large for the WAD file you choose to play + +.. note:: + + The NXDoom port was tested using the shareware version of DOOM, whose WAD + file is commonly named DOOM1.wad. You may find this online on various sites. + Other WAD files are available online but are not guaranteed to work (i.e., + the `OTTAWAU.wad + `_ + file I tried did not run properly) + + +Playing +------- + +To launch the game, just run: + +.. code:: console + + nsh> nxdoom -iwad /path/to/my/iwadfile.wad + +and replace the path with your WAD file's path. + +Other Notes +----------- + +Translations +^^^^^^^^^^^^ + +The game does support different translations via headers with game strings. One +such example is ``src/doom/d_french``, which was my half-attempt at translating +the game strings to French (I stopped halfway). The main problem with +translations is that the game seems unable to render non-ASCII text (i.e. any +French words with accents have missing letters where the accents were). A way +around this would be great, and other translations are welcome. + +Source Comments +^^^^^^^^^^^^^^^ + +I made an effort to preserve all the original comments from the Chocolate DOOM +source, which in turn seems to have made an effort to preserve the original DOOM +code comments. Some are quite vulgar. + +Optimizations +^^^^^^^^^^^^^ + +DOOM uses 32-bit wide, signed fixed-point numbers for calculations. This should +be entirely compatible with the NuttX fixed-point library. However, in my +attempt to switch to the NuttX-native library, the textures began to render +strangely and I experienced periodic crashes. This would be one good +optimization. + +Another useful optimization would be to eliminate the lookup tables used for +sine, cosine and tangent. These make the game logic fast, but they also take up +the most amount of memory in the binary. Removing them could save several +hundred KB. CPUs have come a long way since DOOM was written and the compute hit +might be worth it for the memory reduction on embedded. + +Another good optimization would be to examine the use of 32-bit natural ``int`` +variables and decided if smaller sizes could be used. I imagine this was +originally done for the native word-size optimizations on the computers of the +era, but it results in extra memory use on large internal arrays especially. diff --git a/Documentation/platforms/sim/sim/boards/sim/index.rst b/Documentation/platforms/sim/sim/boards/sim/index.rst index c2487ba2ed937..7c1fde0b91cd3 100644 --- a/Documentation/platforms/sim/sim/boards/sim/index.rst +++ b/Documentation/platforms/sim/sim/boards/sim/index.rst @@ -946,6 +946,17 @@ Of course, this configuration can only be used in environments that support X11! -CONFIG_EXAMPLES_NXTERM=n +CONFIG_EXAMPLES_NXTERM=y +nxdoom +------ + +Play :doc:`NXDoom ` on the Simulator using X11 +keyboard input and graphics. Read the docs for NXDoom to see how to play. + +.. warning:: + + X11 keyboard codes are not perfectly translated to the NuttX codec currently, + so some controls will not work properly. + nxffs ----- diff --git a/boards/sim/sim/sim/configs/nxdoom/defconfig b/boards/sim/sim/sim/configs/nxdoom/defconfig new file mode 100644 index 0000000000000..f2daec575db0d --- /dev/null +++ b/boards/sim/sim/sim/configs/nxdoom/defconfig @@ -0,0 +1,85 @@ +# +# This file is autogenerated: PLEASE DO NOT EDIT IT. +# +# You can use "make menuconfig" to make any modifications to the installed .config file. +# You can then do "make savedefconfig" to generate a new defconfig file that includes your +# modifications. +# +# CONFIG_NSH_CMDOPT_HEXDUMP is not set +CONFIG_ALLOW_GPL_COMPONENTS=y +CONFIG_ARCH="sim" +CONFIG_ARCH_BOARD="sim" +CONFIG_ARCH_BOARD_SIM=y +CONFIG_ARCH_CHIP="sim" +CONFIG_ARCH_SIM=y +CONFIG_BOARDCTL_APP_SYMTAB=y +CONFIG_BOARDCTL_POWEROFF=y +CONFIG_BOARD_LOOPSPERMSEC=0 +CONFIG_BOOT_RUNFROMEXTSRAM=y +CONFIG_BUILTIN=y +CONFIG_COVERAGE_ALL=y +CONFIG_COVERAGE_TOOLCHAIN=y +CONFIG_CRYPTO=y +CONFIG_DEBUG_ASSERTIONS=y +CONFIG_DEBUG_ASSERTIONS_EXPRESSION=y +CONFIG_DEBUG_FEATURES=y +CONFIG_DEBUG_SYMBOLS=y +CONFIG_DEV_GPIO=y +CONFIG_DEV_LOOP=y +CONFIG_DRIVERS_VIDEO=y +CONFIG_ETC_FATDEVNO=2 +CONFIG_ETC_ROMFS=y +CONFIG_ETC_ROMFSDEVNO=1 +CONFIG_FAT_LCNAMES=y +CONFIG_FAT_LFN=y +CONFIG_FS_BINFS=y +CONFIG_FS_FAT=y +CONFIG_FS_HOSTFS=y +CONFIG_FS_PROCFS=y +CONFIG_FS_RAMMAP=y +CONFIG_FS_ROMFS=y +CONFIG_GAMES_NXDOOM=y +CONFIG_GAMES_NXDOOM_ENDOOM=y +CONFIG_GAMES_NXDOOM_KBDPATH="/dev/kbd" +CONFIG_GPIO_LOWER_HALF=y +CONFIG_HAVE_CXXINITIALIZE=y +CONFIG_IDLETHREAD_STACKSIZE=4096 +CONFIG_INIT_ENTRYPOINT="nsh_main" +CONFIG_INPUT=y +CONFIG_IOEXPANDER=y +CONFIG_IOEXPANDER_DUMMY=y +CONFIG_LIBC_ENVPATH=y +CONFIG_LIBC_EXECFUNCS=y +CONFIG_LIBC_LOCALE=y +CONFIG_LIBC_LOCALE_CATALOG=y +CONFIG_LIBC_LOCALE_GETTEXT=y +CONFIG_LIBC_MAX_EXITFUNS=1 +CONFIG_LIBC_NUMBERED_ARGS=y +CONFIG_NDEBUG=y +CONFIG_NSH_BUILTIN_APPS=y +CONFIG_NSH_FILE_APPS=y +CONFIG_NSH_READLINE=y +CONFIG_PATH_INITIAL="/bin" +CONFIG_PIPES=y +CONFIG_PSEUDOFS_ATTRIBUTES=y +CONFIG_PSEUDOFS_FILE=y +CONFIG_PSEUDOFS_SOFTLINKS=y +CONFIG_READLINE_TABCOMPLETION=y +CONFIG_SCHED_BACKTRACE=y +CONFIG_SCHED_EVENTS=y +CONFIG_SCHED_HAVE_PARENT=y +CONFIG_SCHED_WAITPID=y +CONFIG_SIM_FBHEIGHT=1200 +CONFIG_SIM_FBWIDTH=1920 +CONFIG_SIM_FRAMEBUFFER_COUNT=1 +CONFIG_SIM_HOSTFS=y +CONFIG_SIM_KEYBOARD=y +CONFIG_SIM_TOUCHSCREEN=y +CONFIG_SIM_WALLTIME_SIGNAL=y +CONFIG_SIM_X11FB=y +CONFIG_START_MONTH=6 +CONFIG_START_YEAR=2008 +CONFIG_SYSTEM_DUMPSTACK=y +CONFIG_SYSTEM_GCOV=y +CONFIG_SYSTEM_NSH=y +CONFIG_VIDEO_FB=y