piuGBA

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

Created by [r]labs.

Join our Discord server to find pre-built ROMs and user-created content!

Key features

• Full .ssc files support, including:
  • Normal, hold and fake notes
  • BPM changes
  • Scroll speed changes
  • Stops/Delays and async-stops
  • Warps and fast-BPM warps
• Multiple game modes:
  • Campaign: Play, unlock songs and defeat bosses
  • Arcade: Play songs in any numerical difficulty level
    • Single: 1 player, either Single (5-panel) or Double (10-panel) charts
    • Multi VS: VS battles via Link Cable or Wireless Adapter
    • Multi COOP: Double (10-panel) charts via Link Cable or Wireless Adapter
  • Impossible: Faster songs with insane mods
• Speed multipliers can be changed in-game
• Mods support:
  • Stage break: On, Off or SuddenDeath
  • Pixelate: Mosaic effect
  • Jump/Reduce: Moves game area
  • Bounce: Makes the arrows bounce
  • Color filter: Alters colors
  • Speed hack: AutoVelocity, FixedVelocity or RandomSpeed
  • Mirror and random steps
  • Training mode: Rate and Fast-forward
  • AutoMod: Swaps mods randomly
• Background videos can be displayed using an EverDrive
• Hardware integrations:
  • Rumble
  • I/O LED Sync
  • SRAM LED Sync
  • PS/2 input
• BGA DARK background with blink effect
• Song selector with names, backgrounds and sound previews
• Optimized to support ~70 songs per ROM file.

Downloads

The downloads provided in our Releases section include:

• A portable song importer for Windows.
• 4 clean builds (without songs) ready to be used with the importer.
  • If you use the portable importer, these files are not needed!
• A small demo with 9 songs from Project Outfox Serenity's Volume I & II sets.

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

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

Install

Windows

• Choose a folder (from now, GBA_DIR) and use this file structure:
  • gba
    • tools
      • devkitPro
    • projects
      • piugba
• Install the toolchain:
  • Dev
    • devkitPro&gcc 9.1.0: The devkit for compiling GBA ROMs. It comes with:
      • grit: Used to convert paletted bitmaps to C arrays or raw binary files
      • gbfs: Used to create a package with all the game assets
    • node.js 14.*: The JS runtime
    • make 3.81: The build automation tool
  • Media Processing
    • ImageMagick 7.0.10.3: The tool used to convert images to paletted bitmaps
    • ffmpeg (with libgsm) 3.3.3: The tool used to convert audio files to PCM
      • To avoid using the ffmpeg.exe binary included with ImageMagick, add it to PATH first!
      • Check this by running where ffmpeg
    • pngfix: A small command line util to fix corrupted PNG files
  • Other
    • Git Bash: Linux shell and tools. It contains required commands like dd or md5sum
    • VSCode: The IDE
• Install node dependencies:

cd scripts/importer
npm install

• Add to ~/.bash_profile:

# 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"

• You can check if the tools are installed correctly by running ./scripts/toolchain/check.sh

VSCode

• Recommended plugins: C/C++ Extensions, EditorConfig, Prettier - Code formatter
• Recommended settings: here

Actions

Commands

• make clean: Cleans build artifacts
• make assets: Compiles the needed assets in src/data/content/_compiled_sprites (required for compiling)
• make build: Compiles and generates a .gba file without data
• make import: Imports the songs from src/data/content/songs to a GBFS file
• make package: Compiles and appends the GBFS file to the ROM
• make start: Starts the compiled ROM
• make rebuild: Recompiles (clean+build+package) a full ROM
• make restart: Recompiles and starts the ROM
• make reimport: Reimports the songs and starts the ROM without recompiling

Parameters

Scripts

Build sprites

# use #FF00FF as transparency color
grit *.bmp -ftc -pS -gB8 -gT ff00ff -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

• In Makefile, replace -Ofast by -Og -g to include debug symbols in the .elf file
• In mGBA, go to Tools -> Start GDB server...
• Start debugging in VS Code

Undefined reference to function name

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

Open-source projects involved

• wgroeneveld/gba-sprite-engine: Dec 18, 2019
  • Forked at: afska/gba-sprite-engine
• pinobatch/gsmplayer-gba: Feb 9, 2020
• AntonioND/libugba: May 20, 2022
• afska/gba-link-connection: v6.0.3
• FatFS: R0.15