libretro/emulators/prboom-plus.yml

emulator: PrBoom+
type: standalone
core_classification: game_engine
source: "https://github.com/coelckers/prboom-plus"
upstream: "https://github.com/coelckers/prboom-plus"
profiled_date: "2026-08-08"
source_commit: "969515162c5aebea4ad7a125ee178dcad3d576ad"
core_version: "2.6.66"
display_name: "Doom (PrBoom+)"
cores:
  - prboom-plus
systems:
  - doom
mode: standalone

notes: |
  Doom source port forked from PrBoom, with the software and OpenGL renderers
  in a single binary. FindIWADFile accepts doom2f, doom2, plutonia, tnt, doom,
  doom1, doomu, freedoom2, freedoom1, freedm, hacx, chex, rekkrsa, bfgdoom2
  and bfgdoom (d_main.c:144-165). ES-DE runs it as "prboom-plus -iwad <file>",
  so the IWAD is content, not a system file.

  prboom-plus.wad holds the engine's own lumps: the palette, the water
  colormap, the sine, tangent and gamma tables, the HUD layouts, the status
  bar digits, the crosshairs, the dog and plasma sprites, the GLSL shader
  sources, and the DEHACKED patches applied to Chex Quest, the BFG Edition
  and NERVE.WAD. M_LoadDefaults installs it as wad_files[0] and aborts with
  "PrBoom-Plus.wad not found. Can't continue." when I_FindFile returns
  nothing (m_misc.c:1723-1724). It loads even under -noload, which caps the
  autoload loop at that one entry (d_main.c:1877-1879). Lumps coming from it
  are tagged LUMP_PRBOOM so a PWAD can override them (w_wad.c:185-196).

  The tree ships the inputs, not the file: data/CMakeLists.txt builds it with
  the rdatawad tool from the raw palette, lumps, PPM graphics and WAV sounds
  under data/, then installs it into PRBOOMDATADIR, which is
  <prefix>/share/prboom-plus (CMakeLists.txt:188-189, data/CMakeLists.txt:370).

  I_FindFile searches, in order: the config directory, the working directory,
  PRBOOMDATADIR, $DOOMWADDIR, the build-time DOOMWADDIR, $HOME/doom, $HOME,
  /usr/local/share/games/doom, /usr/share/games/doom, /usr/local/share/doom,
  /usr/share/doom, then every entry of $DOOMWADPATH (SDL/i_system.c:437-449,
  471-505). The working directory entry carries no prefix, so an absolute
  name resolves on that pass. Existence is the only test, and the requested
  extension is appended only when the name as written is missing
  (SDL/i_system.c:532-538). The config directory is the directory holding the
  binary on Windows (SDL/i_system.c:289-311), and ~/.prboom-plus or the
  XDG path from SDL_GetPrefPath elsewhere (SDL/i_system.c:347-383). The macOS
  build replaces the list with ~/Library/Application Support/PrBoom-Plus, the
  bundle resource path, and the bare name (MAC/i_system.m:57-59, 117-142).

  snd_midiplayer picks the MIDI backend and defaults to fluidsynth on Windows,
  sdl elsewhere (m_misc.c:444-450). Only the sdl value leaves
  use_experimental_music clear and routes MIDI through SDL_mixer
  (SDL/i_sound.c:1662-1668, 1221-1225); every other value brings up the
  in-tree players. Their init results are recorded once at startup
  (SDL/i_sound.c:1383-1384) and consulted per song, a player that failed to
  init being logged and passed over for the next entry of music_player_order
  (SDL/i_sound.c:1511-1538). fluidsynth is the only one reading an external
  file. The OPL2 player that follows it takes its instruments from the IWAD
  GENMIDI lump (MUSIC/oplplayer.c:337-354).

files:
  - name: "prboom-plus.wad"
    system: doom
    description: "PrBoom+ engine data WAD"
    required: true
    size: 357768
    md5: "1164ae723c9181698cc41dde6a341132"
    sha1: "8a799c6615702aac72016b784e30ea1abd3e197b"
    crc32: "a4626dfa"
    source_ref: "m_misc.c:1723-1724 (I_FindFile then I_Error), d_main.c:1873-1895 (autoload), w_wad.c:185-196 (LUMP_PRBOOM tagging), CMakeLists.txt:41 (PACKAGE_TARNAME), CMakeLists.txt:234-235 (WAD_DATA), data/CMakeLists.txt:364-370 (rdatawad build and install)"
    note: >
      The code checks existence only, then rejects a file whose header is
      neither IWAD nor PWAD (w_wad.c:216-218). Hashes are those of the file
      rdatawad produces from the data/ assets at this revision, which matches
      the copy in the v2.6.66 release archive byte for byte. They identify the
      2.6.66 build; other versions carry different lumps.

  - name: "TimGM6mb.sf2"
    system: doom
    description: "General MIDI soundfont for the fluidsynth MIDI player"
    required: false
    hle_fallback: true
    source_ref: "m_misc.c:445-446 (_WIN32 defaults for snd_midiplayer and snd_soundfont), MUSIC/flplayer.c:193-202 (I_FindFile2 then fluid_synth_sfload)"
    note: >
      Named by the Windows default of snd_soundfont, where snd_midiplayer also
      defaults to fluidsynth, so a stock Windows configuration reads it. Any
      soundfont works: the value is a config string and I_FindFile2 appends
      .sf2 only when the name as written is missing. A load failure returns 0
      from fl_init, and the song falls through to the next player on the list,
      the built-in OPL2 synth.

  - name: "default-GM.sf3"
    system: doom
    description: "General MIDI soundfont named by the non-Windows soundfont default"
    required: false
    hle_fallback: true
    source_ref: "m_misc.c:448-449 (non-_WIN32 defaults, /usr/share/sounds/sf3/default-GM.sf3), MUSIC/flplayer.c:193-202 (I_FindFile2 then fluid_synth_sfload)"
    note: >
      The default is an absolute path, which resolves through the unprefixed
      working directory entry of the search table. Reached once snd_midiplayer
      is set away from its sdl default, since sdl keeps the fluidsynth player
      out of the picture entirely. Same fallback to the OPL2 synth as the
      Windows default.

analysis:
  engine_wad_contents:
    source_ref: "data/CMakeLists.txt:24-340 (rdatawad input lists), data/CMakeLists.txt:342-362 (WAD_SRC and WAD_CMDLINE)"
    note: >
      What rdatawad packs into prboom-plus.wad, in the order the command line
      builds it.
    palette: palette.rgb
    lumps:
      - "SWITCHES, ANIMATED"
      - "the CR* colour translation tables"
    colormaps: "WATERMAP, between C_START and C_END"
    tables:
      note: "Between B_START and B_END"
      entries:
        - "SINETABL, TANGTABL, TANTOANG, GAMMATBL"
        - "CHEXDEH, BFGBEX, NERVEBEX"
        - "GLSHADOW, GLFP, GLVP"
        - "-PRBHUD-, read by hu_stuff.c:1144"
        - "the M_* OpenGL automap icons listed in gl_map.c:48-68"
    sounds: "DSDGSIT, DSDGATK, DSDGACT, DSDGDTH, DSDGPAIN"
    graphics: "the DIG* status bar digits, STBR*, the BOX* frame pieces, STKEYS6-8, STCFN096, M_BUTT1/2, M_COLORS, M_PALNO, M_PALSEL, M_VBOX, CROSS1-3"
    flats: "-N0_TEX-, between FF_START and FF_END"
    sprites: "TNT1A0, the DOGS* frames, PLS1* and PLS2*, between SS_START and SS_END"

  shader_override:
    files:
      - "shaders/glvp.txt"
      - "shaders/glfp.txt"
    source_ref: "gl_shader.c:144-152 (path built from I_DoomExeDir), gl_shader.c:84-129 (ReadLump)"
    note: >
      Read from the config directory when present. ReadLump falls back to the
      GLVP and GLFP lumps in the ns_prboom namespace when the file is missing,
      and those lumps are built into prboom-plus.wad
      (data/CMakeLists.txt:60-61). No distribution ships the .txt form: it is
      an override slot, and the shipped content is already covered by the WAD.

  generated_files:
    note: "Written by the program itself, none is user-supplied"
    entries:
      - filename: "prboom-plus.cfg"
        source_ref: "m_misc.c:1586-1600 (BOOM_CFG, path from I_DoomExeDir), m_misc.c:1606 (read)"
      - filename: "RGB2PAL.dat"
        source_ref: "gl_hires.c:938-953 (read), gl_hires.c:962-967 (opened wb and written)"
        note: >
          A 24-bit RGB to palette lookup table built from V_GetPlaypal, so its
          contents follow whichever IWAD is loaded. gl_hires.c:920-936 prefers
          an RGB2PAL lump of the right length when a WAD supplies one.
      - filename: "<hires image>.cache"
        source_ref: "gl_hires.c:1144-1147 (read), gl_hires.c:1179 (gld_HiRes_WriteCache)"
        note: "Keyed on the source image mtime and discarded when it differs."
      - filename: "levelstat.txt"
        source_ref: "e6y.c:968"
      - filename: "levelinfo.txt"
        source_ref: "d_main.c:1049-1060, behind GL_DOOM and PRBOOM_DEBUG"
      - filename: "temp_a.nut, temp_v.nut"
        source_ref: "m_misc.c:1065-1066 (cap_tempfile1, cap_tempfile2)"

  user_supplied_paths:
    note: "Named on the command line or in the config, with no fixed filename"
    entries:
      - what: "IWAD, -iwad or autodetected from the standard names"
        source_ref: "d_main.c:144-165 (standard_iwads), d_main.c:977-990 (FindIWADFile)"
      - what: "PWADs, -file"
        source_ref: "d_main.c:1906-1927"
      - what: "DEHACKED and BEX patches, -deh, plus the dehfile_1 and dehfile_2 config keys and the autoload directories"
        source_ref: "d_main.c:2036-2055, d_main.c:2081-2099, m_misc.c:336-337"
      - what: "extra autoloaded WADs, wadfile_1 and wadfile_2"
        source_ref: "m_misc.c:334-335, d_main.c:1873-1895"
      - what: "autoload directories, <config dir>/autoload/doom-all and one per IWAD"
        source_ref: "d_main.c:1400-1414 (GetAutoloadBaseDir), d_main.c:1500-1519 (D_AutoloadIWadDir)"
      - what: "demos, -playdemo, -fastdemo, -record"
        source_ref: "r_demo.c:89-119, g_game.c:2570, g_game.c:3150"
      - what: "external high resolution texture packs, under textures/, flats/ and patches/"
        source_ref: "gl_hires.c:467-631 (hires_paths), gl_hires.c:703-719 (gl_texture_hires_dir or I_DoomExeDir)"
      - what: "savegames, DOOMSAVEDIR or the config directory"
        source_ref: "d_main.c:1019-1032, m_menu.c:957"
      - what: "response files, @name"
        source_ref: "d_main.c:1094-1112"

  external_programs:
    note: "Invoked as processes, not read as data files"
    entries:
      - what: "ffmpeg, video capture and muxing"
        source_ref: "m_misc.c:1062-1064 (cap_soundcommand, cap_videocommand, cap_muxcommand)"
      - what: "wget then unzip, fetching a WAD a game server asks for"
        source_ref: "d_client.c:236-257 (execlp), doc/prboom-plus.6:200-206"
      - what: "getwad_cmdline, run through system() when a needed WAD is missing"
        source_ref: "r_demo.c:1641-1704 (D_TryGetWad), m_misc.c:1029 (default empty, so the path is inert until configured)"