SwordigoDesktop & Swordigo Runtime Engine (SRE)

Standard Binary Compatibility Layer, ARM64 JIT Execution Runtime, and Software Development Kit for Linux.

---

1. Overview

SwordigoDesktop is a open-source native Linux compatibility layer, reverse-engineering SDK, and modding toolchain for Touch Foo's Swordigo.

Instead of relying on heavy OS virtualization or high-overhead Android emulators, SwordigoDesktop implements a hybrid binary-translation architecture:

• Host Engine: Parses and maps original ARM64 ELF binaries (libswordigo.so) into a contiguous 64-bit virtual memory space.
• JIT CPU Acceleration: Executes ARM64 machine instructions using Dynarmic, a high-performance A64 Just-In-Time compiler configured with 512MB code cache allocation and targeted x86_64 FMA fast-paths.
• API Bridge Layer: Intercepts Android Bionic libc calls, GLES 1.1/2.0 graphics routines, OpenSL audio, and JNI methods, routing them directly to host-native SDL3, OpenGL, and OpenAL Soft APIs.
• Guest Trampoline Runtime (SRE): Injects libsre.so at guest address 0x2000000 via 16-byte ARM64 function trampolines to replace legacy GNU atomic string spinlocks, thread contention bottlenecks, and mobile rendering restrictions.

---

2. System Architecture

+-----------------------------------------------------------------------+
|                         Host Process (x86_64 Linux)                   |
|                                                                       |
|  swordigo_boot          SDL3 Window          OpenGL / Vulkan Pipeline |
|  |-- ELF Loader         |-- Input Events     |-- FBO Viewport Scaler  |
|  |-- JNI Bridge         |-- Keybindings      |-- PostFX (SSAO, Rays)  |
|  `-- ImGui Overlay      `-- Display Config   `-- Upscaler (FSR/Sharp) |
|                                                                       |
+-----------------------------------------------------------------------+
|                  Dynarmic A64 JIT CPU Core (512MB Cache)              |
|                                                                       |
|  +-----------------------------------------------------------------+  |
|  |                     Guest Address Space (3.5 GB)                |  |
|  |                                                                 |  |
|  |  libswordigo.so (0x1000000)   libsre.so (0x2000000)  JNI Structs|  |
|  |                                                                 |  |
|  |  <-- ARM64 Instructions Translated via Dynarmic JIT Core -->   |  |
|  +-----------------------------------------------------------------+  |
|                                                                       |
+-----------------------------------------------------------------------+
|                       Bridge & Trampoline Layer                       |
|  ~400 JNI & Native Function Bridges mapped to Host C++ implementations|
+-----------------------------------------------------------------------+

---

3. Subsystem Breakdown

3.1 Host Frontend & Binary Loader (src/loader/)

• ELF Parsing (elf_loader_arm64.cpp): Parses ELF64 headers, maps PT_LOAD segments with page-aligned permissions, and resolves R_AARCH64_RELATIVE, R_AARCH64_GLOB_DAT, and R_AARCH64_JUMP_SLOT relocations.
• Virtual Memory Map: Allocates a single 3.5GB page-aligned host buffer (calloc) ensuring low memory alignment.

3.2 CPU Execution Core (src/platform/emulator_dynarmic64.cpp)

• JIT Tuning: Configured with 512MB code cache to eliminate JIT block re-compilation stalls.
• Unsafe Fast-Paths: Enables Unsafe_UnfuseFMA to map ARM NEON FMA instructions to native x86 hardware FMA, and Unsafe_InaccurateNaN to bypass ARM canonical NaN bit pattern transformations.
• Instruction Cache Invalidation: Listens for IC IVAU / IC IALLU system instructions via InstructionCacheOperationRaised callbacks to invalidate JIT code blocks dynamically.

3.3 SRE Guest Runtime (src/sre/)

• Non-Atomic String Replacements (sre_string.c): Replaces GNU libstdc++ copy-on-write std::string atomic refcounting (LDAXR/STLXR) with single-threaded direct integer operations, eliminating exclusive monitor spinlocks.
• GLES Render Hooking (sre_background.c, sre_gui_native.c): Intercepts immediate matrix calls and raw CPU vertex arrays, converting them into modern GPU-side Vertex Buffer Objects (VBO).

3.4 FBO Viewport Scaler & PostFX (src/platform/fbo_scaler.cpp)

• Decouples native 960x544 game rendering from host desktop display resolution.
• Upscaling Algorithms: AMD FidelityFX Super Resolution (FSR 1.0), Sharp Bilinear, CRT Scanline simulation.
• Post-Processing Pass: Multi-pass Screen Space Ambient Occlusion (SSAO), 64-sample radial god rays, bloom extraction, and chromatic aberration.

---

4. Building and Toolchain Setup

4.1 System Prerequisites

Debian / Ubuntu:

sudo apt update
sudo apt install build-essential gcc-aarch64-linux-gnu \
    libsdl3-dev libsdl3-image-dev libgl-dev \
    libunicorn-dev libopenal-dev libvorbis-dev zlib1g-dev pkg-config

Fedora / RHEL:

sudo dnf install gcc gcc-c++ gcc-aarch64-linux-gnu \
    SDL3-devel SDL3_image-devel mesa-libGL-devel \
    unicorn-devel openal-soft-devel libvorbis-devel zlib-devel pkg-config

4.2 Building from Source

# Clone the repository
git clone https://github.com/TheCorrectSynovian/SwordigoDesktop.git
cd SwordigoDesktop

# Compile host executable and ARM64 guest library
make -j$(nproc)

# Launch the runtime environment
./run_swordigo.sh

---

5. Keybindings and Control Mapping

Key	Action	Subsystem
WASD / Arrow Keys	Character Movement	Game Input
Space / W	Jump / Double Jump	Game Input
J / Z	Sword Attack	Game Input
K / X	Magic Spell	Game Input
I	Inventory & Item Management	Game Input
Escape	Pause Menu / Configuration	Game Input
F1	Toggle SRT Debug Overlay	Host Overlay
F4	Cycle Viewport Upscaler Mode	FBO Scaler
F8	Pause / Resume CPU Emulation	Emulator Core
` (Backtick)	Open Raijin Interactive Lua Debug Console	Developer Console

---

6. Technical Documentation Index

All technical documentation, reverse-engineering analyses, and API specifications are unified in the docs/ directory:

• Architecture Specifications: Engine architectural designs, SRE platform master plans, Yuzu Dynarmic JIT research, Linux ELF loader specifications.
• ARM64 & Emulation: JIT correctness logs, LDXR/STXR exclusive monitors, ELF relocation inventories, memory layout audits.
• Graphics & Rendering: FBO viewport scaler design, GLES2 pipeline plan, PostFX remastering plans, GPU thread architecture.
• APIs & Subsystems: Native SRE hook reference (34 active hooks), Lua scripting catalog, GUI overlay APIs, VFS virtual filesystem.
• Formats & Schemas: PowerVR POD 3D model spec, PVR texture spec, Scene spec, Protobuf wire schema, Save file spec.
• Modding & SwKiwi: SwKiwi modloader architecture, RLSwordigo 7.0 reversing, modding guides, API audits.
• Release Notes: Version release notes from v1.0.0 through v8.0 Beta 1.
• Misc & Logs: Diagnostic traces, platform compatibility matrices, build guides.

---

7. License and Copyright

• SwordigoDesktop Engine & SRE Codebase: Released under the GNU General Public License v2.0 or later.
• Swordigo Game Assets: Original game assets, binaries, and trademarks remain the intellectual property of Touch Foo / Ville Mäkynen. This compatibility layer requires user-supplied game data files.