Skip to content

Instantly share code, notes, and snippets.

@beer-psi
Last active May 12, 2024 18:10
Show Gist options
  • Save beer-psi/db93f0f75a56af35ba44c20431d52748 to your computer and use it in GitHub Desktop.
Save beer-psi/db93f0f75a56af35ba44c20431d52748 to your computer and use it in GitHub Desktop.
3simai

This document describes the syntax for "standard" 3simai, based on how 3simai interpreted and played the chart file.

This is not intended to be an absolute guide, and you should adapt to whatever oddities your chart viewers/editors have.

Table of contents

  1. Difficulty
  2. Metadata
    1. Difficulty-specific metadata
    2. Metadata extensions
  3. Chart creation
    1. Setting the BPM
    2. Setting beat divisor
    3. Placing notes
    4. Marking the end

Difficulty

3simai has 7 difficulties which are assigned numbers 1 to 7:

  1. EASY
  2. BASIC
  3. ADVANCED
  4. EXPERT
  5. MASTER
  6. Re:MASTER
  7. ORIGINAL/宴会場

Metadata

Chart metadata is written in &<key>=<value> form. For example: &title=Garakuta Doll Play

3simai only: When typing a value which contains reserved characters (&, =, +, \, %), URL-encode it: & -> %26.

Notes for implementors

maidata.txt is simply an application/x-www-form-urlencoded text file, please don't parse it by scanning through lines and finding keywords like &title= or &artist=.

Key Details
title The title of the song.
3simai also supports subtitles, which is written smaller than the title and is seperated by a thick vertical bar : &title=BaBan!! ┃-甘い罠-
artist The artist of the song.
smsg A short message displayed on the introduction screen in PLAY mode in 3simai.
des The name of the charter/note designer.
first Chart offset in seconds, decides when the first note starts playing.
lv_x The level of x difficulty. It can be a whole number with an optional +, or a single character: &lv_7=宴, &lv_6=14+, &lv_5=14.
inote_x The chart for x difficulty.

Difficulty-specific metadata

smsg, des and first can vary by difficulty level. To write difficulty-specific metadata, add _x to the key, with x corresponding to the difficulty.

Difficulty-specific metadata takes precedence over global metadata.

>> The chart offset for Re:MASTER is 1.234 seconds, while others are 1.5 seconds
&first=1.500
&first_6=1.234

>> Note designer for EXPERT is rioN, for MASTER is Jack
&des_4=rioN
&des_5=Jack

Chart creation

Setting the BPM

BPM needs to be specified at the very beginning of a chart. It can be a whole or decimal number.

To set the BPM to 123.45:

&inote_1=
(123.45)

Setting beat divisor

The length between two beats in a song is one bar. By default, one bar consists of 4 quarters, since usually the time signature in songs is 4/4. However, if you want to place eighth notes, you will need to set the beat divisor:

&inote_1=
(123.45){8}

Now after this, one bar will consists of 8 equal parts.

The higher the number, the more notes you can place in one bar:

● are the notes that you can place

{1}  ●○○○○○○○○○○○○○○○
{2}  ●○○○○○○○●○○○○○○○
{4}  ●○○○●○○○●○○○●○○○
{8}  ●○●○●○●○●○●○●○●○
{16} ●●●●●●●●●●●●●●●●

But large numbers aren't always necessary. For example, if you set the beat divisor to 64, but there's only one note per bar, it would be a waste of text:

&inote_1=
(123.45){64}
1,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,

Instead, you can lower the beat divisor and save characters:

&inote_1=
(123.45){1}
1,

(Advanced) You can also set a custom duration for each measure using the {#float} syntax:

>> Make a measure last 1.5 seconds
&inote_1=
(123.45){#1.5}
1,

Placing notes

maimai note positions are numbered from 1 to 8, with 1 being the top right button, and 2-8 numbered clockwise:

  8 1
7     2
6     3
  5 4

Please go to each note type's individual section for more information:

Marking the end

Once you finish writing the chart, place a capital E at the end:

&inote_1=
(120){4}
1,5,3,7,
{1}
5h[4:3],
8^3[8:7],
,
2b/3b,
,
,
E

Without this E, the chart will abruptly end when the music stops playing, cutting short any SLIDEs and HOLDs.

However, you can't place E after the music ends either.

TAPs and BREAKs

To place a note, write the number corresponding to the position, then a comma:

>> This will play quarter notes 1, 3, 5, 7 in order
&inote_1=
(120){4}
1,3,5,7,

If you don't want to have a note, just omit the number:

&inote_1=
(120){4}
1,3,5,7,
{8}
5,,2,3,4,,7,8,

Modifiers

Place modifiers after the note: <note><modifier>

List of modifiers:

Modifier Details
b BREAK
x EX (CRITICAL PERFECT unless MISS)
$ Turns into star tap note
$$ Turns into spinning star tap note

Modifiers can be combined in any order:

>> EX BREAK on position (1)
1bx

HOLDs

With hold notes, you will also need to tell 3simai how long to hold.

For example, if you want to hold (1) for a bar:

&inote_1=
(120){4}
1h[1:1],

h after the number indicates that it's a HOLD. To set the hold length, write [x:y], where x is the beat divisor and y is the length.

To hold (2) for 3 quarter notes:

&inote_1=
(120){4}
2h[4:3],

To hold (3) for 5 eighth notes:

&inote_1=
(120){4}
3h[8:5],

Absolute duration

It is also possible to make a hold last for an absolute duration with the [#x] syntax.

To hold (7) for exactly 1.5 seconds:

&inote_1=
(120){4}
7h[#1.5],

Instant holds

If you omit [x:y], then the HOLD duration becomes instant, to the point where it looks like a hexagon TAP. This is often used in boss charts, such as sølips MASTER.

Modifiers

Modifiers b and x can be added to create BREAK HOLD, EX HOLD and BREAK+EX HOLD respectively:

&inote_1=
(120){4}
2hb[4:3],3hx[4:3],4hbx[4:3],

SLIDEs

SLIDEs consist of 3 parts: the beginning TAP, the slide shape, and the slide length.

Keep in mind that slides do not move until a quarter after the TAP.

SLIDEs are written similarly to HOLDs:

<start><shape><end>[x:y]

where x is the beat divisor and y is the length.

Slide duration

  • An instant slide can be made by setting x and y to 0.
  • The [BPM#x:y] syntax can be used to set a custom BPM for the slide (useful for delay slides)
  • Absolute slide duration:
    • [#x]: Slide for exactly x seconds, with x being a decimal.
    • [BPM#x]: Same as above, with a custom BPM
    • [y##x]: Delay for y seconds, then slide for x seconds. Both are decimal numbers.

Slide shape

(descriptions by donmai)

For slides that have only one end for a given position, the ending position is exactly opposite to the starting position.

Shape Details
- Straight line from start to end
^ Along the judgement ring (3 places maximum)
> Along the judgement ring, heading right from start
< Along the judgement ring, heading left from start
v Start to center (straight) to end (straight)
s S-shaped Zigzag (only one end for a given position)
z Z-shaped zigzag (only one end for a given position)
q Arc along the center (clockwise)

p Arc along the center (counterclockwise)
pp Start to center (straight) to end (CCW arc)
qq Start to center (straight) to end (CW arc)
V Similar to v, but it goes to another button exactly two places away from the starting point instead of the center.
A slide that starts from 1, goes through 3 and ends at 6 is written: 1V36
w Fan slide (only one end for a given position)

Multiple slides starting from the same point

For example, to combine 1-4[8:1] and 1-6[8:1]:

1-4[8:1]*-6[8:1]

Place the * character between the combined slides, and omit the starting point for the second slidde.

The third, and fourth, and so on, are written similarly:

>> Five straight slides starting from (1) moving at the same time
1-3[8:1]*-4[8:1]*-5[8:1]*-6[8:1]*-7[8:1]

☆TAP modifiers

Modifier Details
b BREAK
x EX (CRITICAL PERFECT unless MISS)
? Tapless slide
! Tapless slide (star is not displayed)
$ Tapless slide (maiPad PLUS only)
@ Change ☆TAP to regular tap

Add them before the slide shape: 1bs5

BREAK SLIDE

Add a b after the slide length: 1-4[x:y]b

CHAIN SLIDE

Combining slides 4-1, 1-6 and 6-3 is written: 4-1-6-3[x:y]

BREAK CHAIN SLIDEs can also be done: 4-1-6-3[x:y]b

It is also possible to set a different slide duration for each part of a CHAIN SLIDE. In this configuration, all parts must have a duration:

4qq4[x:y]z8[c:d]

>> This will error
4-1-6[c:d]-3[x:y]

TOUCH and TOUCH HOLD

These are placed the same way as TAPs and HOLDs, but instead of writing the number, the touch region is written.

touch regions

For example:

&inote_1=
(120){4}
E2,E8,E4,E6,

TOUCH HOLD can only be placed in the C region.

&inote_1=
(120){4}
Ch[1:1],

In maimai DX, some TOUCH and TOUCH HOLDs will cause firework effects. To replicate that in simai, add an f after the touch region:

&inote_1=
(120){4}
Cf,

Same for TOUCH HOLD:

&inote_1=
(120){4}
Chf[1:1],

Writing Cfh is also fine, but writing Chf is recommended.

BOTH/EACH

In maimai, if two notes appear at the same time, they will be colored yellow (except BREAKs). These are called EACH.

To place EACHs, seperate the two notes with a slash /:

>> EACH of two taps
1/2,

>> (3) TAP and (4) HOLD
3/4h[2:1],

>> (5) HOLD and (6) BREAK
5h[1:1]/6b,

>> (7)-(2) (straight line) SLIDE and (8)-(3) (straight line) SLIDE are
7-2[4:1]/8-3[4:1],

>> the / is not needed for two TAP notes:
12,

>> Make (3) yellow without having to place two notes:
3/0,

>> Pseudo EACH (tap at the same time but not marked yellow):
3`1,

There are some extra metadata keys which can be used. However, they are not standard, so these metadata might be meaningless when using another chart player/editor.

maiPad PLUS

Key Details
wholebpm Song BPM. This is optional, however apparently this makes slide delay time independent of BPM changes?
pvstart Marks when the PV starts playing relative to the song
pvend Marks when PV stops playing relative to the song
demo_seek Starts playing song preview at this point
demo_len Length of song preview
track The filename of the music
seek Similar to first
wait Wait for the specified period after the game starts before playing music

AstroDX

Key Details
alias_x Sets the difficulty name for difficulty x
color_x Sets the difficulty color for difficulty x
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment