yavsrg / prelude

The rhythm game framework that powers Interlude

What is YAVSRG?

YET ANOTHER VERTICALLY SCROLLING RHYTHM GAME is a collection of rhythm game projects full of the features and ideas I think make games of this genre fun to play.

The project is centred around my custom rhythm game client, Interlude, and the tooling around it.

Visit yavsrg.net to read more about this project and its features.

🎮 Playing the game

Various player guides, including a wiki, are built into the game to help you get started, especially if you're coming from another popular rhythm game client.
You can also check out the wiki here in your browser!

On Windows - Download the latest release from the website, extract it and play!
On macOS and Linux - You currently must build the game from source, I've made this quick and easy, see below

🧱 Building Interlude

Note

If you just want to play the game on Windows, you do not need to do this, instead get the game by downloading the latest release from the site

1. Cloning the codebase to your machine requires Git, and building requires the .NET 8 SDK
   Follow the install instructions for both of these for your platform

2. To set up the codebase on your machine, run these commands in your terminal:

# Navigate to somewhere you want to store the interlude codebase
git clone https://github.com/YAVSRG/YAVSRG.git
cd YAVSRG/scripts
chmod +x ./setup_repo.sh
./setup_repo.sh
chmod +x ./setup_cli.sh
./setup_cli.sh

The steps above should set up the yavsrg CLI command. Try running yavsrg version, you should see a version number output in the terminal.
If this hasn't worked and you are stuck, get assistance from me in the discord

3. Run yavsrg play to build and play the latest version.
   From now on yavsrg play will launch the game when you want to play.
   To update your game when a new version comes out, run yavsrg update.

To later uninstall the yavsrg command line tool, run dotnet tool uninstall --global yavsrg.cli
After that you can delete the entire YAVSRG folder to entirely remove the game and all data from your system.

🧱 Building Interlude <for developers only>

Note

If the setup guide for non-developers on Linux/macOS didn't work, please do not try these steps and instead get assistance in the discord if all you want to do is play.

The yavsrg update command will checkout and build the latest release, if you are a developer you will want to build what is on your local branch instead.

Use yavsrg debug_run to build and test the current branch, or go and look inside at what it does and use an IDE feature accordingly.

On first startup via yavsrg debug_run, the game will tell you that you need the correct bass.dll/dynlib/so for your platform placed in YAVSRG/interlude/src/bin/Debug/net8.0
Look for it here https://github.com/YAVSRG/YAVSRG/tree/main/engine/lib
If your platform isn't there contact me in the discord or search online for it

If you open YAVSRG.sln in Visual Studio 2022, setting Interlude as the active project will let you simply build and run with F5 which is my current workflow.

While Interlude stores all its data in the same folder as the exe by default, you can change that to a specific location - In YAVSRG/interlude/src/bin/Debug/net8.0/config.json you can edit WorkingDirectory to whatever is convenient

I use "C:/Interlude/dev" on Windows
If you previously built Interlude as a non-developer, I recommend setting it to "../../../../../GAME" so both builds share data

🤝 Contributing

Come join the discord -- Send me playtesting feedback, feature requests, bug reports, etc. I'm active a lot in there

Pull requests are very welcome! If you spot a bug, typo or other minor change and have a quick fix, feel free to submit a PR. If you want to work on a feature please check with me first via Discord

Warning

IMPOSTOR SYNDROME DISCLAIMER

Don't know F#? Don't know how to code but want to learn? This is a hobby project largely dedicated to expanding my skills as a programmer and I would be pleased if it could do the same for you.

Ask away in the Discord, I'm often free to chat about how I or the codebase work and will happily give YOU the tools to make meaningful contributions.

prelude's Issues

Stacked note resolution when converting osu! files

osu! format is a collection of objects at timestamps, allowing for some expressions not allowed in Interlude charts

Examples:

1. Stacked notes (2 notes occurring at the same time)
2. Notes inside hold notes or at the beginning/end of hold notes
3. Hold notes inside hold notes
4. Hold notes ending before they begin
   and more

Proposing that instead of disallowing these files/failing conversion instantly, some recoveries could be made that are sensible in every case I care about:

1. Ignore the second note
2. Ignore the note
3. Ignore the inner hold (second one encountered)
4. Treat this as a regular note

Not a big priority just something I should have written down/think about at least

Converting .osu file with hold notes inside each other causes a crash

Sort/group charts by grade achieved

A little more complex than it seems, we'll see though

Pattern generator

part of the editor

i need to design a way of expressing patterns that is both simple and easy to learn but also capable of having fine control over what patterns are generated

it would be sensible to have some presets in the editor so people can pick it up easily without reading a guide

basic syntax:

the pattern generator takes a stream of characters (a bit like regex) and a snap distance and places notes on every row to form the specified pattern

[ ] groups characters inside it to apply to one snap, as each note is otherwise placed a snap later than the previous

_ can be used to indicate a blank row/skip a snap to allow gaps in patterns

digits (1234567890) indicate a note in that column (0 being column 10)

J indicates a note that forms a jackhammer (appears in a column where there is also a note in the previous row). It is picked randomly and if there are no notes in the chart a random column should be picked (and no error shown)

j indicates a note that forms a jackhammer like J, however the generator will attempt to alternate hands/evenly distribute jacks as much as possible to form minijacks instead of anchors

S indicates a stream - a random note that does not form a jackhammer - if this is not possible a random column will be selected (no error)

s indicates a stream however the generator will attempt to produce rolls by selecting notes in columns that minimise note density per column. Minimising fully will result in full rolls/split rolls etc so it should randomly choose between maybe the 2 best columns

examples:
[12][34] - jumptrill
1234 - roll
[ss]s - jumpstream (comfortable but can still contain trills)
[12]3[14]2[34]3[14]2 - a kind of jumptrillable jumpstream
[1357][sss] - brackets
[ss]s[ss][ss][ss]s[ss]s - triple jumpstream
[sss]S[ss]S - dense handstream
[ss]j - that one galaxy collapse pattern we havent named yet
[js] - jumpgluts
[1234]j[ss]s - quadstream
[1234][jjj] - dawts favourite patter

more design to improve the syntax soon

Ruleset validation (in some form)

my custom record deserializer

• calls the "Default" property of the record
• replaces default values with read values if they are non null
• preserves boundings on settings

I would now like it to also call a Validate function, another static method attached to the record type, if it exists, which can repair/delete values that are otherwise not caught such as an array being the wrong size

Useful for certain options where I want a certain data contract but cannot enforce it currently without just adding verification steps ad-hoc

Hitobjects not correctly ordered by time create invalid charts on osu import

Obviously.

Best fix may be just to sort by time?
Or instantly reject any chart that does this because anyone who does this is a fool

Charts failing to write due to multithreaded calls to Percyqaz.Json

will also create issue in Percyqaz.Json

Feature: Auto-generation of wiki pages from some parts of Prelude

Ongoing task as more of the api is set in stone to make nice doc files to read through
Can add links as the main roadmap of the wiki

Personal bests don't update correctly when you beat an existing best

Needs investigation

Noteskin Authoring

Noteskins need to store author name and version, then they can be exported as .isk archives

Auto mod incurs NGs on hold notes

SQLite storage for scores and cached charts

Replace modules with namespaces to make code more suitable for all .NET consumption

follow these
https://docs.microsoft.com/en-us/dotnet/fsharp/style-guide/component-design-guidelines
https://docs.microsoft.com/en-us/dotnet/fsharp/style-guide/formatting
https://docs.microsoft.com/en-us/dotnet/fsharp/style-guide/conventions

that'll be a fun afternoon

Refactor: Store replays as a sequence of keyboard inputs

this one is more involved

Setup

Currently scores are stored as rows of information corresponding to each row in the chart
The information stores the deltas of your hits/flags about needing to hit notes

Drawbacks are

• Cannot faithfully represent other engines like osu! with different LN mechanics or Etterna where cbrushing is basically the entire score system
• Code is somewhat difficult to explain/get familiar with
• Scores easily invalidated by bugs found and tweaks made to game mechanics
• Scores easily invalidated by glitches with mods and other issues

Solution

SCORE FORMAT 1: Stores a score as sequence of snapshots of your keyboard hits
This is:

• How osu, quaver, soundsphere do it
• Easy to compress to potentially smaller than current score format
• More powerful, allowing the existing data to be calculated quite trivially from it
• Theoretically interoperable with osu, quaver and soundsphere scores/replays (we'll see)

SCORE FORMAT 2: The existing format

• This format becomes internal (format 1 is what is saved in the database) and used to provide information for the score screen - You calculate the data in a pass or live while playing as before, and it contains judgement counts/standard deviations/all that stuff

New drawbacks (old ones are gone)

• Need to know the note data for the chart in order to know anything about the score
• Need to know the modded note data for the chart in order to know anything about modded scores
  (These both impact server-side calculations of any kind)

Sort/group charts by time last played

If I can do grade achieved I can do this (and it's been asked for before)

Refactor: ColoredChart becomes a Record

Score systems become theme-driven

Haven't found a scripting solution for Interlude yet and maybe I never will
Code will always be more flexible than config files, but sometimes you gotta settle for what you have

In the meantime users would really benefit from theming their own score systems in

A score system is comprised of:

• List of what judgements exist, their names and colors
• Rules on hit windows and judgement assignment
• Rules on point assignment
• Rules for combo stuff

Future features:

• In this same file you design HP rules too? Can't see a reason why these related things should be in two places if they are only going to be used in pairs
• Possible "Score" output out of 1 or 10 million

Cases to cover in config:

• Assign a value to hold head and tail separately
• Assign a value to head + tail combined

Wife curve and osu rules for LN judgements will be hard coded cases
SC+ will get binned I think, literally only I used it and everyone else defaulted to osu!

Switch to FSharp.Json instead of Newtonsoft.Json

cause it looks cleaner and more compatible with F# data types

Error parsing osu!standard and osu!catch maps with no slider hitsound/addition information

annoyed because I can't find documentation on it anywhere but it seems like you can elide the last three parts of a slider object's info as seen here https://osu.ppy.sh/wiki/en/osu!_File_Formats/Osu_(file_format)
Just having
X,Y,Time,Type,Hitsound,Shape|Points,Slides,Length is valid in osu in addition to the usual
X,Y,Time,Type,Hitsound,Shape|Points,Slides,Length,EdgeSounds,EdgeSets,Addition

Pattern analysis

More thought before I start on this

A pattern analyser would be useful for classifying charts as a certain % pattern X and a certain % pattern Y, and then this can be used for similar chart recommendations

Needs to be keymode independent so no immediately reaching for "jumpstream" (although 4k will have its own set of names for patterns)

End goals of pattern stuff

• A measure of "chart similarity", for recommendations
• An ability to type "jumpstream" or "double stairs" into search and pick out charts that meet a certain pattern requirement
• Other stats displayable on score screen

Remove mines

I'm sick of maintaining mines just for the decoration they add to charts

Pros of mines:

• Decoration for files
• Minedodge files (which literally nobody does any more)

Cons of mines:

• Stepmania and osu versions of charts differ by just mines and have different hashes which makes my life way way more difficult when it comes to maintaining a chart database in the future
• Have to maintain a lot of fiddly code to handle OK and NG judgements just for mines, removing mines entirely streamlines that to just the LN/regular note code
• Do they add much game wise? No because they are something you actively don't tap, in fact a player that doesn't tap in gaps can have their mines invisible with no gameplay change. They also don't really fit into accuracy mechanics anywhere
• Mines can create otherwise "empty" noterows which cause a whole bunch of issues I have to work around

So I'm proposing to just delete mines out of the game and nobody will miss them

Refactor: Store note rows as a NoteType array

Current bitmap solution was ill-tough-out by 18 year old me and was maintained for backwards compatibility purposes

Since I am refactoring a lot, might as well revisit this code which I think can be made a lot more understandable with not a huge time cost

Setup

Each row of notes in a beatmap consists of several bitmaps, one for notes, hold heads, hold middles, hold tails, mines, etc.
"easy" to enumerate a specific kind of note

Solution

Proposed format: Just an array of note types. Add a new note type called NOTHING

Current format permits two kinds of things to be in the same column at the same time, on the same row
Proposed format eliminates this possibility so more accurately fits the domain (where this should be impossible)

All operations will now be very readable
Proposed format fairly easy to compress still

Test rig feature list

Testing rig plan (as a list of features) to be fairly simple yet cover my blind spots

• Import a bunch of charts from many places (osu! mainly to test the parser)
• All failed cases (mainly for osu!) go in a folder for inspection on how to improve parser
• Run sanity checks on as many charts as possible to ensure correctness
• Use these charts as a sample for score/replay round trips
• Use these charts as a sample for modifier round trips
• Use these charts to test auto-replay attains perfect scores
• Use these charts to mass-sample difficulty calculation results

Refactor: Move note hitting mechanics to Prelude

This must be done before #20 can be started

Make sense designwise and is part of a move to rewrite gameplay as a choice between different note hitting mechanics

.qua Support

Should be easy enough

Use relative song folder paths instead of absolute for collections

Better portability, but should have an optimised way to retrieve charts by hash (maybe by storing cache as a db)

More flexibility in loose-mode texture loading

Some textures can be wider than they are tall
Some textures can be taller than they are wide
Some textures have no restrictions on dimensions
Some textures do not support animation
Some textures do not need multiple rows

These rules should be associated with each texture and checked against

Use struct tuples instead of reference tuples

For improved performance where relevant.
Can be done at a later stage in development

Mirror mod is broken

New grades system

after talks with qqp some updates to grade systems could be useful for

• player motivation (avoid miss count)
• emulation of other games where miss count matters for your grade

grades should take into account both miss count and accuracy, by consisting of two thresholds (percentages of notes you should be below, percentage of accuracy you should be above)

this also supports move towards splitting SC and SC+ to not count misses at all but display "-X" where X is the number of misses you have

scores (accuracy, cbs) should be lexicographically sorted

Refactor: Beatmap becomes a Record

Chart searching shorthands

osu! has stuff like "key=5 title" and will use key=5 as a filter, as well as using title as a keyword in search. I'm considering a similar setup but mostly this issue is to design efficient keyword searching

useful abilities in such a filter system

• inequalities such as difficulty thresholds, lengths
• limiting keyword search to just one field like pack title, song title, creator
• possible dropdown in search box that lets you retype previously used filter combinations

Inverse mod

Mod that "inverts" a chart in the classical LN sense

Notes become holds that are only released at 1/4* of a beat before the next note
Holds become notes

*Mod should in future come with a couple of settings to change this value (1/1 and 1/2 would both be very useful)

Complete .sm file support

This involves

• writing .sm to file
• converting interlude charts to stepmania charts
• supporting warps and stops when parsing .sm data

I'll split into 3 different issues when I actually start work on them