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
    • Multi Coop: Double (10-panel) charts via Link Cable
  • Impossible: Hardcore charts with insane mods
• Speed multipliers can be changed in-game
• Mods support:
  • Stage break
  • Pixelate: Mosaic effect
  • Jump/Reduce: Moves game area
  • Decolorize: Inverts/removes colors
  • Random speed
  • Mirror and random steps
  • Training mode: Rate and checkpoints
• Hardware integrations:
  • Rumble
  • I/O LED Sync
  • SRAM LED Sync
• BGA DARK background with blink effect
• Song selector with names, backgrounds and sound previews
• Optimized to support ~70 songs per ROM file.

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

• Install everything (read the section below).
• Create in src/data/content/songs one folder per song, including:
  • one .mp3 file with the song
  • one .png file with the background
  • one .ssc file with the charts
• Run:

make import
make assets
make restart ENV=production

Full guide:

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 10: 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 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: Reimport 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 ../

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, check if they're in Makefile's SRCDIRS list!

Open-source projects involved

• wgroeneveld/gba-sprite-engine: Dec 18, 2019
  • Forked at: rodri042/gba-sprite-engine
• pinobatch/gsmplayer-gba: Feb 9, 2020
• rodri042/gba-link-connection