Playnote: The Big Idea

Playnote: The Big Idea

A wise man once said,

making your vision clear ahead of time not only helps you stay on track but attracts potential users interested in what you’re going for, and early feedback is extremely important

Alright, it wasn’t a wise man, it was me, on Discord, last week. That’s all the more reason though to write up a clear statement of scope – what Playnote is and isn’t going to be. No more witty intros, let’s go.

Reliable and performant by default

Starting on the guts end of things – a big area where Playnote can improve over the competition is technical soundness. No crashes, no memory leaks, no stutters, no lock-ups regardless of how heavy an operation, clear error reporting when something goes wrong. Performance should be smooth on any reasonably modern device, the latencies (both audio and video) as low as the platform allows, and independent from rendering framerate. There’s no valid reason for a rhythm game to have to run at 480 FPS to feel responsive on a 120Hz display – that’s a waste of 75% of the frames. To this end, the code is written to be exception-safe from day one, and all failures tested to be handled as expected, including critical ones always triggering a clean shutdown.

Defaults have power. All this should require no upfront configuration; settings are good, but they should default to the most performant options, only to be changed to improve compatibility when the user encounters an issue.

As low-level as needed, but no lower

Paraphrasing a quote that Einstein may or may not have said, Playnote isn’t a slave to any particular level of abstraction, sometimes to the horror of fans of any particular one. A project that aims for technical excellence in a niche area is going to need to reinvent some wheels, but the majority of components can be off-the-shelf. The biggest challenge of any hobby project is finishing before you die, and any choice needs to have this in mind.

The unspoken value of libraries and abstractions is a reduction in the number of lines of my own code. Code I wrote has been used once (by me), while code others wrote has been used by thousands of people; so, the more of my own game has been written by someone else, the better it’s going to be. If in doubt, get data – seek benchmarks, or just go for it and then profile the outcome.

Fix the design of BMS invisibly

BMS is not a good format. It’s dragged down by decades of bad decisions and non-standard extensions, and this is much of the reason why BMS clients can be hard to work with. Playnote should go out of its way to hide as much of that as possible and pretend BMS is reliable and amazing, with whatever algorithms and heuristics it takes to achieve that. Text encodings are detected, typo’d header commands are fixed, oversized WAV samples are compressed. It should be up to the programmer to deal with these challenges, not up to the user.

Best-effort compatibility

There’s a lot of BMS files out there, and the older they are the more broken they tend to be, in ways I surely can’t even begin to imagine right now. hitkey‘s write-up lists some of the horrors he encountered. Playnote will strive to support all valid BMS files, at least initially. Some leniency is already baked into the parser, and any further fixes for compatibility with invalid BMS files will be done on a case-by-case basis. I would love to aim for 100% compatibility, but that can only be a goal once all more important things are done first. Please understand.

One aspect where compatibility must be maintained is with older BMS clients. When importing a song and converting it into a format that’s as quick to load as possible, it must use only formats that still work with LR2 and beatoraja. This is so that it’s possible to revert from Playnote to an older client, should one be unhappy with Playnote and decide to go back. With the currently planned design, a library is a collection of optimized zip files, which can be simply unpacked into old-school song folders.

Effortless user experience

As much I disagree with its gameplay design choices, osu! is a masterclass in UX. A single-exe installer that unpacks into %APPDATA%, built-in song downloader, reasonably preconfigured for getting started right away; to get more songs, all you need to do is drag a downloaded song file onto the game window to import it. There are no technical reasons why a BMS client couldn’t be just as easy to use. Features that optimize the newcomer experience are first-class. BMS power users must of course be satisfied as well, but hiding away features that are useful less often into “Advanced” submenus will improve the UI flows for everyone.

Unique visual style

The game will stick with 2D graphics of course, but that’s no reason why it shouldn’t try to stand out – an attractive screenshot will always sell a game better than a list of features. I’m no traditional artist, but with strong past graphics programming experience, I can make something interesting from a tech art perspective. The current plan is for all graphics to be built out of SDFs, including text; this will allow for highly dynamic forms, with perfect analytical antialiasing at any scale. This concept has already been successfully attempted and used in production for editor tooling at Guerilla Games.

The visual style will be clean, minimal and stylish; taking inspiration from N++, NieR:Automata, and the work of The Designers Republic. I like to believe I have some sense of aesthetics, so it might take a lot of trial and error, but I should at least realize when I arrive at something visually pleasing. I’m dreading the process, but looking forward to the results.

Break bad traditions

This one might be controversial, but I believe that some parts of the BMS standard should be actively ignored and redesigned to better match how the modern audience plays rhythm games. For example, the #RANK header allows a chart to decide between (typically) four sizes of judgment windows. This might’ve sounded like a good idea at the time, but rhythm games these days don’t tend to vary their timing between songs or between difficulties. Most recent BMS charts go for the easiest rank, which over time gave BMS the reputation of being loose and good for training physical speed. #RANK will be ignored, but to respect BMS’s place, the windows will be slightly looser than in IIDX.

This is also the reason why Playnote will not allow importing scores from a previous BMS client, or connecting to an existing internet ranking service. LR2 and beatoraja already have different timing windows for the same rank (a fact that spawned the LR2oraja fork), and even identical values can feel different on different engines and with different latencies. There’s simply no way to make scores directly comparable in a way that would satisfy everyone. Even re-simulating a play with the same inputs would be questionable, since it doesn’t take into account the player’s mental state.

Another example is the #PLAYLEVEL header, which specifies a difficulty number to be shown in song select. These are infamous for not being very useful, since the value is entirely at the chart creator’s discretion, and there’s no way to specify the scale (normal/insane/etc.) Third-party difficulty tables have been created to fix that by independently ranking charts’ difficulty, often via a community voting process. Playnote will ignore #PLAYLEVEL entirely, displaying only its calculated average notes-per-second unless a table is available for the chart.

The little things are good!

BMS clients are full of minor features people love, and the lack of any one of them can be a dealbreaker for someone out there. 2-Player battle, lamps above Full Combo, practice mode, gauge auto-shift, etc. If it makes sense at all, it will be implemented.

Customization over skinning

Due to the planned nature of the renderer, skins would be very difficult to implement, and so are not part of the plans for the 1.0 release. Customization is part of the very soul of BMS though, so many pre-made layouts and components will be available to choose from, with arbitrary image display available as well for shareable areas like the result screen.

Afterword

That was a lot! Still, I think it’s important to have the general roadmap out there, even if just to keep myself accountable to it in the future. Please keep in mind that this is the vision for 1.0, and doesn’t mean the end of development. Other major features, like an internet ranking, online profile or a chart recommendation system, are not out of question, just out of scope for the initial release.

If you feel particularly strongly about any of these items, please let me know via a GitHub issue.

Playnote Progress Report #1

Playnote Progress Report #1

Whew, has it really been half a year? Back then I didn’t expect I would still be working on it after all this time, let alone see it become a Serious Project. But, I’m getting ahead of myself. This is the first Progress Report, so proper introductions are in order.

The story so far

Skip this section if you’re familiar with BMS. If you’re not – it’s a rhythm game that looks roughly like this:

DP BMS gameplay in beatoraja, by yours truly

Rectangles are falling, hit the lane’s assigned key to play the missing sounds in the music and complete the song. The gameplay is the same as beatmania IIDX, a commercial arcade rhythm game by Konami’s Bemani division; BMS is the fan-made version, with all music and charts made by members of the community (yes, all the music is original!) The video shows the 14-key mode (Double Play), my personal preference, but 7-key and others are available as well and are arguably far more popular.

Many clients were made that all play charts in the BMS format, but probably the most legendary of them all was Lunatic Rave 2 by lavalse. It was built largely to resemble and replicate the functionality of the PS2 releases of IIDX, and enjoyed great popularity due to its level of polish and performance. During its time, the BMS community grew by orders of magnitude. Sadly, the game’s development was cut short in 2010, allegedly due the developer losing access to the source code. By 2015, the official website went offline. Projects exist to add features and fix bugs in the most recent version, but since all they have is a compiled executable, it takes painstaking decompilation effort and making larger changes is difficult.

A screenshot of Lunatic Rave 2 song select screen
LR2 song select, in all its 640×480 glory

LR2 was followed up by beatoraja, a next-gen BMS client by exch. Written in Java and hosted on GitHub, it expands on LR2’s feature set, adding higher resolutions, more QoL and better stability. While still clunky in some aspects, it’s an incredibly impressive effort, and the best we have right now. The language barrier proved to make it difficult to contribute improvements to the original repository, so western development has continued in forks like Endless Dream.

Motivation

One fine afternoon, I was setting up beatoraja on a new Linux install. Right away, it took half an hour just to get it to start, since I didn’t have Java installed, let alone the required JavaFX library runtime. Importing my massive BMS library took hours, and then… none of the songs were actually imported. The game didn’t tell me why. All I could do was split the library into multiple groups, then try importing each one. Most of them worked, a few didn’t. A few more bisects later, and I identified the three songs that broke the import process if they were present. It was already evening, and I didn’t get to play that day. The next day, I discovered that the game has more latency on Linux, due to the bindings of PortAudio it was using. It also dropped inputs when both Shifts were pressed on the keyboard at the same time, which is apparently an inherent limitation of LWJGL.

I walked away from this experience feeling that we deserve better than this. LR2 is great but dead and buried, and beatoraja is opensource but held back by the choice of programming language and its own architecture. If I wanted my perfect BMS client, I was going to have to do it myself.

A Windows folder properties window, showing a large BMS song library
6.8 million tiny files, 27 gigabytes’ worth of sector padding

I spent the next few months toying with the idea. Why do we need to store each song as folders of 2000 files that waste disk space and take ages to copy, even on an SSD? Why does updating the library mean I don’t get to play until it’s finished? Why does the game only feel responsive at ~500fps, even though my screen is 144 Hz? Why can’t I play against a friend locally with each of us picking a different difficulty of the same song? None of these problems are inherent limitations of the BMS format, they just need someone to go out there and solve them. I’ve already been walking around with half-designed solutions in my head, and I was confident I’d be able to do it if I put my mind to it.

Finally, the time was right. I lost my job, and needed something to pass the time while waiting for a new one to come along. I pushed the initial commit, and Playnote was born. Soon after, my favorite C++ IDE became free for non-commercial use, further bolstering my motivation. I decided on a goal of making at least one commit per day, no matter how small, which was a great idea in retrospect – it’s really satisfying to watch that daily streak number go up.

Progress

Fast-forward to the present – what do we have so far? Well, the game looks like this:

Screenshot of Playnote in its current state
Don’t judge, the graphics are temporary

It’s being developed in C++23 for Windows and Linux, with a custom audio engine and Vulkan for graphics. Currently, it can load one BMS chart at a time via the command line, and allows you to play it yourself (with a keyboard or a controller) or watch a perfect autoplay. Most charts work, though there are edge cases, and a few uncommon BMS features, like mines and control flow, aren’t yet supported.

The interesting parts, and the most difficult ones, are under the hood. The total input-to-keysound latency is 6ms on Linux and 8ms on Windows (2 or 3ms of audio buffer, +1ms limiter look-ahead, times two for round-trip latency.) The game is heavily threaded, inputs always polled at the highest possible rate, and engine ticks completely independent from the renderer. And it loads songs directly from archives!

There are a few smaller things it already does that no other BMS client has done so far:

  • All songs play at the same volume by analyzing them with a ReplayGain-like algorithm.
  • A heuristic detects the BMS file’s text encoding, fixing mojibake in both Japanese (Shift-JIS) and Korean (EUC-KR) charts with no need to mess with system locale.
  • Note density graph is a sum of Gaussians, and the average notes-per-second value uses a root-mean-square based algorithm to be a more useful measure of overall chart density than an arithmetic mean of time-bins.
Screenshot of Playnote note density graph
Blue line shows average NPS, purple shows peak NPS

The future

The next milestone, version 0.0.4, focuses on the chart database and song import process. In other words, it’ll be the first version that’s usable without messing with the command line.

Stay tuned for the next Progress Report! Between them, I might also post some deep-dives into the design process, and stories from development.

If you are interested in giving Playnote a try, you can find the repository here, and the automated Windows build is available in the latest GitHub Actions artifact.