docs/sus.md
# sus形式
## 概要
**基本的には**[Susフォーマット - Seaurchin Wiki](https://seaurchin.kb10uy.org/wiki/score/format)に準拠しています。
細かいところは[Seaurchinとの違い](/diff/)をご覧ください。
## 単語の定義
このsus-analyzerでも使われている独自単語一覧です。
公式
: Seaurchinの事を指します。ややこしくてすみません。
本家
: 名前は伏せますが、ゲーセンにあるアレです。
公式sus
: Seaurchin Wikiにある[Susフォーマット - Seaurchin Wiki](https://seaurchin.kb10uy.org/wiki/score/format)の事を指します。
メタデータ
: 曲名やBPM等が該当します。#の直後が英字の行です。
譜面データ
: ノーツが定義されている行です。#の直後が数字の行です。
## メタデータ
sus-analyzerでは下記メタ情報に対応しています。
Seaurchinとは違い、全てのメタデータを"で囲う事が出来ます。しかし、Seaurchinとの互換性を維持するために、公式susに準拠する事を**強く**おすすめします。
sus-analyzerには独自の概念として、<font color="Crimson">**必須項目**</font>と<font color="DarkBlue">**任意項目**</font>が存在します。
譜面を構成するにあたって最低限必要だろうと考えられるものです。
必須項目は赤、任意項目は青に分類してあります。
### <font color="Crimson">#SONGID</font>
楽曲IDを文字列で指定します。並び替え等に使用されます。差分譜面等でも楽曲が同一であればSONGIDは統一されるべきです。
### <font color="Crimson">#TITLE</font>
楽曲の曲名を文字列で指定します。
### <font color="Crimson">#ARTIST</font>
楽曲のアーティストを文字列で指定します。
### <font color="Crimson">#DESIGNER</font>
譜面デザイナーを文字列で指定します。
ネタを仕込むのは構いませんが、バラバラにしすぎるとソート等で若干困るかもしれません。
### <font color="Crimson">#DIFFICULTY</font>
譜面の難易度を**数値**か**特定形式の文字列**を指定します。レベルではありません。
数値は下記の通りになります。
- 0: BASIC
- 1: ADVANCED
- 2: EXPERT
- 3: MASTER
- 4: WORLD'S END
文字列を指定する場合は2種類の記法があります。
どちらでも指定出来る内容は変わりません。
- "4:☆☆両"
- "両:☆☆"
### <font color="Crimson">#PLAYLEVEL</font>
譜面のレベルを基本的に数値で指定します。
!!! Tip
\#PLAYLEVELは必須扱いになっていますが、WORLD'S ENDではPLAYLEVELを使用しません。
そのため、**WORLD'S ENDの譜面に限り不要**です。
WORLD'S ENDのsusファイルに記載することは可能ですが、処理には影響しません。
### <font color="DarkBlue">#WAVE</font>
楽曲の音楽ファイルをsusからの相対パスで指定します。
拡張子は、sus-analyzerを依存しているパッケージによります。
そのため、sus-analyzerでは拡張子の制限はありません。
また、WAVEは実質的に必須項目だと思いますが、音源の入手元が個人により違う事等を考え、譜面ファイルとしては任意項目扱いにしています。
### <font color="DarkBlue">#WAVEOFFSET</font>
楽曲のオフセットを秒単位で指定します。正の値を指定すると譜面より遅れて再生が開始します。
**この項目は、WAVEを指定している時に限り必須です。**
### <font color="DarkBlue">#MOVIE</font>
背景動画をsusからの相対パスで指定します。サイズは16:9推奨です。
こちらも、拡張子はsus-analyzerを依存しているパッケージによります。
そのため、sus-analyzerでは拡張子の制限はありません。
### <font color="DarkBlue">#MOVIEOFFSET</font>
拝啓動画のオフセットを秒単位で指定します。正の値を指定すると譜面より遅れて再生が開始します。
**この項目は、MOVIEを指定している時に限り必須です。**
### <font color="DarkBlue">#JACKET</font>
ジャケットの画像をsusからの相対パスで指定します。
サイズは1:1推奨です。
### <font color="DarkBlue">#BACKGROUND</font>
背景画像をsusからの相対パスで指定します。
こちらも拝啓動画と同じくサイズは16:9推奨です。
### <font color="Crimson">#BASEBPM</font>
楽曲の基本となるBPMを数値で指定します。
## 譜面データ
ノーツを表現するには2種類の構文存在します。
```
#mmmtl: <NOTES>
#mmmtlx: <NOTES>
```
というものです。
実際に数値に置き換えてみると
```
#00114: 1400 0000
#00128A: 1400 2400
```
といった感じになります。
上記の2行を例に説明していきたいと思います。
### 1-3桁目 - 小節番号
\#<font color="Crimson">001</font>14: 1400 0000
\#<font color="Crimson">001</font>28A: 1400 2400
まず、上3桁について説明します。
ここには**小節番号**を整数3桁で指定します。
000が1小節目、001が2小節目、といった感じです。
### 4桁目 - レーン種別
\#001<font color="Crimson">1</font>4: 1400 0000
\#001<font color="Crimson">2</font>8A: 1400 2400
4桁目には、**レーン種別**を整数1桁で指定します。
- 1: ショートノーツレーン
- 2: HOLDロングノーツレーン
- 3: SLIDEロングノーツレーン
- 4: AIR HOLD(Action含む)ロングノーツレーン
- 5: AIRノーツレーン
### 5桁目 - レーン番号
\#0011<font color="Crimson">4</font>: 1400 0000
\#0012<font color="Crimson">8</font>A: 1400 2400
5桁目にはレーン番号を指定します。
レーンはスライダーに合わせて16分割されていて、左から0,1,2の順で最後が16になります。
ただし、レーン番号に指定出来るのは1桁なので、16進数に変換して指定します。
0,1,2,3,4,5,6,7,8,9,A,B,C,D,E,F
### 6桁目 - 識別番号
\#00128<font color="Crimson">A</font>: 1400 2400
6桁目は少し特殊で、ロングレーンの識別番号を指定します。
ロングレーンというのは4桁目が2,3,4に該当するものです。
ロングノーツは重なる可能性があるので、識別番号で分けてあげる感じですね。
ロングレーンの識別番号は、扱いがやや特殊です。
全ての識別番号は、終了を同じタイミングで開始を行えます。
全ての識別番号は、種別（SLIDE/HOLD/AIR）が違えば、同じ識別番号を同時に使用する事が可能です。
HOLDの識別番号はレーンが違えば、同じ識別番号を同時に使用する事が可能です。
要するに、可能な限り使い回しが出来るようになっています。
### 5桁と6桁 - ショートノーツとロングノーツ
一つ前の項目で説明したとおり、6桁目にはロングレーン識別番号を指定します。
つまり、6桁の構文はロングノーツ専用の構文となります。
ショートノーツレーン(種別が1,5)は5桁、ロングノーツレーン(種別が2,3,4)は6桁だという事を覚えておきましょう。