magiceyes v0.6.0

magiceyes 0.6.0

Savestates, and a rendering bug that had been skewing every frame GP2X games drew into their
second framebuffer.

Savestates

• F5 saves where you are, F8 puts it back. Nine numbered slots as well: F6 and F7 pick one,
  Shift+F5 saves to it, Shift+F8 loads it. F4 opens a picker showing when each slot was saved
  and what was on screen at the time. All of it is on a new State menu too.
• A save is the whole machine, not a save file: both CPUs, all memory, the display and audio
  hardware, and the files the game had open, each reopened at the position it was at.
  A game's own save files are on disk and are not rewound with it, so loading a state from
  before an in-game save leaves that save file in place.
• Saves live in states// beside the executable, alongside the existing config, firmware,
  cache and saves folders, and can be moved with File then Settings.
• Saving does not disturb the running game: it stops, reads, and starts again, and the game
  carries on unaware. A load asked for while the emulator is paused takes effect when you
  resume.
• Also driveable from the control channel and the MCP tools, for scripted testing.

Rendering

• GP2X games that draw through the second framebuffer, /dev/fb1, had those frames come out
  three rows up and 64 pixels left, wrapped around the screen. The address handed to the game
  was not page aligned, so the game drew at one place and the display read from another. A
  game that alternates the two buffers gets it on every second frame, which in Payback looked
  like the picture jumping sideways as you played.
• The display scanout address is a 32 bit value held in two 16 bit registers, and games write
  it one half at a time. The display no longer acts on a half written address, which used to
  point it at neither buffer.

Audio

• Opening a second game left the sound device running at the first game's sample rate, so the
  new game played an octave too high and stuttered. It now reopens when the format changes.

Emulation correctness

• The self modifying code table is cleared when a game is unloaded. It was carrying into the
  next game, where skipping code invalidation is not safe.
• The second CPU core now stops and starts with the rest of the machine when a savestate is
  taken on a paused emulator.

Packaging

• The 0.5.0 download was built from a stale copy of the bundled runtime. The device libraries
  that ship inside the zip were four months old, so 0.5.0 went out without that period's work
  on the DRM stubs, the GLES and EGL shims, the EABI SDL shim, and two support libraries,
  even though its notes described those fixes. Nothing warned anyone: the runtime is staged
  separately from the source and the release job just used whatever had been staged last. The
  0.5.0 zip was 51MB where it should have been about 112MB, which is the whole tell.
  0.6.0 is built from the current runtime, so upgrading from 0.5.0 also brings you those
  fixes, and the release job now refuses to build when the staged runtime does not match the
  source it was built from.
• Release builds now apply the complete set of emulator core patches. Built from a clean
  checkout, which is what the release job does, four of them were being skipped, including the
  fix for the crash on loading a second game on Windows. That one affected released binaries
  only, not local builds.

Testing

• Savestates are covered by unit tests for the file format, an end to end test that saves,
  moves the game on, restores and checks the picture came back, and refusal tests for damaged,
  foreign and incompatible states.

magiceyes v0.5.0

magiceyes 0.5.0

A compatibility release: no new device, 97 commits of fixes found by running 972 games and
fixing what the failures had in common.

Compatibility

• 739 of 972 GP2X, Wiz and Caanoo games are playable; 794 put gameplay on screen. 52 boot to
  a black screen, 126 never render.
• By platform: GP2X 503/631, Wiz 117/147, Caanoo 119/194 (plus 44 Caanoo games that reach
  gameplay with a visible problem).
• When this testing started in August, 253 were playable. The bar changed once since then: it
  used to require 25 fps and working audio, and now requires 20 fps and allows silence, since
  many games have no audio at all.
• 59 folders held no runnable binary (source dumps, skin packs, data-only add-ons) and are not
  counted as games.

Engine: black screens

• The Wiz GLBasic games (~20 of them) drew into the framebuffer page the firmware SDL had
  panned away from and never flipped. The display now moves to the live page when the pinned
  one stops changing.
• A second mmap of /dev/fb0 shares the same pages instead of getting blank memory, and the Wiz
  portrait scanout ioctl is implemented.
• GP2X: framebuffer/upper-RAM aliasing, the /dev/dsp fill loop, and emulated device fds that
  were too high to survive a select().
• .bss is zeroed on MAP_FIXED, Pollux palettes are modelled, and static games get the GP2X
  display model regardless of which folder they shipped in.
• The touchscreen is a free-running ADC again, so games that wait on a touch reading at
  startup no longer hang.
• Pollux vsync, the mirrored 2D blitter register window, and the Pollux GPIO button pads (a
  stuck all-buttons-pressed word was quitting games at boot).

Engine: games that never started

• 151 games, mostly Caanoo, died in the dynamic loader on a missing library or symbol. Fixed
  by runtime staging and shim exports.
• Launcher scripts are read correctly (BennuGD and script-launched games), and libraries in
  the game folder take priority over firmware ones.
• SDL_FreeSurface no longer frees the video surface, matching real SDL 1.2. Games that free
  the screen on shutdown were corrupting the heap.
• Also: sigsuspend under LinuxThreads, synthetic /proc, indirect syscalls, SysV shared memory,
  affinity, a per-run guest /tmp, MIDI patch staging.

Engine: picture and speed

• Full 2D scaler model (line stride, horizontal downsample, vertical source stepping), which
  fixed the sheared and doubled picture problem. Volleyball shows the whole court, para3 shows
  all its text, 800x600 games are readable.
• Blits into paletted surfaces map to real palette indexes instead of index 0 (noiz2sa's white
  screen).
• Busy-polling on the pacing registers is throttled, which lifted 27 games off the fps floor.
  Audio device pacing fixed the Her Knights audio/video drift.

Compatibility tracker

Per-game compatibility is at
zdiemer/magiceyes-compat: one issue per game
with a screenshot, a clip, the status, and what stopped it. It replaces the short
hand-written list this repo used to carry.

Tooling (developer-facing)

• MCP debug server (tools/mcp/): a live engine across calls, with screenshots, filmstrips,
  input injection, audio analysis, run reports and thread state.
• Debugger core: pause, single-step, breakpoints, watchpoints, memory read/write, ELF symbols
  for named backtraces. Compiled out of release bundles; CI asserts the shipped magiceyes.exe
  contains neither the control channel nor a socket import.
• Test harness: scorecards, per-game results, motion clips, and checks that measure the picture
  itself (shear, duplication, noise, geometry).
• Automatic input: tests pick buttons based on what is on screen instead of running one fixed
  script, check each press against the same screen left alone, and avoid buttons that ended the
  game.

One backend

The qemu-user backend is gone. Linux now runs the same engine as Windows, which is what
every number above was measured on. ./magiceyes.sh launches that engine plus the viewer,
and it handles GPEComp files, folders and .zip archives itself, so there is no rootfs to
stage by hand. host/qemu/ and the duplicate device model in host/common/ are removed.

Known gaps

• 111 games run at speed with no audio, 42 run below 20 fps, 12 render a wrong picture.
• Of the 126 that never render: 44 are not 32-bit ARM binaries, 12 are incomplete or
  unextractable dumps, 62 are unexplained.
• Patissier renders incorrectly, the Rhythmos video background is Linux-only, and the Caanoo
  firmware menu does not take touch input.
• These numbers come from the Linux build. The Windows build compiles from the same engine
  sources, but its file, memory-mapping and timing layers differ and it has not been run game
  by game, so results on Windows may not match.

Full changelog: v0.4.0...v0.5.0

magiceyes v0.4.0

magiceyes 0.4.0

New device: GP2X Caanoo (Pollux)

• Caanoo support added — Propis, Rhythmos, and Redemption: Liar are playable.
• Rhythmos plays its songs with the MPEG-4 video background.
• Software then host-GPU GLES1.1/EGL shim, EABI runtime, touchscreen (mouse), and system fonts all bundled.

Compatibility

• Broader GP2X corpus support: incompatible titles cut from 22 to 13, unimplemented syscalls from 10 to 0.
• Wiz: Her Knights and Deicide 3 render correctly on the new real-libSDL path.

Engine

• Dynamic titles now run on the device's real libSDL instead of the fake-SDL shim (fixes blit/surface corruption).
• Host-GPU GLES passthrough — Caanoo GLES titles render on the real OpenGL GPU (default; ME_GL_BACKEND=sw to opt out).
• Fixed the Windows multi-reload heap-corruption crash and a hot-reload present/teardown race.
• Portable storage: config, firmware, cache, and per-game saves live beside the exe; content-hashed GPEComp cache.

Firmware boot and install

• Install real device firmware in-process (no external tools): Wiz (UBI/UBIFS), GP2X F100/F200 and Caanoo (YAFFS1/2).
• Boot the device's own gp2xmenu under the engine: render, navigate, and launch games.

Interface

• Controller support plus remappable per-device keybinds and an in-app settings overlay.
• Single-process Windows bundle: native menus, Settings tabs, keybind editor, confirm-on-exit, GPU-accelerated viewer.
• File > Open now loads dynamic Caanoo/Wiz titles.

Tooling

• Headless triage harness (tools/test): per-title and per-corpus scorecards, regression baselines, input record/replay.
• New COMPATIBILITY.md tracking per-title status across all three handhelds.
• CI builds the Windows bundle on every push and publishes the release zip on v* tags.

Known gaps

• Patissier is not yet working (Wiz and Caanoo).
• Odonata and Retrovirus (GP2X) and Propis (Wiz, no touchscreen) reach gameplay with notable gaps.

Full changelog: v0.3.0...v0.4.0

Release-build assets

Firmware/game-derived runtime assets (rootfs-eabi, rootfs-win, Caanoo fonts, guest stubs) consumed by the Release CI to package the Windows bundle. Refreshed by host/win/stage_release_assets.sh. Not a user download -- the runnable bundle is the v* releases.

magiceyes v0.3.0

Full Changelog: v0.2.0...v0.3.0

magiceyes v0.2.0

First native Windows release of magiceyes — run Game Park Holdings GP2X / Wiz games on a PC.

Highlights

• Single-process magiceyes.exe (engine + SDL2 viewer in one process); the only runtime dependency is the bundled SDL2.dll.
• Open with no game (empty window) or pass a .gpe, a game folder, or a .zip — a shell-script launcher .gpe is followed to the real ARM binary automatically.
• Native menu bar: File (Open / Open Recent / Reload / Exit), View (scale 1–4× / Fullscreen), Audio (Mute / Volume), Help (Controls / About).
• Inline GPEComp decompression for static self-extractors; File → Open hot-reloads a different game in-process (no restart).
• CLI: --scale, --fullscreen (also F11 / Alt-Enter), --mute, --volume, --timescale, --help, --version, plus ME_* diagnostic flags.

Status

GP2X static games and GPEComp stubs run (e.g. Payback — video, audio, input, ~30fps). Dynamically-linked titles (e.g. Wiz) are detected but not yet runnable in the native build (the native dynamic linker is still pending).

Install

Unzip and run magiceyes.exe — keep SDL2.dll next to it. See README.txt for controls.

Controls

D-pad = arrows · A/B/X/Y = Z/X/A/S · Start = Enter · Select = Backspace · L/R = Q/W · Fullscreen = F11 · Quit = Esc

---

Free software under the GNU GPL v2 (see LICENSE); statically links a fork of the Unicorn CPU emulator (qemu TCG). SDL2 is under the zlib license.