Supermodel (Sega Model 3) - Libretro Port (Modernized)

A modernized fork of the Sega Model 3 (Supermodel) Libretro core, optimized for modern Linux distributions and updated to C++17 standards.

Project lineage and review status

This branch is based on the official libretro/Libretro-Supermodel repository. Much of the modern Libretro frontend was originally developed by sgiannop/Libretro-Supermodel; that work remains the foundation of this integration and should be credited as such.

The subsequent integration, feature work, diagnosis, and validation were developed with assistance from ChatGPT 5.6 Sol as part of a study project. This disclosure is not a substitute for review: every change should be independently inspected and tested before it is accepted into an official release.

🚀 Key Improvements

• Unified Makefile: Single build configuration supporting 6 platforms (Linux, Windows, macOS, Android, RPi64, aarch64) following libretro/skeletor standards.
• Platform Auto-Detection: Automatic platform detection with sensible defaults; platform-specific source filtering for incompatible features.
• Native Libretro Audio: Removed legacy SDL audio dependency in favor of native audio_batch_cb synchronization at either the default 60 Hz cadence or native Model 3 timing.
• C++17 Migration: Replaced legacy SDL-based threading and synchronization with native C++17 std::mutex, std::lock_guard, and atomic operations.
• Ubuntu 24.04 Compatibility: Fixed header conflicts and link-time errors present in the original codebase specifically for modern GCC versions.
• Synchronous A/V Timing: Matches standalone Supermodel's default 60 Hz cadence and 735-sample stereo audio packets; RetroArch owns final A/V synchronization.
• Improved Input Mapping: Full support for Analog/Digital gamepads and keyboard out of the box with improved deadzone handling.
• Configurable Service & Test Buttons: Service and Test buttons are now mappable through the RetroArch input configuration.
• Force Feedback / Rumble: Full force feedback support for steering wheel games via the Libretro rumble interface.
• Linked Cabinets: Experimental API-native Model 3 networking through the Libretro Netpacket interface, without core-owned sockets or discovery.
• Game-aware NVRAM: Optional per-game Service Menu settings and first-boot Single/Stand Alone/No Link initialization while preserving ordinary frontend .srm ownership.
• True Widescreen: Expands the 3D horizontal field of view into a native 16:9 framebuffer, with an optional wide lower-background layer. Plain 4:3 stretching remains the frontend's responsibility.
• Libretro Portability: Remapped configuration, NVRAM, and asset paths to follow official Libretro standards (system and save directories).
• No External GL Dependency: GLEW replaced with glsym from libretro-common — no system GL extension library required on any platform.
• Android Support: Full NDK integration with architecture-specific optimization (arm64, arm with NEON, x86_64, x86) and OpenGL ES 3.0.
• macOS Universal Binary: Builds for both Intel (x86_64) and Apple Silicon (arm64) via osxcross with automatic CPU tuning.
• Raspberry Pi Optimized: GLES3 rendering with CPU-specific tuning for RPi5 (Cortex-A76), RPi4 (Cortex-A72), and generic aarch64.
• Windows Support: Full cross-platform support with dedicated Windows build targets using MinGW — no vendored prebuilt libraries required.

📂 Required Assets

The core follows standard Libretro conventions and uses the following location:

• Preferred path: [RetroArch System Directory]/supermodel/
• Files:
  • Games.xml is required to identify ROM sets. The official embedded copy is extracted on first use when no external file exists.
  • Music.xml is optional and enables the corresponding music metadata.
  • Supermodel.ini is an optional advanced, read-only override. The official embedded copy is extracted on first use; an existing file is always authoritative and is never updated by the core.

The initial port's [System]/supermodel/Config/ layout remains a compatibility fallback, but new installations should use the preferred flat directory.

Video geometry

Widescreen Mode reproduces Supermodel's native widescreen behavior instead of stretching the 4:3 image:

• Disabled renders the original 496x384 view.
• Widescreen expands full-screen 3D viewports horizontally inside a 16:9 framebuffer (683x384 at native resolution), while keeping 2D layers at their original geometry.
• Widescreen + Wide Background also stretches the lower 2D background layer to fill the side areas. HUD and upper overlays retain their original aspect.

Supermodel's standalone Stretch setting is intentionally not exposed: final 4:3-to-16:9 stretching is already provided by RetroArch's aspect-ratio and scaling controls. True widescreen renders about 37.7% more horizontal pixels than the native 4:3 mode, so its performance should be measured separately. Changes to Widescreen Mode take effect after restarting the content, matching the renderer-initialization semantics of standalone Supermodel.

At resolutions above native, 2D Layer Upscaling Filter selects Supermodel's own filter for tile layers before they are composited with the 3D scene. At 496x384 the engine deliberately uses nearest-neighbor filtering regardless of this option.

SCSP DSP Engine defaults to the current MAME-derived implementation. The legacy ElSemi engine is retained as a compatibility choice for titles such as Fighting Vipers 2. Both this setting and the 2D filter require a content restart. Sound and DSB music volume follow standalone's full 0–200% range.

Timing and synchronization

Model 3 Timing Mode offers the same default 60 FPS cadence used by standalone Supermodel and a native 57.524160 Hz mode. Both report 44100 Hz stereo audio. The default submits 735 samples per retro_run; native timing uses a deterministic fractional 766/767-sample cadence so the long-term audio rate remains exact. Native timing requires a multi-threaded emulation mode and is most useful with a display able to follow the reported refresh rate.

The core does not expose its own VSync setting: the Libretro frontend owns the display swapchain, video presentation, audio synchronization, and final sample rate conversion.

For objective performance checks, enable Frame Timing Overlay. Besides the engine's PPC, renderer, GPU, synchronization and sound timings, it shows 61-frame averages for the engine, frontend audio submission, overlay, final blit, miscellaneous core work, frontend presentation, total retro_run, the worst frame, actual frontend cadence, engine capacity, and callback capacity. At 60 Hz, sustained retro_run time must remain below the 16.67 ms frame budget; Present may include the frontend's VSync wait. Actual measures the real cadence between calls from the frontend, while Engine cap is derived from Supermodel's frame execution alone. Callback cap is the theoretical rate implied by all time spent inside retro_run and is not the displayed frame rate. Audio/pacing may include intentional frontend waiting when RetroArch audio synchronization is enabled.

Controller mappings and RetroArch input labels are selected automatically from the control signature declared by the loaded game. See Libretro control profiles for the complete catalog and the fallback rules.

NVRAM is normally persisted by the frontend as <content>.srm. To import a standalone Supermodel save, place <rom-set>.nv directly in the frontend save directory. The core reads .nv only when no .srm data was supplied. If both are present, .srm takes precedence and the ignored .nv path is reported in the log. An invalid .nv is ignored and replaced by default machine settings in a new .srm. The core never writes or overwrites the native .nv file.

Automatic Initial NVRAM Setup affects only a newly created save and supplies validated Single, Stand Alone, or No Link defaults for games that otherwise stop at a network check. NVRAM Settings is separate and disabled by default; when enabled, it exposes only the fields and values validated for the current ROM set and reapplies those per-game choices at startup.

Linked-cabinet networking

Network Board controls whether supported games see the emulated connection board. During RetroArch Netplay, the core uses only the official Libretro Netpacket interface; it does not open its own sockets or perform peer discovery.

The frontend and emulated-cabinet roles are deliberately paired. RetroArch assigns participant ID 0 to the host, which the core uses as the first Model 3 cabinet and network initiator. Therefore:

• start the RetroArch Netplay host before its clients;
• configure the RetroArch host as Master in the game's NVRAM settings or Service Menu;
• never configure a RetroArch client as Master;
• configure every Type 1 client as Slave; Type 2 clients may use a supported Slave / Satellite role.

Every peer must use the same ROM set, core version, Linked Cabinets value, and compatible timing settings. Changes made through NVRAM Settings take effect when the content is restarted.

🛠 Build Instructions

Unified Makefile System: This core uses a single unified Makefile supporting 6 platforms:

• Linux/Unix (native)
• Windows (MinGW cross-compile or native MSYS2)
• macOS (osxcross universal binary: x86_64 + arm64)
• Android (NDK: arm64, arm, x86_64, x86)
• Raspberry Pi 64-bit (RPi5, RPi4, generic aarch64)
• Generic aarch64 (ARM64 Linux)

Quick Start (All Platforms)

# Linux (default platform)
make -j$(nproc)

# Windows (cross-compile from Linux)
make platform=win -j$(nproc)

# macOS (osxcross from Linux)
make platform=osx -j$(nproc)

# Android (all architectures default to arm64)
make platform=android -j$(nproc)

# Raspberry Pi 64-bit
make platform=rpi64 -j$(nproc)

# Generic aarch64
make platform=aarch64 -j$(nproc)

# Debug build (any platform)
make DEBUG=1 platform=<platform> -j$(nproc)

# Clean build artifacts
make clean

---

Linux (Native Build)

1. Install Dependencies (Ubuntu/Debian)

sudo apt update
sudo apt install build-essential libgl1-mesa-dev libglu1-mesa-dev zlib1g-dev

2. Compile

make -j$(nproc)

3. Install

cp supermodel_libretro.so ~/.config/retroarch/cores/

---

Windows

You can build the core either natively on Windows or via cross-compilation from Linux.

Option A: Native Windows Build (MSYS2)

1. Install MSYS2: Download and install from msys2.org.
2. Open the "MSYS2 MinGW 64-bit" terminal (avoid the default MSYS terminal).
3. Install Dependencies:

   pacman -S mingw-w64-x86_64-toolchain mingw-w64-x86_64-make mingw-w64-x86_64-zlib

4. Compile:

   make platform=win -j%NUMBER_OF_PROCESSORS%

Option B: Cross-Compilation (from Linux)

1. Install the MinGW-w64 toolchain:

   sudo apt update
   sudo apt install binutils-mingw-w64-x86-64 g++-mingw-w64-x86-64 libz-mingw-w64-dev

2. Compile:

   make platform=win -j$(nproc)

Output: supermodel_libretro.dll → Copy to RetroArch cores/ directory.

---

macOS (Intel & Apple Silicon Universal Binary)

This core generates a universal binary supporting both Intel (x86_64) and Apple Silicon (arm64 M1/M2/M3+).

Option A: Native macOS Build

If building on a macOS system with Xcode installed:

# Install dependencies via Homebrew
brew install zlib

# Compile (generates universal binary)
make platform=osx -j$(sysctl -n hw.ncpu)

# Install
cp supermodel_libretro.dylib ~/.config/retroarch/cores/

Option B: Cross-Compilation from Linux (Recommended for CI/CD)

1. Install osxcross toolchain (to /opt/osxcross):

   sudo mkdir -p /opt
   sudo git clone https://github.com/tpoechtrager/osxcross /opt/osxcross
   cd /opt/osxcross
   
   # Download macOS SDK (follow osxcross documentation for MacOSX12.0.sdk)
   wget -nc https://github.com/rtrussell/osxcross-build/releases/download/12.0/MacOSX12.0.sdk.tar.xz
   mv MacOSX12.0.sdk.tar.xz tarballs/
   
   # Build osxcross
   sudo ./build.sh

2. Compile (Makefile auto-detects osxcross):

   # Universal binary (x86_64 + arm64)
   make platform=osx -j$(nproc)
   
   # With debug symbols
   make platform=osx DEBUG=1 -j$(nproc)

   The Makefile automatically:

   • Detects osxcross at /opt/osxcross
   • Uses o64-clang/o64-clang++ compilers
   • Configures SDK and deployment target
   • Generates universal binary for both architectures

   To override osxcross location:

   make platform=osx OSXCROSS_ROOT=/custom/path -j$(nproc)

3. Transfer to macOS (if building on Linux):

   scp supermodel_libretro.dylib user@mac:~/Downloads/
   # On Mac: cp ~/Downloads/supermodel_libretro.dylib ~/.config/retroarch/cores/

Build Details:

• Deployment Target: macOS 10.15 (Catalina) and newer
• Architecture: Universal binary (x86_64 + arm64)
• Renderer: Modern OpenGL 3.2+ (Legacy3D excluded)
• Build Time: ~90 seconds on 4 cores

---

Android (NDK)

Requires Android NDK. The Makefile checks ~/Android/Sdk/ndk/28.2.13676358 by default.

# arm64 (default and recommended)
make platform=android -j$(nproc)

# 32-bit ARM (armv7-a with NEON)
make platform=android arch=arm -j$(nproc)

# x86_64
make platform=android arch=x86_64 -j$(nproc)

# x86 (32-bit)
make platform=android arch=x86 -j$(nproc)

# Custom NDK path
NDK_ROOT=/path/to/ndk make platform=android -j$(nproc)

Build Features:

• Automatic NEON optimization for ARM architectures
• Position-independent code (PIC) for all binaries
• Static C++ runtime linking
• API level 24 (NDK Clang toolchain)
• GLES 3.0 rendering support

Output: supermodel_libretro_android.so → Copy to Android RetroArch cores directory (usually /data/data/com.retroarch/cores/)

---

Raspberry Pi 64-bit (RPi5, RPi4, aarch64)

Build for Raspberry Pi 4/5 with OpenGL ES 3.0 support.

1. Install Cross-Compilation Toolchain (on build machine)

sudo apt update
sudo apt install aarch64-linux-gnu-gcc aarch64-linux-gnu-g++ zlib1g-dev:arm64

2. Compile

# Raspberry Pi 5 (cortex-a76)
make platform=rpi64 -j$(nproc)

# or generic aarch64
make platform=aarch64 -j$(nproc)

The Makefile auto-tunes the CPU based on platform:

• rpi5: Cortex-A76 optimizations
• rpi4-64: Cortex-A72 optimizations
• rpi64 (default): Cortex-A53 optimizations
• aarch64: Generic aarch64 (no CPU-specific tuning)

3. Transfer to Raspberry Pi

scp supermodel_libretro_aarch64.so pi@raspberrypi:~/.config/retroarch/cores/supermodel_libretro.so

Platform Features:

• GLES 3.0 rendering via glsym_es3
• Legacy3D renderer excluded (GLES incompatible)
• Optimized for aarch64 ARM architecture
• Full force feedback support
• Synchronous 60 Hz audio (735 stereo samples per frame)

Performance Notes: On Raspberry Pi, performance varies by game and model:

• RPi 5: Can handle most games at native resolution
• RPi 4: Older/simpler titles (VF3, Daytona) run well; may need scaling for demanding titles
• RPi 3: Limited performance; resolution scaling recommended

---

Generic aarch64 (Standalone ARM64 Linux)

For generic ARM64 Linux systems (not Raspberry Pi):

make platform=aarch64 -j$(nproc)

Same as RPi64 but without CPU-specific tuning. Suitable for:

• ARM64 servers
• Generic ARM development boards
• Amazon Graviton instances
• Other aarch64 Linux systems

---

🎮 Performance Notes

For performance-heavy titles (e.g., Sega Rally 2 or Daytona USA 2), ensure you are running the core in Release mode. This core uses synchronous audio; if your CPU cannot maintain the full 60 Hz emulation speed, you may experience audio stuttering.

On Raspberry Pi, performance depends on the specific model and game. Older titles (e.g., Virtua Fighter 3) run well on Pi 4/5, while demanding titles may require resolution scaling adjustments via RetroArch core options.