Add 3do/ subdir (baseline -- v0.1.0, no release yet)

Scaffolds the 3DO Opera test app following the established per-
console pattern (VERSION / CHANGELOG / LICENSE / README / Makefile-
free Docker build / etc.). v0.1.0 is the bring-up baseline: builds
a 2.5MB .iso via trapexit/3do-devkit and renders P1's live 32-bit
DoControlPad bitfield + per-button held labels.

Toolchain notes:

- trapexit/3do-devkit ships pre-built Norcroft ARM C compilers +
  3DO tools as Linux x86 binaries only. The 3doiso step is a Windows
  binary that runs under wine. Our buildtools/Dockerfile clones the
  devkit at a pinned commit, adds libc6-i386 + wine32, and pre-makes
  the devkit tree everyone-writable so the host-uid'd container run
  can overlay our src/main.cpp on top.
- On Apple Silicon / non-x86 hosts the container runs under
  --platform=linux/amd64 (CI's ubuntu-latest is native amd64, no
  emulation overhead).
- Wine wants HOME to be owned by the running user; bind-mount-backed
  /work/.wine-home works because /work belongs to the host user.

Wired into both CI workflows:

- verify-build.yml gets a new matrix entry + Build (3DO) step. CI
  picks up every push to main.
- release.yml gets the `3do)` parse-case + Build (3DO) + Stage
  (3DO) steps -- dormant until a `3do-v<semver>` tag is pushed.
  The release artifact name is joypad_tester_v<ver>_3do.iso.

Documentation:

- README.md Consoles + Acknowledgements tables gain 3do.
- CLAUDE.md existing-subdirs list gains 3do with toolchain caveats.
- .dev/docs/3do_roadmap.md tracks the queued v0.2+ work:
  multi-controller polling (up to 8 pads), per-port device-type
  detection (mouse / lightgun / sillypad / steering wheel, with
  parsed values + 3dodev.com refs), GameCube-style logo header,
  custom Joypad boot/splash replacing the devkit placeholder, and
  the matching joypad-logo bouncing screensaver (7-color cycle to
  match gcn/gba/pce).

Reference for the v0.2+ work: Charles Doty (RasterSoft)'s
3DO Controller Test Multi (2016, "free of any licences"); its 8-pad
polling loop + pure-C Sprite renderer are the patterns we'll lean
on. We didn't vendor any of his code into v0.1.0.

Author: RobertDaleSmith

.dev/docs/3do_roadmap.md

@@ -0,0 +1,90 @@
+# 3DO roadmap (v0.2 -> v1.0)
+
+`3do/` v0.1.0 is the bring-up baseline: scaffold + Docker build +
+single-pad P1 button readout. v1.0 = feature parity with the other
+consoles in the suite.
+
+## Reference: Charles Doty's 3DO Controller Test Multi
+
+[Source on 3dodev.com](https://3dodev.com/software/homebrew/console_tools),
+mirrored locally at `~/Downloads/3DOControllerTestMulti/`. Charles
+Doty (RasterSoft, 2016) released this "free of any licences, credit
+would be appreciated but not required" — so we can crib its patterns
+or vendor selected modules directly with credit.
+
+Specific reusable bits in his tree:
+- `src/System.c` — 8-pad `InitControlPad(8)` + `readControlPad` loop
+- `src/Sprite.c/.h` — pure-C CEL sprite renderer (don't need to
+  port back from trapexit's C++ `BasicDisplay` if we want lean C)
+- `src/Display.c` — screen-buffer + double-buffer setup
+- `Banner.bmp` + `Graphics/` — example art layout (the actual art
+  is RasterSoft branding, not for reuse, but the asset shape is)
+
+When we tackle items below, the first move is "look at Charles
+Doty's source for the device pattern, then build our own."
+
+## Pending work (queued for v0.2+)
+
+### 1. Multi-controller support (up to 8 pads)
+
+3DO supports up to 8 control pads via the daisy-chain protocol. Call
+`InitControlPad(8)` and render P1..P8 readouts. Render layout needs a
+rethink — the current single-screen P1-only layout doesn't scale.
+
+### 2. Device-type detection + parsed values
+
+Beyond the standard control pad, the 3DO supports:
+
+- **3DO Mouse** — X/Y movement, three buttons (L/M/R). API: separate
+  from `DoControlPad`; uses the event broker. Mouse-event packets
+  carry deltas and button mask. See https://3dodev.com/ docs on
+  ControlPad events and event-broker mouse-class IDs.
+- **Light Gun** — for games like Mad Dog McCree, Crime Patrol. Lives
+  on the same daisy-chain electrical interface but reports
+  (x, y, trigger) per event poll.
+- **SillyPad / arcade controllers** — variants that map to standard
+  pad bits but expose additional pins.
+- **Steering wheel** (Capcom CPS Changer-style) — niche, if anyone
+  actually shipped one.
+
+Per-port detection: probe each daisy-chain slot for its device-class
+ID and select the renderer accordingly. Display device-class label
+next to "P1/P2/.." (e.g., "P1: Mouse  x +12 y -8  L M R").
+
+Authoritative device-type docs live at https://3dodev.com/ — link to
+specific page(s) in the per-port renderer comment headers.
+
+### 3. Logo header on main screen
+
+Match the GameCube tester's top-of-screen branded layout: small
+joypad logo to the left of the "Joypad Tester - 3DO" title, rendered
+as a sprite/cel. Asset comes from `joypad/branding/logo_solid.svg`
+(or a 3DO-friendly resized derivative), converted to 3DO's CEL
+format via the devkit's `pcxtocel` tool (or equivalent).
+
+### 4. Custom boot/splash screen
+
+Replace the devkit's default banner.png with our own Joypad-branded
+splash. The 3DO BIOS reads the splash from the disc's TAKEME/banner
+area; bake-in is handled by the devkit's `3doiso` step. Source
+asset: `joypad/branding/` (same as other consoles), exported as a
+3DO-friendly 320x240 image.
+
+### 5. Bouncing-logo idle screensaver
+
+Identical to gcn/gba/pce: after 30s idle, clear screen and bounce
+the 64x64 joypad logo around the visible area, color-cycling through
+red -> green -> yellow -> blue -> magenta -> cyan -> white on each
+wall bounce, same step rate as the other consoles. Implementation
+uses the devkit's cel/sprite API + a small palette-mutate loop.
+
+### 6. Public release
+
+Tag `3do-v1.0.0` once items 1-5 land and the result is verified on:
+
+- RetroArch with Opera core (4DO emulation)
+- Real 3DO hardware (CD-R burn) or an ODE
+
+The release workflow + tag-prefix wiring is already in place
+(.github/workflows/release.yml has the `3do)` parse case + build +
+stage steps); just need the VERSION bump + tag push when ready.

.github/workflows/release.yml

@@ -36,6 +36,7 @@ jobs:
             snes)     PRETTY="Super Nintendo" ;;
             gba)      PRETTY="Game Boy Advance" ;;
             pce)      PRETTY="PC Engine" ;;
+            3do)      PRETTY="3DO" ;;
             *)        PRETTY="$CONSOLE" ;;
           esac
           echo "console=$CONSOLE" >> "$GITHUB_OUTPUT"
@@ -112,6 +113,26 @@ jobs:
             joypad-tester-huc:release \
             make
 
+      - name: Build (3DO)
+        if: needs.parse.outputs.console == '3do'
+        run: |
+          cd 3do
+          mkdir -p build .wine-home
+          docker build --platform=linux/amd64 -t joypad-tester-3do:release buildtools/
+          docker run --rm \
+            --platform=linux/amd64 \
+            -v "$(pwd):/work" \
+            -u "$(id -u):$(id -g)" \
+            -e HOME=/work/.wine-home \
+            joypad-tester-3do:release \
+            bash -c "
+              set -e
+              cp /work/src/main.cpp /opt/3do-devkit/src/main.cpp
+              cd /opt/3do-devkit
+              make NAME=joypad-tester
+              cp iso/joypad-tester.iso /work/build/joypad-tester.iso
+            "
+
       - name: Stage release artifacts (GameCube)
         if: needs.parse.outputs.console == 'gcn'
         working-directory: ${{ needs.parse.outputs.console }}
@@ -185,6 +206,16 @@ jobs:
           cp build/joypad-tester.pce "_release/joypad_tester_v${VERSION}.pce"
           ls -la _release/
 
+      - name: Stage release artifacts (3DO)
+        if: needs.parse.outputs.console == '3do'
+        working-directory: 3do
+        run: |
+          # Single .iso artifact; emulators + flash-friendly burn target.
+          VERSION="${{ needs.parse.outputs.version }}"
+          mkdir -p _release
+          cp build/joypad-tester.iso "_release/joypad_tester_v${VERSION}_3do.iso"
+          ls -la _release/
+
       - name: Build release body
         id: notes
         working-directory: ${{ needs.parse.outputs.console }}

.github/workflows/verify-build.yml

@@ -37,6 +37,12 @@ jobs:
             image: ""
             artifacts: |
               pce/build/joypad-tester.pce
+          - console: 3do
+            # trapexit/3do-devkit cloned at pinned commit inside
+            # 3do/buildtools/Dockerfile -- see the Build (3DO) step.
+            image: ""
+            artifacts: |
+              3do/build/joypad-tester.iso
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -104,6 +110,30 @@ jobs:
             joypad-tester-huc:ci \
             make
 
+      - name: Build (3DO)
+        if: matrix.console == '3do'
+        run: |
+          # ubuntu-latest is x86_64, so the --platform=linux/amd64 in
+          # the Dockerfile is a no-op (no emulation needed). The
+          # devkit + i386/wine setup gets cached in the image so only
+          # the first run is slow.
+          cd 3do
+          mkdir -p build .wine-home
+          docker build --platform=linux/amd64 -t joypad-tester-3do:ci buildtools/
+          docker run --rm \
+            --platform=linux/amd64 \
+            -v "$(pwd):/work" \
+            -u "$(id -u):$(id -g)" \
+            -e HOME=/work/.wine-home \
+            joypad-tester-3do:ci \
+            bash -c "
+              set -e
+              cp /work/src/main.cpp /opt/3do-devkit/src/main.cpp
+              cd /opt/3do-devkit
+              make NAME=joypad-tester
+              cp iso/joypad-tester.iso /work/build/joypad-tester.iso
+            "
+
       - name: Upload artifacts
         uses: actions/upload-artifact@v4
         with:

3do/.gitignore

@@ -0,0 +1,4 @@
+build/
+_release/
+.wine-home/
+.DS_Store

3do/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Joypad Tester — 3DO — Changelog
+
+## v0.1.0 — 2026-05-12
+
+First release. Bring-up of the 3DO controller test ROM via the
+trapexit/3do-devkit toolchain.
+
+### Highlights
+
+- Live P1 button readout: raw 32-bit `DoControlPad` bitfield rendered
+  on screen, plus per-button labels for the 11 standard 3DO inputs
+  (D-pad, A/B/C, Start, Stop, L/R shifts).
+- Two-pad slot reserved in the polling code (`InitControlPad (2)`) —
+  P2 hex is shown alongside P1; full P2 button-grid display comes
+  next.
+
+Full feature breakdown + build / loading instructions in
+[`3do/README.md`](https://github.com/joypad-ai/joypad-tester/blob/main/3do/README.md).

3do/LICENSE.md

@@ -0,0 +1,45 @@
+MIT License
+
+Copyright (c) 2026 Robert Dale Smith
+
+The Joypad Tester 3DO ROM source (`src/main.cpp`) is original work
+licensed under MIT.
+
+The build pipeline depends on Antonio SJ Musumeci's
+[3do-devkit](https://github.com/trapexit/3do-devkit) (ISC), which is
+cloned at a pinned commit by `buildtools/Dockerfile` and supplies:
+
+- the Norcroft ARM C/C++ compilers,
+- 3DO Portfolio SDK headers / libraries,
+- the `BasicDisplay` C++ helper class + `abort_err` panic handler
+  (used unmodified from the devkit's `src/`).
+
+`BasicDisplay` (`display.cpp`/`.hpp`) and `abort.c`/`abort.h` are
+trapexit's ISC code, linked into our LaunchMe as part of the
+standard devkit build. Their copyright + ISC notice live in the
+devkit repository.
+
+The 3DO Portfolio SDK headers (`include/3dosdk/`) are originally
+copyrighted by The 3DO Company; they are widely redistributed
+within the 3DO homebrew scene and ship inside the trapexit devkit
+that we depend on at build time.
+
+---
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

3do/README.md

@@ -0,0 +1,115 @@
+# Joypad Tester — 3DO
+
+3DO Opera (Panasonic FZ-1 / FZ-10, GoldStar GDO, Sanyo TRY, etc.)
+build of the [Joypad Tester](../README.md). Reads the 3DO control
+pad daisy-chain and renders the live button state on screen.
+
+## What it tests
+
+The active 3DO control pad's full 32-bit `DoControlPad` bitfield,
+shown as raw hex plus a per-button held-or-not grid:
+
+```
+Joypad Tester - 3DO
+===================
+
+P1 raw: 0x00000000
+P2 raw: 0x00000000
+
+P1 buttons:
+.       .
+.       .
+.       .
+.       .
+.       .
+.
+```
+
+| Source | Detected as |
+|--------|-------------|
+| 3DO control pad (D-pad, A/B/C, Start, Stop, L/R shift) | `DoControlPad` slot 1 / slot 2 |
+| 3DO mouse / lightgun / arcade panel | not yet wired (uses different SDK calls) |
+
+Buttons rendered: Up, Down, Left, Right, A, B, C, Start, Stop, L (Left
+Shift), R (Right Shift). "Stop" is the X button on the original 3DO
+pad — its symbol is the eject-style square.
+
+## trapexit/3do-devkit toolchain
+
+3DO homebrew is built with the Norcroft ARM C/C++ compilers (originally
+1990s ARM Ltd / Acorn) bundled in
+[trapexit/3do-devkit](https://github.com/trapexit/3do-devkit). The
+devkit also ships 3DO Portfolio SDK headers + a small modern C++
+helper layer (`BasicDisplay`, `abort_err`, etc.) that we link
+against unmodified. We pin to a specific devkit commit
+(`e0845bc4` at v0.1.0) inside [`buildtools/Dockerfile`](buildtools/Dockerfile);
+bumping it = rebuilding the image.
+
+The compilers are 32-bit x86 binaries (Linux only) — and one
+post-compile step (`3doiso`) is a Windows binary the devkit runs via
+Wine. The Docker image bakes both: `libc6-i386` for the 32-bit
+dynamic loader, `wine32` for the iso composer. On Apple Silicon or
+any non-x86 host, the container runs under `--platform=linux/amd64`.
+
+## Build
+
+The toolchain is Docker-only:
+
+```
+./build_docker.sh                # build (first run also builds image)
+./build_docker.sh clean          # nuke build/
+./build_docker.sh rebuild-image  # force toolchain image rebuild
+```
+
+`build/joypad-tester.iso` is the in-tree output. CI builds on every
+push to `main` (see
+[`.github/workflows/verify-build.yml`](../.github/workflows/verify-build.yml)).
+
+## Loading on hardware
+
+### 3DO emulator (Opera / Phoenix / RetroArch's Opera core)
+
+Drop `joypad_tester_v<ver>.iso` onto the emulator. Opera-based
+cores require a 3DO BIOS dump in their `system/` directory
+(`panafz1.bin` / `panafz10.bin` / `goldstar.bin` / `sanyotry.bin`).
+
+### Real 3DO hardware
+
+Burn the `.iso` to CD-R (700 MB blank, ISO mode — 3DO Opera
+filesystem is iso9660-compatible enough that standard burning tools
+handle it). Boot on a chipped console; unmodified retail consoles
+won't boot homebrew CDs.
+
+ODE / SD-loader options like the
+[Plextor / Polymega-replacement chips](https://3dodev.com/) are
+the contemporary path; check 3dodev.com for current hardware notes.
+
+## Releases
+
+Tagged as `3do-v<semver>` from the repo root — see
+[`3do/CHANGELOG.md`](CHANGELOG.md) for per-version notes. The release
+workflow attaches `joypad_tester_v<semver>_3do.iso` to each GitHub
+Release.
+
+## Origin / credits
+
+Built on Antonio SJ Musumeci's
+[3do-devkit](https://github.com/trapexit/3do-devkit) (ISC) — see
+[`LICENSE.md`](LICENSE.md). The Joypad Tester source
+(`src/main.cpp`) is original; `BasicDisplay` + `abort_err` come
+verbatim from the devkit and link in as part of the standard
+homebrew build.
+
+3DO Portfolio SDK headers / libraries shipped within the devkit are
+originally copyrighted by The 3DO Company and widely redistributed
+in the 3DO homebrew scene.
+
+Charles Doty (RasterSoft) wrote the original
+**3DO Controller Test Multi** (2016) — released "free of any licences,
+credit would be appreciated but not required". Distributed in the
+homebrew scene by Aer Fixus. Source is available on
+[3dodev.com](https://3dodev.com/software/homebrew/console_tools).
+Their 8-pad polling loop + Sprite/CEL rendering modules are the
+reference shape for our v0.2 multi-controller + screensaver work
+(see `.dev/docs/3do_roadmap.md`). v0.1.0 is a from-scratch bring-up
+against the modern trapexit devkit's `BasicDisplay` helper.

3do/VERSION

@@ -0,0 +1 @@
+0.1.0