Native Gen2 camera controls and renderer runtime qualification

.github/workflows/gen2-permissions-contract.yml

@@ -0,0 +1,38 @@
+name: native Gen2 movement permissions
+on:
+  pull_request:
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: gen2-permissions-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  contract:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7
+        with:
+          repository: bryanthaboi/gen1recomp
+          ref: 535a5ec088c1ae1bf4d91dd3e35a56f64cf46d91
+          path: .contract-reference/gen1
+      - name: Install test runtime
+        run: sudo apt-get update && sudo apt-get install -y luajit
+      - name: Compare queries with actual native grid movement
+        run: luajit tests/engine/gen2_movement_permissions.lua
+      - name: Exercise native special movement handoffs
+        run: luajit tests/engine/gen2_movement_handoffs.lua
+      - name: Compare all Crystal collision pairs with the pinned Gen1 engine
+        run: |
+          mkdir -p /tmp/gen2-permissions-contract
+          luajit tools/gen2_permissions_contract.lua native > /tmp/gen2-permissions-contract/native.txt
+          (cd .contract-reference/gen1 && luajit "$GITHUB_WORKSPACE/tools/gen2_permissions_contract.lua" reference) > /tmp/gen2-permissions-contract/reference.txt
+          cmp /tmp/gen2-permissions-contract/native.txt /tmp/gen2-permissions-contract/reference.txt
+      - uses: actions/upload-artifact@v6
+        if: always()
+        with:
+          name: gen2-permissions-contract
+          path: /tmp/gen2-permissions-contract
+          if-no-files-found: ignore

.github/workflows/runtime-upvalues.yml

@@ -0,0 +1,131 @@
+name: Native runtime capacity
+on:
+  pull_request:
+    paths:
+      - '.github/workflows/runtime-upvalues.yml'
+      - 'tools/runtime-upvalue-check/**'
+      - 'tools/build_native_preview.py'
+      - 'tools/package_native_release.py'
+      - 'tests/test_runtime_component.py'
+      - 'tests/test_native_preview.py'
+  workflow_dispatch:
+  workflow_call:
+permissions:
+  contents: read
+concurrency:
+  group: runtime-upvalues-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  qualify:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - runner: ubuntu-24.04
+            label: linux-x64
+          - runner: windows-2022
+            label: windows-x64
+            love-artifact: '12514271124'
+            library: lua51.dll
+          - runner: macos-15-intel
+            label: macos-x64
+            love-artifact: '12513712494'
+            library: libluajit.so
+          - runner: macos-15
+            label: macos-arm64
+            love-artifact: '12513712494'
+            library: libluajit.so
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 25
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          path: engine
+          ref: ${{ github.sha }}
+      - uses: actions/checkout@v7
+        with:
+          repository: LuaJIT/LuaJIT
+          ref: a4c064539ea931274d407e1249b4bb575424a0f4
+          path: runtime-source
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+      - uses: ilammy/msvc-dev-cmd@0b201ec74fa43914dc39ae48a89fd1d8cb592756
+        if: runner.os == 'Windows'
+        with:
+          arch: x64
+      - name: Build both runtimes and qualify closures, C API and engine
+        shell: bash
+        run: >-
+          python engine/tools/runtime-upvalue-check/qualify.py
+          --luajit-source runtime-source
+          --output "${{ runner.temp }}/runtime-capacity/candidate"
+          --engine-tests
+      - name: Fetch pinned LOVE12 host artifact
+        if: matrix.love-artifact != ''
+        shell: bash
+        run: >-
+          curl --fail --location --retry 2
+          --output "${{ runner.temp }}/love-runtime.zip"
+          "https://nightly.link/love2d/love/actions/artifacts/${{ matrix.love-artifact }}.zip"
+      - name: Qualify the actual LOVE12 host, thread VM and FFI
+        if: matrix.love-artifact != ''
+        shell: bash
+        run: >-
+          python engine/tools/runtime-upvalue-check/love_abi.py
+          --runtime-archive "${{ runner.temp }}/love-runtime.zip"
+          --qualification "${{ runner.temp }}/runtime-capacity/candidate/report.json"
+          --library "${{ runner.temp }}/runtime-capacity/candidate/artifacts/extended/${{ matrix.library }}"
+          --output "${{ runner.temp }}/runtime-love-abi/candidate"
+      - uses: actions/upload-artifact@v7
+        if: always()
+        with:
+          name: runtime-capacity-${{ matrix.label }}
+          path: |
+            ${{ runner.temp }}/runtime-capacity/candidate/report.json
+            ${{ runner.temp }}/runtime-capacity/candidate/*.log
+            ${{ runner.temp }}/runtime-capacity/candidate/artifacts/
+            ${{ runner.temp }}/runtime-love-abi/candidate/report.json
+            ${{ runner.temp }}/runtime-love-abi/candidate/*.log
+          if-no-files-found: error
+          retention-days: 14
+  components:
+    needs: qualify
+    runs-on: macos-15
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          path: engine
+          ref: ${{ github.sha }}
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+      - uses: actions/download-artifact@v8
+        with:
+          pattern: runtime-capacity-*
+          path: runtime-candidates
+      - name: Verify component packaging guards
+        shell: bash
+        run: python -m unittest discover -s engine/tests -p test_runtime_component.py -v
+      - name: Combine the two qualified Mac slices
+        shell: bash
+        run: >-
+          python engine/tools/runtime-upvalue-check/component.py
+          --platform macos
+          --candidate runtime-candidates/runtime-capacity-macos-x64
+          --candidate runtime-candidates/runtime-capacity-macos-arm64
+          --output "${{ runner.temp }}/qualified-runtime/candidate/macos"
+      - name: Stage the qualified Windows component
+        shell: bash
+        run: >-
+          python engine/tools/runtime-upvalue-check/component.py
+          --platform windows
+          --candidate runtime-candidates/runtime-capacity-windows-x64
+          --output "${{ runner.temp }}/qualified-runtime/candidate/windows"
+      - uses: actions/upload-artifact@v7
+        with:
+          name: qualified-desktop-runtime
+          path: ${{ runner.temp }}/qualified-runtime/candidate/
+          if-no-files-found: error
+          retention-days: 14

docs/native-apple-silicon-quality.md

@@ -0,0 +1,52 @@
+# Apple Silicon desktop quality
+
+`Performance.detect()` treated every non-mobile ARM host as a low-end
+handheld, including macOS. The supplied Johto package correctly identified
+the M3 CPU/GPU as capable, but its AUTO policy also consumed that engine
+classification and started at LOW. In a fresh Crystal GPU test this selected
+the 720p-class scene budget, flat sky, disabled clouds and disabled shadows.
+
+macOS now uses the existing desktop core-count policy on Apple Silicon, as
+Intel Macs already did. Explicit LOW/BALANCED selections remain available;
+ARM Linux handhelds and mobile detection retain their existing behavior.
+No mod-specific quality preset or saved setting is forced by the engine.
+
+At fork source `7b05320fcc85c13f445f928586d5cd91ea39e16b`, a fresh profile
+reports engine HIGH. The unchanged supplied package starts at MEDIUM under
+its own conservative Gen2 AUTO policy, with the balanced scene resolution,
+full sky, clouds and low-quality shadows enabled. The previous LOW default
+was a classification error, not an intrinsic limit of native Gen2 rendering.
+
+For the 800×720 logical / 1600×1440 physical test window, measured color
+targets are:
+
+| Selection | Scene color target | Presented world |
+| --- | --- | --- |
+| Previous fresh AUTO / LOW | 800×720 | 1600×1440 |
+| Corrected fresh AUTO / MEDIUM | 1200×1080 | 1600×1440 |
+| NATIVE, AA OFF | 1600×1440 | 1600×1440 |
+| NATIVE, AA 2X | 2263×2036 | 1600×1440 |
+
+The active drawWorld pipeline already receives physical pixel dimensions.
+Its private adapter translates these correctly; the older compose helper's
+logical-size fallback does not explain this active-path reduction. Inspecting
+the helper alone would give the wrong diagnosis. Window, scene, readable-depth
+and presentation-target sizes must be distinguished.
+
+The existing performance suite passes 42 assertions, including six new Mac
+regressions for detection, AUTO resolution, published tier, explicit selections
+and the desktop core-count floor. GPU verification is source-bound in the
+[quality receipt](qa/native-foundation/johto-native-apple-silicon-quality.json).
+The comparison uses actual imported Crystal and all 27,329 supplied mod files
+unchanged, with fresh isolated QA profiles, skipped introduction and a selected
+town position. It is image-size/camera smoke coverage, not a frame-rate benchmark
+or normal story acceptance. Native/AA presets are changed through the real mod
+option event interface only in those QA profiles.
+
+Sharper edges do not establish complete renderer parity. The generated
+Stadium overworld extension still exceeds the stock runtime's 60-upvalue
+limit; the base voxel scene is visible, but model/occlusion parity remains
+open. A preliminary 4X comparison produced sharper images but its second
+owned-window proof failed the stale-frame check. It is not accepted as a
+successful 4X run, and 4X is not made the default. No source/assets/screenshots,
+ROM data or saves from the supplied package are published.

docs/native-gen2-camera-movement.md

@@ -0,0 +1,124 @@
+# Native Gen2 external movement handoffs
+
+`src.world.gen2.FieldMoves` now resolves to `Gen2FieldMoves` for its movement
+constants and `isBiking` / `isSurfing` predicates. They are the existing
+`Gen2PlayerState` functions, so scripts and native surf/bicycle changes remain
+immediately observable. There is no shadow movement byte. Legacy action,
+fly-picker and collision-classification APIs are still absent: native script
+and ROM-derived terrain protocols must not be replaced with guessed results.
+
+This is sufficient for the supplied continuous camera controller to install
+over the existing native `pollInput` and `stepBody` phases. Merely supplying
+the name was insufficient for forced terrain: that controller completes its
+public landing phases itself, then hands ice/current/forced-door movement back
+to the engine. The native engine previously waited for its own grid landing
+before starting those actions.
+
+`resumeForcedMovement` now admits that return before ordinary input. Current
+and forced-door collision bytes select their native direction without a held
+key. The external ice `turningDirection` latch starts the existing ice handler.
+Both paths retain native collision, actor interpolation, script queues and
+completed-step callbacks. They do not replay an already completed free-body
+landing. Blocked forced movement retains ownership of that frame. Scripts,
+overlays, transitions, battles and in-progress actions cannot acquire a second
+queue. The external ice latch and native ice latch are retired on map changes;
+ordinary floor clears the external latch. Other generations retain their path.
+
+## Verification
+
+- `tests/engine/gen2_field_state_queries.lua`: 30 state/alias assertions.
+- `tests/engine/gen2_forced_body_handoff.lua`: 584 assertions using real native
+  maps, collision, runner and actor queues across Gold, Silver, Crystal and
+  Prism, plus other-generation refusal. Includes blocked currents, directional
+  walls, pending owners and error recovery.
+- Existing body/input, special-handoff and CountStep suites: 21, 549 and 313
+  assertions respectively.
+- The committed fork passes 328 engine suites, three SDK suites and all quick
+  tiers. The independent upstream composition passes the focused native suites.
+
+An additional local CPU probe loads the supplied `3.1.2-omega.1.8`
+`GoldCameraControls`, `FirstPerson`, `ThirdPerson`, `VoxelState` and `Mat4`
+modules without changing their source. It passes 92 assertions on both the
+fork and independent upstream composition. It exercises actual camera-space
+key/stick math, both selected camera modes (including an extended third-person
+body bearing), sub-cell travel, occupied-wall sliding, native counters, a real
+coordinate script, Repel text ownership, native bicycle/surf movement and
+ice/current/door returns. The previous `main` fails installation with
+`Gold free-movement dependencies unavailable`.
+
+The probe supplies a renderer-availability boundary and does not draw graphics.
+It uses public native fixtures rather than an imported ROM. Script clocks
+outside the body phase are not a complete game loop. This is **CPU integration
+acceptance**, not full-package, GPU, all-story or Windows hardware acceptance.
+No supplied mod code/assets or cartridge data are distributed. See the
+[source-bound receipt](qa/native-foundation/johto-native-camera-state.json).
+
+## Full-package GPU movement smoke
+
+At source `62ca106fadebfcca1b262cde05a60a081c10d765`, fresh actual Crystal imports
+with all 27,329 supplied Ver.1.8 files unchanged pass the scoped movement smoke
+on macOS OpenGL/VSync 0 and Metal/VSync 1. Each backend executes 12 actual free
+body ticks in First and Third Person, crosses a logical cell, retains a false
+native grid-moving flag and accepts the real V key callback to change mode.
+Each backend passes 19 driver assertions and two fresh OS-window proofs.
+The images were inspected: they show visible, upright scenery.
+
+The introduction is skipped and a native New Bark Town position is selected
+for this controlled walk. This does not verify normal doors, map boundaries,
+forced terrain with GPU, all story/encounters or Windows. A test-only assumption
+about `npcAt` stopped the first run; the revised test uses native occupancy.
+
+The generated model renderer still reports the separate 60-upvalue compile
+failure. The fallback scene is visible; avatar/occlusion and complete First/
+Third Person visual equivalence are **not accepted** by these proofs. The PR
+remains a development checkpoint pending broader movement/transition tests.
+The existing public release assets are unchanged by this follow-up.
+
+## Full-package normal transition smoke
+
+The next actual Crystal matrix passes 212 assertions on each of macOS
+OpenGL and Metal. In both First and Third Person it walks through the normal
+Cherrygrove Mart and Center entrances, opens/closes the native START menu
+without moving behind it, walks inside to the exit, and returns through the
+real directional carpet and native fade. It also crosses the actual
+Cherrygrove/Route 29 connection in both directions. That is 12 transitions,
+four menu ownership checks and four fresh owned-window proofs per backend.
+Selected camera modes survive normal map handoffs and all final native owners
+are clear. Original supplied files remain byte-identical.
+
+OpenGL uses source `18489b7a`; Metal uses `aa669f69`, which additionally
+integrates the current fork's separate launcher work. The
+[source-bound receipt](qa/native-foundation/johto-native-camera-transitions.json)
+distinguishes these builds. Initial exterior approaches are selected by QA;
+travel itself uses real native input. Camera yaw uses the supplied look API,
+so this is not physical mouse acceptance. No window resize is implied by the
+legacy capture labels.
+
+Two failed scenarios remain explicit: the first backward-facing entrance
+looked into the front void and failed the blank-frame guard; the ordinary
+forward-looking approach passes without changing that guard. A separate
+fresh-save New Bark west approach did not clear a native owner and is not
+accepted here. The successful connection matrix uses Cherrygrove/Route 29,
+outside that early-story approach. Full story, all maps, forced-terrain GPU,
+Windows and complete avatar/model/occlusion parity remain open. The generated
+Stadium extension is still uninstalled. This checkpoint does not change the
+existing release assets.
+
+## Transitions with the experimental runtime
+
+The separate extended-upvalue arm64 LÖVE host now repeats the complete normal
+transition matrix with `rendererInstalled == true` required. OpenGL at source
+`6f0f8d2c` and Metal at `6f926f9c` each pass 213 assertions, 12 normal door/map
+transitions, four native menu ownership checks and four fresh OS-window
+proofs. Both selected cameras retain native ownership and return correctly.
+All 27,329 supplied files remain unchanged. The
+[runtime receipt](qa/native-foundation/johto-native-runtime-upvalues.json)
+binds these results to the separately qualified Lua library.
+
+All eight room proofs were inspected and show upright geometry and NPC
+figures. Black-and-white objects remain visible in some First Person frames;
+complete avatar/model/occlusion and performance parity remain unaccepted.
+Initial QA positions and skipped introduction still preclude all-story
+acceptance. These tests use the experimental host, not the public release's
+stock 60-upvalue runtime. Windows and universal packaging remain separate
+gates.

docs/native-gen2-movement-handoffs.md

@@ -0,0 +1,48 @@
+# Native Gen2 special movement handoffs
+
+Gen2 controls can return special movement to the existing native overworld
+through `tryConnection(direction)`, `tryLedgeJump(direction)` and
+`tryPushBoulder(direction, x, y)`. The last method requires the actual adjacent
+cell in that direction. These methods use the existing map/warp, ledge and
+boulder handlers, player interpolation, script queues and completion events.
+
+Admission requires the current Gen2 world and save, a standing actor, no
+overlay or battle, and no active or pending native script, field action or
+transition. Both the persistent world with an empty overlay stack and the
+legacy world on top of its stack are supported. An expired numeric whirlpool
+hold is clear; a positive hold retains control. Nested admission from a
+synchronous native callback is refused, and a handler error remains visible
+without leaving a permanent admission lock.
+
+The connection path retains directional carpet exits. A carpet is an input
+action, so an integration must not substitute an immediate arrival warp.
+Ordinary seam steps also check directional walls on the standing and
+destination cells before changing map. Scripted seams keep their deliberate
+collision bypass.
+
+The native Strength handler checks directional walls on both the player's
+approach and the boulder's step. Previously, its land/water check admitted
+those walls. Both the existing grid path and the new public handoff now refuse
+that push before queuing movement. Native occupancy, Strength activation,
+object classification, destination passability and completion effects retain
+their existing ownership.
+
+## Verification and limits
+
+`luajit tests/engine/gen2_movement_handoffs.lua` exercises actual map definitions,
+native connection selection, all four seam directions, native player/NPC
+interpolation, two-cell ledge queues and boulder completion. Only graphics/map
+materialization and the audio device are substituted. Native directional
+carpet fades are advanced to completion. The suite also checks busy owners,
+invalid directions, exact boulder coordinates, callback reentry, error cleanup,
+and the unchanged scripted collision bypass.
+
+The directional-wall regressions cover Gold, Silver, Crystal and Prism. A
+complete valid-byte/directional query comparison with the pinned Gen1 engine
+is covered by the prerequisite terrain-query contract. This follow-up builds
+on that implementation; it does not replace any generation's world controller.
+
+These are native CPU tests. They do not establish complete continuous-movement
+activation, the FieldMoves facade, all special terrain/landing behavior, or
+actual VASC GPU acceptance. The full generated VASC model renderer remains
+blocked by the separately documented compiler limit.