From 2300f16a299e44932c171f13a6639ab0509e4c0c Mon Sep 17 00:00:00 2001 From: matthewcodergamer Date: Mon, 14 Sep 2026 11:57:19 -0400 Subject: [PATCH 1/6] Docs: add native iOS GTA IV/V program plan --- docs/NATIVE_IOS_PROGRAM_PLAN.md | 654 ++++++++++++++++++++++++++++++++ 1 file changed, 654 insertions(+) create mode 100644 docs/NATIVE_IOS_PROGRAM_PLAN.md diff --git a/docs/NATIVE_IOS_PROGRAM_PLAN.md b/docs/NATIVE_IOS_PROGRAM_PLAN.md new file mode 100644 index 0000000..bbf3dd3 --- /dev/null +++ b/docs/NATIVE_IOS_PROGRAM_PLAN.md @@ -0,0 +1,654 @@ +# Native iOS Program Plan — GTA IV + GTA V + +This document defines the shipping architecture and zero-to-playable plan for native iOS builds based on the Xbox 360 versions of Grand Theft Auto IV and Grand Theft Auto V. + +The baseline device is **iPhone 11 / Apple A13**. Later iPhones should benefit from the same architecture with higher render scale, larger caches, and more thermal headroom. + +## 1. Architecture decision + +### Shipping architecture + +**Do not ship a runtime PowerPC JIT.** + +The final IPA architecture is: + +```text +owned Xbox 360 executable + | + | developer/build machine only + v +static PowerPC -> C++ recompilation + | + v +Apple Clang ARM64 + | + v +native ARM64 game/runtime code + | + +---- RAGE/platform host services + +---- VFS / audio / saves / input + +---- Xenos resource + shader translation + v +Metal + | + v +iPhone 11 / A13 +``` + +For GTA IV, the source/reference project is LibertyRecomp and the static recompilation path is ReXGlue-based. + +For GTA V, the clean public reference is SanRecomp, which targets the Xbox 360 release and uses XenonRecomp for PowerPC -> C++ recompilation. GTA V should become a separate `SanRecomp-iOS` project rather than mixing both games into one runtime repository. + +### Why no shipping JIT + +A JIT adds runtime translation overhead, executable-memory complexity, platform restrictions, larger failure surface, more RAM pressure, and unpredictable frame-time spikes. Static recompilation gives the compiler the whole program ahead of time and produces normal ARM64 code that can be optimized, linked, profiled, symbolicated, and packaged like a native iOS application. + +A JIT or emulator may still be useful **only as a development reference** on a Mac when comparing behavior, but it is not part of the IPA architecture. + +### What Git is for + +Git/GitHub is the source-control and CI layer, not the game execution layer. The development model is: + +```text +main + stable integration state + +feature/stage-N-name + one coherent milestone + +GitHub Actions + portable tests + macOS compile/tests + unsigned iOS ARM64 compile + artifact validation + +physical device gate + signed install + launch + Metal correctness + performance / memory / thermal +``` + +Never put proprietary game data in Git history. + +## 2. Two-project strategy + +### Project A — LibertyRecomp-iOS / GTA IV + +Repository: `matthewcodergamer/LibertyRecomp-iOS` + +Reference source: `matthewcodergamer/LibertyRecomp` + +Goals: + +- native ARM64 executable +- Metal renderer +- user-imported legally owned Xbox 360 game data +- touch + physical controllers +- saves, audio, lifecycle, diagnostics +- iPhone 11 / A13 30 FPS target +- final signed IPA + +This is the first production target because LibertyRecomp is already further along than the GTA V static-recomp project. + +### Project B — SanRecomp-iOS / GTA V + +Future repository: `matthewcodergamer/SanRecomp-iOS` + +Reference source: `OZORDI/SanRecomp` + +Goals: + +- Xbox 360 GTA V static recompilation +- native ARM64 application +- shared Apple platform concepts from the GTA IV project +- Metal renderer and Xenos resource translation +- iPhone 11 / A13 baseline +- touch/controller support +- final signed IPA + +Do **not** base this project on leaked GTA V source code, leaked mobile ports, redistributed Android game payloads, or unofficial binaries. Public reports of unofficial Android/Switch work may be useful as broad feasibility evidence only; no code, assets, or proprietary source from those projects should enter this repository. + +## 3. Shared Apple platform layer + +Do not prematurely create a third repository. First stabilize these interfaces inside LibertyRecomp-iOS, then extract only code that is actually reusable. + +Candidate shared modules: + +```text +ApplePlatform/ + Lifecycle + AppPaths + Logging + Diagnostics + MemoryPressure + ThermalState + AudioSession + ControllerDiscovery + TouchOverlay + FilesImporter + SaveExport + +MetalHost/ + Device + Queue + FrameContext + ResourceUpload + PipelineCache + ShaderCache + TexturePool + BufferPool + DynamicResolution + GPUCounters +``` + +Game-specific RAGE, patches, guest addresses, executable fingerprints, shader semantics, and resource rules remain in their own project. + +## 4. GTA IV zero-to-complete path + +### Phase IV-0 — Foundation + +Already underway. + +- pin exact LibertyRecomp revision +- CI +- prohibited-asset guard +- game version schema +- private-content verifier +- macOS reference path +- unsigned iOS shell compile + +Gate: all public CI green without GTA data. + +### Phase IV-1 — Reference build and reproducibility + +- fetch exact pinned LibertyRecomp commit +- preserve upstream ReXGlue/RAGE/VFS/audio/save/input/shader code +- build the macOS reference configuration +- record compiler, commit, executable revision, and renderer backend +- establish a deterministic supported Xbox 360 executable fingerprint + +Gate: a known private game revision boots in the reference project and the exact SHA-256 is recorded locally and then added to the public compatibility manifest as metadata only. + +### Phase IV-2 — iOS ARM64 platform target + +- make iOS ARM64 a first-class target +- iOS 16+ device deployment target +- Apple Clang +- no x86 translation +- Metal only for graphics +- no Vulkan or D3D backend in the shipping iOS target +- shell-only mode independent of GTA data +- compile-time feature toggles + +Gate: clean CI produces a linked unsigned ARM64 `.app` without proprietary payloads. + +### Phase IV-3 — Native application shell + +- UIKit/scene lifecycle +- Metal device/queue/drawable +- clear/present +- AVAudioSession +- GameController discovery +- file paths +- memory warnings +- thermal-state notifications +- foreground/background transitions +- diagnostics screen + +Gate on physical iPhone: 50 repeated cold launches and suspend/resume cycles without crash. + +### Phase IV-4 — Content import + +- use iOS Files picker +- validate selected extracted Xbox 360 game folder +- require known executable revision +- storage preflight +- `Game.staging` import +- validate completed staging tree +- atomic promote to `Game` +- mark game/cache data as excluded from iCloud backup +- keep saves exportable +- resumable/retryable failure flow + +Gate: interrupted import can never be mistaken for a valid installation. + +### Phase IV-5 — Static game linkage + +- run ReXGlue on the supported private executable on a build machine +- compile generated C++ as ARM64 +- link the recompiled executable code into the iOS app +- keep large game data external to the IPA +- embed build metadata linking app commit to supported game revision + +Gate: the native app enters the recompiled guest entry path. + +### Phase IV-6 — CPU semantic correctness + +Before gameplay debugging, prove: + +- integer carry/overflow +- rotates/masks +- CR/XER behavior +- endian loads/stores +- floating-point conversions/rounding/NaNs +- VMX permutations and saturation +- destination/source register aliasing +- atomics +- memory ordering +- timebase + +Gate: ReXGlue regression tests pass on ARM64 and known vector aliasing bugs remain covered. + +### Phase IV-7 — Guest memory + kernel/RAGE host services + +- guest address translation +- alignment checks +- allocation bookkeeping +- endian helpers +- crash diagnostics +- threads/events/mutexes/timers +- VFS +- async file I/O +- user/save containers +- input enumeration +- network stubs where required + +Gate: runtime initializes without unknown kernel/platform blockers. + +### Phase IV-8 — Metal renderer + +Bring-up order: + +1. clear/present +2. debug geometry +3. GTA vertex/index upload +4. first translated shader +5. first GTA draw +6. depth/stencil +7. textures/samplers +8. blending +9. render targets/resolves +10. post-processing + +Do not port an entire emulator GPU. Translate the game/runtime's Xenos-facing abstractions into Metal using the existing static-recomp renderer architecture. + +Gate: a GTA-generated draw produces recognizable geometry. + +### Phase IV-9 — Shader + resource correctness + +- Xenos texture formats +- tiling/untile +- endian conversion +- mips +- vertex formats +- index formats +- depth/stencil +- resolve semantics +- blend/alpha +- gamma/sRGB +- viewport/scissor +- sampler behavior +- Xenos shader -> Metal-consumable representation +- stable shader cache +- Metal pipeline-state cache + +Gate: logos/menu render without basic shader/resource corruption. + +### Phase IV-10 — Streaming/VFS + +Preserve GTA IV's original residency system instead of replacing it. + +- asynchronous RPF reads +- bounded staging buffers +- no main-thread storage I/O +- resource dependency order +- timely release of conversion/upload scratch memory +- per-frame streaming diagnostics + +Gate: long fast drives through the city do not deadlock and resident memory stops growing after warm-up. + +### Phase IV-11 — Physics/collision + +Debug from first divergence: + +```text +sector request + -> collision archive load + -> fixups + -> body creation + -> broadphase insertion + -> pair generation + -> narrowphase + -> contact +``` + +Never hide a CPU/runtime bug by moving the player upward or disabling collision. + +Gate: character and vehicles remain on streamed world geometry. + +### Phase IV-12 — Audio/media + +- reuse existing XMA path +- bounded audio buffers +- no blocking I/O in real-time callback +- interruption/route handling through AVAudioSession +- dialogue/radio/engines/weapons/cutscene validation + +Gate: 30-minute drive with stable audio and successful interruption recovery. + +### Phase IV-13 — Input and mobile controls + +One Xbox input abstraction, two input sources: + +- physical controller +- touch overlay + +Touch requirements: + +- left stick +- right camera region +- ABXY +- triggers/bumpers +- D-pad +- Start/Back +- L3/R3 +- on-foot and vehicle layouts +- size/position/opacity/deadzone/sensitivity editor +- auto-fade when controller is active + +Gate: opening gameplay is completable without a physical controller. + +### Phase IV-14 — Save/lifecycle safety + +- atomic save writes +- previous-save backup +- save import/export +- background pause +- safe Metal quiesce +- audio interruption +- drawable reacquisition +- controller rebind + +Gate: repeated suspend/resume and forced-exit tests do not corrupt saves. + +### Phase IV-15 — Gameplay certification + +Minimum path: + +launch -> logos -> title -> menu -> New Game -> opening -> player control -> first vehicle -> city drive -> mission transition -> save -> relaunch -> load -> continue. + +Gate: full sequence passes on iPhone 11. + +### Phase IV-16 — Open-world compatibility + +- every island +- fast driving +- traffic/peds +- wanted system +- weapons/explosions +- weather/day-night +- interiors +- boats/helicopters/motorcycles +- mission scripting +- long sessions + +Gate: no known base-story progression blocker. + +### Phase IV-17 — iPhone 11 optimization + +Only optimize measured bottlenecks. + +CPU: + +- reduce host abstraction overhead +- eliminate avoidable copies and allocations +- replace spin waits with appropriate synchronization +- batch high-frequency API calls +- use QoS rather than attempting hard core pinning +- keep game/render critical work latency-focused +- keep streaming/background work off the critical path + +GPU: + +- Metal-native render passes +- pipeline caching +- texture/buffer pools +- reduce redundant state transitions +- merge compatible passes +- reduce transient render-target bandwidth +- use original Xbox 360 assets first +- dynamic resolution +- reduced shadows/reflection cost under pressure + +Memory: + +- per-category accounting +- bounded shader/pipeline/resource caches +- aggressively release upload/untile scratch buffers +- memory-pressure trims +- no duplicate full game trees + +Thermal: + +- 30 FPS cap +- dynamic resolution first +- then shadow/reflection/post-effect reductions +- emergency cache trim +- never allow thermal adaptation to change mission logic + +Gate: sustained 30-minute session on iPhone 11 without jetsam and with acceptable thermal behavior. + +### Phase IV-18 — IPA release pipeline + +CI can produce unsigned compile artifacts. A final installable IPA requires Apple signing. + +Release flow: + +```text +clean checkout + -> fetch exact upstream pin + -> verify supported game revision metadata + -> generate/reuse static recompiled code + -> build shader artifacts + -> Xcode Release archive + -> sign/provision + -> export IPA + -> install on physical device + -> run certification suite +``` + +Never store signing certificates or provisioning profiles in the public repository. + +## 5. GTA V zero-to-complete path + +GTA V starts only after the GTA IV Apple platform and Metal lessons are stable enough to reuse. + +### Phase V-0 — Separate project bootstrap + +Create `SanRecomp-iOS` and pin `OZORDI/SanRecomp` to an exact commit. + +- no copied source snapshot +- no leaked GTA V source +- no Android-port binaries +- no game assets +- same prohibited-asset CI policy +- same private executable fingerprint model + +Gate: clean public repository with reproducible upstream pin. + +### Phase V-1 — Desktop oracle + +- build SanRecomp reference target first +- run XenonRecomp-generated code on desktop/macOS +- preserve all existing RAGE/recompiler work +- record first failing subsystem + +Gate: known reference build and diagnostics. + +### Phase V-2 — Reuse Apple platform shell + +Port only proven reusable pieces from LibertyRecomp-iOS: + +- lifecycle +- file importer +- paths +- audio session +- controller/touch layer +- diagnostics +- memory pressure +- thermal controller +- Metal frame host + +Do not copy GTA IV-specific patches or guest addresses. + +Gate: GTA V iOS shell builds unsigned on CI. + +### Phase V-3 — Static ARM64 linkage + +- XenonRecomp PPC -> C++ on build machine +- compile generated code with Apple Clang +- link native ARM64 +- no runtime JIT + +Gate: enter GTA V guest/runtime bootstrap. + +### Phase V-4 — RAGE host services + +- threads/synchronization +- VFS +- file I/O +- save/profile +- timers +- controller +- audio +- memory + +Gate: initialization proceeds to renderer startup. + +### Phase V-5 — Xenos -> Metal + +GTA V will need its own renderer correctness work even if the Metal host is shared. + +- resource formats +- shader translation +- render targets +- depth/stencil +- blending +- post-processing +- shadow maps +- resolves +- pipeline caching + +Gate: first GTA V-generated geometry. + +### Phase V-6 — Streaming + +GTA V has more content pressure than GTA IV, so the iPhone 11 plan must be strict: + +- original Xbox 360 assets only +- asynchronous reads +- bounded residency +- bounded conversion buffers +- no duplicate texture copies after upload +- aggressive cache eviction under memory pressure +- persistent pipeline/shader cache on disk + +Gate: prologue and first open-world transition without unbounded memory growth. + +### Phase V-7 — Gameplay systems + +- physics +- animation +- AI +- script VM +- cutscenes +- vehicles +- weapons +- audio +- saves + +First-divergence debugging remains mandatory. + +Gate: complete prologue and enter open world. + +### Phase V-8 — iPhone 11 performance mode + +The iPhone 11 target is **playable 30 FPS**, not visual parity with modern console/PC editions. + +Initial assumptions: + +- Xbox 360 content set +- 30 FPS cap +- dynamic internal resolution +- conservative shadows/reflections +- bounded population only if profiling proves necessary and only through safe, game-supported controls +- no high-resolution texture packs +- no PC-only effects +- precompiled/cached pipelines where practical + +Gate: sustained playable open-world drive on iPhone 11 without memory termination. + +### Phase V-9 — Full-story certification + IPA + +- mission compatibility database +- long-session soak tests +- save/reload +- background/foreground +- controller/touch +- thermal tests +- signed Release archive +- IPA install + +Gate: base story has no known progression blocker and the IPA is reproducibly buildable. + +## 6. iPhone 11 is the baseline, not the ceiling + +Do not design the project around the newest iPhone and then attempt to scale down later. + +Every major subsystem must have an A13 baseline mode first: + +- render scale +- shadow quality +- reflection frequency +- post-processing quality +- cache sizes +- staging-buffer limits +- streaming concurrency +- thermal response + +Newer iPhones can raise those limits after the baseline works. + +## 7. Definition of playable + +A build is not called playable because it reaches a menu. + +For this program, playable means: + +- native ARM64 executable +- no shipping JIT or x86 translation +- Metal rendering +- stable input +- stable audio +- safe saves +- game-data import +- repeatable launch +- open-world traversal +- mission progression +- bounded memory +- background/foreground safety +- acceptable sustained thermal behavior +- physical iPhone 11 validation + +## 8. Hard rules + +1. Never commit or redistribute Rockstar game assets or executable payloads. +2. Never use leaked GTA V source code as an implementation base. +3. Never make the shipping architecture depend on Xenia, Wine, Box64, Winlator, or runtime x86/PPC translation. +4. Never call a system fixed until the actual test/CI/device gate passes. +5. Never optimize before measuring. +6. Never hide a guest/runtime semantic failure with gameplay hacks. +7. Keep GTA IV and GTA V game-specific code separated. +8. Reuse the Apple platform layer only where the interface is proven common. +9. iPhone 11 remains the release baseline until explicitly changed. +10. 30 FPS is the initial performance contract; 60 FPS is a later-device enhancement, not a baseline requirement. From 0d3cc62b3f88c5c79bea0e92b7912b6c39ea0b78 Mon Sep 17 00:00:00 2001 From: matthewcodergamer Date: Mon, 14 Sep 2026 11:57:47 -0400 Subject: [PATCH 2/6] Docs: define iPhone 11 baseline performance budget --- docs/IPHONE11_BASELINE.md | 234 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 234 insertions(+) create mode 100644 docs/IPHONE11_BASELINE.md diff --git a/docs/IPHONE11_BASELINE.md b/docs/IPHONE11_BASELINE.md new file mode 100644 index 0000000..101a8f8 --- /dev/null +++ b/docs/IPHONE11_BASELINE.md @@ -0,0 +1,234 @@ +# iPhone 11 / A13 Baseline + +The iPhone 11 is the minimum performance target for both native static-recomp projects. + +This document defines initial engineering budgets. They are targets for measurement and tuning, not claims that a finished port already reaches them. + +## Core target + +- Device baseline: iPhone 11 / A13 +- Architecture: ARM64 +- Graphics API: Metal +- Minimum iOS target: iOS 16+ +- Primary frame-rate target: 30 FPS +- Frame budget: 33.33 ms +- Long-session target: at least 30 minutes without memory termination or unrecoverable thermal degradation + +## Render-scale strategy + +Do not render the game at the iPhone panel's full native resolution by default. + +### GTA IV initial range + +- nominal internal target: roughly 960x540 to 1280x720 +- dynamic-resolution controller tracks GPU frame time +- lower temporary floor is allowed during heavy scenes if needed to preserve frame pacing + +### GTA V initial range + +- nominal internal target: roughly 854x480 to 1280x720 +- expected typical range should be established by profiling, not guessed in advance +- prioritize stable frame pacing over short benchmark peaks + +Upscaling to the display is a presentation step. A later project stage may evaluate higher-quality spatial/temporal upscaling if it is cheaper than rendering more native pixels. + +## Frame-budget policy + +At 30 FPS: + +```text +Total budget 33.33 ms +CPU and GPU may overlap. +``` + +The profiler must separately report: + +- game thread +- render submission +- physics +- scripts/AI +- streaming +- audio +- GPU frame time +- drawable wait +- shader/pipeline creation + +No optimization decision should be based on FPS alone. + +## CPU policy + +The A13 has heterogeneous cores. Do not attempt unsupported hard affinity assumptions. + +Use host scheduling/QoS intentionally: + +- critical game/render work: latency-sensitive +- streaming/decompression/resource conversion: bounded worker pool +- audio: realtime-safe path, no blocking I/O +- diagnostics/cache maintenance: background/utility + +Rules: + +- avoid spin-wait loops +- avoid per-frame heap churn +- batch repetitive host calls +- remove redundant endian/conversion work from hot paths +- cache immutable translations +- do not create more workers than measured workloads justify + +## GPU policy + +Metal is the only shipping graphics API. + +Priorities: + +1. stable frame pacing +2. correct rendering +3. bandwidth reduction +4. pipeline reuse +5. resolution/quality scaling + +Use: + +- cached `MTLRenderPipelineState` objects +- bounded texture/buffer pools +- private GPU resources where appropriate +- short-lived staging buffers +- render-pass reuse where correctness permits +- Metal debug labels and GPU captures during development + +Avoid: + +- runtime shader compilation inside normal gameplay when artifacts can be prepared or cached +- keeping CPU and GPU copies of large resources after the CPU copy is no longer needed +- recreating pipelines every frame +- full-resolution transient effects without evidence they fit the budget + +## Quality ladder + +### Performance baseline + +- 30 FPS cap +- aggressive dynamic resolution +- Xbox 360 textures/assets/LOD first +- conservative shadows +- conservative reflections +- reduced expensive post-processing +- no MSAA unless a specific pass requires it for correctness + +### Balanced + +For later devices or scenes with headroom: + +- higher dynamic-resolution target +- improved shadow resolution/distance +- improved reflection frequency +- selected post effects restored + +### Quality + +Not an iPhone 11 certification requirement. + +## Memory policy + +The exact safe process limit varies with iOS/device state, so do not code against a guessed jetsam number. + +Instead maintain explicit categories: + +```text +recompiled code/runtime +RAGE guest memory +textures +GPU buffers +render targets +audio +streaming residency +resource-conversion scratch +shader cache +pipeline cache +UI/host platform +``` + +Initial engineering policy: + +- aim for a normal-play working set comfortably below the point where iOS memory pressure begins +- start with a conservative soft target near 2 GB resident memory and adjust only from physical-device measurements +- trim rebuildable caches immediately on memory warning +- bound every cache by bytes, not only entry count +- release conversion/upload scratch memory as soon as the GPU no longer needs it +- never keep duplicate extracted game installations +- do not load the whole world into RAM + +The Xbox 360 versions are chosen partly because their original content/streaming systems were designed around far smaller console memory budgets. Preserve that streaming discipline. + +## Streaming policy + +- async I/O +- no main-thread file reads +- limited request concurrency +- predictable staging-ring budget +- prioritize imminent gameplay assets +- release temporary untile/decompression buffers promptly +- instrument bytes read, queue depth, request latency, cache hit rate, and residency + +If streaming causes hitching, determine whether the cause is storage latency, decompression, fixups, upload bandwidth, or missing residency—not simply "make the cache bigger." + +## Thermal controller + +Thermal adaptation order: + +1. reduce dynamic render scale +2. reduce shadow cost +3. reduce reflection/update cost +4. reduce optional post-processing +5. trim nonessential caches/workers + +Do not change simulation speed, mission logic, physics tick semantics, or script timing to manage temperature. + +Track: + +- nominal +- fair +- serious +- critical + +A serious/critical event must be logged with frame time and memory state so the threshold can be tuned from real device data. + +## GTA IV baseline acceptance + +A candidate iPhone 11 build is acceptable only when it can: + +- launch reliably +- reach gameplay +- drive through streamed city sectors +- maintain usable 30 FPS-class frame pacing in representative scenes +- survive 30 minutes without memory termination +- survive background/foreground transitions +- save, quit, relaunch, and load + +## GTA V baseline acceptance + +GTA V has a stricter content-pressure problem. Initial certification is: + +- complete prologue +- enter open world +- drive continuously through multiple streamed areas +- stable controls/audio +- no unbounded memory growth +- no persistent shader-compilation stalls after warm-up +- no memory termination in a 30-minute run +- 30 FPS target with dynamic resolution and Xbox 360-class assets/settings + +If iPhone 11 cannot meet a gate, profile the first limiting subsystem. Do not immediately abandon the device target or switch to a translation/emulation stack. + +## Newer iPhones + +Newer devices inherit the same native ARM64/Metal path. They can scale upward through data-driven presets: + +- higher render scale +- larger caches +- better shadows +- more reflections +- more post-processing +- optional higher frame-rate targets + +The codebase should not require separate game ports for each iPhone generation. From fd05e27365e1d3bcb968583bd76679001daacb30 Mon Sep 17 00:00:00 2001 From: matthewcodergamer Date: Mon, 14 Sep 2026 11:58:05 -0400 Subject: [PATCH 3/6] Docs: link native iOS program plan --- README.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/README.md b/README.md index 016811f..638e7b5 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,15 @@ The compatibility manifest intentionally has **no invented GTA IV hash**. Until - Final artifact: signed `.ipa` - Game data: imported separately from a legally owned Xbox 360 copy +## Native GTA IV + GTA V program plan + +The project now has a program-level architecture for taking both Xbox 360 titles to native iOS without making runtime emulation/JIT the shipping design: + +- [`docs/NATIVE_IOS_PROGRAM_PLAN.md`](docs/NATIVE_IOS_PROGRAM_PLAN.md) — GTA IV and GTA V zero-to-playable architecture, Git workflow, static recompilation strategy, Metal path, content/import model, physical-device gates, and IPA release flow. +- [`docs/IPHONE11_BASELINE.md`](docs/IPHONE11_BASELINE.md) — A13 frame-time, rendering, memory, streaming, GPU, and thermal policy. + +GTA IV remains the first production target in this repository. GTA V should use a separate future `SanRecomp-iOS` project pinned to the public Xbox 360 static-recomp work, while reusing only Apple-platform components that have been proven reusable here. Leaked GTA V source or redistributed unofficial mobile payloads are not an acceptable implementation base. + ## What is never committed This repository contains code, tooling, tests, documentation, and build infrastructure only. Do not commit `default.xex`, RPF archives, Xbox disc/ISO/STFS payloads, Rockstar assets, locally generated proprietary game payloads, signing certificates/private keys, or provisioning profiles. CI enforces the obvious cases. From d37be344140692cb0f5aae9a7c48407a7c5cc497 Mon Sep 17 00:00:00 2001 From: matthewcodergamer Date: Mon, 14 Sep 2026 12:06:10 -0400 Subject: [PATCH 4/6] Plan GTA V iOS source-vs-static-recomp strategy --- docs/GTA5_SOURCE_VS_X360_DECISION.md | 140 +++++++++++++++++++++++++++ 1 file changed, 140 insertions(+) create mode 100644 docs/GTA5_SOURCE_VS_X360_DECISION.md diff --git a/docs/GTA5_SOURCE_VS_X360_DECISION.md b/docs/GTA5_SOURCE_VS_X360_DECISION.md new file mode 100644 index 0000000..e414815 --- /dev/null +++ b/docs/GTA5_SOURCE_VS_X360_DECISION.md @@ -0,0 +1,140 @@ +# GTA V iOS — Source Port vs Xbox 360 Static Recomp Decision + +## Decision + +There are two technically serious native-iOS routes. Which one is primary depends on whether the GTA V source tree is lawfully obtained and licensed for use. + +### Route A — lawful complete source tree: preferred technical route + +If we have a complete, lawfully obtained GTA V source tree and the right to modify/use it, the fastest native-iOS architecture is a direct ARM64 source port: + +```text +GTA V source + -> remove/replace Windows/console platform layer + -> Apple Clang ARM64 + -> native iOS runtime + -> direct Metal renderer + -> iPhone 11/A13 +``` + +Why this is technically best: + +- no runtime CPU translation +- no PowerPC semantic emulation layer +- no big-endian guest-memory model unless the source itself requires one +- whole-program optimization by Apple Clang/LLVM +- direct access to RAGE systems for profiling and mobile-specific fixes +- easier symbolication and crash diagnosis +- highest ceiling for A13 optimization + +The main cost is the platform port: Windows/Direct3D dependencies, middleware, file systems, threading, input, audio, launcher/DRM assumptions, and renderer backends must be replaced or isolated. + +### Route B — public/legal clean-room route: Xbox 360 static recomp + +If the source tree cannot legally be used, use `OZORDI/SanRecomp` + XenonRecomp as the primary public route: + +```text +owned Xbox 360 default.xex + -> XenonRecomp PowerPC -> C++ on build machine + -> Apple Clang ARM64 + -> SanRecomp RAGE/runtime host + -> Xenos resource/shader translation + -> Metal + -> iPhone 11/A13 +``` + +This route is slower at the CPU/runtime-correctness level but has two major iPhone advantages: + +- Xbox 360-era data/settings were designed for a 512 MB console memory system +- the public project already has PowerPC->C++, RAGE/runtime structures, installer/VFS work, and a Metal-capable renderer abstraction in progress + +No shipping JIT is planned for either route. + +## Do not use the PC binary + translation stack as the final architecture + +A Windows x86-64 binary route such as x86-64 emulation/translation + Win32 compatibility + D3D translation may be useful only as a temporary experiment. It is not the target IPA architecture because it adds: + +- CPU translation overhead +- JIT/executable-memory complications on iOS +- Win32 API compatibility work +- D3D -> intermediate API -> Metal translation overhead +- extra memory pressure +- harder frame pacing and thermal control +- harder debugging and App Store-style signing/distribution constraints + +For a real native IPA, compile source or statically recompiled C++ to ARM64 ahead of time. + +## PC-source vs Xbox-360-static-recomp comparison + +| Category | Lawful PC/console source port | Xbox 360 static recomp | +|---|---|---| +| CPU efficiency ceiling | Best | Very good once correct | +| Time to ARM64 code | Fast if source builds cleanly | Recompiler already exists, but semantic fixes remain | +| Renderer work | D3D/console backend -> Metal | Xenos abstraction/shaders -> Metal | +| Memory pressure | PC content/config can be heavy | Much better baseline because 360 was memory constrained | +| Asset size | Heavier unless mobile profile is created | Better mobile starting point | +| Debuggability | Best | Good with guest-PC/runtime diagnostics | +| Legal/public collaboration | Only if rights permit | Best public clean-room route | +| iPhone 11 optimization access | Best | Good, but guest/runtime semantics constrain changes | +| Risk | middleware/platform dependencies | recompiler/runtime/render correctness | + +## Recommended program + +### If lawful source is available + +1. Create a private `GTA5-iOS-source-port` workspace. Do not put proprietary Rockstar source into the public repo. +2. Build the source unchanged on its supported desktop target first. +3. Inventory platform boundaries: renderer, OS, threads, VFS, input, audio, networking, launcher/DRM, media, middleware. +4. Add an ARM64 Apple target that compiles engine/runtime code without rendering. +5. Bring up a minimal native iOS shell and enter RAGE initialization. +6. Replace graphics with a direct Metal backend. Avoid Vulkan/DXVK in the final build. +7. Create an A13 mobile configuration using Xbox-360-class visual targets: 30 FPS, dynamic 480p-720p internal resolution, low/medium shadows, conservative reflections/post FX, bounded streaming pools. +8. Reduce content residency and optional PC-era features before reducing simulation correctness. +9. Add touch/controller input, AVAudioSession, lifecycle, saves, importer/asset deployment. +10. Profile on iPhone 11 and tune CPU/GPU/memory/thermal independently. +11. Package/sign IPA only after physical-device certification. + +### If source cannot legally be used + +Continue with SanRecomp/XenonRecomp as the clean route and reuse the Apple-platform lessons from LibertyRecomp-iOS. + +## A13 baseline rules + +- iPhone 11 is the minimum certification target. +- 30 FPS target: 33.33 ms frame budget. +- Direct Metal only in the shipping build. +- Dynamic internal resolution, initially 480p-720p class for GTA V. +- Do not target native display resolution on A13. +- Xbox-360-class texture/LOD quality first. +- No MSAA by default unless required for correctness. +- Cache Metal pipeline states; do not create pipelines in gameplay hot paths. +- Async file I/O; no main-thread streaming reads. +- Bound texture, audio, shader, pipeline, and conversion caches by bytes. +- Release transient upload/decompression/untile buffers immediately when safe. +- Treat ~2 GB resident memory as an initial soft engineering target only; actual thresholds must come from physical-device measurements. +- Thermal degradation order: render scale -> shadows -> reflections -> post effects -> cache/worker trim. +- Never alter mission logic, physics tick rate, or script semantics to manage temperature. + +## Why a 2017 MacBook Air can run GTA V while an iPhone still needs a port + +Raw CPU/GPU capability is not the only variable. The Mac can run an existing x86-64 Windows build with a mature PC renderer, has more sustained cooling/power and typically more system memory. The iPhone must run an ARM64/Metal build, has 4 GB-class total memory on the iPhone 11, uses passive cooling, and iOS can terminate memory-heavy processes. A native port removes much of the architectural overhead, but it still has to be engineered for the phone's memory, graphics API, lifecycle, and thermal envelope. + +## Current public evidence + +- SanRecomp publicly targets GTA V Xbox 360 static recompilation with XenonRecomp and has Apple/Metal paths in its build/runtime. +- Current public reporting on the unofficial native Switch GTA V port shows ARM-native execution is feasible on 4 GB-class hardware, but that project is reported to rely on leaked Rockstar source and therefore is not a code source for this project. +- The useful lesson from that work is architectural: native ARM compilation plus aggressive memory/content/graphics tuning can outperform compatibility-layer approaches. + +## Immediate next engineering step + +Do not build two full implementations at once. First determine the legal/technical status of the available source tree: + +- exact branch/version +- complete or partial +- desktop buildability +- renderer APIs present +- platform abstraction layout +- middleware dependencies +- whether its license/rights permit modification and use + +If it is lawfully usable and complete, source-port architecture becomes GTA V Track A. SanRecomp remains Track B and a valuable behavioral/reference implementation. If not, Track B becomes primary. \ No newline at end of file From e25eed1b62c6aa8f8ad2caf49d1bfa880a586a86 Mon Sep 17 00:00:00 2001 From: matthewcodergamer Date: Mon, 14 Sep 2026 12:18:22 -0400 Subject: [PATCH 5/6] Plan Switch/Android reference reuse for GTA V iOS --- docs/GTA5_SOURCE_VS_X360_DECISION.md | 100 +++++++++++++++++++++++++-- 1 file changed, 94 insertions(+), 6 deletions(-) diff --git a/docs/GTA5_SOURCE_VS_X360_DECISION.md b/docs/GTA5_SOURCE_VS_X360_DECISION.md index e414815..121b71f 100644 --- a/docs/GTA5_SOURCE_VS_X360_DECISION.md +++ b/docs/GTA5_SOURCE_VS_X360_DECISION.md @@ -78,6 +78,91 @@ For a real native IPA, compile source or statically recompiled C++ to ARM64 ahea | iPhone 11 optimization access | Best | Good, but guest/runtime semantics constrain changes | | Risk | middleware/platform dependencies | recompiler/runtime/render correctness | +## Switch/Android port reuse strategy — work smarter, but reuse the right layer + +The unofficial Switch/Android work is valuable because it can eliminate discovery work, but it does **not** mean a compiled Switch or Android game can simply be renamed into an IPA. + +### Best case: source + rights are available + +If a Switch/Android port's source is legally usable, reuse the source-level work that is genuinely portable: + +- ARM64 fixes +- pointer/alignment fixes +- endianness assumptions already removed +- reduced memory pools +- lower-resolution render targets +- mobile LOD/settings tables +- asset-conversion recipes +- shader simplifications +- streaming/cache limits +- controller/input abstraction changes +- build-time feature disables + +Then replace only the platform-specific host: + +```text +optimized ARM64 GTA V source + | + +-- Switch Horizon/libnx host [replace] + +-- Android/Bionic host [replace] + v +iOS/Darwin host + +-- UIKit lifecycle + +-- Mach-O / Apple Clang + +-- Metal + +-- AVAudioSession + +-- GameController + +-- iOS Files/storage paths + v +iPhone 11 +``` + +This is the shortest legitimate source-level route because the expensive ARM/mobile optimization work can be preserved while only the OS/GPU integration is retargeted. + +### If only a compiled Switch build exists + +A Nintendo Switch `.nro`/`.nso` is ARM64, but it targets Horizon OS, Nintendo/libnx APIs, a different executable format/ABI environment, and Switch graphics/audio/input services. iOS expects Mach-O binaries, Darwin system libraries, Apple lifecycle APIs, and Metal. + +Therefore a compiled Switch binary is **not** a drop-in iOS binary. A loader/compatibility layer would become its own binary-translation/OS-emulation project and is not our preferred fastest path. + +### If only a compiled Android build exists + +An Android ARM64 `.so`/APK is also not directly linkable into an iOS app. Android uses ELF, Bionic/Linux APIs, Android lifecycle/JNI and typically GLES/Vulkan-facing platform code; iOS uses Mach-O, Darwin/UIKit and Metal. + +Again, source-level reuse is much better than binary wrapping. + +### Assets: reuse the recipe, not redistributed game data + +Do not place Rockstar assets, another project's compressed game pack, or leaked/proprietary build products in the public GitHub repository. + +Instead reproduce the mobile asset transformation against the user's own legally obtained game files: + +```text +owned GTA V data + -> asset audit + -> per-class mobile conversion manifest + -> texture resize/recompression where safe + -> LOD/mobile settings generation + -> audio/video policy + -> validation hashes + -> local/private output +``` + +The public repo can contain conversion code, manifests, tests, expected metadata, and documentation without containing the transformed copyrighted game data itself. + +### Practical priority order + +1. Obtain/identify a legally reusable source-level Switch or Android port, if one exists. +2. Diff its ARM/mobile changes against the original lawful GTA V source tree. +3. Extract only portable engine/optimization changes into a private source workspace. +4. Reproduce its asset optimization as scripts/manifests against owned GTA V files. +5. Replace Horizon/Android platform code with iOS/Darwin. +6. Implement/directly use Metal rather than carrying a Switch/Android graphics compatibility layer into the shipping build. +7. Compile ARM64 ahead of time and package as a native Mach-O iOS app. +8. Profile on iPhone 11 and continue optimization from measured bottlenecks. + +This is the preferred shortcut if lawful source-level reuse is available. + ## Recommended program ### If lawful source is available @@ -123,18 +208,21 @@ Raw CPU/GPU capability is not the only variable. The Mac can run an existing x86 - SanRecomp publicly targets GTA V Xbox 360 static recompilation with XenonRecomp and has Apple/Metal paths in its build/runtime. - Current public reporting on the unofficial native Switch GTA V port shows ARM-native execution is feasible on 4 GB-class hardware, but that project is reported to rely on leaked Rockstar source and therefore is not a code source for this project. +- Public reporting in September 2026 says the same developer is working on an Android build, but this does not establish a public, legally reusable source repository. - The useful lesson from that work is architectural: native ARM compilation plus aggressive memory/content/graphics tuning can outperform compatibility-layer approaches. ## Immediate next engineering step -Do not build two full implementations at once. First determine the legal/technical status of the available source tree: +Do not build two full implementations at once. First determine what reusable source-level material actually exists and can legally be used: -- exact branch/version +- exact Switch/Android project and revision +- whether source is public or private +- license/rights status - complete or partial -- desktop buildability -- renderer APIs present +- asset pipeline scripts versus redistributed assets +- ARM64/mobile patches +- renderer API/backend - platform abstraction layout - middleware dependencies -- whether its license/rights permit modification and use -If it is lawfully usable and complete, source-port architecture becomes GTA V Track A. SanRecomp remains Track B and a valuable behavioral/reference implementation. If not, Track B becomes primary. \ No newline at end of file +If lawful source-level Switch/Android work exists, use it as a shortcut and retarget the platform layer to iOS. If only compiled binaries exist, do not make binary wrapping the primary route; fall back to the lawful GTA V source-port path or SanRecomp clean-room path. \ No newline at end of file From d1dc3bbb37043020b628295c8878e19e500f2235 Mon Sep 17 00:00:00 2001 From: matthewcodergamer Date: Mon, 14 Sep 2026 12:33:32 -0400 Subject: [PATCH 6/6] Document GTA V code-first, assets-later workflow --- docs/GTA5_CODE_FIRST_ASSETS_LATER.md | 200 +++++++++++++++++++++++++++ 1 file changed, 200 insertions(+) create mode 100644 docs/GTA5_CODE_FIRST_ASSETS_LATER.md diff --git a/docs/GTA5_CODE_FIRST_ASSETS_LATER.md b/docs/GTA5_CODE_FIRST_ASSETS_LATER.md new file mode 100644 index 0000000..2759f90 --- /dev/null +++ b/docs/GTA5_CODE_FIRST_ASSETS_LATER.md @@ -0,0 +1,200 @@ +# GTA V iOS — Code First, Assets Later + +This document defines a staged workflow for preparing a GTA V iOS port before the full game-data set is available on the development machine. + +## Legal/source boundary + +Owning GTA V on Epic Games gives access to the installed game data for that copy, but it does not by itself grant rights to proprietary Rockstar source code. Do not place Rockstar source, leaked source, game assets, private keys, or redistributed mobile/Switch game packs in this public repository. + +If a complete GTA V source tree is lawfully available and may be modified, keep it in a separate private workspace. If not, use the public SanRecomp/XenonRecomp clean-room route. + +## Goal + +Do as much iOS-specific engineering as possible before importing the real GTA V assets. The codebase should be able to build, launch, initialize platform services, exercise the renderer, and validate the asset pipeline with synthetic fixtures. + +## Phase 0 — Public iOS scaffold + +Build without GTA V data: + +- Apple Clang ARM64 target +- iOS 16+ deployment target +- UIKit application/scene lifecycle +- CAMetalLayer / Metal device / command queue +- frame loop and clear/present test +- AVAudioSession setup +- GameController discovery +- touch-input abstraction +- Application Support / Documents / Cache paths +- logging and crash diagnostics +- memory-pressure notifications +- thermal-state notifications +- foreground/background handling +- CI cross-compilation of an unsigned ARM64 app + +Gate: clean public checkout builds without any Rockstar data. + +## Phase 1 — Engine/platform abstraction + +If lawful source is available privately, isolate platform dependencies behind small interfaces rather than scattering iOS conditionals throughout the engine. + +Suggested boundaries: + +```text +Platform/ + Threads + Time + Files + VirtualMemory + Logging + User + Saves + Input + Audio + Networking + Video + +Render/ + Device + Buffers + Textures + Samplers + PipelineState + RenderPass + ShaderLibrary + UploadQueue + Present +``` + +Gate: as much engine/runtime code as possible compiles for `arm64-apple-ios` with renderer/game-data consumers stubbed where necessary. + +## Phase 2 — Asset contract before assets + +Define the mobile asset pipeline before the laptop has the complete GTA V installation. + +Public code may include: + +- manifest schemas +- file-type classifiers +- expected logical paths +- hashing/validation code +- dependency graphs +- texture-conversion interfaces +- mesh/LOD conversion interfaces +- audio/video policy interfaces +- cache-key generation +- storage preflight +- staging + atomic promotion logic +- synthetic test fixtures + +Do not hard-code proprietary file contents into tests. + +Example output layout: + +```text +Application Support/GTA5-iOS/ + Game/ + Cooked/ + Textures/ + Geometry/ + Audio/ + Video/ + Shaders/ + Cache/ + Config/ + +Documents/GTA5-iOS/ + Saves/ +``` + +## Phase 3 — Synthetic renderer validation + +Before GTA data exists, prove the Metal path with generated content: + +1. clear/present +2. colored triangle +3. indexed geometry +4. textured quad +5. depth test +6. alpha blending +7. offscreen render target +8. mipmapped texture +9. instancing +10. compute/upload test if required +11. pipeline-cache reuse +12. dynamic-resolution resize + +Gate: stable 30 FPS shell on the iPhone 11 with no unbounded memory growth. + +## Phase 4 — A13 baseline from day one + +Use the iPhone 11 profile immediately: + +- 30 FPS target / 33.33 ms frame budget +- ARM64 AOT only +- direct Metal +- dynamic internal resolution approximately 854x480 to 1280x720 +- no MSAA by default +- conservative shadow/reflection targets +- bounded texture/buffer/shader/pipeline caches +- async storage +- no main-thread asset reads +- conservative worker count +- initial ~2 GB resident-memory soft engineering target, adjusted only from real device measurements +- thermal degradation order: resolution -> shadows -> reflections -> post FX -> cache/work trim + +## Phase 5 — Laptop asset ingestion later + +When the development laptop is available: + +1. Install the user's legitimate GTA V copy through Epic Games. +2. Record the exact game build/version. +3. Point the local/private asset tool at the installed game directory. +4. Inventory every archive/resource class before modifying anything. +5. Produce hashes and a machine-readable manifest. +6. Run conversion into a separate staging directory; never modify the original installation in place. +7. Validate converted outputs before promotion. +8. Measure size per category before and after conversion. +9. Import the cooked output to the iPhone through the app's file importer or a development deployment path. +10. Keep all Rockstar-derived outputs private/local. + +## Compression/optimization order + +Do not blindly recompress every file. Optimize in this order: + +1. remove content not required by the selected single-player build/profile +2. reduce duplicate/redundant build outputs +3. tune texture resolution and GPU format where quality permits +4. tune LOD and distance settings +5. reduce expensive render-target sizes +6. tune audio/video bitrate only after measuring their storage and runtime cost +7. bound streaming residency and temporary conversion buffers +8. preserve files that are already efficiently compressed unless conversion has a measured benefit + +Every transformation should be deterministic and recorded in a manifest so the mobile data pack can be reproduced from the owned desktop installation. + +## First real-data milestones + +Once real game data is available, bring it in incrementally: + +```text +engine boot + -> one known texture + -> one known mesh + -> one translated shader/material + -> first GTA-authored draw + -> frontend/logo resources + -> menu + -> map sector streaming + -> player + -> vehicle + -> prologue + -> open world +``` + +Do not begin by copying the complete PC installation to the phone and debugging everything at once. + +## Source-first limitation + +The full GTA game cannot be proven playable with no matching assets. What can be completed early is the Apple platform layer, ARM64 build path, Metal renderer host, asset contracts/converters, diagnostics, controls, memory/thermal policy, CI, and synthetic rendering tests. + +Real integration starts when a matching, legitimately obtained game-data set is available.