ailu-puzzle

A native port of Felyne Puzzle (アイルーでパズルー, Airu de Puzzle, PSP, Japan, NPJH-50614), the Monster Hunter Diary puzzle game, made by static recompilation: the game's PSP code is translated ahead of time into C++ and compiled for your machine, then run on a reimplementation of the PSP system software. It is not an emulator and not a decompilation.

[!IMPORTANT] ailu-puzzle is built on Yakumo, TeamGDB's native port of Monster Hunter Portable 3rd HD Ver., and on the PSPRecomp framework it uses. ailu-puzzle is a fork that specifically targets Felyne Puzzle (アイルーでパズルー) and no other game: its game profile, profiles/ailupuzzle, adapts Yakumo's recompiler, PSP system and renderer to this title.

ailu-puzzle is an independent project. It is not part of Yakumo and is not affiliated with, reviewed or endorsed by TeamGDB or the Yakumo authors. Please do not report ailu-puzzle problems to the Yakumo project. To play Monster Hunter Portable 3rd HD Ver., use Yakumo itself.

This project does not include any game assets. You must provide the files from your own legally obtained copy of Felyne Puzzle (NPJH-50614, version 1.00) to build and play ailu-puzzle.

Legal disclaimer

ailu-puzzle is an independent, open-source project and is not affiliated with, authorized by, sponsored by, or endorsed by CAPCOM, Sony, or any of their affiliates.

Monster Hunter, Felyne Puzzle (アイルーでパズルー), CAPCOM, PlayStation, PSP, and all related trademarks, game assets, artwork, audio, characters, and other intellectual property belong to their respective owners.

ailu-puzzle does not include any game assets or original game files: no disc image, no copy of the game's executable or data, no code recompiled from it, and no textures, models, audio or video from the game. Every build generates its code from the player's own copy of the game.

Because of that, the programs and packages you build (the executable, the AppImage, the Android APK) contain code derived from your copy of the game. Keep them for your own use and do not share them.

Users are solely responsible for obtaining, dumping, extracting, and using their game copy in accordance with the laws applicable in their jurisdiction. ailu-puzzle does not support, provide, link to, or encourage the use of unauthorized or pirated copies of the game.

Any references to the original game or its trademarks are made solely for identification, compatibility, and interoperability purposes. The license covering ailu-puzzle applies only to the project's own original code and materials and to the code it inherits from Yakumo and PSPRecomp under their MIT License; it does not grant any rights to third-party intellectual property.

Status: playable, early

On Linux (Mesa, recorded with scripted input) the game shows its save-data dialogs and the title screen with its music, and plays through the main menu, Felyne creation, the festival mode's first story scenes and the first puzzles at the PSP's 30 frames per second.

Works	Not verified yet, or missing
The whole game recompiled (2 780 functions), decrypted from your own EBOOT.BIN	Long play sessions and every game mode
Disc reading straight from your .iso, menus, text, 2D and 3D drawing	Sound on real speakers (music and effects decode; nobody has listened yet)
Felyne creation, story scenes, puzzles	The AppImage, the Steam Deck and the Android build for this game
Saving and loading the system save	Online features and local wireless play (not implemented)

profiles/ailupuzzle/README.md is the player and builder guide; profiles/ailupuzzle/BRINGUP.md records what was fixed, how it was verified, and what is known to be missing.

Building and playing

ailu-puzzle is built from source, on your machine, from your own disc image. On Arch Linux:

profiles/ailupuzzle/scripts/build_linux.sh --deps --iso ~/Games/FelynePuzzle.iso
out/ailupuzzle/bin/Yakumo profiles/ailupuzzle/game

The first build takes one to three hours. The same script makes an AppImage for Linux desktops and SteamOS (--appimage, or --sdk to build it in the Steam Runtime container), and profiles/ailupuzzle/scripts/build_android.sh makes an Android APK. Every option is in the profile README.

Disc mods

Patches for the disc image (xdelta patches against the clean ISO) can be used as disc mods: profiles/ailupuzzle/tools/make_disc_mod.py turns a patch and your clean image into a small mod that is applied while the game reads the disc, leaving your image untouched, and the in-game menu's Mods page or profiles/ailupuzzle/scripts/mods.sh turns it on and off. See Disc mods.

Names you will still see

To keep the fork easy to update from Yakumo, ailu-puzzle keeps Yakumo's internal names: the program is out/ailupuzzle/bin/Yakumo and its window says ailu-puzzle, settings and saves live in ~/.local/share/Yakumo/AiluPuzzle/, and the environment variables start with MHP3RD_. These names do not mean the program is Yakumo or plays Monster Hunter Portable 3rd.

How it works

The game's code, PSP_GAME/SYSDIR/EBOOT.BIN, is decrypted, analyzed and every instruction is emitted as C++, which is compiled into the program; an interpreter covers anything the analysis missed, so nothing stops the game, it only runs slower there. Around that code sits a reimplementation of the PSP system inherited from Yakumo and extended for this game: a kernel with threads, semaphores, lightweight mutexes, callbacks and timers; disc I/O read straight from the image; a Vulkan renderer for the PSP's graphics engine; software voice mixing, ATRAC music and the PSP font library; and input from SDL3.

Repository layout

profiles/ailupuzzle/   ailu-puzzle: everything specific to Felyne Puzzle, with its
                     host, build scripts, packaging, tests and documentation
include/psprecomp/   Framework interfaces: runtime, memory, Allegrex state (from PSPRecomp, via Yakumo)
src/                 Framework: ELF loading, decoder, runtime, interpreter
tools/               Framework: analyzer and C++ code generator
tests/               Framework regression tests
configs/             PSP NID data
profiles/mhp3rd/     Yakumo's original profile for Monster Hunter Portable 3rd HD Ver.,
                     kept unchanged as the base ailu-puzzle was forked from
docs/                Yakumo's guides, inherited (see below)

The recompiled code is generated locally from your copy of the game and is never committed.

Documentation

Document	What it covers
profiles/ailupuzzle/README.md	Building on Arch Linux, the AppImage, Android, disc mods, running and debugging ailu-puzzle
profiles/ailupuzzle/BRINGUP.md	What was fixed to make the game run, how each fix was verified, known gaps
profiles/ailupuzzle/MHP3RD_HOST_REFERENCE.md	Yakumo's guide to the controls, settings and variables ailu-puzzle inherits
docs/, AGENTS.md, CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md	Yakumo's own documents, inherited unchanged apart from a note at the top. They describe Yakumo and Monster Hunter Portable 3rd HD Ver.; the framework parts (architecture, build system, profile guide) apply to ailu-puzzle too
README.es.md, README.ru.md	Yakumo's Spanish and Russian READMEs, inherited; they describe Yakumo

Credits

ailu-puzzle exists because of the work it is built on:

• Yakumo by @MHunterG and @mojitosunrise (TeamGDB): the PSP system, renderer, audio, movies, saves, interface and build that ailu-puzzle adapts
• PSPRecomp: the static recompilation framework
• SDL3: windowing, input and audio output
• FFmpeg: music and movie decoding
• Vulkan: rendering
• Dear ImGui: the menus and setup screens
• tiny-AES-c: save-data support
• stb_truetype: font rasterization
• xxHash: texture hashing

Third-party notices are in profiles/ailupuzzle/packaging/THIRD_PARTY_NOTICES.md.

License

MIT; see LICENSE. The copyright notices of the PSPRecomp and Yakumo contributors in it are kept, as the license requires. Third-party files keep their own notices beside them.