libretro/emulators/thextech.yml

emulator: TheXTech
type: standalone
core_classification: game_engine
source: "https://github.com/TheXTech/TheXTech"
upstream: "https://github.com/TheXTech/TheXTech"
profiled_date: "2026-10-04"
source_commit: "a72915cd9a2c811f2388423775f20d75bb2107bd"
display_name: "TheXTech"
cores: []
systems: [smbx]

notes: |
  C++ reimplementation of the SMBX 1.3 engine. The engine itself ships
  no game assets; asset packs are searched at startup under every root
  of AppPathManager::assetsSearchPath(): the root itself (legacy
  layout), then each directory or archive of its assets/ folder.
  ref: src/main/asset_pack.cpp:249-378 (s_find_asset_packs),
       lib/AppPath/private/app_path.cpp:135-181

  A directory is scanned when it carries graphics/ui/, an archive when
  it carries _meta.ini. Two descriptors are recognized:
    _meta.ini      archive pack ([content] engine "TheXTech", platform
                   matching the running target, pack-id)
    gameinfo.ini   directory pack ([game] id, menu images under
                   [android])
  A pack under assets/ is ignored when no id could be read; the legacy
  root pack needs none.
  ref: src/main/asset_pack.cpp:125-207, 334-339

  The pack-selection menu loads an icon, a logo and a background. Only
  the logo is checked: without it the pack is ignored ("Could not load
  UI assets from possible asset pack").
  ref: src/main/asset_pack.cpp:115-117, 225-233, 282-283

  The selected pack is then loaded by GFX_t::load, which fails when one
  of the UI images it requires from graphics/ui/ is missing.
  ref: src/gfx.cpp:121-229, src/main/asset_pack.cpp:415-438

  TheXTech is content-agnostic. The reference packs that TheXTech
  releases alongside the engine are the SMBX 1.3 asset pack
  (`thextech-assets-smbx13`) and the free Adventures of Demo pack
  (`thextech-assets-adventures-of-demo`); any pack that satisfies the
  structure above runs.

  Paths below are written from a search root. TheXTech/ is the name the
  build gives its user directory (THEXTECH_DIRECTORY_PREFIX) and its
  system directory; the application directory is searched the same way.
  ref: CMakeLists.txt:297, lib/AppPath/private/app_path_unix.cpp:46, 103,
       lib/AppPath/private/app_path.cpp:87

files:
  # ================================================================
  # Pack discovery
  # ================================================================

  - name: "assets/"
    type: directory
    category: game_data
    path: "TheXTech/assets/"
    required: false
    source_ref: "src/main/asset_pack.cpp:131-181, 290-300, 313-319"
    note: "Every file directly under assets/ is opened as an archive and kept as a pack when it holds _meta.ini; every subdirectory is kept when it holds graphics/ui/. _meta.ini is read only through the archive prefix: [content] engine must be TheXTech, platform must match the build, pack-id names the pack."

  - name: "gameinfo.ini"
    category: game_data
    path: "TheXTech/gameinfo.ini"
    required: false
    source_ref: "src/main/asset_pack.cpp:126, 182-190, src/main/game_info.cpp:143"
    note: "Directory pack descriptor. [game] id names the pack, [android] logo/background override the menu images."

  - name: "thextech.ini"
    category: game_data
    path: "TheXTech/thextech.ini"
    required: false
    source_ref: "lib/AppPath/private/app_path.cpp:98, 196-222"
    note: "Read from the application directory at startup. [Main] force-portable = true makes that directory the user directory, so settings and saves stay next to the executable."

  # ================================================================
  # Images of the pack-selection menu
  # ================================================================

  - name: "thextech_128.png"
    category: game_data
    path: "TheXTech/graphics/ui/icon/thextech_128.png"
    required: false
    source_ref: "src/main/asset_pack.cpp:115, 225"
    note: "Pack icon. Loaded during pack scan, result not checked."

  - name: "MenuGFX2.png"
    category: game_data
    path: "TheXTech/graphics/ui/MenuGFX2.png"
    required: true
    source_ref: "src/main/asset_pack.cpp:116, 226-230, 334-335, src/gfx.cpp:201"
    note: "Main menu logo. Pack ignored if no logo loads; GFX_t::load requires it as well."

  - name: "background2-2.png"
    category: game_data
    path: "TheXTech/graphics/background2/background2-2.png"
    required: false
    source_ref: "src/main/asset_pack.cpp:117, 227-233"
    note: "Menu background. Loaded during pack scan, result not checked."

  # ================================================================
  # Core content (engine iterates on disk, filenames are the pack's
  # own; the directory contract is what the engine checks)
  # ================================================================

  - name: "graphics/"
    type: directory
    category: game_data
    path: "TheXTech/graphics/"
    required: true
    source_ref: "src/main/asset_pack.cpp:274, 326-327, src/gfx.cpp:121-229, src/load_gfx.cpp:120-123"
    note: "graphics/ui/ must exist for a directory to be scanned as a pack; GFX_t::load rejects the pack when a required UI image is missing."

  - name: "fonts/"
    type: directory
    category: game_data
    path: "TheXTech/fonts/"
    required: false
    source_ref: "src/fontman/font_manager.cpp:270, 477-499"
    note: "Raster fonts described by *.font.ini files. Without the directory, or with no font in it, the built-in fallback fonts are loaded."

  - name: "languages/"
    type: directory
    category: game_data
    path: "TheXTech/languages/"
    required: false
    source_ref: "lib/AppPath/private/app_path.cpp:311-315, src/core/language/language_common.cpp:72-83, 104-122"
    note: "thextech_<lang>.json and assets_<lang>.json translations. Without the directory no translation is listed."

  - name: "sound/"
    type: directory
    category: game_data
    path: "TheXTech/sound/"
    required: false
    source_ref: "src/sound.cpp:1319"
    note: "SFX directory, files named by sounds.ini. Game runs without sounds."

  - name: "music/"
    type: directory
    category: game_data
    path: "TheXTech/music/"
    required: false
    source_ref: "src/sound.cpp:1318"
    note: "Music tracks, files named by music.ini."

  - name: "sounds.ini"
    category: game_data
    path: "TheXTech/sounds.ini"
    required: false
    source_ref: "src/sound.cpp:1322, 1348-1354, 1363"
    note: "SFX index. A message box reports its absence and the game runs without SFX."

  - name: "music.ini"
    category: game_data
    path: "TheXTech/music.ini"
    required: false
    source_ref: "src/sound.cpp:1321, 1341-1347, 1356"
    note: "Music index. A message box reports its absence and the game runs without default music."

  - name: "editor.ini"
    category: game_data
    path: "TheXTech/editor.ini"
    required: false
    source_ref: "src/editor/editor_custom.cpp:962, 979, src/main/translate.cpp:888"
    note: "Item lists of the built-in editor, read when the translation table is built."

  - name: "intro.lvlx"
    category: game_data
    path: "TheXTech/intro.lvlx"
    aliases: ["intro.lvl"]
    required: true
    source_ref: "src/game_main.cpp:172-185, 224-250, 1095-1106"
    note: "Level shown behind the main menu. intro.lvl is opened when intro.lvlx is absent, and a level picked from introset/ takes the place of both; with none of the three the game exits on a fatal error."

  - name: "introset/"
    type: directory
    category: game_data
    path: "TheXTech/introset/"
    required: false
    source_ref: "src/game_main.cpp:194-222, 247, src/main/level_file.cpp:321-339"
    note: "Directory of .lvl/.lvlx intro levels; one is picked at random when present, otherwise the root intro level is opened. The Adventures of Demo pack carries none; these 19 levels come from the introset/ of the Nostalgic Paradise pack (Blue Edition 0.2.8b, nostalgic-paradise-stable.7z). A level reads custom graphics from introset/ and from the subfolder named after it (07/, 08/, 10/); every other block, BGO, NPC and background ID they use is present in the Adventures of Demo graphics."

  - name: "outro.lvlx"
    category: game_data
    path: "TheXTech/outro.lvlx"
    aliases: ["outro.lvl"]
    required: false
    source_ref: "src/game_main.cpp:857-869"
    note: "Level shown behind the credits, unless the episode names its own. outro.lvl is opened when outro.lvlx is absent."

  - name: "worlds/"
    type: directory
    category: game_data
    path: "TheXTech/worlds/"
    required: false
    source_ref: "src/main/menu_main.cpp:361-370"
    note: "Episodes shipped with the pack, listed next to the user's worlds directory."

  - name: "battle/"
    type: directory
    category: game_data
    path: "TheXTech/battle/"
    required: false
    source_ref: "src/main/menu_main.cpp:701-706"
    note: "Battle mode levels shipped with the pack."