OpenBOR Runtime Engine Guide

The definitive engineering manual for the Open Beats of Rage runtime framework. Not an emulator. A software-driven 2D side-scrolling engine executing autonomous game packs with version-sensitive coupling, unlimited layers, and entity-based architecture.

Overview

OpenBOR is fundamentally not an emulator. It is a highly decoupled, software-driven, two-dimensional side-scrolling engine. Each game is a self-contained pack containing bespoke scripts, compiled assets, and localized runtime logic. The relationship between the executable and the game pack is highly sensitive and version-specific.

Beginning: Architectural Paradigm Shift

OpenBOR rejects hardware mimicry. It maps retro aesthetics to modern computing paradigms, leveraging host RAM rather than constrained emulated VRAM. Entities are self-contained programmatic game objects existing as single logical pointers in system memory. The engine supports unlimited layers, 16.7 million colors via 32-bit RGB rendering, and virtual framebuffers for perspective warping.

Pack Protocols: Paks/ (compiled .pak files), Logs/ (diagnostic output), Saves/ (version-sensitive binary config), ScreenShots/ (captured gameplay). Each pack is an autonomous software package that overrides engine assumptions via internal scripts.

Intermediate: Engine Profiles, Migration, and Input

Three Engine Performance Profiles: Legacy (Builds 3xxx-3743, SDL 1.2, ~750KB single-threaded), Mid-Cycle (Builds 4000-6391, SDL 2.0, GPU-accelerated), Modern (Build 7530+/v4.0, Object-Centric, heavy RAM, 32-bit assets). Input responsiveness governed by strict 25ms total latency budget.

Pit Stop Migration Pipeline: Stop 1 = Build 4153 (Legacy Stability), Stop 2 = Build 6391 (Mid-Cycle SDL 2.0 final), Stop 3 = Build 7530+ (Modern strict type handling). Never skip intermediate stops.

Nuclear Configuration Migration: Never reuse .sav files across versions. Delete old config, execute Headless Boot for fresh generation, remap inputs from scratch, scan OpenBorLog.txt for syntax errors.

Input Mapping Anomalies: Build 6391 controller slot shifting with identical controllers. Analog joystick deficiencies require native OpenBOR Options menu remapping, not frontend configuration.

Cabinet Killer Traps

12 critical failure points: (1) Treating OpenBOR as emulator, (2) Pack-engine version mismatch, (3) Reusing .sav across versions, (4) Controller slot shifting Build 6391, (5) Analog joystick not registering, (6) Skipping Pit Stop migration steps, (7) Zombie Variables from legacy saves, (8) Ebox/gravity misalignment after upgrade, (9) Injecting logic state directly, (10) 32-bit PNG assets on legacy engine, (11) Unzipping .pak files, (12) Frontend assumes Libretro API.

Advanced: Isolation Contract, Corruption Detection, Frontend Orchestration

Input Priority Hierarchy (inviolable): inputall Script > Level Keyscript > Entity Keyscript > Global key#.c > Default Engine Action. Never inject logic state directly into runtime.

Silent Corruption Detection via APAD protocol. Gravity refactor between Build 6391 and 4.0 displaces entities on Z-axis. Hitbox matrix: Red Box (Attack), Blue Box (Body), Green Box (Range).

Zombie Variables: Modern engine expects integer constants but legacy saves force string types. Flush Protocol: typeof() to detect, clearglobalvar() to purge.

Frontend Orchestration: Dummy File Protocols (.openbor/.bor extensions) for EmulationStation and LaunchBox. RetroPie wrapper scripts via runcommand.sh. CLI parameters for optimized execution.

Headless Boot Audit: 15-second CLI launch with four failure metrics (Process Survivability, Log String Integrity, Asset Compliance, Memory Leaks).

FAQ

Is OpenBOR an emulator? No. It is a runtime engine/framework for executing autonomous 2D beat-em-up game packs.

Why does my game crash after updating? Packs are version-coupled. Use Pit Stop Migration Pipeline.

Why are controller mappings scrambled? Version-sensitive binary offsets in .sav file. Delete and regenerate.

Why won't analog sticks work? Standalone binary ignores frontend configs. Remap in native OpenBOR Options menu.

How to add to LaunchBox/EmulationStation? Dummy File Protocol with wrapper scripts.

Characters floating after upgrade? Gravity refactor between 6391 and 4.0. Run APAD protocol.

Can I use latest build for all games? No. Packs are version-specific.

Multiplayer mapping shifts on reboot? Build 6391 slot shifting. Delete .sav files, use XInput wrappers.