# beatoraja: a Java and libGDX player for BMS and bmson charts

> beatoraja is a cross-platform desktop rhythm game built on Java and libGDX that plays BMS and bmson charts, with practice mode, detailed timing feedback and a heap footprint that wants several gigabytes. It suits players who already own the charts, and it stops short of several import formats it names in its own feature list.

**exch-bms2/beatoraja** — Cross-platform rhythm game based on Java and libGDX.

- Repository: https://github.com/exch-bms2/beatoraja
- Stars: 797 · Forks: 159
- Language: Java
- License: GPL-3.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/exch-bms2-beatoraja

## A JVM rhythm game aimed at chart files, not a general media player

beatoraja is a rhythm game that reads BMS and bmson song files and plays them as a judgement-driven game on the desktop. The project description calls it a cross-platform rhythm game based on Java and libGDX, and the README states that it works on Windows, Mac OS, and Linux. That places it in a specific niche. It is not a general media player that opens every chart format, and it is not a browser title. It is a JVM application that loads a chart, renders the note lane and scores your timing against it.

The audience is people who already hold BMS or bmson content and want a desktop player with the vocabulary of arcade rhythm titles. The feature list is written in those terms: three types of Long Note mode, a display of note timing duration, judge details showing fast or slow offsets in milliseconds, eight groove gauge types, eleven clear lamp types, a pms judge, and a practice mode. The chart is the center of the design rather than an accessory to it.

The repository layout supports that reading. Top-level entries include skin/, defaultsound/, font/, random/, folder/ and manual/ directories next to src/, lib/ and natives/, which is the arrangement of a game that expects a local song folder and a replaceable skin. The declared topics are bmson and rhythm-game, and no homepage is listed, so the project presents itself as the software on its own.

## Judgement is split into gauges, clear lamps and a pms rule

Scoring in beatoraja is layered, and the three layers are configurable rather than fixed. The first layer is the judge itself. The project can show the timing duration of a note, in the style of the green number in IIDX, and it can report judge details as a fast or slow value expressed in milliseconds. That readout is the reason many players would care about the project at all, because it turns a hit into a measurement you can argue with.

The second layer is progression. Eight groove gauge types are offered, with examples such as assist-easy, ex-hard and ex-grade, so difficulty is adjusted along two axes at once: how forgiving the gauge is and how much it is worth. The third layer is outcome. Eleven clear lamp types are listed, including assist, light-assist, ex-hard, perfect and max, which is how a single run is turned into a graded result.

Long notes have their own branching. The project names three types of Long Note mode: Long Notes, Charge Notes and Hell Charge Notes, plus a Back Spin Scratch mode in the IIDX style. Long notes are where rhythm titles usually lose players, so offering several judgements for the same gesture rather than one is a deliberate design choice.

The pms judge is the outlier. The documented rule is a maximum of one miss per one note, and the combo is reset when a miss occurs. That is a stricter standard than a typical combo system, and it makes a pms chart a much harder read than a normal one.

## Practice mode, difficulty tables and generated courses

beatoraja includes a practice mode, and the command line accepts a practice flag alongside the usual launch arguments. That combination matters because the alternative to a practice mode in most rhythm titles is a separate build or a third-party trainer, and neither is mentioned here.

More unusual is the difficulty table workflow. The project can import a difficulty table folder and create a course from it, with constraints such as mirror or random, no hispeed, and others along the same lines. A course here is a curated set of charts with rules applied, not a playlist you assembled by hand. If you already maintain a table of charts for a local player, beatoraja can consume that folder directly.

The same care applies to imports from other formats. LunaticRave2 scores can be imported for clear lamp and score values, though the project is explicit that the score verifier such as scorehash is not included. In other words, imported scores carry over as numbers and grades, but the anti-tampering check that a native LunaticRave2 install would perform does not come with them. Treat the imported value as a number to learn from rather than a certified result.

## Launching with java -jar and sizing the heap before you press start

The documented launch form is a single java invocation with a flag group and a path to the chart file. The flags are a for autoplay, p for practice, r1 through r4 to start one of four replay slots, and s to skip the configuration step.

```bash
java -jar beatoraja.jar -(a|p|r1|r2|r3|r4|s) [BMS path]
```

The first real use is best done with the skip flag so that a new configuration does not get in the way of confirming the runtime works, then with autoplay so you can watch the chart scroll and check that the judge is responding.

The memory instruction is the part people miss. The project states that beatoraja uses a large amount of heap memory and recommends extending it, giving -Xms1g -Xmx4g as the example. On a 32-bit JRE the maximum heap is limited to roughly 1.4G to 1.6G, and the project says 32-bit is not recommended in the first place. The system requirements name Java Runtime Environment 17 64bit and OpenGL 3.1 as a minimum, with a link to an LWJGL issue describing cases where the game may not run on Windows 10 with Intel HD Graphics 2000 or 3000. Start the JVM with the heap flags rather than discovering the failure later.

## The Docker image builds with Ant and OpenJFX on top of Temurin 17

The repository ships a Dockerfile, so a container path exists alongside the local jar. The base image is a JDK, and the build layer installs the tooling the project needs rather than relying on a prebuilt binary.

```dockerfile
FROM eclipse-temurin:17-jdk
```

The image pulls a platform specific OpenJFX SDK and Apache Ant, exposes them through ANT_HOME and PATH, and sets the working directory to the source tree. The command that runs the build is the Ant target create_run_jar, with the OpenJFX lib directory passed in as an Ant library path.

```dockerfile
CMD ["ant", "-lib", "/opt/openjfx/lib", "create_run_jar"]
```

The Ant target name tells you the project produces a runnable jar, which matches the launch form above. The same implication appears in the top-level build.xml file and in the launch4j directory, the latter being the wrapper configuration used to turn the jar into a desktop executable.

The platform constraints of the base image are worth noting. The OpenJFX SDK is fetched for the linux-x64 build, so this particular container definition is not a universal multi-architecture image, and the graphics requirement of OpenGL 3.1 still applies inside the container, which usually means GPU access has to be arranged rather than assumed.

## LunaticRave2 skin import stops at the archive and surface formats

The feature list contains its own limitation. beatoraja can import a LunaticRave2 skin, but the project marks that work as in progress and states that it does not support DirectXArchive (.dxa) and DirectDrawSurface (.dds) files. Those two formats are common in existing LunaticRave2 skin packs, so in practice an import from a complete pack may arrive partly rendered. Expect to supply missing textures yourself rather than assuming the import is complete.

The gap is worth reading as a boundary on the project rather than a temporary inconvenience. The named format support stops at bmson 0.2.1 and 1.0.0, and there is no statement in the project notes about other BMS dialects. If your library depends on formats outside that list, there is no documented route for them.

On content, the project states plainly that the application should not be used for playing copyrighted contents. That notice sits alongside the feature set rather than in a separate policy file, and it is the fairest summary of how the software is meant to be used: as a player for material you have the right to play.

## The last push landed on 2026-10-19 while the newest tagged release dates from 2020

The repository is not archived, and the last push was on 2026-10-21, so code is still moving in the tree. The release history tells a different story at the packaging level. The newest listed release is 0.7.6 on 2020-03-27, before that 0.7.4 on 2019-10-28, and before that 0.7.3 on 2019-09-22. The two timelines are separated by years, which means the tagged binaries and the working tree are at very different points in their history.

For a user, that gap decides where you install from. The runnable jar described in the usage line corresponds to a released build, while the current tree may contain later changes that are not in any tagged artifact. Nothing in the project notes explains how those two lines are reconciled, so treat the release tag and the source tree as separate artifacts and decide which one you want to run.

The licence is GNU General Public License v3, and the project carries a LICENSE file at the top level. For a player who only runs the application, the practical consequence is that the shipped source stays available under that licence. For anyone who plans to redistribute a modified build or to fold parts of the code into another project, the terms of that licence apply to the work as a whole, and you should read the LICENSE text yourself rather than rely on a summary.

## Conclusion

beatoraja is worth adopting if you keep BMS or bmson charts and want a desktop player with granular timing readouts, practice mode and course generation, and if your machine can give the JVM several gigabytes of heap. It is the wrong choice if you need the LunaticRave2 skin formats it lists as unsupported, if you want score verification, or if you are looking for a maintained desktop rhythm title. Before you commit, verify three things yourself: that your chart format matches the bmson 0.2.1 or 1.0.0 support it claims, that your Java runtime is the 64-bit JRE 17 it asks for, and that your display path satisfies the OpenGL 3.1 minimum, since the project calls out Intel HD Graphics 2000 and 3000 on Windows 10 as a known problem.

## FAQ

### What system requirements does beatoraja need?

The project lists Java Runtime Environment 17 64bit and OpenGL 3.1 or newer, and it says 32bit is not recommended. It also notes that the game may not work on Windows 10 with Intel HD Graphics 2000 or 3000, pointing to an LWJGL issue for details.

### How do I start beatoraja in autoplay or practice mode?

The usage line is java -jar beatoraja.jar -(a|p|r1|r2|r3|r4|s) [BMS path]. The a flag enables autoplay, p enables practice, r1 through r4 select a replay slot, and s skips the configuration step.

### Does beatoraja support bmson charts and LunaticRave2 content?

It supports bmson 0.2.1 and 1.0.0. It can import a LunaticRave2 skin, but that work is in progress and DirectXArchive (.dxa) and DirectDrawSurface (.dds) files are not supported, and LunaticRave2 score import carries clear lamp and score values without the score verifier such as scorehash.

### How much memory does beatoraja need to run?

The project says beatoraja uses a large amount of heap memory and recommends extending it, giving -Xms1g -Xmx4g as an example. On a 32bit JRE the maximum heap is limited to about 1.4G to 1.6G, which is why 64bit is the recommended runtime.

## Sources

- [exch-bms2/beatoraja on GitHub](https://github.com/exch-bms2/beatoraja)
- [Issues](https://github.com/exch-bms2/beatoraja/issues)
- [License: GPL-3.0](https://github.com/exch-bms2/beatoraja/blob/master/LICENSE)
- [README](https://github.com/exch-bms2/beatoraja/blob/master/README.md)
- [Releases](https://github.com/exch-bms2/beatoraja/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/exch-bms2-beatoraja