パッケージ com.lmt.lib.bms

クラス BmsSpec


  • public final class BmsSpec
    extends Object
    BMSの仕様を表します。

    BMSライブラリで扱うことのできるBMSの仕様は、利用者がBMSデータの仕様を決定することができるようになっています。 このクラスは利用者が決定したBMS仕様を表現し、必要に応じて利用者が参照できます。また、本クラスの最大の目的は BmsContentの挙動を制御することにあります。

    BMS仕様が提供する情報には以下のものが含まれています。
    - メタ情報。BMSの記述のうち"#"または"%"で始まる情報のことであり、BmsMetaクラスで表現されます。
    - チャンネル。BMSの記述のうち小節番号+チャンネル番号+":"で始まる情報のことであり、BmsChannelクラスで表現されます。
    - BMSデータにおける最小値・最大値・初期値等の情報。これらの情報はBMSライブラリの規定値であり変更できません。

    BMS仕様を生成するにはBmsSpecBuilderを使用します。ビルダーに対してメタ情報、チャンネル等の情報を 構成し、最終的にBmsSpecオブジェクトを生成して返します。生成されたオブジェクトはBMSコンテンツの制御や BMSデータの読み込み、書き込みなど、BMSデータを扱う様々な状況で必要になります。

    メタ情報(BmsMeta)について
    メタ情報はBMSコンテンツに関連付けられる付加的な情報のことであり、代表的な情報には楽曲のタイトル、アーティスト、 BPM等が挙げられます。メタ情報は「構成単位」と「名称」で分割して管理されます。メタ情報を参照する場合、 構成単位は呼び出すメソッドの種類「getSingleMeta(java.lang.String)」「getMultipleMeta(java.lang.String)」「getIndexedMeta(java.lang.String)」で 決定し、名称はそれぞれのメソッドの引数として指定します。構成単位が異なれば、名称が同じでも構いません。 但し、メタ情報の定義次第では同じ名前で構成単位ごとにデータの型が異なるという状況になる可能性があります。 (そのようなBMS仕様にするかは利用者側に委ねられます)

    チャンネル(BmsChannel)について
    チャンネルはBMSコンテンツにおいて、時間軸を必要とする要素を表す情報のことです。チャンネルで表すことのできる情報は 音の発音タイミング、画像の切り替えタイミング等が存在します。これらの情報は1小節につき最大でCHINDEX_MAX+1個 まで保有することができるようになっています。BMSでは各チャンネルに保有される「タイムライン要素」を用いて BMSコンテンツを表現していきます。

    ユーザーチャンネルについて
    ユーザーチャンネルとは、BMS仕様に規定されたチャンネルのうちチャンネル番号がUSER_CHANNEL_MIN以上の チャンネルのことを指します。これらのチャンネルはBMSコンテンツを表すチャンネルとしてではなく、アプリケーションの 制御上必要になる一時的な情報を格納するためのチャンネルとして利用することを目的としています。 そのため、ユーザーチャンネルはBmsLoaderによる外部データからの読み込み対象外、BmsSaverによる 外部データへの書き込み対象外となります。

    非サポート要素について
    BMSライブラリでは、一般的に「CONTROL FLOW」と呼ばれる要素をサポートしません。CONTROL FLOWは#RANDOM、#SWITCH およびそれに付随する要素を指します。これらの要素は使用頻度が著しく低く、且つ仕様が複雑で実装が困難であることから サポートを見送っています。

    関連項目:
    [BmsSpecBuilder] BMS仕様を構築する方法についての説明, [BmsMeta] メタ情報の詳細についての説明, [BmsChannel] チャンネルの詳細についての説明, [BmsContent] BMS仕様に基づいて生成されたBMSコンテンツの詳細についての説明, [BmsLoader] BMS仕様に基づいて外部データからBMSコンテンツを読み込む方法についての説明, [BmsSaver] BMSコンテンツを外部データに書き込む方法についての説明
    • フィールドの概要

      フィールド 
      修飾子とタイプ フィールド 説明
      static int BASE_DEFAULT
      基数選択可能なデータ型(BmsType.BASE, BmsType.ARRAY)のデフォルトの基数。
      static double BPM_DEFAULT
      BMS定義で初期BPMが未定義の場合に使用されるデフォルトのBPM
      static double BPM_MAX
      BMSライブラリで取り扱い可能な最大のBPMを表します。
      static double BPM_MIN
      BMSライブラリで取り扱い可能な最小のBPMを表します。
      static int CHANNEL_MAX
      BMSライブラリで取り扱い可能な最大のチャンネル番号を表します。
      static int CHANNEL_MEASURE
      BMSライブラリにおいて、小節線のチャンネル番号を表します。
      static int CHANNEL_MIN
      BMSライブラリで取り扱い可能な最小のチャンネル番号を表します。
      static int CHINDEX_MAX
      チャンネルインデックスの最大値。
      static int CHINDEX_MIN
      チャンネルインデックスの最小値。
      static int INDEXED_META_INDEX_MAX
      索引付きメタ情報へのアクセスで使用可能な最大のインデックス値を表します。
      static double LENGTH_MAX
      小節長変更チャンネルに設定可能な最大の値を表します。
      static double LENGTH_MIN
      小節長変更チャンネルに設定可能な最小の値を表します。
      static int MEASURE_MAX
      最大の小節番号。
      static int MEASURE_MAX_COUNT
      BMSライブラリでサポートする小節数の上限を表します。
      static int MEASURE_MIN
      最小の小節番号。
      static int MULTIPLE_META_INDEX_MAX
      重複可能メタ情報へのアクセスで使用可能な最大のインデックス値を表します。
      static int SPEC_CHANNEL_MAX
      BMS仕様として定義可能な最大のチャンネル番号を表します。
      static int SPEC_CHANNEL_MIN
      BMS仕様として定義可能な最小のチャンネル番号を表します。
      static double STOP_MAX
      BMSライブラリで取り扱い可能な最大の譜面停止時間を表します。
      static double STOP_MIN
      BMSライブラリで取り扱い可能な最小の譜面停止時間を表します。
      static double TICK_COUNT_DEFAULT
      小節の刻み数のデフォルト値。
      static double TICK_MAX
      小節の刻み位置を表す最大の値。
      static double TICK_MIN
      小節の刻み位置を表す最小の値。
      static int USER_CHANNEL_MAX
      ユーザーチャンネルの最大のチャンネル番号を表します。
      static int USER_CHANNEL_MIN
      ユーザーチャンネルの最小のチャンネル番号を表します。
      static int VALUE_16_MAX
      16進配列から読み込み可能な最大の値を表します。
      static int VALUE_16_MIN
      16進配列から読み込み可能な最小の値を表します。
      static int VALUE_36_MAX
      36進配列から読み込み可能な最大の値を表します。
      static int VALUE_36_MIN
      36進配列から読み込み可能な最小の値を表します。
      static int VALUE_62_MAX
      62進配列から読み込み可能な最大の値を表します。
      static int VALUE_62_MIN
      62進配列から読み込み可能な最小の値を表します。
      static int VALUE_MAX
      ノートに設定可能な最大の値を表します。
      static int VALUE_MIN
      ノートに設定可能な最小の値を表します。
    • フィールドの詳細

      • BPM_DEFAULT

        public static final double BPM_DEFAULT
        BMS定義で初期BPMが未定義の場合に使用されるデフォルトのBPM
        関連項目:
        定数フィールド値
      • BPM_MIN

        public static final double BPM_MIN
        BMSライブラリで取り扱い可能な最小のBPMを表します。
        関連項目:
        定数フィールド値
      • BPM_MAX

        public static final double BPM_MAX
        BMSライブラリで取り扱い可能な最大のBPMを表します。
        関連項目:
        定数フィールド値
      • LENGTH_MIN

        public static final double LENGTH_MIN
        小節長変更チャンネルに設定可能な最小の値を表します。
        関連項目:
        定数フィールド値
      • LENGTH_MAX

        public static final double LENGTH_MAX
        小節長変更チャンネルに設定可能な最大の値を表します。
        関連項目:
        定数フィールド値
      • MULTIPLE_META_INDEX_MAX

        public static final int MULTIPLE_META_INDEX_MAX
        重複可能メタ情報へのアクセスで使用可能な最大のインデックス値を表します。
        関連項目:
        定数フィールド値
      • INDEXED_META_INDEX_MAX

        public static final int INDEXED_META_INDEX_MAX
        索引付きメタ情報へのアクセスで使用可能な最大のインデックス値を表します。
        関連項目:
        定数フィールド値
      • STOP_MIN

        public static final double STOP_MIN
        BMSライブラリで取り扱い可能な最小の譜面停止時間を表します。
        関連項目:
        定数フィールド値
      • STOP_MAX

        public static final double STOP_MAX
        BMSライブラリで取り扱い可能な最大の譜面停止時間を表します。
        関連項目:
        定数フィールド値
      • CHANNEL_MEASURE

        public static final int CHANNEL_MEASURE
        BMSライブラリにおいて、小節線のチャンネル番号を表します。

        このチャンネル番号は、BMS仕様には存在しないものです。BMSライブラリを使用するうえでの処理でのみ 用いられるチャンネル番号で、唯一最小~最大チャンネル番号の範囲外を示す特別な値です。

        楽曲位置の走査を行う場合に、走査対象のチャンネルを検査するテスターに渡される場合があります。 詳しくはBmsContent.seekNextPoint(int, double, boolean, IntPredicate, BmsPoint)を参照してください。

        関連項目:
        定数フィールド値
      • CHANNEL_MIN

        public static final int CHANNEL_MIN
        BMSライブラリで取り扱い可能な最小のチャンネル番号を表します。
        関連項目:
        定数フィールド値
      • CHANNEL_MAX

        public static final int CHANNEL_MAX
        BMSライブラリで取り扱い可能な最大のチャンネル番号を表します。
        関連項目:
        定数フィールド値
      • SPEC_CHANNEL_MIN

        public static final int SPEC_CHANNEL_MIN
        BMS仕様として定義可能な最小のチャンネル番号を表します。
        関連項目:
        定数フィールド値
      • SPEC_CHANNEL_MAX

        public static final int SPEC_CHANNEL_MAX
        BMS仕様として定義可能な最大のチャンネル番号を表します。
        関連項目:
        定数フィールド値
      • USER_CHANNEL_MIN

        public static final int USER_CHANNEL_MIN
        ユーザーチャンネルの最小のチャンネル番号を表します。
        関連項目:
        定数フィールド値
      • USER_CHANNEL_MAX

        public static final int USER_CHANNEL_MAX
        ユーザーチャンネルの最大のチャンネル番号を表します。
        関連項目:
        定数フィールド値
      • CHINDEX_MIN

        public static final int CHINDEX_MIN
        チャンネルインデックスの最小値。
        関連項目:
        定数フィールド値
      • CHINDEX_MAX

        public static final int CHINDEX_MAX
        チャンネルインデックスの最大値。
        関連項目:
        定数フィールド値
      • MEASURE_MAX_COUNT

        public static final int MEASURE_MAX_COUNT
        BMSライブラリでサポートする小節数の上限を表します。
        関連項目:
        定数フィールド値
      • TICK_MIN

        public static final double TICK_MIN
        小節の刻み位置を表す最小の値。
        関連項目:
        定数フィールド値
      • TICK_MAX

        public static final double TICK_MAX
        小節の刻み位置を表す最大の値。
        関連項目:
        定数フィールド値
      • TICK_COUNT_DEFAULT

        public static final double TICK_COUNT_DEFAULT
        小節の刻み数のデフォルト値。
        関連項目:
        定数フィールド値
      • VALUE_16_MIN

        public static final int VALUE_16_MIN
        16進配列から読み込み可能な最小の値を表します。
        関連項目:
        定数フィールド値
      • VALUE_16_MAX

        public static final int VALUE_16_MAX
        16進配列から読み込み可能な最大の値を表します。
        関連項目:
        定数フィールド値
      • VALUE_36_MIN

        public static final int VALUE_36_MIN
        36進配列から読み込み可能な最小の値を表します。
        関連項目:
        定数フィールド値
      • VALUE_36_MAX

        public static final int VALUE_36_MAX
        36進配列から読み込み可能な最大の値を表します。
        関連項目:
        定数フィールド値
      • VALUE_62_MIN

        public static final int VALUE_62_MIN
        62進配列から読み込み可能な最小の値を表します。
        関連項目:
        定数フィールド値
      • VALUE_62_MAX

        public static final int VALUE_62_MAX
        62進配列から読み込み可能な最大の値を表します。
        関連項目:
        定数フィールド値
      • VALUE_MIN

        public static final int VALUE_MIN
        ノートに設定可能な最小の値を表します。
        関連項目:
        定数フィールド値
      • VALUE_MAX

        public static final int VALUE_MAX
        ノートに設定可能な最大の値を表します。
        関連項目:
        定数フィールド値
    • メソッドの詳細

      • getSingleMeta

        public final BmsMeta getSingleMeta​(String name)
        情報単位がSINGLEのメタ情報を取得します。
        パラメータ:
        name - メタ情報の名称
        戻り値:
        名称に該当するメタ情報。存在しない場合はnull。
        例外:
        NullPointerException - nameがnull
      • getMultipleMeta

        public final BmsMeta getMultipleMeta​(String name)
        情報単位がMULTIPLEのメタ情報を取得します。
        パラメータ:
        name - メタ情報の名称
        戻り値:
        名称に該当するメタ情報。存在しない場合はnull。
        例外:
        NullPointerException - nameがnull
      • getIndexedMeta

        public final BmsMeta getIndexedMeta​(String name)
        情報単位がINDEXEDのメタ情報を取得します。
        パラメータ:
        name - メタ情報の名称
        戻り値:
        名称に該当するメタ情報。存在しない場合はnull。
        例外:
        NullPointerException - nameがnull
      • getMeta

        public final BmsMeta getMeta​(BmsMetaKey key)
        指定されたメタ情報キーのメタ情報を取得します。

        メタ情報キーの名称・構成単位を使用してメタ情報を検索します。

        パラメータ:
        key - メタ情報キー
        戻り値:
        メタ情報キーに該当するメタ情報。存在しない場合はnull。
        例外:
        NullPointerException - keyがnull
      • getMeta

        public final BmsMeta getMeta​(String name,
                                     BmsUnit unit)
        指定された名称・単位のメタ情報を取得します。
        パラメータ:
        name - メタ情報の名称
        unit - 情報単位
        戻り値:
        名称・単位に該当するメタ情報。存在しない場合はnull。
        例外:
        NullPointerException - nameがnull
        NullPointerException - unitがnull
      • containsMeta

        public final boolean containsMeta​(BmsMetaKey key)
        指定されたメタ情報キーのメタ情報が存在するかどうかを返します。

        メタ情報キーの名称・構成単位を使用してメタ情報の存在チェックを行います。

        パラメータ:
        key - メタ情報キー
        戻り値:
        メタ情報キーに該当するメタ情報が存在する場合はtrue
        例外:
        NullPointerException - keyがnull
      • containsMeta

        public final boolean containsMeta​(String name,
                                          BmsUnit unit)
        指定された名称・単位のメタ情報が存在するかどうかを返します。
        パラメータ:
        name - メタ情報の名称
        unit - 情報単位
        戻り値:
        名称・単位に該当するメタ情報が存在する場合はtrue
        例外:
        NullPointerException - nameがnull
        NullPointerException - unitがnull
      • getMetas

        public final List<BmsMeta> getMetas()
        BMS仕様として定義されたメタ情報のリストを取得します。

        リストに格納されたメタ情報の順番は設定されたソートキーで決定されます。ソートキーの小さいメタ情報が リストの先頭に格納されます。ソートキーが同一のメタ情報は、BMS仕様に先に登録したものが先に格納されます。

        任意型メタ情報はリストには含まれません。

        戻り値:
        メタ情報のリスト
      • getMetas

        public final List<BmsMeta> getMetas​(boolean includeObject)
        BMS仕様として定義されたメタ情報のリストを取得します。

        リストに格納されたメタ情報の順番は設定されたソートキーで決定されます。ソートキーの小さいメタ情報が リストの先頭に格納されます。ソートキーが同一のメタ情報は、BMS仕様に先に登録したものが先に格納されます。

        パラメータ:
        includeObject - メタ情報のリストに任意型メタ情報を含むかどうか
        戻り値:
        メタ情報のリスト
      • metas

        public final Stream<BmsMeta> metas()
        メタ情報を走査するストリームを返します。

        走査する順番は設定されたソートキーで決定され、ソートキーの小さいメタ情報が先に登場します。 ソートキーが同一のメタ情報は、BMS仕様に先に登録したものが先に登場します。

        戻り値:
        メタ情報を走査するストリーム
      • getChannel

        public final BmsChannel getChannel​(int number)
        指定されたチャンネル番号のチャンネルを取得します。
        パラメータ:
        number - チャンネル番号
        戻り値:
        チャンネル番号に該当するチャンネル。存在しない場合はnull。
      • containsChannel

        public final boolean containsChannel​(int number)
        指定されたチャンネル番号のチャンネルが存在するかを返します。
        パラメータ:
        number - チャンネル番号
        戻り値:
        チャンネル番号に該当するチャンネルが存在する場合はtrue
      • getChannels

        public final List<BmsChannel> getChannels()
        BMS仕様として定義されたチャンネルのリストを取得します。

        リストへの格納順は、チャンネル番号の若いチャンネルが先になります。

        ユーザーチャンネルはリストには含まれません。

        戻り値:
        チャンネルのリスト
      • getChannels

        public final List<BmsChannel> getChannels​(boolean includeUser)
        BMS仕様として定義されたチャンネルのリストを取得します。

        リストへの格納順は、チャンネル番号の若いチャンネルが先になります。

        パラメータ:
        includeUser - チャンネルのリストにユーザーチャンネルを含むかどうか
        戻り値:
        チャンネルのリスト
      • channels

        public final Stream<BmsChannel> channels()
        チャンネルを走査するストリームを返します。

        チャンネル番号の若いチャンネルが先に登場します。

        戻り値:
        チャンネルを走査するストリーム
      • getInitialBpmMeta

        public final BmsMeta getInitialBpmMeta()
        初期BPMメタ情報を取得します。
        戻り値:
        初期BPMメタ情報
      • getBaseChangerMeta

        public final BmsMeta getBaseChangerMeta()
        基数選択メタ情報を取得します。

        基数選択メタ情報が未設定の場合、nullを返します。

        戻り値:
        基数選択メタ情報、またはnull
      • hasBaseChanger

        public final boolean hasBaseChanger()
        基数選択メタ情報が設定されているかを取得します。
        戻り値:
        基数選択メタ情報が設定されていればtrue
      • getLengthChannel

        public final BmsChannel getLengthChannel()
        小節長変更チャンネルを取得します。

        BMS仕様として小節長変更が未定義の場合、このメソッドはnullを返します。

        戻り値:
        小節長変更チャンネル
      • getBpmChannel

        public final BmsChannel getBpmChannel​(int number)
        BPM変更チャンネルを取得します。

        BMS仕様としてBPM変更チャンネルが未定義の場合、このメソッドはnullを返します。

        パラメータ:
        number - チャンネル番号
        戻り値:
        BPM変更チャンネル。指定したチャンネル番号に該当するBPM変更チャンネルが存在しない場合null
      • getBpmChannel

        public final BmsChannel getBpmChannel​(int number,
                                              boolean byIndex)
        BPM変更チャンネルを取得します。

        当メソッドでは、チャンネル番号またはインデックス値を使用してBPM変更チャンネルを取得できます。 インデックス値に使用可能な最大値はgetBpmChannelCount()-1です。

        インデックス値の指定可能範囲を超過した値を指定しても、例外をスローせずに戻り値でnullを返します。

        パラメータ:
        number - チャンネル番号またはインデックス値
        byIndex - falseの場合チャンネル番号で、trueの場合インデックス値でチャンネルを取得します。
        戻り値:
        BPM変更チャンネル。指定した値に該当するBPM変更チャンネルが存在しない場合null
      • getBpmChannelCount

        public final int getBpmChannelCount()
        BPM変更チャンネルの数を取得します。
        戻り値:
        BPM変更チャンネルの数
      • hasBpmChannel

        public final boolean hasBpmChannel()
        BPM変更チャンネルが存在するかを取得します。
        戻り値:
        BPM変更チャンネルが存在する場合true
      • getStopChannel

        public final BmsChannel getStopChannel​(int number)
        譜面停止チャンネルを取得します。

        BMS仕様として譜面停止チャンネルが未定義の場合、このメソッドはnullを返します。

        パラメータ:
        number - チャンネル番号
        戻り値:
        譜面停止チャンネル。指定したチャンネル番号に該当する譜面停止チャンネルが存在しない場合null
      • getStopChannel

        public final BmsChannel getStopChannel​(int number,
                                               boolean byIndex)
        譜面停止チャンネルを取得します。

        当メソッドでは、チャンネル番号またはインデックス値を使用して譜面停止チャンネルを取得できます。 インデックス値に使用可能な最大値はgetBpmChannelCount()-1です。

        インデックス値の指定可能範囲を超過した値を指定しても、例外をスローせずに戻り値でnullを返します。

        パラメータ:
        number - チャンネル番号またはインデックス値
        byIndex - falseの場合チャンネル番号で、trueの場合インデックス値でチャンネルを取得します。
        戻り値:
        譜面停止チャンネル。指定した値に該当する譜面停止チャンネルが存在しない場合null
      • getStopChannelCount

        public final int getStopChannelCount()
        譜面停止チャンネルの数を取得します。
        戻り値:
        譜面停止チャンネルの数
      • hasStopChannel

        public final boolean hasStopChannel()
        譜面停止チャンネルが存在するかを取得します。
        戻り値:
        譜面停止チャンネルが存在する場合true
      • generateHash

        public final byte[] generateHash()
        BMS仕様の内容からハッシュ値を計算し、結果を返します。

        ハッシュ値の計算に使用する情報ソースは、全ての任意型(BmsType.OBJECT)ではないメタ情報、および 全ての仕様チャンネルです。小節長変更・BPM変更・譜面停止チャンネルの設定や、メタ情報の登録順もハッシュ値を 計算する要素となります。

        上記のように、BMS仕様の作成手順、作成内容の全ての要素がハッシュ値を決定する要素となることから、BMS仕様を生成する データ内容が少しでも変更された場合、別のハッシュ値が返却されることになります。そのため、当メソッドで返却されるハッシュ値は データフォーマットを解析する処理が変更されていないことを確認するためのセキュリティ対策として用いることを想定しています。

        唯一、任意型メタ情報・ユーザーチャンネルについてはどのような内容をどのような順番で登録したとしてもハッシュ値には 影響しません。これは、BMS仕様が変更されなくてもアプリケーションが更新される場合(※)があることを考慮するためです。 (例えばアプリケーションのバグフィックスなどが挙げられます)

        ※任意型メタ情報、ユーザーチャンネルはアプリケーション向けに割り当てられる情報のため、アプリケーション独自の都合で 追加・変更・削除される可能性が高い。

        戻り値:
        BMS仕様から算出されたハッシュ値
      • setStandardCharset

        @Deprecated(since="0.7.0")
        public static void setStandardCharset​(Charset cs)
        推奨されていません。
        当メソッドは非推奨となりました。代わりにBmsLibrary.setDefaultCharsets(Charset...) を使用してください。それにより、ライブラリで扱う文字セットを優先順に複数扱うことができます。
        BMSライブラリが扱う標準文字セットを設定します。

        BMSライブラリでは、デフォルトの文字セットをShift-JISとして設定しています。これはBMSライブラリが主に 日本で使用されることを想定しているためであり、日本国外向けのアプリケーションを開発する場合はこのメソッドを 呼び出して文字セットを変更してください。

        この設定が使用されるのはBMSを読み込み、書き込み時です。

        パラメータ:
        cs - 標準に設定する文字セット
        例外:
        NullPointerException - csがnull
      • getStandardCharset

        @Deprecated(since="0.7.0")
        public static Charset getStandardCharset()
        推奨されていません。
        当メソッドは非推奨となりました。代わりにBmsLibrary.getPrimaryCharset()を使用してください。
        BMSライブラリが扱う標準文字セットを取得します。
        戻り値:
        標準文字セット