DOOM

.github/workflows/main.yml

@@ -12,7 +12,7 @@ jobs:
   Build:
     strategy:
       matrix:
-        app_name: [Brainfuck, Breakout, Calculator, Diceware, EpubReader, EspNowBridge, GPIO, GraphicsDemo, HelloWorld, M5UnitTest, Magic8Ball, MediaKeys, MystifyDemo, SerialConsole, Snake, TamaTac, TodoList, TwoEleven]
+        app_name: [Brainfuck, Breakout, Calculator, Diceware, Doom, EpubReader, EspNowBridge, GPIO, GraphicsDemo, HelloWorld, M5UnitTest, Magic8Ball, MediaKeys, MystifyDemo, SerialConsole, Snake, TamaTac, TodoList, TwoEleven]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4

Apps/Doom/CMakeLists.txt

@@ -0,0 +1,13 @@
+# tactility-cmakelists-version: 1
+cmake_minimum_required(VERSION 3.20)
+
+if (NOT DEFINED ENV{TACTILITY_SDK_PATH})
+    message(FATAL_ERROR "TACTILITY_SDK_PATH environment variable is not set")
+endif()
+
+get_filename_component(TACTILITY_SDK_PATH "$ENV{TACTILITY_SDK_PATH}" ABSOLUTE)
+include("${TACTILITY_SDK_PATH}/TactilitySDK.cmake")
+
+tactility_project_pre(tactility.doom)
+project(tactility.doom)
+tactility_project_post(tactility.doom)

Apps/Doom/README.md

@@ -0,0 +1,44 @@
+# Doom
+
+A port of [doomgeneric](https://github.com/ozkl/doomgeneric) (id Software's DOOM source, GPL-2.0) for Tactility.
+
+## Overview
+
+Runs the classic 1993 DOOM engine directly on device, using the bundled shareware WAD or your own IWAD/PWAD from the SD card. Rendering, sound (OPL2/OPL3 FM synthesis via a DOSBox-derived emulator), and input all run natively - no external hardware or streaming required.
+
+## Requirements
+
+- M5Stack Tab5 (ESP32-P4) - this app is locked to that device via its manifest
+- An SD card (required by the device for storage in general)
+- A keyboard for gameplay: the Tab5's own keyboard accessory, or a USB keyboard. Without one attached, the game runs but can't receive input beyond touch-to-exit
+- Optional: a full IWAD on the SD card (see below) for the complete game instead of the 3-level shareware episode
+
+## Controls
+
+- **Arrow keys / WASD**: Move and turn
+- **Space / Backspace / Delete**: Use (open doors, flip switches)
+- **F**: Fire
+- **Enter**: Confirm (menus)
+- **Tab**: Automap
+- **Escape**: Menu
+- **Touch the screen**: Exit back to Tactility at any time
+
+## Adding WADs
+
+On first run, the app creates a `doom/` folder at the root of your SD card (`sdRoot/doom/`) if it doesn't already exist, with an empty `ADD_WADS_HERE` marker file inside so it's easy to find.
+
+Drop any of these into that folder to use them instead of the bundled shareware WAD:
+
+- `doom2.wad`, `doom.wad`, or `doom1.wad` - checked in that order; the first one found is used as the IWAD
+- `chiquito.wad` - loaded automatically as a bonus PWAD if present alongside an IWAD
+
+If no IWAD is found on the SD card, the app falls back to the bundled shareware WAD (`doom1.wad`) automatically.
+
+## Saves and settings
+
+Save games and `default.cfg` (key bindings, volume, etc.) are stored in the app's own Tactility user data folder, separate from the WAD folder above - so they persist even if you're only running the bundled shareware WAD with no SD card WAD folder present.
+
+## Known limitations
+
+- Touch input is exit-only; there's no on-screen touch controls for movement/actions, so a keyboard is effectively required to actually play
+- Locked to Tab5/ESP32-P4 for now

Apps/Doom/assets/doom-wad-shareware-license.txt

@@ -0,0 +1,126 @@
+The Doom 1 shareware WAD file is (C) Copyright id Software.
+
+             LIMITED USE SOFTWARE LICENSE AGREEMENT
+
+This Limited Use Software License Agreement (the "Agreement") is a legal 
+agreement between you, the end-user, and Id Software, Inc. ("ID").  By 
+continuing the installation of this game program, by loading or running 
+the game, or by placing or copying the game program onto your computer 
+hard drive, you are agreeing to be bound by the terms of this Agreement.  
+
+ID SOFTWARE LICENSE
+
+     1.   Grant of License.  ID grants to you the right to use the 
+Id Software game program (the "Software"), which is the shareware version 
+or episode one  of the game program.  For purposes of this section, "use" 
+means loading the Software into RAM, as well as installation on a hard disk 
+or other storage  device.  You may not:  modify, translate, disassemble, 
+decompile, reverse engineer, or create derivative works based upon the 
+Software.  You agree thatd the Software will not be shipped, transferred or 
+exported into any country in violation of the U.S. Export Administration Act 
+and that you will not utilize, in any other manner, the Software in violation 
+of any applicable law.
+
+     2.   Copyright.  The Software is owned by ID and is protected by United 
+States copyright laws and international treaty provisions.  You must treat 
+the Software like any other copyrighted material, except that you may make 
+copies of the Software to give to other persons.  You may not charge or 
+receive any consideration from any other person for the receipt or use of 
+the Software without receiving ID's prior written consent as specified in the 
+VENDOR.DOC file.  You agree to use your best efforts to see that any user of 
+the Software licensed hereunder complies with this Agreement.
+
+     3.   Limited Warranty.  ID warrants that if properly installed and 
+operated on a computer for which it is designed, the Software will perform 
+substantially in accordance with its designed purpose for a period of ninety 
+(90) days from the date the Software is first obtained by an end-user.   ID's 
+entire liability and your exclusive remedy shall be, at ID's option, either 
+(a) return of the retail price paid, if any, or (b) repair or replacement of 
+the Software that does not meet ID's Limited Warranty.  To make a warranty 
+claim, return the Software to the point of purchase, accompanied by proof of
+purchase, your name, your address, and a statement of defect, or return the 
+Software with the above information to ID.  This Limited Warranty is void if 
+failure of the Software has resulted in whole or in part from accident, 
+abuse, misapplication or violation of this Agreement.  Any replacement 
+Software will be warranted for the remainder of the original warranty period 
+or thirty (30) days, whichever is longer.  This warranty allocates risks of 
+product failure between Licensee and ID.  ID's product pricing reflects this 
+allocation of risk and the limitations of liability contained in this 
+warranty.
+
+     4.   NO OTHER WARRANTIES.  ID DISCLAIMS ALL OTHER WARRANTIES, EITHER 
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, IMPLIED WARRANTIES OF 
+MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE WITH RESPECT TO THE 
+SOFTWARE AND THE ACCOMPANYING WRITTEN MATERIALS, IF ANY.  THIS LIMITED 
+WARRANTY GIVES YOU SPECIFIC LEGAL RIGHTS.  YOU MAY HAVE OTHERS WHICH VARY 
+FROM JURISDICTION TO JURISDICTION.  ID DOES NOT WARRANT THAT THE OPERATION 
+OF THE SOFTWARE WILL BE UNINTERRUPTED, ERROR FREE OR MEET LICENSEE'S 
+SPECIFIC REQUIREMENTS.  THE WARRANTY SET FORTH ABOVE IS IN LIEU OF ALL OTHER 
+EXPRESS WARRANTIES WHETHER ORAL OR WRITTEN.  THE AGENTS, EMPLOYEES, 
+DISTRIBUTORS, AND DEALERS OF ID ARE NOT AUTHORIZED TO MAKE MODIFICATIONS TO 
+THIS WARRANTY, OR ADDITIONAL WARRANTIES ON BEHALF OF ID.  ADDITIONAL 
+STATEMENTS SUCH AS DEALER ADVERTISING OR PRESENTATIONS, WHETHER ORAL OR 
+WRITTEN, DO NOT CONSTITUTE WARRANTIES BY ID AND SHOULD NOT BE RELIED UPON.
+
+     5.   Exclusive Remedies.  You agree that your exclusive remedy against 
+ID, its affiliates, contractors, suppliers, and agents for loss or damage 
+caused by any defect or failure in the Software regardless of the form of 
+action, whether in contract, tort, including negligence, strict liability or
+otherwise, shall be the return of the retail purchase price paid, if any, or 
+replacement of the Software.   This Agreement shall be construed in 
+accordance with and governed by the laws of the State of Texas.  Copyright 
+and other proprietary matters will be governed by United States laws and 
+international treaties.  IN ANY CASE, ID SHALL NOT BE LIABLE FOR LOSS OF 
+DATA, LOSS OF PROFITS, LOST SAVINGS, SPECIAL, INCIDENTAL, CONSEQUENTIAL, 
+INDIRECT OR OTHER SIMILAR DAMAGES ARISING FROM BREACH OF WARRANTY, BREACH OF 
+CONTRACT, NEGLIGENCE, OR OTHER LEGAL THEORY EVEN IF ID OR ITS AGENT HAS BEEN 
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER 
+PARTY.  Some jurisdictions do not allow the exclusion or limitation of 
+incidental or consequential damages, so the above limitation or exclusion 
+may not apply to you.
+
+     6.   General Provisions.  Neither this Agreement nor any part or portion 
+hereof shall be assigned or sublicensed, except as described herein.  Should 
+any provision of this Agreement be held to be void, invalid, unenforceable or 
+illegal by a court, the validity and enforceability of the other provisions 
+shall not be affected thereby.  If any provision is determined to be 
+unenforceable, you agree to a modification of such provision to provide for 
+enforcement of the provision's intent, to the extent permitted by applicable 
+law.  Failure of a party to enforce any provision of this Agreement shall not
+constitute or be construed as a waiver of such provision or of the right to 
+enforce such provision.  If you fail to comply with any terms of this 
+Agreement, YOUR LICENSE IS AUTOMATICALLY TERMINATED.
+
+     YOU ACKNOWLEDGE THAT YOU HAVE READ THIS AGREEMENT, YOU UNDERSTAND THIS
+AGREEMENT, AND UNDERSTAND THAT BY CONTINUING THE INSTALLATION OF THE 
+SOFTWARE, BY LOADING OR RUNNING THE SOFTWARE, OR BY PLACING OR COPYING THE 
+SOFTWARE ONTO YOUR COMPUTER HARD DRIVE, YOU AGREE TO BE BOUND BY THIS 
+AGREEMENT'S TERMS AND CONDITIONS.  YOU FURTHER AGREE THAT, EXCEPT FOR WRITTEN 
+SEPARATE AGREEMENTS BETWEEN ID AND YOU, THIS AGREEMENT IS A COMPLETE AND 
+EXCLUSIVE STATEMENT OF THE RIGHTS AND LIABILITIES OF THE PARTIES.  THIS 
+AGREEMENT SUPERSEDES ALL PRIOR ORAL AGREEMENTS, PROPOSALS OR UNDERSTANDINGS, 
+AND ANY OTHER COMMUNICATIONS BETWEEN ID AND YOU RELATING TO THE SUBJECT 
+MATTER OF THIS AGREEMENT.
+
+The above license does not appear to grant distribution permission.  Email
+from John Carmack of ID Software provided this clarification:
+
+X-Sender: johnc@mail.idsoftware.com
+X-Mailer: Windows Eudora Pro Version 3.0 (32)
+Date: Sat, 23 Oct 1999 20:01:30 -0500
+To: Joe Drew <hoserhead@woot.net>
+From: johnc@idsoftware.com (John Carmack)
+Subject: Re: Doom shareware WAD license
+
+At 08:02 PM 10/23/99 -0400, you wrote:
+>Can you give me a definite license on the doom 1 shareware wad? I find certain
+>things that say "freely distribute" and others that say "get vendor's license"
+>... All I need to have is a license so I can package it up for Debian.
+>Thanks.
+>Joe
+
+The DOOM shareware wad is freely distributable.  No Quake data is freely
+distributable.
+
+John Carmack
+

Apps/Doom/main/CMakeLists.txt

@@ -0,0 +1,138 @@
+include("$ENV{TACTILITY_SDK_PATH}/TactilitySDK.cmake")
+
+# App sources
+file(GLOB_RECURSE APP_SOURCES Source/*.c*)
+
+# doomgeneric engine sources (vendored from https://github.com/ozkl/doomgeneric, minus the platform backends we don't use)
+set(DOOMGENERIC_DIR doomgeneric)
+set(DOOM_SOURCES
+    ${DOOMGENERIC_DIR}/doomgeneric/dummy.c
+    ${DOOMGENERIC_DIR}/doomgeneric/am_map.c
+    ${DOOMGENERIC_DIR}/doomgeneric/doomdef.c
+    ${DOOMGENERIC_DIR}/doomgeneric/doomstat.c
+    ${DOOMGENERIC_DIR}/doomgeneric/dstrings.c
+    ${DOOMGENERIC_DIR}/doomgeneric/d_event.c
+    ${DOOMGENERIC_DIR}/doomgeneric/d_items.c
+    ${DOOMGENERIC_DIR}/doomgeneric/d_iwad.c
+    ${DOOMGENERIC_DIR}/doomgeneric/d_loop.c
+    ${DOOMGENERIC_DIR}/doomgeneric/d_main.c
+    ${DOOMGENERIC_DIR}/doomgeneric/d_mode.c
+    ${DOOMGENERIC_DIR}/doomgeneric/d_net.c
+    ${DOOMGENERIC_DIR}/doomgeneric/f_finale.c
+    ${DOOMGENERIC_DIR}/doomgeneric/f_wipe.c
+    ${DOOMGENERIC_DIR}/doomgeneric/g_game.c
+    ${DOOMGENERIC_DIR}/doomgeneric/hu_lib.c
+    ${DOOMGENERIC_DIR}/doomgeneric/hu_stuff.c
+    ${DOOMGENERIC_DIR}/doomgeneric/info.c
+    ${DOOMGENERIC_DIR}/doomgeneric/i_cdmus.c
+    ${DOOMGENERIC_DIR}/doomgeneric/i_endoom.c
+    ${DOOMGENERIC_DIR}/doomgeneric/i_joystick.c
+    ${DOOMGENERIC_DIR}/doomgeneric/i_scale.c
+    ${DOOMGENERIC_DIR}/doomgeneric/i_sound.c
+    # OPL3 music: DBOPL (the DOSBox OPL emulator) behind a Nuked-compatible
+    # shim, plus the Chocolate Doom GENMIDI player vendored from the Gin_Doom https://github.com/FigBug/Gin_Doom
+    # fork (pull-based OPL_Render, no SDL).
+    #
+    # Nuked was ~2x over the real-time budget on P4 and ymfm ~108%; DBOPL is
+    # table-driven rather than cycle-accurate and measures ~19-30x cheaper
+    # than ymfm, which is what makes 18-voice OPL3 affordable here.
+    ${DOOMGENERIC_DIR}/doomgeneric/opl3.cpp
+    ${DOOMGENERIC_DIR}/doomgeneric/dbopl/dbopl.cpp
+    ${DOOMGENERIC_DIR}/doomgeneric/opl.c
+    ${DOOMGENERIC_DIR}/doomgeneric/opl_queue.c
+    ${DOOMGENERIC_DIR}/doomgeneric/i_oplmusic.c
+    ${DOOMGENERIC_DIR}/doomgeneric/midifile.c
+    ${DOOMGENERIC_DIR}/doomgeneric/mus2mid.c
+    ${DOOMGENERIC_DIR}/doomgeneric/i_system.c
+    ${DOOMGENERIC_DIR}/doomgeneric/i_timer.c
+    ${DOOMGENERIC_DIR}/doomgeneric/memio.c
+    ${DOOMGENERIC_DIR}/doomgeneric/m_argv.c
+    ${DOOMGENERIC_DIR}/doomgeneric/m_bbox.c
+    ${DOOMGENERIC_DIR}/doomgeneric/m_cheat.c
+    ${DOOMGENERIC_DIR}/doomgeneric/m_config.c
+    ${DOOMGENERIC_DIR}/doomgeneric/m_controls.c
+    ${DOOMGENERIC_DIR}/doomgeneric/m_fixed.c
+    ${DOOMGENERIC_DIR}/doomgeneric/m_menu.c
+    ${DOOMGENERIC_DIR}/doomgeneric/m_misc.c
+    ${DOOMGENERIC_DIR}/doomgeneric/m_random.c
+    ${DOOMGENERIC_DIR}/doomgeneric/p_ceilng.c
+    ${DOOMGENERIC_DIR}/doomgeneric/p_doors.c
+    ${DOOMGENERIC_DIR}/doomgeneric/p_enemy.c
+    ${DOOMGENERIC_DIR}/doomgeneric/p_floor.c
+    ${DOOMGENERIC_DIR}/doomgeneric/p_inter.c
+    ${DOOMGENERIC_DIR}/doomgeneric/p_lights.c
+    ${DOOMGENERIC_DIR}/doomgeneric/p_map.c
+    ${DOOMGENERIC_DIR}/doomgeneric/p_maputl.c
+    ${DOOMGENERIC_DIR}/doomgeneric/p_mobj.c
+    ${DOOMGENERIC_DIR}/doomgeneric/p_plats.c
+    ${DOOMGENERIC_DIR}/doomgeneric/p_pspr.c
+    ${DOOMGENERIC_DIR}/doomgeneric/p_saveg.c
+    ${DOOMGENERIC_DIR}/doomgeneric/p_setup.c
+    ${DOOMGENERIC_DIR}/doomgeneric/p_sight.c
+    ${DOOMGENERIC_DIR}/doomgeneric/p_spec.c
+    ${DOOMGENERIC_DIR}/doomgeneric/p_switch.c
+    ${DOOMGENERIC_DIR}/doomgeneric/p_telept.c
+    ${DOOMGENERIC_DIR}/doomgeneric/p_tick.c
+    ${DOOMGENERIC_DIR}/doomgeneric/p_user.c
+    ${DOOMGENERIC_DIR}/doomgeneric/r_bsp.c
+    ${DOOMGENERIC_DIR}/doomgeneric/r_data.c
+    ${DOOMGENERIC_DIR}/doomgeneric/r_draw.c
+    ${DOOMGENERIC_DIR}/doomgeneric/r_main.c
+    ${DOOMGENERIC_DIR}/doomgeneric/r_plane.c
+    ${DOOMGENERIC_DIR}/doomgeneric/r_segs.c
+    ${DOOMGENERIC_DIR}/doomgeneric/r_sky.c
+    ${DOOMGENERIC_DIR}/doomgeneric/r_things.c
+    ${DOOMGENERIC_DIR}/doomgeneric/sha1.c
+    ${DOOMGENERIC_DIR}/doomgeneric/sounds.c
+    ${DOOMGENERIC_DIR}/doomgeneric/statdump.c
+    ${DOOMGENERIC_DIR}/doomgeneric/st_lib.c
+    ${DOOMGENERIC_DIR}/doomgeneric/st_stuff.c
+    ${DOOMGENERIC_DIR}/doomgeneric/s_sound.c
+    ${DOOMGENERIC_DIR}/doomgeneric/tables.c
+    ${DOOMGENERIC_DIR}/doomgeneric/v_video.c
+    ${DOOMGENERIC_DIR}/doomgeneric/wi_stuff.c
+    ${DOOMGENERIC_DIR}/doomgeneric/w_checksum.c
+    ${DOOMGENERIC_DIR}/doomgeneric/w_file.c
+    ${DOOMGENERIC_DIR}/doomgeneric/w_main.c
+    ${DOOMGENERIC_DIR}/doomgeneric/w_wad.c
+    ${DOOMGENERIC_DIR}/doomgeneric/z_zone.c
+    ${DOOMGENERIC_DIR}/doomgeneric/w_file_stdc.c
+    ${DOOMGENERIC_DIR}/doomgeneric/i_input.c
+    ${DOOMGENERIC_DIR}/doomgeneric/i_video.c
+    ${DOOMGENERIC_DIR}/doomgeneric/doomgeneric.c
+    ${DOOMGENERIC_DIR}/doomgeneric_tactility.c
+)
+
+tactility_component_register(
+    SRCS ${APP_SOURCES} ${DOOM_SOURCES}
+    INCLUDE_DIRS "Source" "${DOOMGENERIC_DIR}/doomgeneric"
+    REQUIRES TactilitySDK driver esp_driver_ppa esp_mm
+)
+
+target_compile_definitions(${COMPONENT_LIB} PRIVATE
+    DOOMGENERIC_RESX=320
+    DOOMGENERIC_RESY=200
+    FEATURE_SOUND
+    # Compiles DBOPL without its DOSBox mixer glue (Adlib::Handler, MixerChannel,
+    # iostream save/load), leaving just DBOPL::Chip, which is all the shim uses.
+    DBOPL_STANDALONE
+)
+
+# Suppress warnings in the vendored doomgeneric engine sources
+# Several of these warning flags (-Wno-old-style-declaration, -Wno-int-conversion,
+# -Wno-discarded-qualifiers, -Wno-implicit-function-declaration,
+# -Wno-incompatible-pointer-types) are C-only; GCC rejects them outright when
+# compiling C++. Apply them to the vendored C sources only, and give the C++
+# sources (the OPL3 shim and DBOPL itself) their own, milder set.
+set(DOOM_C_SOURCES ${DOOM_SOURCES})
+list(FILTER DOOM_C_SOURCES EXCLUDE REGEX "\\.cpp$")
+set(DOOM_CXX_SOURCES ${DOOM_SOURCES})
+list(FILTER DOOM_CXX_SOURCES INCLUDE REGEX "\\.cpp$")
+
+set_source_files_properties(${DOOM_C_SOURCES} PROPERTIES COMPILE_FLAGS
+    "-Wno-error -Wno-dangling-pointer -Wno-unused-but-set-parameter -Wno-int-conversion -Wno-implicit-function-declaration -Wno-discarded-qualifiers -Wno-unused-variable -Wno-unused-but-set-variable -Wno-maybe-uninitialized -Wno-format -Wno-misleading-indentation -Wno-old-style-declaration -Wno-incompatible-pointer-types"
+)
+
+set_source_files_properties(${DOOM_CXX_SOURCES} PROPERTIES COMPILE_FLAGS
+    "-Wno-error -Wno-unused-variable -Wno-unused-but-set-variable -Wno-maybe-uninitialized -Wno-format -Wno-misleading-indentation"
+)