Home

K-AIKO file format

.kaiko (or .ka) is a human-readable file format for K-AIKO. It is designed as a sub-langauge of python, so it is easier to hack and produces more flexible beatmaps. One can also designs your own notes just by a little coding. Even without touching program things, you can already produces amazing beatmaps using default properties. K-AIKO file format provides three kinds of mode for different customizabilities: Stardard mode K-AIKO-std only contains default properties. Extended mode K-AIKO-ext can use installed custom notes. Hack mode K-AIKO-hack doesn't have any restriction; it is just a python script. The benfit of the extended mode is it can be edited by beatmap editor, but notice that it is very dangerous to run untrusted programs, and it is as dangerous as the hack mode. K-AIKO beatmap is composed of its metadada and a note chart, which be represented as an ABC-liked musical notation. The note chart format is designed for both program and human, so one can use the beatmap editor to compose your notes, or just use a text editor to arrange them.

beatmap

The main structure of K-AIKO file format are composed by four parts: header, metadata, declarations and charts.

• header

  K-AIKO file format should start with header: #K-AIKO-<mode>-<version>, where <mode> can be std, ext, hack standing for three different modes, and <version> has the form <major>.<minor>.<patch> indicate the version of file format.

• metadata

  The metadata of beatmap are written as the form: beatmap.<field> = <value>. The field value should be written in specific form.
  Field audio is a singleline-string, which is the relative path of the audio file.
  Field volume is a floating number, which is the volume (in dB) of the audio.
  Fields offset and tempo are floating numbers, which define the timing points of this beatmap. Notice that timing points are not necessarily linear⁽ᴺᴼᵀ ᴵᴹᴾᴸᴱᴹᴱᴺᵀᴱᴰ⁾; some song have variation of beats, and all notes should follow the beat, not the absolute time.
  Field info is a multiline-string, which describes the information of this beatmap.
  Field preview is a floating number, which is the start time of beatmap audio preview.
  Field bar_shift and bar_flip are floating number and boolean value, which are the parameters of initial configuration of playfield.

• declarations⁽ᴺᴼᵀ ᴵᴹᴾᴸᴱᴹᴱᴺᵀᴱᴰ⁾

  In the extended mode, one can use custom notes by declarations. It should be written as the form: beatmap['<symbol>'] = <custom note>. The custom notes can be imported by import <mod> below the header.

• chart

  Note chart of one beatmap can have multiple tracks, and it should be written in a raw triple-quoted string. In the triple quotes, K-AIKO file format uses ABC-liked notation to represent a note chart. It is harder to parse, but also more readable, expressive and processable. Note chart will produce a sequence of targets according to the notes.

chart

note chart in K-AIKO file format look like

TRACK(beat=0, length=1, meter=4):
    x x o x | x x [x x] o |
    # clap
    x x [x x] x | [x x x x] [_ x] x |
    # others
    %(2) ~ ~ ~ | < < < < | < < < < | @(2) ~ ~ ~ |

Its syntax is similar to python. The scope of block is defined by indentation, and open by colon : at the end of line. Notice that each level of indentation should be increased by 4 whitespaces, and vertical indentation (empty lines) should keep clean. The text after the sharp symbol # will be ignored, but it should occupy a entire line.

• track

  The track block is defined by the keyword TRACK, and its body is a pattern of notes defined below.
  One can pass through parameters to track block, which affect the default arrangement of notes. beat (default is 0) determines the starting time of this track; length (default is 1) defines the default note length; meter (default is 4) is the length of measure, and the flag hide (default is False) turns off/on this track while playing, which is just for testing.

• note

  Note is a token followed by parentheses-enclosed arguments (not necessary). Adjacent notes should be separated by whitespace or newline. Bracket [...] and {...} are special patterns of notes.
  The token of the note can be composed of almost any character. For example, x, x(speed=1.2), %(2), _, ~, | are valid syntax of note. Even 😎, <!, $@!^(abc=456) are also valid syntax of note. Only spacing characters \b\t\n\r\f\v, brackets and qutations ()[]{}'", backslash \ and sharp # are invalid for composing token.

Different from ABC notation, there are only 6 types of notations in K-AIKO-std:

• target

  Target represents a hit event during playing. The sequence of targets will be arranged at regular intervals of beats and default length: they indicate the time and duration considered for hitting the object while playing. The targets can be further configured by parentheses-enclosed arguments.
  There are 6 default targets: rest _, soft x, loud o, incr <, roll %, spin @. All targets, including custom targets, should have common properties beat and length. The properties beat and length are set automatically by the arrangement of notes. The starting beat and default length can be set by track parameters. Targets may be related to the context of track (for example, incr should play louder and louder). The rest target _ is a special target, which is actually not a target; it doesn't produce any event.

• script

  Script is an action during playing. They are usually served as performances of beatmap and are unrelated to your score, so they are usually put in the curvy braces (see below instant).
  There are 4 default scripts: Text, Context, Shift, Flip.
  Text can be used by quoted string "...", which shows a text pass through the scrolling bar.
  Context is used to change the context value, which can globally affect the behavior of notes, such as speed, volume, etc..

• lengthen: ~

  As the name, it lengthen the previous note by value length.

• measure: |

  Just like ABC notation, it separates the beats as segments of given length (defined by chart parameter meter). However it is not necessary to put the bar every time; it's just an assertion of time segments. It has no effect on the beatmap, so you can remove them without changing gameplay.

• division: [...]

  It halves the default length inside the bracket. The nested bracket further halves the length. the length of rest note _ and lengthen symbol ~ are also halved. One can make triplet or others divisions by [ ... ]/3.

• instant: {...}

  In the curvy brace, all notes will be playing in the current beat simultaneously with zero length.