Quatrack beatmaps are plain text files. You can make a beatmap with any text editor you like! The extension name is .qbp by default (stands for "Quatrack beatmap").

A beatmap file consists of metadata and beatmap data.

Metadata are just random stuff that aren't a part of the actual gameplay, such as song name, difficulty, artist, mapper, etc. They are at the top of the file. Currently there are these metadata entries, and you can just copy paste these then modify.

$version=1.0
$mapName=
$musicAuth=
$mapAuth=
$mapDifficulty=
$songFile=

$songImage=1.jpg
$songOffset=25ms
$tracks=4
$realTracks=4
$freeSpeed=true

---O
--O-
-O--
O---

Starting from the basics, this is the most basic beat map.

O (upper case letter O as in Oscar) is a single tap, and - (half-width minus sign / hyphen) is blank.

The example above represents four notes from left to right, one per beat (quarter note).

Note that beatmaps are read from bottom to top; i.e. what you see in editor correspond with what you see in-game. It's quite intuitive.

---O|
--O-|
-O--|
O---|

A vertical bar (pipe character) will make the row take half as much time (eighth note). (On the US keyboard, it's on the key above Enter, sharing the same key as the backslash. You type it with shift + that key.)

---O||
--O-||
-O--||
O---||

Each additional vertical bar divides the time by 2 again. The example above is 16th note.

If you are familiar with numbered musical notation (Jianpu), the vertical bar is like the under line in that notation - imagine looking at the beatmap from the side.

---O~
--O-~
-O--~
O---~

Wavy line (tilde) will make this row take +1 beat. (On the US keyboard, this character is to the left of the number 1 key, sharing the same key as the backtick. Also use shift + that key to type.)

---O*2
--O-/2
-O--*4
O---/4

Alternatively, you can define time of a row like this. You will need to do this if you need triplets

--OO
OO--
--OO
OO--

You can position multiple notes within a row. This example has two notes at the same time.

A---
----
----
U---

This is a 4-beat hold note with ending judgement (i.e. you need to release the note on the beat). Imagine it visually.

H---
----
----
U---

This is a 4-beat hold note without ending judgement (i.e. you can hold it past the end). Imagine it visually too.

---O|
--O-|
-O--|
O---|
!200

A line starting with an exclamation mark means the tempo (BPM) is 200 from here on. Because beatmap is read from bottom to top, putting on the bottom actually means the start of this section.

---O|
!+1
--O-|
!+1
-O--|
!+1
O---|
!200

Speed changes are written like this. (MrZ: damn that's ugly)

---O|;!+1
--O-|;!+1
-O--|;!+1
O---|;!200

You can use semicolons to put multiple instructions on the same line, which makes it easier to read.

By the way, just like lines are read bottom to top, instructions within a line are read from right to left.

When you write a beatmap, it's good practice to use semicolon as needed to make the beatmap readable. (saves trouble for future you, or whoever that might need to read/edit this map)

!200,4

This means "4 beats per measure from here on". In the game, a counter will start to count the beats

++++ You can add comments here
----*4
!200,4

4 plus signs is a manually placed bar line. If the beat count is not a multiple of 4 (translator's note: maybe actually multiple of whatever you've set), it will throw an error, making it easy to debug whether you have added or missed a beat. Also helps with readability. Like semicolons, it's good practice to put these where appropriate.

You can add comments after a manually placed bar line. For example you can add labels like "end of chorus" or "bar 40"

---O|
--O-|
-O--|
O---|;>1:23.54

Forced timestamp to indicate time since the beginning of the song. Can be used to skip sections that aren't a whole number of beats, or force a precise timing for a note (not recommended).

>+1beat
>-626ms

Add an offset of +1 beat (1 beat later) or -626 ms (626 ms earlier).

Units support ms, s, beat or bar; bar requires you having set a bar length. Leaving out a unit defaults to beat.

>start

A special syntax that set the time to when the scene is entered (equivalent to setting time to 3.6 seconds) (translator's note: [sic] and I think it's -3.6, but I'm not sure). If you need to set track animation ahead of the song, use this syntax.

You need to use a >0 after this, otherwise the beatmap will desync from the start of the song.

----X|
----XX|
----X|
----XX|

This is a random 2121 patterm.

The ---- is there to just align things, while also expressing that there are no pre-set notes.

Every X on the right represents a "random non-repeating single click". (It throws an error and fails to load when there is no place to place the random note.)

----x|
----x|
----x|
----X|

These are four single clicks on the same track.

The upper case X never repeats notes on the same track, and the lower case x always repeats on the same track. (Similarly, it will throw an error if the last row is ---- and this row has no note to repeat.)

----x|
----R|
----x|
----L|

This is two repeating notes on the left, and then two on the right.

L means "a random note on the left-side tracks", and R for right side. Similar to X, upper case never repeats, and lower case always repeats.

Note that for L and R, when there are an odd number of tracks, neither will include the middle track.

#Techmino is fun!

This is a comment.

A line starting with # is comment, and will not be parsed as beatmap data. You can label sections or explain complex sections with this.

|2

Declare that you'd like to write two notes per row.

When you added 10 animation tracks in a 4K beatmap, you can use |4 so that you don't need to write all 14 notes per row, making your job easier.

Note that you might need to use this in conjunction with & (note redirect).

%L2,L1,R1,R2

Rename the four tracks to L2, L1, R1, R2 respectively. (This is also the default for 4K.)

%L1,R1,x,x

Rename the first two tracks to L1 and R1 (which will usually correspond to the two index finger keys for the player), and the other two to nameless tracks (nameless tracks aren't assigned keys, and will also disable the track's touch screen interactions to prevent mis-click. It's recommended that you leave animation tracks unnamed.)

%L2 L1 R1 R2,x,x,x

Give the first track all 4 keys' names! This will make all 4 keys trigger the first track's notes; can use this to allow multiple fingers to press fast notes.

Note that if one key is assigned to multiple tracks, then pressing the key triggers all the tracks. Use with caution.

---O|
--O-|
-O--|
O---|;&4321

Looks like a staircase from left to right? This is actually from right to left!

&4321 makes tracks 1/2/3/4 point to tracks 4/3/2/1, i.e. mirrored

&2134 swaps tracks 1/2, and another &2134 changes it back (this configuration is relative, it doesn't "set to" 2134)

---O|
--O-|
-O--|
O---|
&1234,4321

This is a staircase that randomly goes left to right or right to left.

Providing multiple configurations after & will choose one at random, and providing no configuration resets to default.

&A shuffles the track redirects randomly.

^FFFF00,FFC000,FF6000,FF0000

Set colors for 2/3/4/5 simultaneous notes to yellow, orange-ish, red-ish, red respectively. (Unless you specify, 6+ simultaneous notes use the same color as 5.)

Not providing colors will reset to default (the one above).

You can choose the colors to work with the background image, which makes the visuals work better.

Side note: the colors are defined using HEX color codes. Computers define colors using RGB (red, green, blue), with each having a range of 0-255. Hex codes are the three values one after another in hexadecimal. For example, yellow is 255 red, 255 green and 0 blue, which the computer represents as (255, 255, 0), or (FF, FF, 00) in hexadecimal. Put them together as FFFF00 and it's the color code.

(translator's note: you can also find a color picker, either within some apps you are using like Word or Photoshop, or find one online, which will show you the RGB values and/or color codes of any color you choose.)

----X
----*0
OO--

If you really want a truly random row and don't want the previous row's notes to affect repeating note rules, you can add a zero-time empty row like this.

----X;@
----X;@123

The first random note here actually has a fixed position (MrZ: but I'm not sure where exactly it is), and the one after is actually random.

@ sets random seed, which makes the random number generator deterministic. This consistency also extends across beatmaps, provided that the seed is the same.

Providing multiple numbers after the @, separated by comma, makes it choose a seed at random. You can try to find a few good random seeds in advance, if you do not want some unfortunate true randomness cause unexpected behavior.

Providing no numbers will make it use system time, i.e. actually random.

====E
---O||
--O-||
-O--||
O---||
====S196

This is a 16th note staircase that loops 196 times!

==== marks repetition sections. ====S begins the loop, and number after it denotes how many times you want it to loop (defaults to 2). ====E ends the loop.

-OO-||
====E
---O||
====M
--O-||
-O--||
O---||
====S196

This is a 16th note staircase that loops 196 times, but the last note is a double!

====M is a break point that ends the last loop early and skip to ====E.

(If you are familiar with sheet music, you might have seen something similar.)

/set_judge:30ms,50ms,80ms,120ms,160ms

Set judgement window. You need to provide 5 window radius sizes from highest to lowest accuracy, separated by comma. Unit can be ms or s, defaults to ms.

The example is the default used by the game.

Note that this is not a global property of the beatmap, and it can be changed half way through the song (though it's not recommended to do so).

/set_acc_points:101,100,75,0,-100

Set accuracy score. You need to provide 5 percentage scores for the 5 judgement windows, separated by comma. The highest number must be >=100, or else it would be impossible to reach 100% accuracy.

This can also be set half way across the song, but also not recommended.

[1]p,-100,0

Move track 1 left by 100 units.

We start with p for moving a track. [1] is for track 1, p for the command type of moving, and then the x and y offset to move by. (positive x is to the right, positive y is downwards. The origin is the center of the screen. By default, the screen spans -640 to 640 on the x axis, and -360 to 360 on the y-axis.) (translator's note: i.e. as if the screen was 1280x720.)

[1]position,,-100

Move track 1 upwards by 100 units.

You can leave out the x or the y in a move command, which gets defaulted to 0.

Both p and position can be used. Maybe the full words is easier to memorize, and you can use either.

[1]P,0

Move track 1 to x=0 and y=where it starts off by default.

UPPERCASE P means "set absolute direction" instead "move". If you don't provide a value, it defaults to "starting position", i.e. where the tracks are when it started. (In the future this might be changed for ease of use)

[1]r,60

Rotate clockwise 60 degrees around the center of the bottom. The parameter is how many degrees to rotate clockwise (and if you provide negative, it's counter-clockwise). Leaving it out defaults to ... an error (why would you not give an angle to rotate by)

[1]R,60

Similarly, an uppercase R means "set to a certain angle", leaving black means point back up

[1]s,1.5,1

Stretch horizontally by x1.5, and vertically by x1 (i.e. unchanged)

s for scaling the track. Leaving out the parameters defaults to 0 (unchanged). The unit is "one track" (i.e. the default size is 1).

[1]S,1.5,1

Directly set the scale ratio. Defaults to 1

[1]d,100

Increase falling speed by 100. Parameter is mandatory. The initial value is 1000.

[1]D,100

Set falling speed to 100. Default to restore initial value.

(translator's note: idk if it's transparency or opacity. i.e. idk if 100% is fully visible or fully hidden.)

[1]t,-50

Reduce transparency by 50%. Parameter mandatory.

[1]T,30

Set transparency to 30%. Default to restore initial value.

[1]a

Toggle availability. No parameters.

[1]A,false

Set availability to false (disabled). Defaults to true (enabled).

[1]C,FF0000

Set track color to red. Defaults to E6E6E6 (a white that isn't too bright and blinding).

[1]c,800000

Increase red channel of the track color by hexadecimal 80. (MrZ: Is it actually useful? I just did it for the sake of having a pair of upper/lowercase commands)

You can add a negative sign before the color code

[1]N,100

Set track name display opacity (alpha) to 100%. Defaults to 0% (hides the name).

[1]L,hide

Set rendering mode of the "side line" of the track to hide (i.e. only show the judgement line). Defaults to normal.

Other possible parameters are hard (solid-colored line, no gradient), double (extends line symmetrically to both sides; no functionality but makes animations easier), or harddouble (both hard and double at the same time).

Because it switches between a few set modes, this only has an UPPERCASE variant.

Same syntax as a, but toggles judgement line display

[1,2,3]s,2

Scale horizontally to x2 for tracks 1, 2, and 3.

If you need to manipulate multiple tracks, this makes it easier.

[A]s,2

Scale horizontally to x2 for ALL tracks.

A for all tracks, L and R for left and right tracks respectively. (For odd-number tracks, the middle track is not included by either.)

[A]P
[A]R
[A]S

Reset all tracks' position, rotation, and scale.

[A]P;[A]R;[A]S

You can also use semicolon to put commands on a single line.

OOOO;[A]r,360

A four-note-at-the-same-time, while also triggering an animation at the same time.

Having too many animation commands makes the beatmap hard to read. It's recommended to put animations in the same line as the notes like this, so that the notes are not separated apart.

Here are examples for "rotate track 1 by 90 degrees" with different animation curves:

[1]<S>R,90

No animation, it instantly snaps to the destination

[1]<L,2>R,90

Animate linearly (i.e. at a constant speed) over two beats.

Time units support ms, s, beat and bar, defaults to beat.

[1]<T,1>R,90

Animate, using the [0, pi] part of curve y=-cos(x), over 1 beat.

Time units support ms, s, beat and bar, defaults to beat.

[1]<E,2.6>R,90

Exponentially approach the destination. The larger the number, the faster the approach. Just type in a value by feeling and test it out

[1]<P,1,2>R,90

Animate, using the [0,1] part of y=x^2, over 1 beat.

Time units support ms, s, beat and bar, defaults to beat.

The exponent has to have an absolute value of >1. An exponent of 1 ex linear. An exponent of 2 is a smooth start (ease in). Negative numbers have a special meaning; -2 is like a smooth stop (ease out), opposite of 2. (it's hard to describe what it's like between 1 and 2, or above 2. Try it yourself)

Summary of all curves:
instant: <S>
linear: <L, duration>
exponential approach: <E, decay speed>
power (ease in): <P, duration, exponent>
sine (ease in and out): <T, duration>

If you do not specify an animation curve, it defaults to <E,12>, a fast approach that is somewhat natural.

While tracks is easy to adjust on the fly, notes are too numerous and is difficult to directly adjust within the notes syntax. Thus, we're making it like this: after you set the command, all notes after this point on this track will apply this animation.

(1)C,FF0000

Set track 1 notes to red. Defaults to E6E6E6 (not-blinding white).

(1)C,FF0000,FFFFFF

Make track 1 notes animate "from red to white".

More precisely speaking, all notes spawn 2.6 seconds in advance; the notes will spawn red, change color over time, and become completely white when it touches the judgement line.

(1)C,FF0000,FF0000,FF0000,FFFFFF

Make track 1 notes "stay red for the first 3/4 of its lifetime, and animate to white in the last 1/4". (translator's note: ... I think it's actually 2/3 and 1/3?)

(1)T,50

Make track 1 notes' transparency 50%. Defaults to 80%.

(1)T,100,100,100,0

Make track 1 notes "fully visible for the first 3/4 time, and gradually disappear during the last 1/4". (translator's note: same as above, I think it's 2/3 1/3)

(1)X,-10,10,-10,10,0

Make track 1 notes "sway left and right until it touches the judgement line"

(1)Y,-10,10,-10,10,0

Make track 1 notes "squiggle up and down until it touches the judgement line"

Timing of all note animations are like this:

from note spawns (2.6 seconds ahead, can't change in current version) until it's supposed to be hit

After the note passes the judgement line, it will stay with the last value

Ctrl+Alt+1/2/3/4/5 can adjust beatmap playback speed, which is useful for debugging animations or song offset.

The table below provides equivalent commands for symbols introduced before.

For track and note animations, the command-style syntax are as following:

/set_track:track_id;<animation_curve,param_1,param_2,...>operation,param_1,param_2,...

/set_note:track_id;operation,param_1,param_2,...

You have learned all the syntax there are for Quatrack beatmap!

There will be more note types and animation commands in the future, and you can drop feature requests if you have ideas!

Please keep supporting this game!