Home

Awesome

piuGBA

This is a PIU simulator for the GBA that uses StepMania SSC charts.

demo1demo2demo3demo4demo5demo6demo7demo8demo9demo10demo11demo12

<img alt="rlabs" width="16" height="16" src="https://user-images.githubusercontent.com/1631752/116227197-400d2380-a72a-11eb-9e7b-389aae76f13e.png" /> Created by [r]labs.

<img alt="discord" width="16" height="16" src="https://user-images.githubusercontent.com/1631752/116226650-a180c280-a729-11eb-8ae2-be2745d40481.png" /> Join our Discord server to find pre-built ROMs and user-created content!

Key features

Downloads

The downloads provided in our Releases section include:

To play, you need to download a ROM from our Discord or build a custom ROM.

How does it work?

A 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.

Charts 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.

Read the wiki for more details!

How to a build a ROM

Wiki: Building a ROM

Developing

Install - Any OS (Docker)

# download docker image
docker pull afska/piugba-dev

# compile game assets
./dockermake.sh assets

# install importer dependencies
./dockermake.sh install

# run ./dockermake.sh {action} {arguments...}
# for example, to build a clean Arcade ROM, use:
./dockermake.sh build ENV=production ARCADE=true

Actions

Commands

Parameters

NameValuesDescription
ENVdevelopment, or debug or productiondebug: everything is unlocked, backgrounds are disabled, and stage-break is OFF.<br>development: the same thing, but including backgrounds.<br>production: backgrounds, stage-break ON, and working locks.<br><br>Non-production versions also have:<br><br>1) PIU-style controls by default, and a debug menu to correct songs' offsets. See Wiki: Correcting offsets.<br><br>2) If SELECT is pressed when a campaign song starts, stage-break will be ON regardless of the environment.<br><br>3) Profiling code and some logs.
BOSSfalse or trueAutomatically adds boss levels to the campaign modes.
ARCADEfalse or trueCreates an arcade-only version of the game that only uses numeric levels, without the campaign modes.<br><br>Add this parameter to both import and build commands!
SONGSpath to a directorySongs directory. Defaults to: src/data/content/songs
VIDEOLIBpath to a directoryVideo library output directory. Defaults to: src/data/content/piuGBA_videos
VIDEOENABLEfalse or trueEnables the conversion of video files (from ${SONGS}/_videos) to the VIDEOLIB folder.
HQAUDIOLIBpath to a directoryHQ Audio library output directory. Defaults to: src/data/content/piuGBA_audios
HQAUDIOENABLEfalse or trueEnables the conversion of HQ audio files to the HQAUDIOLIB folder.
FASTfalse or trueUses async I/O to import songs faster. It may disrupt stdout order.

In Docker builds, for SONGS, VIDEOLIB and HQAUDIOLIB, only use relative paths to folders inside your project's directory!

Install - Windows (Native)

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.

cd scripts/importer
npm install

# set your ImageMagick install path here:
export PATH=$PATH:/c/Program\ Files/ImageMagick-7.0.10-Q16

export GBA_DIR="/c/Work/gba" # <<< CHANGE THIS PATH

export DEVKITPRO="$GBA_DIR/tools/devkitPro"
export PATH="$PATH:$GBA_DIR/tools/devkitPro/bin"
export PATH="$PATH:$GBA_DIR/tools/devkitPro/devkitARM/bin"
export PATH="$PATH:$GBA_DIR/tools/devkitPro/tools/bin"

VSCode

Scripts

Build sprites

# use #FF00FD as transparency color
grit *.bmp -ftc -pS -gB8 -gT ff00fd -O shared_palette.c

Build backgrounds

magick file.png -resize 240x160\! -colors 255 file.bmp
grit file.bmp -gt -gB8 -mRtf -mLs -ftb

Build music

ffmpeg -y -i file.mp3 -ac 1 -af 'aresample=18157' -strict unofficial -c:a gsm file.gsm
ffplay -ar 18157 file.gsm

Build filesystem

gbfs files.gbfs *.pius *.gsm *.bin
# pad rom.gba to a 256-byte boundary
cat rom.gba files.gbfs > rom.out.gba

Build gba-sprite-engine

rm -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/

Build importer.exe

cd scripts/importer
npm install -g pkg
pkg --targets node14-win --config package.json -o importer.exe --public --public-packages "*" --no-bytecode --compress GZip src/importer.js

Troubleshooting

How to debug

Undefined reference to function name

If you've added new folders, ensure they're in Makefile's SRCDIRS list!

Open-source projects involved