Add Pro Action Replay MK3 cheat-cartridge emulation

Wraps the SNES core with the Datel MK3 BIOS for cheat entry, trainer and live cheat application: rtl/chip/mk3 (IO, mapper, intercept, NMI hook, SRAM, switch FSM, top wrapper) plus its qip hook, the Pocket package and chip32 loader, build/asset scripts, manuals, and a tag-triggered build & release workflow. Ships only this core; the agg23/srg320 RTL is retained for the build.

Author: timboettiger

.github/FUNDING.yml

@@ -1,113 +1,56 @@
-################################################################################
-# How to create a tag to launch the workflow
-# git tag -a "0.1.0" -m "Release v0.1.0"
-# git push origin --tags
-################################################################################
-# WARNING: Make sure to set action permissions to max ("Read and write permissions")
-name: Build/Release
+# Build and release the core on a version tag.
+#   git tag v0.2.1        && git push origin v0.2.1        -> release
+#   git tag v0.2.1-beta   && git push origin v0.2.1-beta   -> pre-release
+# Repo setting: Actions -> Workflow permissions -> "Read and write".
+name: Build & Release
+
 on:
-  workflow_dispatch:
   push:
     tags:
-      - "[0-9]+.[0-9]+.[0-9]+*"
+      - "v[0-9]+.[0-9]+.[0-9]+*"
+  workflow_dispatch:
 
 permissions:
   contents: write
 
 jobs:
-  synthesis:
+  build:
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        core: ["main", "pal", "spc", "sa1gsu", "pal_sa1gsu"]
-
     steps:
-      - name: "🧰 Checkout Repository"
-        uses: actions/checkout@v4
-
-      - name: "🧰 Checkout Packybara"
+      - name: Checkout
         uses: actions/checkout@v4
-        with:
-          repository: "agg23/pocketpublish"
-          path: ".github/publish"
 
-      - name: "🏗️ Compile design"
-        shell: bash
+      - name: Compile bitstream
         run: |
-          map_value() {
-              case "$1" in
-                  main)
-                      echo "ntsc"
-                      ;;
-                  pal)
-                      echo "pal"
-                      ;;
-                  spc)
-                      echo "ntsc_spc"
-                      ;;
-                  sa1gsu)
-                      echo "ntsc_sa1gsu"
-                      ;;
-                  pal_sa1gsu)
-                      echo "pal_sa1gsu"
-                      ;;
-                  *)
-                      echo "Unknown input"
-                      ;;
-              esac
-          }
-
-          build_type=$(map_value "${{ matrix.core }}")
-          cmd="docker run --rm -v ${{ github.workspace }}:/build raetro/quartus:21.1 quartus_sh -t generate.tcl $build_type"
-          echo "Running command: $cmd"
-          eval $cmd
+          docker run --rm -v "${{ github.workspace }}:/build" -w /build \
+            raetro/quartus:21.1 \
+            quartus_sh --flow compile projects/snes_pocket.qpf
+          sudo chown -R "$USER" projects/output_files
 
-      - name: Upload failure artifact
-        uses: actions/upload-artifact@v4
+      - name: Upload logs on failure
         if: failure()
-        with:
-          name: failure_output_files
-          path: projects/output_files/
-
-      - name: Reverse bitstream
-        shell: bash
-        run: |
-          mkdir artifacts
-          pip3 install -r .github/publish/requirements.txt
-          python3 .github/publish/reverse.py projects/output_files/snes_pocket.rbf artifacts/snes_${{ matrix.core }}.rev
-
-      - name: Upload artifact
         uses: actions/upload-artifact@v4
         with:
-          name: snes_${{ matrix.core }}
-          path: artifacts/snes_${{ matrix.core }}.rev
-
-  packaging:
-    runs-on: ubuntu-latest
-    needs: synthesis
-    env:
-      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-    steps:
-      - name: "🧰 Checkout Repository"
-        uses: actions/checkout@v4
+          name: quartus-output
+          path: projects/output_files/
 
-      - name: "🧰 Checkout Packybara"
-        uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
         with:
-          repository: "agg23/pocketpublish"
-          path: ".github/publish"
+          python-version: "3.x"
 
-      - name: "Create folders"
+      - name: Convert assets
         run: |
-          pip3 install -r .github/publish/requirements.txt
-          python3 .github/publish/create_folders.py
+          python3 -m pip install --quiet pillow
+          scripts/build-loader.sh
+          scripts/build-icon-image.sh
 
-      - name: Download artifacts
-        uses: actions/download-artifact@v4
-        with:
-          path: staging/Cores/agg23.SNES/
-          merge-multiple: true
+      - name: Package core
+        run: scripts/build-release.sh
 
-      - name: "Release"
-        run: |
-          python3 .github/publish/release.py
+      - name: Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: release/*.zip
+          prerelease: ${{ contains(github.ref_name, '-') }}
+          generate_release_notes: true

.github/workflows/build.yml

@@ -73,4 +73,6 @@ cr_ie_info.json
 !info.txt
 # ROMS Checklist
 !checklist.sha1
-!checklist.md5
+!checklist.md5
+# Local release staging
+/release/

.gitignore

@@ -1,90 +1,51 @@
-# SNES for Analogue Pocket
+# Pro Action Replay MK3 for Analogue Pocket
 
-Ported from the original core developed by [srg320](https://github.com/srg320) ([Patreon](https://www.patreon.com/srg320)). Latest upstream available at https://github.com/MiSTer-devel/SNES_MiSTer.
+A SNES core for the Analogue Pocket that emulates the Datel **Pro Action Replay
+MK3** cheat cartridge on top of [agg23's openFPGA SNES core](https://github.com/agg23/openfpga-SNES)
+(a port of [srg320's MiSTer SNES](https://github.com/MiSTer-devel/SNES_MiSTer)).
+The MK3 BIOS wraps a standard SNES ROM and provides the cartridge's cheat entry,
+trainer, and live cheat application.
 
-Please report any issues encountered to this repo. Most likely any problems are a result of my port, not the original core. Issues will be upstreamed as necessary.
+## Install
 
-> [!WARNING]
-> 
-> Savestates/Memories/Sleep not supported
->
-> Savestates/Memories/Sleep are not supported by any FPGA SNES core. Not this one, not the MiSTer core it's ported from, not the Analogue Super NT one.
-> 
-> **Support for savestates will _not_ be coming** to any of these cores. Do not ask. If you would like to learn more, see [issue #59](https://github.com/agg23/openfpga-SNES/issues/59) and [this discussion on the MiSTer forums](https://misterfpga.org/viewtopic.php?t=4944).
+1. Extract the latest release ZIP to the root of your Pocket SD card.
+2. Place a verified 128 KB MK3 BIOS dump at
+   `Assets/snes/timboettiger.Pro Action Replay/snes-pro-action-replay-mk3.bin`.
+   The BIOS is proprietary Datel firmware and is not distributed here.
+3. Load any SNES ROM through the Pocket UI.
 
-## Installation
+## Modes
 
-### Easy mode
+The cartridge's 3-position switch is exposed as a core option:
 
-I highly recommend the updater tools by [@mattpannella](https://github.com/mattpannella) and [@RetroDriven](https://github.com/RetroDriven). If you're running Windows, use [the RetroDriven GUI](https://github.com/RetroDriven/Pocket_Updater), or if you prefer the CLI, use [the mattpannella tool](https://github.com/mattpannella/pocket_core_autoupdate_net). Either of these will allow you to automatically download and install openFPGA cores onto your Analogue Pocket. Go donate to them if you can
+- **MK3 Menu** — boot into the BIOS for code entry (default)
+- **Cheats Active** — boot the game with cheats applied
+- **No Cheats** — boot the game unmodified
 
-### Manual mode
-To install the core, copy the `Assets`, `Cores`, and `Platform` folders over to the root of your SD card. Please note that Finder on macOS automatically _replaces_ folders, rather than merging them like Windows does, so you have to manually merge the folders.
+## Documentation
 
-## Usage
+The user manuals and the full reverse-engineering documentation live in the
+parent project: <https://github.com/timboettiger/action-replay-mk-iii>.
 
-ROMs should be placed in `/Assets/snes/common`. Both headered and unheadered ROMs are now supported.
+## Build & release
 
-## Features
+Pushing a version tag builds and publishes a release via GitHub Actions
+(`.github/workflows/build.yml`):
 
-### Dock Support
+```
+git tag v0.2.1 && git push origin v0.2.1            # release
+git tag v0.2.1-beta && git push origin v0.2.1-beta  # pre-release
+```
 
-Core supports four players/controllers via the Analogue Dock. To enable four player mode, turn on `Use Multitap` setting.
+It compiles the bitstream (Quartus in Docker), converts the assets, packages the
+core, and attaches the ZIP to the release.
 
-### Expansion Chips
+To build locally: compile `projects/snes_pocket.qpf` with Quartus, then run
+`scripts/build-release.sh`. Other helpers: `scripts/build-loader.sh` (chip32
+loader), and `scripts/build-icon-image.sh` / `scripts/build-platform-image.sh`
+(PNG to Pocket `.bin`).
 
-All original expansion chips supported by MiSTer are also supported on the Pocket. The full list is:
+## Credits & licence
 
-* SA-1 (Super Mario RPG)
-* Super FX/GSU-1/2 (Star Fox)
-* DSP (Super Mario Kart)
-* CX4 (Mega Man X 2)
-* S-DD1 (Star Ocean)
-* SPC7110 (Far East of Eden)
-* ST1010 (F1 Roc 2)
-* BSX (Satellaview)
-
-The Super Game Boy, ST011 (Hayazashi Nidan Morita Shougi), and ST018 (Hayazashi Nidan Morita Shougi 2) are not supported in the MiSTer core, and therefore are not supported here. Additionally, the homebrew MSU expansion chip is not currently supported.
-
-#### BSX
-
-BSX ROMs must be patched to run without BIOS. The BSX BIOS is not currently supported
-
-### Savestates/Memories/Sleep
-
-> **Warning**: Not supported
-
-Savestates/Memories/Sleep are not supported by any FPGA SNES core. Not this one, not the MiSTer core it's ported from, not the Analogue Super NT one.
-
-**Support for savestates will _not_ be coming** to any of these cores. Do not ask. If you would like to learn more, see [issue #59](https://github.com/agg23/openfpga-SNES/issues/59) and [this discussion on the MiSTer forums](https://misterfpga.org/viewtopic.php?t=4944).
-
-### Video
-
-* `Square Pixels` - The internal resolution of the SNES is a 8:7 pixel aspect ratio (wide pixels), which roughly corresponds to what users would see on 4:3 display aspect ratio CRTs. Some games are designed to be displayed at 8:7 PAR (the core's default), and others at 1:1 PAR (square pixels). The `Square Pixels` option is provided to switch to a 1:1 pixel aspect ratio
-* `Pseudo Transparency` - Enable blending of adjacent pixels, used in some games to simulate transparency
-
-### Turbo
-
-* `CPU Turbo` - Applies a speed increase to the main SNES CPU. **NOTE:** This has different compatibility with different games. See the [MiSTer list of games](https://github.com/MiSTer-devel/SNES_MiSTer/blob/master/SNES_Turbo.md) that this feature works with
-* `SuperFX Turbo` - Applies a speed increase to the GSU (SuperFX) chip. Can be used in addition to the `CPU Turbo` option in games like Star Fox to maintain a higher frame rate.
-
-### Controller Options
-
-There are several options provided for selecting which type of controller the core will emulate.
-
-* `Gamepad` - The standard SNES controller used with most games.
-* `Super Scope` - The Super Scope lightgun that's used with most lightgun games. See Lightguns for more details.
-* `Justifier` - The Justifier lightgun that's used with Lethal Enforcers. See Lightguns for more details.
-* `Mouse` - The SNES mouse that's used with Mario Paint and several other games. See SNES Mouse for more details.
-
-### Lightguns
-
-Core supports virtual lightguns by selecting the `Super Scope` or `Justifier` options under `Controller Options`. Most lightgun games user the Super Scope but Lethal Enforcers uses the Justifier. The crosshair can be controlled with the D-Pad or left joystick, using the A button to fire and the B button to reload. D-Pad aim sensitivity can be adjusted with the `D-Pad Aim Speed` setting.
-
-**NOTE:** Joystick support for aiming only appears to work when a controller is paired over Bluetooth and not connected to the Analogue Dock directly by USB.
-
-### SNES Mouse
-
-Core supports a virtual SNES mouse by selecting `Mouse` under `Controller Options`. The mouse can be moved with the D-Pad or left joystick and left and right clicks can be performed by pressing the A and B buttons respectively. Mouse D-Pad movement sensitivity can be adjusted with the `D-Pad Aim Speed` setting.
-
-**NOTE:** The dock firmware doesn't currently support a USB mouse.
+SNES core by srg320, openFPGA port by agg23, MK3 emulation by Tim Boettiger.
+GPL-3.0 — see `LICENSE`; redistributions must include source.