quaver / quaver.api

Keep developing for Quaver with these set of tools and C# libraries.

Quaver.API

📖 Keep developing for Quaver with these set of tools and C# libraries.

Table of Contents

• What's Included
• Contributing
• License

What's Included

We want to make it as easy and seamless as possible for developers to use the same tools as what is utilized in Quaver. That means if we change anything about anything, you'll have everything.

Everything regarding the following is packed into this one library:

• Map & Replay Parsing/Writing
• Map conversions from other games
• Difficulty calculations
• Commonly used enums and helper classes

Contributing

We love and encourage people to contribute to Quaver - whether it be through code, designs, or ideas. Our mission is to provide a space where the rhythm game community's voice is able to be heard. We aim to create the ultimate vertical scrolling rhythm game, and this isn't possible without community input.

The best place to begin contributing to Quaver is through our Discord server, where all of our developers, community, and testers are located.

Any contributions can be made through opening a pull request. When contributing however, please keep in mind that there should only be one branch/pull request per feature. This means if your branch is titled my-new-feature, you shouldn't have any unrelated commits, and the same system is applied to pull requests. Please make sure to keep your pull requests short and concise.

If you are wanting to develop a feature with the goal of having it being in the Steam release, open up an issue first, so we can discuss if it is in the scope of what we are trying to accomplish.

LICENSE

The Quaver game client is split up into submodules which are subject to their own individual licensing. Please see each submodule to view their respective license(s).

The code in this repository is released and licensed under the Mozilla Public License 2.0. Please see the LICENSE file for more information. In short, if you are making any modifications to this software, you must disclose the source code of the modified version of the file(s), and include the original copyright notice.

Please be aware that all game assets are released and covered by a separate license. This should be noted when using this software to create derivatives for commercial purposes. Please see the Quaver.Resources repository for further information regarding licensing.

quaver.api's Issues

MonoGame.Extended dependency

https://github.com/craftworkgames/MonoGame.Extended/blob/master/Source/MonoGame.Extended/Collections/ListExtensions.cs
The shuffle method is the only thing that is used from MonoGame.Extended, can't it be re-implemented in this project instead?
MonoGame.Extended creates warnings about restore stuff when used in a .net core program which is a bit annoying

7k+1 charts' scratch lane should not be affected by Mirror and Randomize

The scratch lane is a special column with different use in mapping than the other columns. Currently, it is flipped/moved when using the Mirror or Randomize mods, and this can make charts unplayable.

Problem 1: Underusage compared to other columns.
In most 7k+1 charts, the scratch lane is underused compared to the others, only being used mostly for emphasis. This is player friendly, since it's usually hit with the pinky finger (on a keyboard), or requires turning a turntable with a controller. Switching it with another column could make the chart significantly more difficult and poorly mapped; just imagine it being mirrored or moved on a chart like FDFD https://www.youtube.com/watch?v=SOK1pJV4168.

Problem 2: It allows for the use of 2 keys, and is thus not replacable by another column.
Players can use 2 keys to hit the scratch lane, or a turn table which has 2 motions (up and down). Due to this, charters often put 1/4th patterns (or denser) on the scratch lane, expecting players to alternate. With MR or RD, those patterns are moved to another lane, and suddenly require vibro to hit, becoming significantly more difficult.

Solution:
In the title. Have the scratch lane be unaffected by the 2 mods. I also propose that it be unaffected by the LN-related conversion mods, for playability's sake, though this matters less since they are less useful than MR and RD.

Imported SM map has weird timing issues after multiple speed changes

Describe the bug
As the title says, a SM map I've imported has the audio / notes become out of sync after multiple speed / velocity / bpm changes. By about 1:47 into the song it feels like the notes are almost half a second later than they should be.

To Reproduce
Steps to reproduce the behavior:
Download Stamina RPG 3 pack, the song is [13] [180] Plus Boy
Import song
Play song
My 4k scroll speed is 29.0 and global audio offset is 36ms

Expected behavior
The chart to play normally

Screenshots
None

Desktop (please complete the following information):

• OS: Windows 10
• Version: Most recent version of quaver as of 12/5/2020

Additional context
I'm unable to actually upload the chart/song here, so if anyone wants to see it just message me on discord and I'll send it to you xDest#7712

Be aware of : inside metadata in osu beatmap parser

var value = line.Split(':').Last();
in Quaver.API/Quaver.API/Maps/Parsers/OsuBeatmap.cs

would return wrong result if the line is something like "Artist: aaaa (CV: xxxxx)"

instead of split use substring with indexof first :

Good accuracy at parts with higher strain should give more QP

The way the current system works is that

easy part : 100%
hard part : 90%

and

easy part : 90%
hard part : 100%

give the same amount of QP because both give a total accuracy of 95%.

I think that the play that does good at the hard part should be rewarded with more QP.

A solution i came up with for this is

or in code form

float totalRating = 0;
for(int i = 0; i < DifficultyRating.Length; i++)
{
    rating += (float)(Math.Pow(DifficultyRating[i], 2.5) * Math.Pow(accuracies[i] / 98, 6));
}
float finalRating =/ (DifficultyRating.Length * 20)

A hacky implementation of this can be found at https://github.com/nobbele/Quaver/tree/qp2

Some numbers will be needing change like DifficultyRating.Length * 20

I don't know if difficulty rating should be raised to the 2.5th power because it could cause issues with songs that have huge difficulty spikes

Finish StepMania conversion

Quaver unable to import Camellia ft Nanahira - Petals by Arzenvald

Quaver somehow unable to import osu!mania map titled Camellia ft Nanahira - Petals that mapped by Arzenvald https://osu.ppy.sh/beatmapsets/634241. I've tried it many times by changing some character in diffname but still not working even though map contains both 4K and 7K only

Some multi-bpm sm charts aren't converted correctly.

Fix autoplay replays not handling stacked notes properly

You can die in a Replay but pass the map ingame

Bug occurs at ~2:08, I 'die'. But this score is submitted and I passed the map in-game.
Veeyu - Gram - Nibelungen - Mythology.zip
https://quavergame.com/user/300350 (my uuid)

Change Qua.GetScrollVelocityAt() to return null instead of the first SV for times before the first SV

Currently for times before the first SV of a map, the method returns the first SV of the map. However during gameplay, notes coming before the first SV don't use the first SV's multiplier, but rather 1 (or a different number, if InitialScrollVelocity is set to a different number in the file). I think it would make more sense if it returned null instead, as there isn't an SV associated with notes and timing lines before the first SV.

From what I can tell, changing it to return null instead of the first SV would minimally affect just the editor (and in my opinion make things make more sense):

• For times before the first SV, Ctrl + I would place an SV of multiplier 1 instead of one with a multiplier the same as the first
• Opening the SV panel at a time before the first SV would cause no SV to be selected
• Adding an SV before the first one would place it with a multiplier of 1 instead of a multiplier the same as the first
• Pressing the Select Current SV button would select nothing for times before the first SV

Serialize failures in replay files

If a user fails and exports the replay, it won't be displayed as failed if they drag it in.

Difficulty Calculation

Common BPM computation includes empty intro time

One would assume that the common BPM is the one that only includes parts that have notes. For example, having a dan map and creating a new guest difficulty that contains only 1 of the maps should display the BPM of the map that was singled out.
The current computation derives from osu! in order to stay compatible with osu! SV maps and computes the common BPM starting from the very beginning of the song instead. If there is a longer song that has a different BPM before the singled out map, then that BPM is going to show in the difficulty selection instead.

Refer to discussion at #130

Suggestion: Lower the accuracy needed to get PR equal to a map's QR

Is your feature request related to a problem? Please describe.
The current threshold for gaining PR higher than the map's QR is much too high causing some scores to be worth less PR than scores that are worse.

In this example both scores are worth almost the exact same amount despite the 1.35x speed score being better. If you disagree with this, find a map that you can get 99% on when using 1.0x speed, then try playing it on 1.15x speed. When you finish the map your accuracy will most likely be around 1.5% or more lower on the 1.15x speed score than on the 1.0x speed score. This drop in accuracy between scores causes the 1.15x score to give much less PR than the 1.0x speed score despite both of them being an exact representation of your skill. This becomes much more apparent when the accuracy is lower than 98% as shown here

Describe the solution you'd like
To fix this the accuracy needed for a score's PR to be equal to the map's QR should be lowered from 98% to 97%. If we keep the maximum PR able to be gained from a map the same, then changing the base number for PR to be higher than QR would make the scaling for accuracy less drastic. This would fix the problem displayed in the two examples shown as well as the hundreds of other instances where this has happened.

Describe alternatives you've considered
I do believe that my solution to the problem is the best but another solution would be to change the PR scaling in relation to accuracy. If we made the scaling for PR less extreme at higher accuracies then it would also fix this problem. I do think that it would be more difficult to implement as well as less effective than my solution though.

An o!m map is missing most of the notes

There are blank lines or something in the hit objects section, and it seems that Quaver currently reads notes only up to the first blank line in there. .osu link

Crediting Errors when Exporting .sm files as .qua

When a .sm file is exported from the editor is a .qua file the chart creator field is empty. The Stepauthor is properly credited when viewing the chart in quaver, however upon exporting the file as a .qua the chart creator field is cleared. This specifically happens when a chart from etterna is loaded in the editor and exported as .qua. When a .sm file is imported and converted into a .qua by dragging the .sm file into quaver, it works as intended.

Similarly, when converting an osu map a description of "This is a Quaver converted version of _______'s map" is given to the .qua file. This is text missing from all converted .sm files. Both imported .sm files and .sm files exported as .qua lack this text when converted to .qua

Scale chart difficulty with Intensity per duration in a way that suffers diminishing returns.

Is your feature request related to a problem? Please describe.
Currently quaver does not seem to have any significant difficulty scaling for identical patterns of the same intensity when it comes to chart duration. On the contrary, sometimes the same pattern for a longer duration can lead to reduced rating. Since quaver does not support pausing and therefore suggests that it values stamina there should be a positive scaling that suffers diminishing returns for longer plays of the same intensity.

Describe the solution you'd like
Possibly logarithmic scaling of difficulty rating for certain duration intensity difficulty.
Arbitrary examples:
30 seconds of burst intensity under current rating system = 30 rating.
60 seconds of identical burst intensity under scaling rating system = 33 rating.
120 seconds of identical burst intensity under scaling rating system = 34 rating.
240 seconds of identical burst intensity under scaling rating system = 34.5 rating.

(These values are chosen arbitrarily to reflect the concept, not the balance of the system.)

Describe alternatives you've considered
A flat bonus to the rating received for accuracy over a time period:
98% over 2 minutes = Received rating identical to song rating.
98% over 4 minutes = Received rating identical to song rating + x.
98% over 6 minutes = Received rating identical to song rating + x times 2.
etc.

Additional context
In a game that values stamina, there should be a direct reward for being good at maintaining focus and having the physical endurance to reflect high individual stamina.

Dead Long Notes should be ignored

Pressing on an LN that was released early gives the player an extra miss

Issue converting osu maps with storyboard samples

in Quaver.API/Quaver.API/Maps/Parsers/OsuBeatmap.cs

// Parse [Events] Data
if (section.Equals("[Events]"))
{
// We only care about parsing the background path,
// So there's no need to parse the storyboard data.
if (line.ToLower().Contains("png") || line.ToLower().Contains("jpg") || line.ToLower().Contains("jpeg"))
{
var values = line.Split(',');
Background = values[2].Replace(""", "");
}
}

You should not ignore sound samples inside the storyboard.
For example, an Easy difficulty of a keysounded map may have left hand piano all in Storyboard and player plays the right hand piano (main melody)

Length isn't important in Difficulty Calculation

A player will massively benefit from a few very high-rated plays.
Maps like "Let the sliding begin", "Prelude, Op. 28, No.16" and so on, will benefit a player often far more in rankings than longer maps, despite shorter maps being objectively easier to clear.
A map that is a minute in length will quickly become a 30-40 second clear with speed multipliers.

It's easy to build muscle memory and slowly increase the speed and I feel a lot of players are carried by this in rankings, myself included.

A longer map requires:

Consistency - Your ability to consistently hit notes accurately. In very short maps, inconsistency is irrelevant, just retry, nothing is at stake.
Focus - Your ability to stay focused and sharp, is there SV? Did they mix jacks in there?
Stamina - Your ability to continue playing without stopping especially during dense sections. This is especially important as you cannot pause and submit a score.

Exponentially reduce difficulty rating based on map length.
It can be hard to implement this as speed multipliers actively reduce map length. Ideally, the decrease is exponential, with it leveling off around when maps have a time of ~2 minutes. Speed multipliers should never be able to reduce the difficulty of a map of course.
There should be a very noticeable decrease in difficulty, exponentially, for maps below the 1 minute mark, somewhere around a 10-15% increased reduction to the current reduction seem reasonable to me.

More suggestions welcome, and thank you for reading :>

Don't treat null as actually null when parsing map metadata

Will throw a NullReferenceException when selecting the map if any of its metadata is parsed as null instead of "null"

Example Map:
https://osu.ppy.sh/beatmapsets/774300/#mania

Banner Resolution Typo

In the editor, AutoMod appears to have a typo regarding the required resolution for a banner.

From the Ranking Criteria site:

Move SM background logic from Quaver to here

Should be moved from here into somewhere in this repo so -convertsm also takes it into account.

Compression for .qua & .qr files

Custom Map Banner Support

Needed for the new design

some maps loaded from osu are incomplete

Describe the bug
as in title

To Reproduce
Steps to reproduce the behavior:

1. open quaver
2. click options "load songs from other games" "detect"
3. some maps only have parts of the original

Expected behavior
complete imported map

Screenshots

quaver detected map ends at the 445th object.

original map is much longer

Desktop (please complete the following information):

• OS: win10
• Browser chrome
• Version 0.31.0

Additional context
map is originally from stepmania. i converted the .sm into .osu (i cant directly convert it to .qua) and zipped it then changed the .zip to .osz. i can import the song normally into osu except trivial issues like offset. then i tried to import the .osz to quaver, however quaver didnt load it (changed into initializing screen for a while then exited with no converted file) theni tried to load the map directly from osu but it wasnt complete. i had to open edit screen in osu then re-export the map as .osz (then osu told me the osz had 2 redundant pictures (because it was from sm) (however i still couldnt import the .osz even if i deleted the two pictures)) the re-exported file could be normally imported tho, and map is complete

SV Diff Calc

Regarding the Current Implementation

Data

The following is a spreadsheet containing the calculated SV factors of some Quaver SV maps, including some ranked SV maps created by PianoLuigi and Pepega Clap, and my unranked SV maps, and some other SV maps.

quaver_sv_factor.xlsx

The first sheet shows the results of the original SV factor calculations, and the second sheet shows the results after they're divided by the map's SV count (I guess it should've divided by n - 1 instead of n, but it shouldn't matter too much).

Analysis

Looking at the first sheet, it appears to me the SV factor is just roughly representing the number of SVs in a map, which is why I divided the SV factor by the number of SVs in a map in the second sheet.

Looking at the second sheet, it appears to me that the maps that were deemed the most difficult mainly used some variation of a stutter.

Burning Pine features a large amount of heavy stutters in about its second half.
Abyss of Frobenoid featurers flickering.
I Can't Even Remember My Own Name features "invisible" notes, which are pretty much just flickers in this context.
Dead Leaves features what I guess would be called vibrations.
data corruption symphony has some "invisible" notes.
Harumachi Clover [Gaming License Renewal Test] also uses "invisible" notes.

Problem

The current implementation treats SV difficulty as coming almost solely from the difference between SV multipliers, but doesn't consider other factors.

It can be very easily argued that a .3x slowjam is harder to read than a stutter normalized to 1x, but the current implementation will treat the stutter as much harder than the slowjam.

Assuming the slowjam goes 1x -> 0.3x -> 1x, the average absolute logarithmic(?) difference found would be 1.2 (Math.Log() defaults to base e).

Using iceSV, a mapper can very easily add a stutter into a map that goes 0x -> 100x, having an average absolute logarithmic difference of 11.5, what seems to be the max difference possible (the zero gets rounded up to 1e-3 in the code). The timings of this stutter could then be manipulated and repeated in a way to make its readability practically the same as a 1x SV.

Factors to Consider During SV Difficulty Calculation

I believe the following factors are necessary for determining the difficulty of an SV map:

• The spacing between notes
• The amount of time each note spends in view
• The way the player's reading height changes during a map

Spacing Between Notes

• Related to the scroll speed of notes, but also accounts for any SV effects that come between two notes.
• The more spacing there is between two notes, the easier it is to determine their time difference
• The less spacing there is between two notes, the harder it is to determine their time difference
• SVs normalized to 1x SV would be treated as the same as 1x SV with regards to spacing
• In the extreme case of 0x SV, it is (almost?) impossible to distinguish between notes
• In the case of negative SV/spacing, umm idk

Amount of Time a Note is Visible

• The more time a note is on screen, the more time there is to react
  • There should exist some point where increasing the amount of time there is to react no longer matters
• The less time a note is on screen, the less time there is to react
  • There should exist some point that is considered memorization
  • Decreases in time to react should no longer matter past this point as well

Reading Height Changes

• In a map with no SVs, a player should generally be looking at around a constant height
  • And if you're not doing this, you're weird
• During slowjam, the player should be reading the map at a lower height
• During fastjam, the player should be reading at a greater height
  • At some point the reading height would be off-screen, and I guess would be considered memo
• With (keep)stills and other gimmicks involving negative SVs, the reading height can go all over the place.