Saturday, December 13, 2014

Handbell Hero!


It's like Guitar Hero, with 4 to 8 players, using a set of handbells from Groth Music. No musical background is necessary to play!


Every year, HelpSystems has an annual employee luncheon, which also involves some kind of game/entertainment thing that's led by a department.

Our department manager, Matt Bresnan, came up with the idea of putting together a Guitar Hero type of game, but using a set of handbells. I was asked to look into the feasibility of writing this app, and was given the MythBusters directive that If it's worth doing, it's worth overdoing!

Given the tools that I already know, Java was the easy choice because it has MIDI capabilities built into the language (which seems excessive, but extremely helpful). On the front-end, JavaFx was the right fit for this project.

Building and Running the game

The instructions for downloading, building, and running the game can be found at the GitHub repo:

The game works best on a Windows PC (using a 720p display or projector), and you'll need the Java 8 SDK (free download) installed (and in your PATH).

After a song completes, you'll need to press Alt-F4 to return to the menu screen (yeah, it's lame - I had it coded up to auto-close the window when the MIDI player/sequencer finished, but occasionally would receive an erroneous/premature "player stopped" event, that would close the game screen)


The most technically challenging part of this game is getting the "falling notes" to sync up with the music as it's played. This involves a bit of "lead-in" time ahead of the player, which means the UI has to understand MIDI tempo information.  For some reason, I couldn't get the math to work out, given the Sequence's Division Type, the Sequencer Tempo in MPQ, and the Sequencer Tempo in BPM.

I found numerous posts and Stack Overflow questions related to this topic, but the math never seemed to work out correctly. 

In the end, I just used a lame/dirty hack involving a properties file which specifies the number of "ticks per second" used by each of the MIDI files. Tip - the app defaults to 1700 ticks per second, so if your file happens to be close to that, there's no adjustment needed.

An even bigger limitation

This game currently ignores the MIDI Set Tempo events that occur within the MIDI Sequence.  There is code present to find/read those events, but since the math/calculations never worked out, I just stuck to fixed-tempo songs.

Adding your own MIDI files

If you'd like to use your own MIDI files (using just the key of C Major), you'll need to save them into the "midi" directory.  If you find that the UI starts at the wrong tempo (which is very likely), run the app using the command hh.bat log

Select your song, and let it play for a few seconds, then close the game (press Alt-F4 a few times).  In your Command Prompt window, you'll see stuff like this:

Ticks 4259.0 to 4341.0
Track entries 8 to 8

Ticks 4341.0 to 4430.0
Track entries 8 to 8

You'll need to determine how many MIDI Ticks there are in one second. Subtract two of the non-zero "PLAYER TICK" values, such as 2730 - 2641 = 89.  Then multiply that times 20, because the game refreshes the UI 20 times a second.  Thus, this song runs at 1780 MIDI ticks per second.

Edit the file resources\stupidHackTempo.props and add an entry for your song. The song's filenames are case sensitive, and you'll need to use the Unicode sequence "\u0020" for any spaces in the song's filename.

Rerun the game, select your song, and hopefully the UI will line up with your music.

Huge thanks to these people!

This was a team effort, and I'd like to give a shout out to these people:
  • Allen Fisher, for doing a superb job putting together the MIDI files.
  • Marshall Baltzell, for doing an amazing job with the two image files, especially on the Handbell Hero logo - he was dead-on with the appearance.
  • Matt Bresnan, for coming up with the initial game design, and giving me the opportunity to take some time to code up game.
  • The creator of the Nightmare Hero font, which adds to the visual effect of the game.
  • The audio effect on the selection menu, which adds to the audible effect of the game.
  • Apache FilenameUtils - they have libraries that make coding easier (and less cumbersome).

Got feedback?

If you love it, hate it, or have any questions, let me know! Either leave a comment below, or share with the entire world via Twitter @Panurgy


  1. This is an amazing find, I've been looking for a visual aspect to show the children I teach handbells. I'm not savvy with java and have found installing this on my pc nearly impossible, is there an easier way of doing so?

    1. Yeah, these instructions are probably obsolete now (along with Java SDK v8), sorry! I wish there was an online/web version what worked through a browser (and eliminated the need for the Java install part ...)