emulator: SDLPAL
type: libretro
core_classification: official_port
source: "https://github.com/sdlpal/sdlpal"
upstream: "https://github.com/sdlpal/sdlpal"
profiled_date: "2026-03-25"
core_version: "v2.0.1"
display_name: "SDLPAL"
cores:
  - sdlpal
systems:
  - sdlpal

notes: |
  Game engine reimplementing the classic Chinese RPG PAL (Sword and Fairy)
  by SoftStar Inc. No BIOS or firmware required. All files are proprietary
  game data from the original 1995 DOS or 1998 Win95 release.

  Place game files in <system_dir>/sdlpal/ or point a .cfg at the game
  directory. The game is available on Steam (app 1546570). Auto-detects
  DOS vs Win95 game data.

  The libretro port disables MP3, OGG, OPUS, native MIDI, and CD audio
  backends (pal_config.h). Only RIX (mus.mkf) and software MIDI synthesis
  via Timidity/TinySoundFont (midi.mkf + user-provided soundfont) are
  available for music.

files:
  # ================================================================
  # Required game data archives
  # util.c:733-737 UTIL_CheckResourceFiles common_files[]
  # global.c:175-182 PAL_InitGlobals
  # ================================================================

  - name: "abc.mkf"
    category: game_data
    path: "sdlpal/abc.mkf"
    required: true
    source_ref: "util.c:734, global.c:55, battle.c:879"
    note: "Animation and battle character data archive."

  - name: "ball.mkf"
    category: game_data
    path: "sdlpal/ball.mkf"
    required: true
    source_ref: "util.c:734, global.c:177"
    note: "Magic effect graphics archive."

  - name: "data.mkf"
    category: game_data
    path: "sdlpal/data.mkf"
    required: true
    source_ref: "util.c:734, global.c:178"
    note: "Core game data archive (scripts, events, game logic)."

  - name: "f.mkf"
    category: game_data
    path: "sdlpal/f.mkf"
    required: true
    source_ref: "util.c:734, global.c:179"
    note: "Face/portrait graphics archive."

  - name: "fbp.mkf"
    category: game_data
    path: "sdlpal/fbp.mkf"
    required: true
    source_ref: "util.c:735, global.c:175"
    note: "Full-screen background picture archive (cutscenes, title)."

  - name: "fire.mkf"
    category: game_data
    path: "sdlpal/fire.mkf"
    required: true
    source_ref: "util.c:735, global.c:180"
    note: "Fire/spell effect graphics archive."

  - name: "gop.mkf"
    category: game_data
    path: "sdlpal/gop.mkf"
    required: true
    source_ref: "util.c:735, res.c:234"
    note: "Game object palette/graphics archive."

  - name: "map.mkf"
    category: game_data
    path: "sdlpal/map.mkf"
    required: true
    source_ref: "util.c:735, global.c:55, res.c:233"
    note: "Map tile and layout data archive."

  - name: "mgo.mkf"
    category: game_data
    path: "sdlpal/mgo.mkf"
    required: true
    source_ref: "util.c:736, global.c:176"
    note: "Map graphic object (sprite overlay) archive."

  - name: "pat.mkf"
    category: game_data
    path: "sdlpal/pat.mkf"
    required: true
    source_ref: "util.c:736, palette.c:53"
    note: "Palette data archive."

  - name: "rgm.mkf"
    category: game_data
    path: "sdlpal/rgm.mkf"
    required: true
    source_ref: "util.c:736, global.c:181"
    note: "RGM graphics archive."

  - name: "rng.mkf"
    category: game_data
    path: "sdlpal/rng.mkf"
    required: true
    source_ref: "util.c:736, rngplay.c:402"
    note: "RNG animation/cutscene sequence archive."

  - name: "sss.mkf"
    category: game_data
    path: "sdlpal/sss.mkf"
    required: true
    source_ref: "util.c:737, global.c:182"
    note: "SSS data archive (message offsets in chunk 3)."

  # ================================================================
  # Message/text data (both required in default mode)
  # text.c:718-719 PAL_InitText
  # ================================================================

  - name: "m.msg"
    category: game_data
    path: "sdlpal/m.msg"
    required: true
    source_ref: "util.c:740, text.c:718"
    note: "Message text data (dialog, story). Opened via UTIL_OpenRequiredFile in default mode."

  - name: "word.dat"
    category: game_data
    path: "sdlpal/word.dat"
    required: true
    source_ref: "util.c:741, text.c:719, global.c:197"
    note: "Word data (menu items, status labels, item/spell names)."

  # ================================================================
  # Object descriptions (DOS version only)
  # global.c:204 PAL_LoadObjectDesc -> ui.c:864
  # ================================================================

  - name: "desc.dat"
    category: game_data
    path: "sdlpal/desc.dat"
    required: false
    source_ref: "global.c:204, ui.c:864"
    note: "Object description strings. DOS version only (skipped for Win95). Returns NULL if absent."

  # ================================================================
  # Embedded font files (optional, DOS game data)
  # font.c:102-197 PAL_LoadEmbeddedFont
  # ================================================================

  - name: "wor16.asc"
    category: game_data
    path: "sdlpal/wor16.asc"
    required: false
    source_ref: "font.c:114"
    note: "Chinese character code mapping for embedded font. Silently skipped if absent."

  - name: "wor16.fon"
    category: game_data
    path: "sdlpal/wor16.fon"
    required: false
    source_ref: "font.c:172"
    note: "Chinese character bitmap font data. Used with wor16.asc for DOS font rendering."

  # ================================================================
  # Sound effect files (optional, at least one recommended)
  # sound.c:962-975 SOUND_Init
  # ================================================================

  - name: "voc.mkf"
    category: game_data
    path: "sdlpal/voc.mkf"
    required: false
    source_ref: "util.c:743, sound.c:969"
    note: "VOC format sound effects archive (DOS version). Preferred for DOS game data."

  - name: "sounds.mkf"
    category: game_data
    path: "sdlpal/sounds.mkf"
    required: false
    source_ref: "util.c:743, sound.c:964"
    note: "WAV format sound effects archive (Win95 version). Preferred for Win95 game data."

  # ================================================================
  # Music files (optional, at least one recommended)
  # audio.c:302-305 AUDIO_OpenDevice
  # ================================================================

  - name: "mus.mkf"
    category: game_data
    path: "sdlpal/mus.mkf"
    required: false
    source_ref: "util.c:744, audio.c:305"
    note: "RIX/OPL music archive. Default music source, played through OPL emulation."

  - name: "midi.mkf"
    category: game_data
    path: "sdlpal/midi.mkf"
    required: false
    source_ref: "util.c:744, midi.c:78, midi_tsf.c:68, midi_timidity.c:130"
    note: "MIDI music archive. Used when Music=MIDI is configured in sdlpal.cfg."

  # ================================================================
  # AVI cutscene videos (Win95 version only, optional)
  # aviplay.c:641-772 PAL_PlayAVI
  # Guarded by fEnableAviPlay && fIsWIN95 (global.c:192)
  # ================================================================

  - name: "1.avi"
    category: game_data
    path: "sdlpal/1.avi"
    required: false
    source_ref: "main.c:197"
    note: "Trademark screen video (Win95 only). Falls back to RNG animation if absent."

  - name: "2.avi"
    category: game_data
    path: "sdlpal/2.avi"
    required: false
    source_ref: "main.c:237"
    note: "Splash screen video (Win95 only). Falls back to sprite animation if absent."

  - name: "3.avi"
    category: game_data
    path: "sdlpal/3.avi"
    required: false
    source_ref: "uigame.c:162"
    note: "In-game event video (Win95 only)."

  - name: "4.avi"
    category: game_data
    path: "sdlpal/4.avi"
    required: false
    source_ref: "ending.c:418"
    note: "Ending sequence video part 1 (Win95 only)."

  - name: "5.avi"
    category: game_data
    path: "sdlpal/5.avi"
    required: false
    source_ref: "ending.c:420"
    note: "Ending sequence video part 2 (Win95 only)."

  - name: "6.avi"
    category: game_data
    path: "sdlpal/6.avi"
    required: false
    source_ref: "ending.c:485"
    note: "Ending sequence video part 3 (Win95 only)."