exp-runtime 0.5.0__tar.gz

exp_runtime-0.5.0/.github/workflows/desktop-builds.yml

@@ -0,0 +1,259 @@
+name: Builds
+
+on:
+  push:
+    branches: ['**']
+    tags: ['v*']
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: desktop-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/') }}
+
+jobs:
+  packages:
+    name: Python wheels (${{ matrix.python }})
+    runs-on: ubuntu-22.04
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.10', '3.14']
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install uv and select Python
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          version: '0.12.13'
+          python-version: ${{ matrix.python }}
+          enable-cache: true
+          cache-suffix: python-${{ matrix.python }}
+
+      - name: Install locked build dependencies
+        run: uv sync --locked --extra build
+
+      - name: Build and audit wheels and source archives
+        shell: bash
+        run: |
+          flags=()
+          if [[ "$GITHUB_REF_TYPE" == tag ]]; then
+            flags+=(--tag "$GITHUB_REF_NAME")
+          fi
+          uv run --locked --extra build python tools/build_packages.py "${flags[@]}"
+
+      - name: Verify isolated pip installs and component removal
+        run: uv run --locked --extra build python tools/test_packages.py
+
+      - name: Upload Python distributions and checksums
+        if: matrix.python == '3.14'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: python-packages
+          path: dist/packages/*
+          if-no-files-found: error
+          retention-days: 30
+
+  ios:
+    name: iOS
+    uses: ./.github/workflows/ios-builds.yml
+
+  build:
+    name: ${{ matrix.target }}
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - target: windows-x64
+            runner: windows-2022
+          - target: linux-x64
+            runner: ubuntu-22.04
+          - target: macos-arm64
+            runner: macos-14
+          - target: macos-x64
+            runner: macos-15-intel
+    defaults:
+      run:
+        shell: bash
+    env:
+      SDL_VIDEODRIVER: dummy
+      SDL_AUDIODRIVER: dummy
+      PYGAME_HIDE_SUPPORT_PROMPT: '1'
+      EXP_TARGET: ${{ matrix.target }}
+      EXP_BUILD_LABEL: ${{ startsWith(github.ref, 'refs/tags/') && github.ref_name || github.sha }}
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install uv and select Python
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          version: '0.12.13'
+          python-version: '3.14'
+          enable-cache: true
+          cache-suffix: ${{ matrix.target }}
+
+      - name: Install locked dependencies
+        run: uv sync --locked --extra build
+
+      - name: Identify native build image
+        if: runner.os != 'macOS'
+        id: rar-image
+        # The hosted image version covers compiler, SDK and CMake updates.
+        # If unavailable, skip caching and build normally.
+        run: echo "version=${ImageVersion:-}" >> "$GITHUB_OUTPUT"
+
+      - name: Restore RAR decoder
+        if: runner.os != 'macOS' && steps.rar-image.outputs.version != ''
+        id: rar-cache
+        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: |
+            build/rar/install
+            build/rar/libarchive-*.tar.xz
+          key: rar-v1-${{ matrix.runner }}-${{ runner.arch }}-${{ steps.rar-image.outputs.version }}-${{ hashFiles('tools/build_rar.py') }}
+
+      - name: Prepare RAR decoder
+        run: uv run --locked --extra build python tools/build_rar.py
+
+      # Persist a successful dependency build even if later tests fail.
+      - name: Save RAR decoder
+        if: steps.rar-cache.outputs.cache-primary-key != '' && steps.rar-cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: |
+            build/rar/install
+            build/rar/libarchive-*.tar.xz
+          key: ${{ steps.rar-cache.outputs.cache-primary-key }}
+
+      - name: Run tests without game content
+        run: uv run --locked --extra build python -m unittest discover -s tests
+
+      - name: Build desktop application
+        run: uv run --locked --extra build python tools/build_desktop.py
+
+      - name: Package, audit and test the extracted download
+        run: >-
+          uv run --locked --extra build python tools/package_desktop.py
+          --target "$EXP_TARGET" --label "$EXP_BUILD_LABEL" --smoke-test
+
+      - name: Upload downloadable archive and checksum
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: desktop-${{ matrix.target }}
+          path: dist/downloads/*
+          if-no-files-found: error
+          compression-level: 0
+          retention-days: 30
+
+  publish-pypi:
+    name: Publish Python distributions to PyPI
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    needs: [build, ios, packages]
+    runs-on: ubuntu-22.04
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/exp-runtime
+    permissions:
+      id-token: write
+    env:
+      EXP_TAG: ${{ github.ref_name }}
+    steps:
+      # Reuse the audited artifacts; do not build or install project code in
+      # the job that can request PyPI credentials.
+      - name: Download tested Python distributions and checksums
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: python-packages
+          path: dist/packages
+
+      - name: Verify checksums and stage only publishable distributions
+        working-directory: dist/packages
+        shell: bash
+        run: |
+          version="${EXP_TAG#v}"
+          mkdir ../pypi
+          for name in exp_runtime exp_runtime_formats exp_runtime_engine exp_runtime_player exp_runtime_shs exp_runtime_cod; do
+            for suffix in -py3-none-any.whl .tar.gz; do
+              file="$name-$version$suffix"
+              sha256sum --check --strict "$file.sha256"
+              cp -- "$file" ../pypi/
+            done
+          done
+
+      - name: Publish wheels and source archives with Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          packages-dir: dist/pypi/
+
+  release:
+    name: Publish versioned downloads
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    needs: [build, ios, packages]
+    runs-on: ubuntu-22.04
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    env:
+      EXP_TAG: ${{ github.ref_name }}
+    steps:
+      - name: Check out release notes
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Download desktop archives and checksums
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          pattern: desktop-*
+          path: dist/release
+          merge-multiple: true
+
+      - name: Download unsigned IPA and checksum
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: ios-arm64-unsigned
+          path: dist/release
+
+      - name: Verify downloaded checksums
+        working-directory: dist/release
+        shell: bash
+        run: |
+          for target in windows-x64.zip linux-x64.tar.gz macos-arm64.zip macos-x64.zip ios-arm64-unsigned.ipa; do
+            test -s "exp-runtime-$EXP_TAG-$target"
+            test -s "exp-runtime-$EXP_TAG-$target.sha256"
+          done
+          sha256sum --check ./*.sha256
+
+      - name: Create release or update its downloads
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+        shell: bash
+        run: |
+          if draft=$(gh release view "$EXP_TAG" --repo "$GH_REPO" --json isDraft --jq .isDraft 2>/dev/null); then
+            gh release upload "$EXP_TAG" dist/release/* --repo "$GH_REPO" --clobber
+            if [[ "$draft" == true ]]; then
+              gh release edit "$EXP_TAG" --repo "$GH_REPO" --draft=false
+            fi
+          else
+            flags=()
+            if [[ "$EXP_TAG" == *-* ]]; then
+              flags+=(--prerelease)
+            fi
+            gh release create "$EXP_TAG" dist/release/* \
+              --repo "$GH_REPO" --verify-tag --title "EXP Runtime $EXP_TAG" \
+              --notes-file RELEASE.md "${flags[@]}"
+          fi

exp_runtime-0.5.0/.github/workflows/ios-builds.yml

@@ -0,0 +1,103 @@
+name: iOS builds
+
+on:
+  workflow_call:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ios-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/') }}
+
+jobs:
+  build:
+    name: Unsigned iPhone app
+    runs-on: macos-26
+    timeout-minutes: 30
+    env:
+      PYTHONDONTWRITEBYTECODE: '1'
+      SDL_VIDEODRIVER: dummy
+      SDL_AUDIODRIVER: dummy
+      PYGAME_HIDE_SUPPORT_PROMPT: '1'
+      EXP_BUILD_LABEL: ${{ startsWith(github.ref, 'refs/tags/') && github.ref_name || github.sha }}
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install uv and select Python
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          version: '0.12.13'
+          python-version: '3.14'
+          enable-cache: true
+          cache-suffix: ios
+
+      - name: Install locked host dependencies
+        run: uv sync --locked --extra desktop
+
+      - name: Restore iOS dependencies
+        id: ios-dependencies-cache
+        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: build/ios/dependencies
+          key: ios-deps-v1-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('ios/dependencies.json', 'tools/build_ios.py') }}
+
+      - name: Prepare iOS dependencies
+        run: |
+          uv run --locked --extra desktop python tools/build_ios.py --prepare --sdk iphonesimulator
+          uv run --locked --extra desktop python tools/build_ios.py --prepare --sdk iphoneos
+
+      # Cache both SDKs before tests or simulator boot can fail.
+      - name: Save iOS dependencies
+        if: steps.ios-dependencies-cache.outputs.cache-primary-key != '' && steps.ios-dependencies-cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: build/ios/dependencies
+          key: ${{ steps.ios-dependencies-cache.outputs.cache-primary-key }}
+
+      - name: Run authored engine and packaging tests
+        run: uv run --locked --extra desktop python -m unittest discover -s tests
+
+      - name: Build simulator app
+        run: uv run --locked --extra desktop python tools/build_ios.py --sdk iphonesimulator
+
+      - name: Verify shared engine and native presentation on iOS
+        run: uv run --locked --extra desktop python tools/test_ios.py --boot-timeout 600 --install-timeout 300
+
+      - name: Upload simulator failure diagnostics
+        if: failure()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: ios-simulator-diagnostics
+          path: build/ios/simulator-diagnostics/
+          if-no-files-found: warn
+          retention-days: 7
+
+      - name: Build unsigned device app
+        run: uv run --locked --extra desktop python tools/build_ios.py --sdk iphoneos
+
+      - name: Audit and package unsigned IPA
+        run: uv run --locked --extra desktop python tools/package_ios.py --label "$EXP_BUILD_LABEL"
+
+      - name: Upload unsigned IPA and checksum
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: ios-arm64-unsigned
+          path: |
+            dist/downloads/*-ios-arm64-unsigned.ipa
+            dist/downloads/*-ios-arm64-unsigned.ipa.sha256
+          if-no-files-found: error
+          compression-level: 0
+          retention-days: 30
+
+      - name: Upload simulator verification report
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: ios-simulator-verification
+          path: build/ios/verification-simulator.json
+          if-no-files-found: error
+          retention-days: 30

exp_runtime-0.5.0/.gitignore

@@ -0,0 +1,68 @@
+# Python environments, caches and generated packages.
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage*
+htmlcov/
+build/
+dist/
+*.spec
+
+# User-provided game files and imported content.
+*.[aA][pP][kK]
+*.[iI][pP][aA]
+*.[eE][xX][pP]
+*.[zZ][iI][pP]
+*.[rR][aA][rR]
+*.[kK][iI][wW]
+*.[sS][aA][vV]
+*.shs-save.json
+*.shs-auto.json
+.shs-library/
+.shs-import-*/
+.exp-import-*/
+.exp-library/
+/library/
+/Episodes/
+/extract/
+/game-assets/
+/converted_assets/
+/debug_images/
+/original-screenshots/
+/output/
+/renpy-*-sdk/
+/decomp/
+
+# Private native research and generated reports.
+*.so
+*.dylib
+*.dll
+*.gpr
+*.rep/
+*.gzf
+/docs/native-*
+/docs/*-audit.json
+/docs/*-trace.json
+/local-reports/
+*.log
+
+# Editor and machine-local state.
+.DS_Store
+.idea/
+.vscode/
+xcuserdata/
+*.xcuserstate
+DerivedData/
+*.xcarchive/
+/ios/Signing.local.xcconfig
+*.p12
+*.p8
+*.mobileprovision
+*.provisionprofile
+.env
+.env.*

exp_runtime-0.5.0/AGENTS.md

@@ -0,0 +1,75 @@
+# EXP Runtime
+
+This is an experimental compatible engine for Surviving High School and Cause
+of Death. Users supply SHS Android 1.0.9 APK / SHS IPA or CoD IPA assets and
+additional EXP episodes. `exp_runtime` executes
+original KiWi bytecode and renders user-supplied resources. It is not a static
+ARM recompilation or a Ren'Py conversion.
+
+## Build and verify
+
+```sh
+uv sync --locked --extra desktop
+uv run --locked --extra desktop python -m unittest discover -s tests
+uv run --locked --extra desktop exp-runtime
+uv run --locked --extra build python tools/build_desktop.py
+```
+
+Tests use authored fixtures. Optional original-content checks skip when a
+player's local content is absent. Do not add original assets as test fixtures.
+
+## Architecture and contracts
+
+One uv workspace produces the `exp-runtime` umbrella and five component wheels.
+Source lives under `packages/{formats,engine,player,shs,cod}/src/exp_runtime`.
+Keep the shared `exp_runtime` namespace free of a root `__init__.py`, and give
+each source file one wheel owner. `tools/build_packages.py` audits the wheels;
+`tools/test_packages.py` checks isolated pip installs. See docs/SDK.md.
+
+- `shs/`, `cod/`: game-specific import, asset/audio bindings and host services.
+- `content.py`: validated EXP/APK/IPA import, exact resource IDs, relocatable
+  per-game libraries and separation of base versus episode resource banks.
+- `decode/bytecode.py`, `vm.py`: lossless KiWi representation and real VM
+  execution, including pending argument frames and callbacks.
+- `engine.py`, `runtime.py`: host services, panel state, clocks, choices,
+  mini games and versioned JSON saves.
+- `application.py`, `desktop*.py`: shared launcher, menu, rendering and input.
+- `graphics.py`, `platforms/`, `ios/`: pygame/native drawing primitives and the
+  Swift iOS host; keep game layout and behavior in the shared Python code.
+- `fonts.py`, `ui_assets.py`, `atlas.py`: native asset and layout contracts.
+
+Follow SCHEMA.md, VM_SPEC.md and docs/ENGINE_ABI.md. Unknown services must
+remain explicit stops with their pending arguments intact. Never invent a
+score, result, scene link or random value to bypass them. The heuristic AST
+parser and Ren'Py experiments belong to the original research project.
+
+Preserve the 1:1 target: original positions, font metrics, portrait masking,
+pagination, panel lifecycle, input gates, timers, randomness and script-visible
+side effects. Recover behavior and presentation together. Use Android 1.0.9
+as the available reference for the reported identical iOS/Android interface.
+The owner selected v0.1.3's SHS skin as the common presentation reference,
+then supplied original screenshots and requested native verification of the
+general title fix. Keep a common dialogue renderer; adapters supply each
+game’s assets and native font metrics. Do not introduce a separate IPA layout.
+The owner subsequently selected the verified iOS dialogue-box opening
+animation for both games/platforms (120 ms travel, then 200 ms expansion).
+This overrides Android's immediate box display; retain the common final
+geometry. See docs/UI_FIDELITY.md for recovered paths and remaining limits.
+Ghidra confirms that both iOS games wrap names at the native region width,
+select a normal/tall header, and keep ordinary body text in its own region.
+Honor those outline-font rules and Android's distinct bitmap-label rules.
+Long titles may straddle the box border: do not force every name wholly above
+it into the normal-height header. Bound fallback ink against the selected
+header, skin, body and portrait; keep the drawing fit separate from saved
+font history. Resolve text colors per game. See docs/IPA.md for evidence.
+For other CoD-specific differences use its
+supplied iOS native reference and docs/COD.md.
+Keep unverified details explicit in the specifications.
+
+Do not bundle APKs, EXPs, extracted art/audio/fonts/scripts, native
+decompilations, screenshots, generated games, player libraries or saves.
+Keep MANIFEST.in and package discovery restrictive. Preserve the inherited
+MIT license and attribution in docs/PROVENANCE.md.
+
+The owner handles Git initialization, commits, remotes and pushes. Creating
+this directory does not authorize publishing it.