JoustMania at Magfest 2017!

What is JoustMania????

• JoustMania is a collection of PlayStation Move enabled party games based off of the "Jostling" mechanic introduced in Johann Sebastian Joust
• JoustMania includes FFA, Teams, Werewolves, Zombies, Commander modes, and lots of other goodies!
• The system is also designed to be easy to set up at conventions and is made to run itself with a large group of people. In convention mode, every game is started once everyone is ready, and announces the rules aloud for new players to learn.

Cool Stuffs!

• Now on Windows & Steam!
• 18+ Player support
• Super easy setup
• Runs in Headless mode, no screen required
• Audio is output directly through the headphone jack, no audio device/usb plugin is necessary.
• Optional web interface, view status and change game settings with your phone
• Custom music support, play with your own music
• Convention mode, no manual instructions needed, the game plays itself and switches between game modes

Hardware

Fully set up JoustMania systems are available in two tiers for your PlayStation Move controllers. Each setup uses a Raspberry Pi 5 (2 GB), case, SD card, power supply, USB audio adapter and HDMI cables, with Bluetooth hardware selected for the tier. For purchasing inquiries, contact joustmaniagame@gmail.com.

• Tier 1 — Indoor PS4 Move: $180. “I have up to five PS4 Move controllers (not PS3) and I am playing indoors.” Uses only the Pi's internal Bluetooth; no dongle.
• Tier 2 — Indoor/outdoor, most common: $220. “I have PS3 and/or PS4 Move controllers and want up to 14 players indoors or outdoors.” Planned around two Feasycom FSC-BP119 adapters. +$20 for each additional seven players.

Player counts, expansion capacity and coverage are planned targets pending validation. Indoor play has felt good with the two PS4 Move controllers tested on internal Bluetooth; five PS4 Moves have not yet been tested. Two Feasycom adapters have now been captured with 12 PS3 Moves (six each) nearby and at distance. The 14-player target, larger expansions and outdoor coverage still need validation. See the setup tiers and validation notes.

If you would like to build your own device you will need the following:

• A Rasberry Pi 5 with sd card and a USB audio adapter (This option is officially supported)
• or a Rasperry pi 4 (tested however ymmv)

Recommended Bluetooth adapter

We recommend the Feasycom FSC-BP119 on Amazon, a Class 1 adapter with an external antenna and CSR8510 A10 chipset. Prefer an identified CSR-based adapter from the CSR alternatives list when this model is unavailable; the exact model and hardware revision matter.

The Feasycom is our leading tested option: one adapter handled seven PS3 Moves and a mixed group of five PS3 plus two PS4 Moves. Two Feasycom adapters handled 12 PS3 Moves, averaging 83–86 updates/s per controller nearby and 48–53/s at distance, grouped by adapter. Its distance results and the user's play assessment were more encouraging than the tested Sena, TRENDnet and StarTech CSR samples. These were short captures with differing controller sets and unmeasured distances, not a controlled range ranking. Sena developed severe stalls when used alongside Feasycom; the cause remains unresolved.

See the September 14 comparison and dual-adapter results. Feasycom still needs low-count, 14-player, outdoor and endurance testing. CSR low-count evidence comes from the earlier Cirago sample; it is not a guarantee for every CSR product. Advertised range is not a guaranteed playing distance.

See the Bluetooth adapter and controller guide for pairing, controller roles, report-gap diagnostics and troubleshooting; the complete adapter results compare the tested chipsets, models, prices and controller counts.

Bluetooth roles and controller capacity

JoustMania lets Bluetooth negotiate roles automatically. System Debug shows each controller's model, role, update rate and report gaps. Use Switch to Central or Switch to Peripheral beside a connected controller for a one-time request; either device can reject it. Higher updates/s alone does not guarantee smoother play.

Several tested Realtek adapters delivered good PS3 Move timing only with five active all-Central links; some also worked with six. Their PS4 Move results were generally better at smaller counts, but only two PS4 Move units were available. CSR is our preferred direction for flexible controller counts. Capacity and range still depend on the individual adapter, role mix and environment. See the measured results and limitations.

Raspberry Pi memory

A 1 GB Pi can run JoustMania, but plan conservatively: running more than about six controllers while also running the web UI in a browser on the Pi may cause performance issues. This is a practical caution, not a tested hard limit of six controllers. Other applications and decoded music leave little headroom. In our 1 GB Pi test, Chromium alongside JoustMania and Codex led to full compressed swap, slow web responses, and audio underruns. Closing Chromium substantially improved responsiveness. Use the web UI from a phone or another computer instead of running the browser on the Pi during play.

For reference, these were observed JoustMania process totals in that test:

State	Resident + swapped memory
Menu, no controllers	338 MiB
Menu, one controller	356 MiB
Menu, two controllers	368 MiB
Two-player game	About 472 MiB
Three-player game	About 521 MiB

The first two controllers added roughly 12–17 MiB each to the menu total. A later snapshot showed about 18–23 MiB per controller worker, including its share of shared memory and swapped pages. These totals use proportional memory accounting (PSS + SwapPss), so shared pages are not counted repeatedly. Swapped memory is shown before compression; these numbers are not all physical RAM usage. Music buffers, game state, and process history change the totals, so do not estimate the full requirement from controller count alone.

The 2 GB Pi offering provides more memory headroom than the tested 1 GB model. We have not established a maximum controller count from this memory test; Bluetooth adapter capacity and controller update rates must also be checked.

Optional:

• USB hub for charging controllers: SABRENT 13 Port SIIG 10 Port

This will allow you to charge 9 controllers at once through the pi

Installation

0. Download and Install Raspbian on the micro SD card, this build was tested on the pi 4 and 5, with the latest version of the raspberry pi OS, 32 or 64 bit. If you would like to try installing on Debian there are some extra instructions here that could help.
1. Connect the bluetooth adapters, (usb audio connector for the pi 5), and speakers
2. Turn on the pi, open a Terminal and run these commands, the pi will reboot on a successful install
3. If something goes wrong during installation, try running setup.sh again.

git clone https://github.com/adangert/JoustMania.git
cd JoustMania
sudo ./setup.sh --disable_internal_bt

For Tier 1 indoor PS4 Move play, leave off --disable_internal_bt to use the internal radio. For setups using external dongles, keep the flag to disable the internal radio. See the setup tiers.

The System Debug page also has an Internal Bluetooth enable/disable button on Raspberry Pi. The button is at the bottom of the page and reflects the current boot state. Confirming the popup saves the setting and reboots the Pi; Cancel changes nothing. Controller pairings and USB adapter settings are preserved. A failed save does not trigger a reboot. The control uses Python 3 and systemctl, already provided by the Pi setup.

You can now disconnect the hdmi cable and run JoustMania in headless mode. JoustMania will automatically boot up on restart, menu music should start playing once the pi boots up. Note audio will only play out of HDMI when plugged into a monitor, and only out of the audio jack when unpluged from a monitor.

Windows development build

For the complete Windows development, controller, packaging, testing, and build workflow, see the Windows development and build guide.

The Windows build uses Python 3.13, PyInstaller, and an adjacent current psmoveapi checkout. Build psmoveapi into its build-hotplug directory, then run:

py -3.13 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements-windows.txt
pwsh -ExecutionPolicy Bypass -File .\build_windows.ps1

The standalone one-folder output is created in dist\piparty. It includes the Python runtime, web templates and static files, audio, psmoveapi.dll, psmove.exe, and the Windows controller-reset executable.

Update Joust Mania

Joustmania will auto update when started and connected to the internet. Sometimes there is a large update, it will say so, then you can press the start and select buttons on a controller to start this update, wait until the pi reboots. If you have the AP enabled, you may need to disable it first to gain access to the internet.

Pairing controllers

• In order to pair controllers permanently, plug them into the Raspberry Pi via USB
• Once plugged in, the controller should turn white indicating that it has been paired correctly
• Press the PlayStation sync button (the circular one in the middle) to wirelessly connect paired controllers to the Pi

If pairing is not working, or you would like to resync all Move controllers, remove its saved ZCM1 and ZCM2 Bluetooth registrations:

ZCM1 and ZCM2 are PlayStation Move hardware versions. ZCM1 is the PS3 version with a white Sony logo, while ZCM2 is the PS4 version with a black Sony logo.

cd JoustMania
sudo ./reset_psmove_connections.sh

This stops JoustMania, removes only PlayStation Move controllers, and starts JoustMania again.

On Windows, first stop JoustMania, then open an Administrator PowerShell in the JoustMania directory.

.\reset_psmove_connections.ps1

The Windows reset removes only Bluetooth devices named Motion Controller and their matching PS Move virtual-cable registry entries.

To list registered Move controllers, their model, assigned adapter, saved pairing state, and current connection state, run:

sudo ./debug_psmove_connections.py

The same report is available from the Controller Status button in the web interface.

If controllers seem to pair to only one Bluetooth adapter, it is likely that they share the same Mac address, refer to this issue: #172

With some bluetooth adapters and ps4 controllers, pushing the playstation sync button before plugging it into the pi may be necessary for it to pair correctly, as well as selecting a dialog pop-up in the raspberry pi UI.

How to select a game mode

• In order to change between games, on any controller press the select button (located on the left side of a controller)
• In order to remove a controller from play, hold the playstation button to turn off the controller.

How to start a game

• When a player presses the trigger button their controller will turn white
• Once all controllers are white the game will begin!

Admin Mode: Joustmania settings

You can become an Admin by pressing all four front buttons on any controller, this will allow you to modify the games settings from the four front buttons on the controller, After a game is played the Admin mode will be reset

• (Cross) Add or remove a game from Convention mode, your controller will be green if the game is added and Red if it is not, Custom Teams mode can not be added to the Convention mode
• (Circle) Change sensitivity of the game. There are three settings, slow, medium, and fast, you will hear a corresponding sound for each
• (Square) toggle the playback of instructions for each game
• (Triangle) show battery level on all controllers (full charge is Green, 80% is Turquoise, 60% is Blue, 40% is Yellow, under 40% is Red)
• The middle button can also be used to rotate through different options, then the start and select buttons can be used to increase and decrease that amount, currently this will allow you to change the amount of teams for random team mode, and whether force start works with every controller or only players who pushed the trigger button.
• Holding down the trigger button for two seconds in admin mode will force start the game.

For further settings such as turning off audio (play_audio) or changing the colors of controllers please edit the joustsettings.yaml file in the Joustmania folder.

Web Interface

The System Debug page includes controller role controls, application and Bluetooth reset buttons, and an Enable/Disable Wi-Fi Hotspot button. Hotspot status comes from NetworkManager and shows whether the hotspot is currently active. Changes show progress or errors and may disconnect the browser while the Pi switches Wi-Fi networks. The shell commands below remain available.

Joustmania can also be controlled via a web browser on your laptop or smartphone. If your Pi is on a network, use the IP address of your Pi (for example, http://192.168.1.xxx/). Alternatively, you can turn your Pi in to an access point and connect your device directly to it. To enable this, run the command

sudo ./enable_ap.sh

Note that this disables normal Wi-Fi on the Pi, the ethernet connection should still work however. The default SSID is "JoustMania" and the default password is "joustpass";

To connect to the game, go to http://joust.mania in your web browser, you may have to disable LTE on mobile. To disable the access point and restore Wi-Fi, run the command

sudo ./disable_ap.sh

Custom Music

• JoustMania comes with a couple of pre-installed default songs.
• Play your own music, by copying it into the respective folders: /audio/(Joust, Zombie, Commander)/music/
• Supports Mp3, Wav, Ogg, flac and others Here,
• All music and audio can be disabled by changing play_audio = False in joustsettings.yaml, this will also disable tempo sensitivity changes for each game mode
• two different menu voices can be selected, either aaron or ivy, you can change this via the menu_voice setting in joustsettings.yaml

Game Rules and Variants

• Keep your controller still while trying to jostle others.
• If your controller is jostled, then you are out of the game!
• The music is tied to the gameplay, the faster the music the faster you can move
• Minimum and recommended player count is listed next to every game mode
• Extended rules can be found on the Wiki

Joust Free-for-All (2+ players)

• This is the first mode that JoustMania boots to
• The most basic version of Joust; be the last one standing!

Joust Teams (Minimum 3+ players, 4+ players recommended)

• This game is the same as Joust Free-for-All however at the beginning players select their team color with the big button in the middle of their controller
• There are six teams to select from

Joust Random Teams (3+ players)

• Same as Joust Teams, however the teams are randomly assigned at start of play
• There are 2-4 teams in this mode, depending on number of players

Traitors (Minimum 6+ players, 9+ players recommended)

• Two or three teams face off against one another, however there is a traitor on every team
• Traitors are on an additional secret team
• If you controller vibrates during the start countdown, you are a traitor!

Werewolves (Minimum 3+ players, 6+ players recommended)

• Hidden werewolves are selected at the beginning of the game.
• When the countdown starts the werewolf will feel a vibration, letting that player know they are a werewolf
• After a short period of time, werewolves will be revealed
• Werewolves win only if they are the last remaining

Zombies (Minimum 4+ players, 10+ players recommended)

• Two players start out as zombies, and try to infect the humans
• Humans can shoot random zombies with bullets
• Bullets are randomly assigned as loot from killing zombies
• Humans try to survive for a couple of minutes, otherwise zombies win!

Commander (Minimum 4+ players, 6+ players recommended)

• Players are split into two teams
• One commander is chosen for each side, if this commander dies, the other team wins
• Commanders can activate special abilities that helps their team win

Swapper (Minimum 3+ players, 4+ players recommended)

• Players start on two teams
• When you die, you switch to the other team
• The last person remaining does not switch

Fight Club (2+ Players)

• Two players fight eachother
• The loser goes to the back of the line
• The winner gains a point
• The player with the most points at the end wins.

Tournament (3+ players)

• Everyone is paired up 1v1 via controller colors
• If your controller is white, wait to be assigned to a new player
• The last person remaining wins!

Non Stop Joust (2+ players)

• Same as FFA, however when you die you respawn
• The player that died the least at the end of the 2.5 minute round wins!

Ninja Bomb (2+ players)

• Players stand in a circle each holding a controller
• Players press A to join the game.
• A bomb is passed around by pressing the A button, if held too long it will explode
• Players can try to pass a traps in order to fake out their opponents.
• If a player presses A or trigger while holding a trap, they explode
• Traps are passed by holding the trigger-button half way, too much or too little and you'll give yourself away
• Traps can also be countered by pressing any of the four front buttons.
• Players have two lives, the last player remaining wins!

Convention/Random mode

• This mode allows for multiple game types to be randomly rotated with instructions played before each game
• Random mode defaults to FFA, Random Teams, Werewolves, and Swapper, more game modes can be added or removed as an Admin or via the web interface (see above)
• Modes with an insufficient number of players will be ignored, if none are available Joust Free-for-All is selected

Support and funding

If you love this game you can support its development by helping out with my patreon here: https://www.patreon.com/adangert

We also have some great contributors if you would you like to help out with development, or find any bug fixes we would be happy to test them out and incorperate them into the repo!

The System Debug controller table also shows application report gaps over a rolling 10-second window: p95 and the longest completed gap. Provisional p95 colors are green ≤22 ms, yellow ≤30 ms, red >30 ms; longest-gap colors are green ≤30 ms, yellow ≤50 ms, red >50 ms. These thresholds reflect initial controller tests, not Bluetooth standards. Hover over p95 for p99 and counts of pauses over 50/100 ms. These measure delivery to JoustMania, not over-air timing or motion-to-game latency. History resets on reconnection. Timing uses Python's standard library; no additional setup packages or packet-capture tools are required.

System Debug selects the next USB pairing adapter beside its heading. Select a different adapter there to override one successful pairing; the selection then returns to the algorithm’s next target. Connect one controller over USB at a time. Automatic assignment first fills identified Realtek adapters to five controllers one adapter at a time in hci order. Next it uses round robin across all other adapters, including CSR and unknown chipsets, until each reaches six. It then brings any remaining Realteks to six using round robin. Only once every available adapter has six assignments does round robin assign seventh slots. With no Realteks, all adapters alternate from the first pairing; with only Realteks, round robin starts after each reaches five. Identification uses the reported HCI manufacturer, not the retail brand. Seven is the automatic assignment ceiling; a manual override can still select an adapter at that target. Counts combine current PS Move connections with successful USB assignments in this session; restarting clears session reservations. Saved registrations alone do not count, and existing wireless connections are not moved. A failed attempt keeps the override; unplugging its adapter returns to automatic.

System Debug provides Identify beside each controller status: it shows white for three seconds, then restores the color currently requested by the game. Unpair in the last column removes that controller’s host registrations (including saved registrations on unavailable adapters); reconnect it by USB to pair again. Individual role switches appear only for connected controllers with an available adapter and known role. Model labels distinguish ZCM1 (PS3) and ZCM2 (PS4).

For the tested BrosTrend AIC8800D80 combo adapter, connect it while running setup.sh to install its firmware loader automatically. For an existing installation, run sudo bash setup_aic8800.sh --install. The helper verifies a pinned BrosTrend driver package, installs DKMS/build dependencies and firmware, and enables its storage-mode eject rules. Bluetooth then uses the existing btusb driver. The tested USB sequence is a69c:5732 → a69c:8d80 → 368b:8d81. If the vendor replaces its download, checksum validation stops installation until the new package is reviewed.

Individual Unpair remains available while a different controller is pairing over USB. Only removal of the controller currently being paired is blocked, to avoid its registration being recreated by the in-progress pairing command.