$ ./hode --4k --hd-wide --smooth --hd-cache=./cache --prerender
HD mode: 15x scale (3840x2880), 16:9 widescreen, disk cache, prerender
prerender level 0 (rock) [████████████████████████████████] 5320/5320 (100%) 6.9s

The original engine logic is preserved exactly — same 12.5 Hz tick, same .lvl / .sss / .mst / .paf data path, same per-level scripted callbacks. This fork adds a configurable presentation pipeline on top: chained-xBRZ HD upscaling with MLAA edge smoothing, 16:9 widescreen with palette-aware borders, decoupled 60 Hz interpolated render, persistent disk cache, sprite + cutscene prerender, plus a programmable Unix-socket automation API and a handful of menu / input / portability fixes.

The project uses a hand-written GNU Makefile. The only external dependency is SDL2. C++11 with warnings turned up (-Wall -Wextra -Wpedantic); the build is warning-free on macOS clang and Linux gcc.

make -j"$(nproc 2>/dev/null || sysctl -n hw.ncpu)"

Outputs ./hode (~800 KB binary). make clean removes objects and dependency files.

make -j"$(nproc 2>/dev/null || sysctl -n hw.ncpu)" \
  CPPFLAGS='-O2 -std=c++11 -Wall -Wextra -Wno-unused-parameter -Wpedantic -MMD'

#elif defined(__APPLE__)
  #include <libkern/OSByteOrder.h>
  #define le16toh(x) OSSwapLittleToHostInt16(x)
  #define le32toh(x) OSSwapLittleToHostInt32(x)
  #define htole16(x) OSSwapHostToLittleInt16(x)
  #define htole32(x) OSSwapHostToLittleInt32(x)
  static const bool kByteSwapData = (__BYTE_ORDER__ == __ORDER_BIG_ENDIAN__);

Step-by-step on a fresh macOS install:

# 1. Xcode Command Line Tools (clang + git)
xcode-select --install

# 2. Homebrew SDL2
brew install sdl2

# 3. Build
make -j"$(sysctl -n hw.ncpu)"

# 4. Run (data files alongside the binary)
./hode --hd

If brew is in /opt/homebrew (Apple Silicon default), make sure it's on PATH so sdl2-config resolves:

echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zprofile
source ~/.zprofile

$ make clean && make -j$(sysctl -n hw.ncpu) 2>&1 | tail -3
c++  -g -std=c++11 ... -c -o video.o video.cpp
c++  -o hode andy.o automation_api.o ... `sdl2-config --libs`

# Debian / Ubuntu / WSL
sudo apt install build-essential libsdl2-dev pkg-config

# Fedora / RHEL
sudo dnf install gcc-c++ SDL2-devel

# Arch
sudo pacman -S base-devel sdl2

make -j"$(nproc)"

Headless CI:

SDL_AUDIODRIVER=dummy xvfb-run -a ./hode --automation=/tmp/hode.sock --hd

WSL2 + WSLg (built into Windows 11) works out of the box:

sudo apt install build-essential libsdl2-dev pkg-config
make -j"$(nproc)"

Native Windows builds (MinGW / MSYS2) are not currently maintained — the Makefile assumes POSIX. Patches welcome.

Place these next to the binary or pass --datapath=PATH:

PSX disc data (*.dax, MDEC backgrounds, SPU ADPCM) is also supported — the HD upscaler works for both PC and PSX paths.

RELEASES.yaml (carried over from upstream) lists SHA-1 hashes for every game version validated against (French / German / English Win32, demos, PSX). If your data files act weird, compare them there.

# Vanilla 256×192 windowed (upstream behaviour)
./hode

# HD (1536×1152) at default 6× scale
./hode --hd

# 4K with 16:9 borders, 60 Hz interpolation, persistent cache, prerender first run
./hode --4k --hd-wide --smooth --hd-cache=./cache --prerender

# Skip menu, jump to Island level, checkpoint 2, in HD
./hode --level=isld --checkpoint=2 --hd

# Custom 9× scale (2304×1728)
./hode --hd-scale=9

# Scriptable mode — opens a Unix socket and disables menu/loading/cutscenes
./hode --automation=/tmp/hode.sock --hd

# Read data files from elsewhere
./hode --datapath=/Volumes/HOD-CD --savepath="$HOME/Library/Application Support/hode"

All flags use the GNU long form (--name or --name=value); there are no short flags.

Level names (also accept indices): rock, fort, pwr1, isld, lava, pwr2, lar1, lar2, dark.

CLI flags override matching hode.ini keys.

Place a hode.ini next to the binary (or in --datapath) for persistent configuration:

[engine]
disable_paf       = false   ; skip cutscenes (auto-true if HOD.PAF missing)
disable_mst       = false   ; skip monster scripting (debugging only)
disable_sss       = false   ; skip sound script (debugging only)
disable_menu      = false   ; boot straight into the game
max_active_sounds = 16      ; SSS object pool cap
difficulty        = 1       ; 0=easy, 1=normal, 2=hard
frame_duration    = 80      ; ms per game tick (default 80 = 12.5 Hz)
loading_screen    = true    ; show "please wait" image during level load

[display]
scale_factor      = 3       ; integer upscaler factor (legacy non-HD path)
scale_algorithm   = nearest ; nearest | linear | xbr | nearest+blur | …
gamma             = 1.0     ; output gamma (1.0 = neutral)
fullscreen        = false
widescreen        = false   ; legacy 16:9 path (blur-stretch). Prefer hd_widescreen.
hd_mode           = false   ; same as --hd
hd_scale          = 0       ; same as --hd-scale=N (0 = default 6)
hd_widescreen     = false   ; same as --hd-wide
hd_cache          = ./cache ; same as --hd-cache
smooth_anim       = false   ; same as --smooth
automation_socket = /tmp/hode.sock ; same as --automation

./hode (no flags) gives you the upstream behaviour: 256×192 indexed-colour framebuffer, integer-upscaled scale_factor times by SDL through the chosen software scaler. Behaviour and visuals match upstream hode exactly.

--hd / --fullhd / --4k / --hd-scale=N route every visible pixel through HdCompositor (hd_compositor.{h,cpp}):

• Background bitmap is upscaled once per screen change and reused.
• Each sprite is upscaled once per (content + dimensions + flip + palette) tuple and cached.
• HD framebuffer is RGBA32; SDL2 streams it to a SDL_Texture per frame.

xBRZ scales by 2×, 3×, 4× or 5× per pass; arbitrary scales decompose into two passes:

After the chained scale, mlaa_smooth() runs a morphological-edge-AA pass that softens stair-stepping artefacts on diagonal edges (cape, hair, plasma traces).

--hd-wide switches the HD framebuffer from 4:3 to 16:9. The 4:3 game stays centred; left and right margins are filled with a vertical gradient sampled from the top and bottom rows of the current screen's palette, then darkened to ~⅓ brightness so it reads as ambient atmosphere instead of fake gameplay. Borders re-sample whenever the screen changes, so they track lighting/mood per area.

--smooth decouples logic from rendering:

        ┌───── 12.5 Hz ─────┐         ┌───── ~60 Hz ─────┐
        │  game tick        │         │   render frame   │
        │  ‒ AI / physics   │   ──►   │   ‒ interpolate  │
        │  ‒ sprite list    │         │     prev → curr  │
        │  ‒ snapshot pos   │         │   ‒ blit to HD   │
        └───────────────────┘         └──────────────────┘

• Game tick stays at 80 ms (12.5 Hz). Collision, AI, sound, scripted callbacks behave exactly as upstream.
• Game::saveInterpolationState() snapshots (prev, curr) for Andy and every visible sprite at each tick.
• Game::renderInterpolatedFrame(t) — called at the render rate — blends with t ∈ [0,1].

The result is fluid on-screen motion with zero impact on gameplay timing.

--hd-cache=PATH makes every upscaled artifact persistent.

PATH/
├── 6x/                                  ← sprites at the active scale
│   └── spr_<key:016x>_<w>x<h>.raw      ← header (int32 w, int32 h) + w*h*4 RGBA
├── 8x/
└── paf/
    ├── 6x/
    │   ├── v00/                          ← cutscene 0 (intro)
    │   │   ├── f0000.raw
    │   │   └── …
    │   ├── v22/                          ← Canyon Andy-falling-with-cannon
    │   └── v24/                          ← Island Andy-falling
    └── 8x/

Each <scale>x/ directory is independent — switching --hd-scale populates a new directory without touching existing ones.

key = FNV-1a-64(
        decoded indexed bytes (w × h)
      ⊕ w little-endian uint16
      ⊕ h little-endian uint16
      ⊕ flags & 3                      ← horizontal-flip bit
      ⊕ palette FNV-1a-64
      )

Including the palette hash is the reason the same sprite content rendered with different on-screen palettes (between screens, cross-fade, cutscenes) gets distinct cache entries. Without this, low scales (HD/FullHD) would occasionally show wrong-coloured sprite frames as a stale entry was reused after a palette transition.

--prerender populates the cache up-front, once per level (tracked via Game::_hdPrerenderedMask). After Game::restartLevel() finishes loading the level and before the gameplay loop starts:

1. Sprite phase — walk every (sprite-type, frame, flip) tuple across:
   • the main level table _resLevelData0x2988PtrTable[0..31]
   • every screen's backgroundLvlObjectDataTable[0..7] (per-screen background animations: trees, water, ambient effects). Without this, those animations only upscaled the first time they appeared on-screen.
2. PAF phase — fast-forward decode the small in-gameplay clips (Canyon falling with cannon, Canyon falling, Island falling) plus the level's intro cutscene. Each not-yet-cached cutscene is decoded full-speed without audio/display/sleep so the existing HD frame callback writes every frame to disk.
3. Both phases share one progress bar:

   prerender level 0 (rock) [████████████████████████████....] 4720/5320 (88%) 5.2s eta 0.7s
   

_playedMask (watched cutscenes) is snapshotted/restored across each PAF prerender so your save isn't polluted with movies you didn't actually watch. After the bar completes, the engine pumps SDL once and re-baselines inp.prevMask = inp.mask so any held keys don't fire phantom press/release events on the first gameplay tick.

--automation=/tmp/hode.sock opens a non-blocking AF_UNIX SOCK_STREAM listening for one client at a time. Newline-delimited JSON in both directions.

--automation implies:

• 🚫 disable_menu = true — boot straight into gameplay
• 🚫 loading_screen = false — no "please wait"
• 🚫 disable_paf = true — cutscenes skipped

• One JSON object per line, terminated with \n.
• Server only responds to get_state and screenshot. Other commands are fire-and-forget.
• One client at a time. Connection drop is detected on next read(); engine continues and re-accept()s.

get_state reply:

{
  "andy": {
    "x": 128, "y": 96, "screen": 0,
    "anim": 0, "frame": 0, "sprite": 0,
    "hasCannon": true, "dying": false
  },
  "level": 0, "checkpoint": 0, "screen": 0,
  "endLevel": false,
  "monsters": [
    {"x": 200, "y": 100, "type": 1, "i": 0},
    {"x": 220, "y": 100, "type": 2, "i": 0}
  ],
  "monsterCount": 2
}

Input bit layout:

import socket, json

s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
s.connect("/tmp/hode.sock")
f = s.makefile("rwb", buffering=0)

def send(j): f.write((json.dumps(j) + "\n").encode())
def recv_line(): return json.loads(f.readline().decode())

# State snapshot
send({"cmd": "get_state"})
state = recv_line()
print(state["andy"], "monsters:", state["monsterCount"])

# Walk right + run for 30 ticks
send({"cmd": "input", "dir": 2, "act": 1, "frames": 30})

# Frame-by-frame step for 10 ticks
send({"cmd": "step", "count": 10})

# Screenshot — header then raw RGB
send({"cmd": "screenshot"})
hdr = recv_line()           # {"width":256,"height":192,"format":"rgb","size":N}
img = b""
while len(img) < hdr["size"]:
    img += s.recv(4096)
open("frame.rgb", "wb").write(img)

# Jump to a specific level
send({"cmd": "set_level", "level": 3, "checkpoint": 0})

# Linux
SDL_AUDIODRIVER=dummy xvfb-run -a ./hode --automation=/tmp/hode.sock --hd

# macOS (still needs a window server; for true headless use Linux in CI)
SDL_AUDIODRIVER=dummy ./hode --automation=/tmp/hode.sock

Drop-in Python drivers using the automation API. All require a running ./hode --automation=/tmp/hode.sock.

┌──────────────────── main.cpp ────────────────────┐
│  parse CLI / hode.ini → readConfigIni()         │
│  open SETUP.DAT       → Resource::loadSetupDat │
│  init SDL2/audio      → System::init / setupAudio│
│  if --hd : new HdCompositor                      │
│  if --automation : new AutomationApi             │
│  loop:                                           │
│    Game::loadSetupCfg                            │
│    apply keymap                                  │
│    Menu::mainLoop  (unless --automation)         │
│    Game::mainLoop(level, checkpoint)             │
└──────────────────────────────────────────────────┘
                  │
                  ▼
┌──────────────────── Game ────────────────────────┐
│  Resource (.lvl/.sss/.mst/.paf parsers)          │
│  Video (256×192 indexed framebuffer + palette)   │
│  PafPlayer (cutscene streaming)                  │
│  Mixer (software audio mix)                      │
│  HdCompositor* (optional HD path)                │
│  AutomationApi* (optional socket server)         │
│  per-level callbacks (level1_rock.cpp .. level9) │
└──────────────────────────────────────────────────┘
                  │
                  ▼
        ┌─────────────────────┐
        │   System (abstract) │  ← System_SDL2 (this build)
        │                     │     System_PSP, System_Wii (legacy)
        └─────────────────────┘
                  │
                  ▼
              SDL2 (Metal/OpenGL/D3D)

Original logic (256×192, 8-bit indexed)
        │
        ▼  drawScreen() collects sprite list (z-sorted)
        │
        ▼  HdCompositor::beginFrame(bgLayer, palette, screenNum, bgId)
        │   ‒ expand palette 6→8-bit
        │   ‒ if screen changed: SpriteUpscaler::upscaleBackground()
        │   ‒ memcpy _hdBackground → _hdFramebuffer
        │
        ▼  for each sprite:
        │     SpriteUpscaler::getOrUpscale(sprData, w, h, flags, palette)
        │       ‒ decodeSprToTemp(): RLE → indexed
        │       ‒ key = FNV-1a(indexed + dims + flags + palette hash)
        │       ‒ RAM lookup → disk lookup → upscale chain → MLAA → cache
        │     blitHdSprite(): alpha-test composite into _hdFramebuffer
        │
        ▼  HdCompositor::endFrame()
        │   ‒ if widescreen: compositeWidescreen() draws gradient borders
        │
        ▼  System_SDL2::copyRectRGBA(): SDL texture stream → present

HOD.PAF
  │   one container, k cutscenes, indexed by uint32 LE offset
  ▼
PafPlayer::preload(num)
  │   read sub-header, allocate 4 page buffers + demux blocks
  ▼
PafPlayer::mainLoop()                          ← _prerenderMode skips audio/display/sleep
  │   per frame:
  │     ‒ read N file blocks into demux buffers (video or ADPCM audio)
  │     ‒ decodeVideoFrame() → write current page buffer
  │     ‒ callback(frame) → gamePafFrameCallback (game.cpp)
  │           ├── (legacy) g_system->copyRect to 256×192 layer
  │           └── (HD) cache hit? → present
  │                   else upscale → save to disk → present
  │     ‒ if !prerender: setPalette + updateScreen + sleep frameMs
  ▼
PafPlayer::unload()

Level callbacks dispatch from Game::callLevel_* into the levelN_<code>.cpp matching _currentLevel.

Menu → Settings → Keyboard Controls lets you bind any of Run / Jump / Shoot / Special:

• ✅ Letters, digits, Shift, Ctrl, Alt – have icon glyphs in the engine's bitmap font.
• ✅ Space, Enter, Tab, Backspace, Cmd/Win – bindable; menu shows short text labels (SP, EN, TB, BS, WN).
• ✅ Two slots per action – first bind goes into slot 1, second into slot 2.
• ✅ One key, one action – binding a key already used by another action automatically clears the prior binding.
• ✅ Defaults stay live – LCtrl, F, LAlt, G, LShift, H, D, Space remain mapped to their defaults alongside any custom keys, so the in-menu Select handler always works while you're rebinding the rest.
• ✅ OK / Cancel / Test row – navigable via ←/→. Select on OK keeps changes, Cancel reverts, Test enters live key-press visualisation.
• ✅ Esc cancels bind – inside the bind prompt cancels the bind only; doesn't propagate to the outer menu.

--cheats=N is a bitmask:

--debug=N is OR'd into g_debugMask:

--debug=255 enables everything.

setup.cfg is the engine's binary save file (212 bytes, SetupConfig in defs.h:55). It tracks per player slot:

• Per-level progress (highest checkpoint reached)
• Last-played level + checkpoint
• Watched-cutscenes bitmask
• 32 bytes of controls (16 bytes joystick, 8 bytes keyboard scancodes, 8 unused)
• Difficulty, stereo, volume, last-level

Up to 4 player slots, selected via the menu.

A high-level diff vs usineur/hode master:

• 🎁 New modules — hd_compositor, sprite_upscaler, edge_smooth, automation_api, plus four Python automation drivers.
• 🚩 New CLI flags — --hd, --hd-scale, --hd-wide, --hd-cache, --fullhd, --4k, --smooth, --automation, --prerender.
• 📝 New INI keys — hd_mode, hd_scale, hd_widescreen, hd_cache, smooth_anim, automation_socket.
• 🔑 Sprite cache key changed from heap pointer to FNV-1a(content + dims + flags + palette hash). The upstream pointer-keyed disk cache effectively never produced cross-run hits.
• 📐 Widescreen window sizing — --hd-wide now also sizes the SDL window 16:9 (otherwise the wide framebuffer was squashed back into a 4:3 window and gradient borders were invisible).
• 🎨 Palette-correct beginFrame — HdCompositor::beginFrame() now expands the engine's 6-bit palette to 8-bit instead of treating it as already 8-bit, so border colours and HD sprite colours are not ~4× too dim.
• 🎬 PAF HD path with disk cache and a fast-forward prerender(num) that skips audio / display / sleep.
• 🌊 Smooth animation — 60 Hz interpolated render with 12.5 Hz logic.
• 🧰 Menu / input fixes — OK / Cancel / Test sub-buttons, one-key-one-action enforcement, Space / Enter / Tab / Backspace / Cmd-Win bindable, default keys stay live alongside custom keys, font-pointer init hardened, edge state cleared on waitForKeyPress.
• 🍎 macOS portability — intern.h selects <libkern/OSByteOrder.h> on __APPLE__.

• The HD compositor only supports the SDL2 backend. PSP / Wii are not HD-capable in this fork.
• --4k is internally 16× cropped to 15× to fit the 4K UHD frame; visible artifacts are below 1 px.
• Cutscene prerender at 4K can use multiple GB of disk per cutscene. For the full PAF set, prefer --hd or --fullhd.
• The legacy --widescreen (blur-stretch) is preserved for parity but --hd-wide is preferred when the HD compositor is on.
• The automation API supports one client at a time.

1. Fork the repo on GitHub
2. Branch off master:

   git checkout -b feature/<short-name>

3. Make changes; follow the existing style:
   • Tabs for indentation, K&R braces
   • snake_case for free functions, lowerCamelCase for methods, _member for fields
   • Plain C++11 — no STL containers in hot paths; raw arrays + malloc/free are fine
4. Build cleanly with -Wall -Wextra -Wpedantic (no new warnings)
5. Commit with a descriptive message and open a PR against this fork or usineur/hode

• Original engine — reverse-engineered by Gregory Montoir (cyx@users.sourceforge.net). See usineur/hode, upstream README.txt, and CHANGES.txt (preserved in this tree).
• Original game — Heart of Darkness by Amazing Studio (1998), published by Infogrames / Ocean.
• xBRZ-style scaling — based on Zenju's xBRZ algorithm — https://sourceforge.net/projects/xbrz/
• MLAA edge smoothing — classic anti-aliasing technique (Reshetov 2009 / Jimenez et al.)

External links:

• 🎮 MobyGames: Heart of Darkness
• 🌐 heartofdarkness.ca — fan resource
• 🐙 usineur/hode upstream

The engine source is provided under the same terms as upstream hode (no explicit LICENSE file in upstream — treat it as "use at your own risk; please credit the original author"). The HD additions in this fork inherit the same terms.

The Heart of Darkness game data (HOD.PAF, SETUP.DAT, *_HOD.*) is copyrighted by Amazing Studio / Infogrames and is not redistributed here. You must own a legitimate copy of the original game to play.