{"id":39892857,"url":"https://github.com/afska/piugba","last_synced_at":"2026-01-18T14:44:36.917Z","repository":{"id":53136744,"uuid":"242247485","full_name":"afska/piugba","owner":"afska","description":"🎮 PIU simulator for the GBA.","archived":false,"fork":false,"pushed_at":"2025-11-08T00:26:06.000Z","size":13285,"stargazers_count":124,"open_issues_count":0,"forks_count":6,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-11-08T02:32:37.397Z","etag":null,"topics":["advance","ddr","game-boy-advance","gameboy","gba","homebrew","link-cable","multiplayer","piu","pump","pump-it-up","rhythm","rhythm-game","rom","stepmania","wireless-adapter"],"latest_commit_sha":null,"homepage":"https://discord.com/invite/JE33cc2","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/afska.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-02-21T23:19:14.000Z","updated_at":"2025-11-08T00:26:11.000Z","dependencies_parsed_at":"2023-10-14T17:16:40.133Z","dependency_job_id":"f5d9ae01-7848-4c64-8598-8a256bf41e1a","html_url":"https://github.com/afska/piugba","commit_stats":{"total_commits":1617,"total_committers":1,"mean_commits":1617.0,"dds":0.0,"last_synced_commit":"ec5b165a0d310d3cd79bffbd47aca66d2253b9f1"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/afska/piugba","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afska%2Fpiugba","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afska%2Fpiugba/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afska%2Fpiugba/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afska%2Fpiugba/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/afska","download_url":"https://codeload.github.com/afska/piugba/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afska%2Fpiugba/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28538316,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T13:04:05.990Z","status":"ssl_error","status_checked_at":"2026-01-18T13:01:44.092Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["advance","ddr","game-boy-advance","gameboy","gba","homebrew","link-cable","multiplayer","piu","pump","pump-it-up","rhythm","rhythm-game","rom","stepmania","wireless-adapter"],"created_at":"2026-01-18T14:44:36.369Z","updated_at":"2026-01-18T14:44:36.903Z","avatar_url":"https://github.com/afska.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# piuGBA\n\nThis is a PIU simulator for the GBA that uses [StepMania](https://github.com/stepmania/stepmania) SSC charts.\n\n![demo1](https://i.imgur.com/Lo1Mxdd.gif)![demo2](https://i.imgur.com/GpeOG6v.gif)![demo3](https://i.imgur.com/FJzNbrp.gif)![demo4](https://i.imgur.com/yFCJ6uO.gif)![demo5](https://i.imgur.com/EXxgXyX.gif)![demo6](https://i.imgur.com/TsE0Y8n.gif)![demo7](https://i.imgur.com/y3IulCQ.gif)![demo8](https://i.imgur.com/9D3H3DO.gif)![demo9](https://i.imgur.com/asZvw0g.gif)![demo10](https://i.imgur.com/OV3ugLj.gif)![demo11](https://i.imgur.com/m4D0HYn.gif)![demo12](https://i.imgur.com/gqwIXPk.gif)\n\n\u003e \u003cimg alt=\"rlabs\" width=\"16\" height=\"16\" src=\"https://user-images.githubusercontent.com/1631752/116227197-400d2380-a72a-11eb-9e7b-389aae76f13e.png\" /\u003e Created by [[r]labs](https://r-labs.io).\n\n\u003e \u003cimg alt=\"discord\" width=\"16\" height=\"16\" src=\"https://user-images.githubusercontent.com/1631752/116226650-a180c280-a729-11eb-8ae2-be2745d40481.png\" /\u003e Join our [community](https://discord.com/invite/JE33cc2)!\n\n## Key features\n\n- Full **.ssc files** support, including:\n - Normal, hold and fake notes\n - BPM changes\n - Scroll speed changes\n - Stops/Delays and async-stops\n - Warps and fast-BPM warps\n- Multiple **game modes**:\n - Campaign: Play, unlock songs and defeat bosses\n - Arcade: Play songs in any numerical difficulty level\n - Single: 1 player, either Single (5-panel) or Double (10-panel) charts\n - Multi VS: VS battles via Link Cable or Wireless Adapter\n - Multi COOP: Double (10-panel) charts via Link Cable or Wireless Adapter\n - Impossible: Faster songs with insane mods\n- **Speed multipliers** can be changed in-game\n- **Mods** support:\n - Stage break: On, Off or SuddenDeath\n - Pixelate: Mosaic effect\n - Jump/Reduce: Moves game area\n - Bounce: Makes the arrows bounce\n - Color filter: Alters colors\n - Speed hack: AutoVelocity, FixedVelocity or RandomSpeed\n - Mirror and random steps\n - Training mode: Rate, Fast-forward, Rewind\n - AutoMod: Swaps mods randomly\n- **Background videos** _(uncompressed 240x160)_ can be displayed using a flash cart\n- **HQ audio** _(uncompressed s8 PCM)_ can be played using a flash cart\n- Two **themes**: _Classic_ and _Modern_\n- **BGA DARK** background with blink effect\n- **Song selector** with names, backgrounds and sound previews\n- Hardware **integrations**:\n - Rumble\n - I/O LED Sync\n - SRAM LED Sync\n - PS/2 input\n- **Optimized** to support ~70 songs per ROM file.\n\n## Downloads\n\nThe downloads provided in our [Releases](https://github.com/afska/piugba/releases) section include:\n\n- A portable song importer for Windows.\n- 4 clean builds (without songs) ready to be used with the importer.\n - _If you use the portable importer, these files are not needed!_\n- A small demo with 9 songs from [Project Outfox Serenity](https://projectoutfox.com/outfox-serenity)'s Volume I \u0026 II sets.\n\n**To play, you need to [build a ROM with your songs](https://github.com/afska/piugba/wiki/Building-a-ROM).**\n\n## How does it work?\n\nA node.js script (the **importer**) converts a list of SSC/MP3/PNG files into binary files which the GBA can then understand. For audio, it uses GSM audio files which are very small in size.\n\nCharts are converted into a format created for this project called **PIUS**. Then everything is bundled in a **GBFS** file (a filesystem created by the GBA scene) and appended to the final ROM.\n\n**[Read the wiki](https://github.com/afska/piugba/wiki)** for more details!\n\n## How to a build a ROM\n\n**[Wiki: Building a ROM](https://github.com/afska/piugba/wiki/Building-a-ROM)**\n\n# Developing\n\n## Install - Any OS (Docker)\n\n- If you are on Windows, install [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install)\n- Install [Docker](https://www.docker.com/)\n- Run:\n```bash\n# download docker image\ndocker pull afska/piugba-dev\n\n# compile game assets\n./dockermake.sh assets\n\n# install importer dependencies\n./dockermake.sh install\n\n# run ./dockermake.sh {action} {arguments...}\n# for example, to build a clean Arcade ROM, use:\n./dockermake.sh build ENV=production ARCADE=true\n```\n\n## Actions\n\n### Commands\n\n- `make install`: Installs the importer dependencies\n- `make check`: Verifies that all the tools are installed correctly\n- `make clean`: Cleans build artifacts (except assets)\n- `make assets`: Compiles the needed assets in `src/data/content/_compiled_sprites` (required for compiling)\n- `make build`: Compiles and generates a `.gba` file without data\n- `make import`: Imports the songs from `src/data/content/songs` to a GBFS file\n- `make pkg`: Appends the GBFS file to the ROM (`piugba.gba` -\u003e `piugba.out.gba`)\n- `make package`: Compiles and appends the GBFS file to the ROM _(build+pkg)_\n- `make start`: Packages and starts the compiled ROM _(package + launch rom)_\n- `make rebuild`: Recompiles a full ROM _(clean+package)_\n- `make restart`: Recompiles and starts the ROM _(rebuild+start)_\n- `make reimport`: Reimports the songs and starts the ROM without recompiling _(import+package+start)_\n\n### Parameters\n\n| Name | Values | Description |\n| --------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `ENV` | **`development`**, or `debug` or `production` | `debug`: everything is unlocked, backgrounds are disabled, and stage-break is OFF.\u003cbr\u003e`development`: the same thing, but including backgrounds.\u003cbr\u003e`production`: backgrounds, stage-break ON, and working locks.\u003cbr\u003e\u003cbr\u003eNon-production versions also have:\u003cbr\u003e\u003cbr\u003e1) PIU-style controls by default, and a _debug menu_ to correct songs' offsets. See **[Wiki: Correcting offsets](https://github.com/afska/piugba/wiki/Building-a-ROM#correcting-offsets)**.\u003cbr\u003e\u003cbr\u003e2) If _SELECT_ is pressed when a campaign song starts, stage-break will be ON regardless of the environment.\u003cbr\u003e\u003cbr\u003e3) Profiling code and some logs. |\n| `BOSS` | false or **true** | Automatically adds _boss levels_ to the campaign modes. |\n| `ARCADE` | **false** or true | Creates an arcade-only version of the game that only uses numeric levels, without the campaign modes.\u003cbr\u003e\u003cbr\u003eAdd this parameter to both _import_ and _build_ commands! |\n| `SONGS` | _path to a directory_ | Songs directory. Defaults to: `src/data/content/songs` |\n| `VIDEOLIB` | _path to a directory_ | Video library output directory. Defaults to: `src/data/content/piuGBA_videos` |\n| `VIDEOENABLE` | **false** or true | Enables the conversion of video files (from `${SONGS}/_videos`) to the `VIDEOLIB` folder. |\n| `HQAUDIOLIB` | _path to a directory_ | HQ Audio library output directory. Defaults to: `src/data/content/piuGBA_audios` |\n| `HQAUDIOENABLE` | **false** or true | Enables the conversion of HQ audio files to the `HQAUDIOLIB` folder. |\n| `FAST` | **false** or true | Uses async I/O to import songs faster. It may disrupt stdout order. |\n\n\u003e In Docker builds, for `SONGS`, `VIDEOLIB` and `HQAUDIOLIB`, only use relative paths to folders inside your project's directory!\n\n## Install - Windows (Native)\n\n\u003e Advanced usage only! The code requires specific versions of tools that are difficult to obtain, and I cannot provide them. I created the Docker image so everyone can have the same environment.\n\n- Choose a folder (from now, `GBA_DIR`) and use this file structure:\n - `gba`\n - `tools`\n - `devkitPro`\n - `projects`\n - `piugba`\n- Install the toolchain:\n - Dev\n - **devkitPro** `r53` (with gcc `9.1.0`): The devkit for compiling GBA ROMs. It comes with:\n - _grit_: Used to convert paletted bitmaps to C arrays or raw binary files\n - _gbfs_: Used to create a package with all the game assets\n - ⚠️ While newer versions of gcc may work, they might require some tweaks. I've noticed that with gcc 14 the code runs 5% slower and have worse compatibility with some emulators, so I prefer to stick with gcc 9.\n - **node** `14.*`: The JS runtime\n - **make** `3.81` (compiled for `i386-pc-mingw32`): The build automation tool\n - Media Processing\n - **ImageMagick** `7.0.10.3`: The tool used to convert images to paletted bitmaps\n - **ffmpeg** `3.3.3` (bundled with `libgsm`): The tool used to convert audio files to GSM\n - ⚠️ Avoid using the `ffmpeg.exe` binary included with _ImageMagick_ or any other version. After `3.3.3`, they stopped including `libgsm` on Windows builds.\n - **png-fix-IDAT-windowsize** `0.5`: A small command line util to fix corrupted PNG files\n - Other\n - [Git Bash](https://gitforwindows.org): Linux shell and tools. It contains required commands like `dd` or `md5sum`\n - [VSCode](https://code.visualstudio.com): The IDE\n- Install node dependencies:\n\n```bash\ncd scripts/importer\nnpm install\n```\n\n- Add to `~/.bash_profile`:\n\n```bash\n# set your ImageMagick install path here:\nexport PATH=$PATH:/c/Program\\ Files/ImageMagick-7.0.10-Q16\n\nexport GBA_DIR=\"/c/Work/gba\" # \u003c\u003c\u003c CHANGE THIS PATH\n\nexport DEVKITPRO=\"$GBA_DIR/tools/devkitPro\"\nexport PATH=\"$PATH:$GBA_DIR/tools/devkitPro/bin\"\nexport PATH=\"$PATH:$GBA_DIR/tools/devkitPro/devkitARM/bin\"\nexport PATH=\"$PATH:$GBA_DIR/tools/devkitPro/tools/bin\"\n```\n\n- You can check if the tools are installed correctly by running `make check`\n\n## VSCode\n\n- Recommended plugins: `C/C++ Extensions`, `EditorConfig`, `Prettier - Code formatter`\n- Recommended settings: [here](scripts/toolchain/vscode_settings.json)\n\n## Scripts\n\n### Build sprites\n\n```bash\n# use #FF00FD as transparency color\ngrit *.bmp -ftc -pS -gB8 -gT ff00fd -O shared_palette.c\n```\n\n### Build backgrounds\n\n```bash\nmagick file.png -resize 240x160\\! -colors 255 file.bmp\ngrit file.bmp -gt -gB8 -mRtf -mLs -ftb\n```\n\n### Build music\n\n```bash\nffmpeg -y -i file.mp3 -ac 1 -af 'aresample=18157' -strict unofficial -c:a gsm file.gsm\nffplay -ar 18157 file.gsm\n```\n\n### Build filesystem\n\n```bash\ngbfs files.gbfs *.pius *.gsm *.bin\n# pad rom.gba to a 256-byte boundary\ncat rom.gba files.gbfs \u003e rom.out.gba\n```\n\n### Build gba-sprite-engine\n\n```bash\nrm -rf cmake-build-debug ; mkdir cmake-build-debug ; cd cmake-build-debug ; cmake ../ -G \"Unix Makefiles\" ; make ; cp engine/libgba-sprite-engine.a ../../piugba/libs/libgba-sprite-engine/lib/libgba-sprite-engine.a ; cd ../ ; rm -rf ../piugba/libs/libgba-sprite-engine/include/ ; cp -r ./engine/include ../piugba/libs/libgba-sprite-engine/\n```\n\n### Build importer.exe\n\n```bash\ncd scripts/importer\nnpm install -g pkg\npkg --targets node14-win --config package.json -o importer.exe --public --public-packages \"*\" --no-bytecode --compress GZip src/importer.js\n```\n\n## Troubleshooting\n\n### How to debug\n\n- In `Makefile`, replace `-Ofast` by `-Og -g` to include debug symbols in the `.elf` file\n- In mGBA, go to Tools -\u003e Start GDB server...\n- Start debugging in VS Code\n\n### Undefined reference to _function name_\n\nIf you've added new folders, ensure they're in `Makefile`'s `SRCDIRS` list!\n\n## Open-source projects involved\n\n- Sprite engine by [wgroeneveld/gba-sprite-engine](https://github.com/wgroeneveld/gba-sprite-engine): Dec 18, 2019\n - Forked at: [afska/gba-sprite-engine](https://github.com/afska/gba-sprite-engine)\n- GBA hardware access by [tonclib](https://github.com/gbadev-org/libtonc)\n- GSM playback by [pinobatch/gsmplayer-gba](https://github.com/pinobatch/gsmplayer-gba): Feb 9, 2020 + optimizations\n- Interrupt handler by [AntonioND/libugba](https://github.com/AntonioND/libugba): v0.3.0\n- LZ77 decompression by [Cult-of-GBA/BIOS](https://github.com/Cult-of-GBA/BIOS): Sep 11, 2024\n- Multiplayer support by [afska/gba-link-connection](https://github.com/afska/gba-link-connection): v8.0.0\n- microSD reading by [afska/gba-flashcartio](https://github.com/afska/gba-flashcartio): v1.0.5 + fixes\n- FAT parsing by [FatFS](http://elm-chan.org/fsw/ff/): R0.15\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fafska%2Fpiugba","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fafska%2Fpiugba","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fafska%2Fpiugba/lists"}