JSONファイル

本頁內容尚未翻譯。

このページでは、RealTrainMod（RTM）のアドオン制作に使用するJSONファイルの種類と用途、そしてJSONの文法について説明します。

JSONとは

JSONは、JavaScript Object Notationの略で、テキストベースのデータ記述言語です。
わかりやすく言えば、人間と機械の両方が読み書きしやすい辞書形式のメモ書きのようなものです。

仕様を遵守したJSONは、人間やコンピュータが必ず同じ解釈をできるため、完全に正確にデータを伝え合うことができます。
このため、コンピュータやインターネットのさまざまな場面でデータのやり取りや保存に利用されています。

JSONファイルの用途

RTMでは、以下の3つの用途でJSONファイルを使用します。

モデル設定用
列車やレールなどの複雑な設定が必要なモデルの追加には必ず必要になる。
最も使用頻度が多い。
音声イベント設定用
加速や減速などの操作で発火する音声イベントと、実際の音声ファイルを結びつける役割がある。
RTMに限らずMinecraft全体で利用されており、そのファイル名からsounds.jsonとも呼ばれる。
アップデート通知設定用
アドオンの更新をユーザーに通知するために使用する。
検証されたアップデート情報は、プレイヤーがワールドにログインした際に通知される。

各JSONファイルでの具体的な設定方法については、以下のそれぞれの解説ページを参照してください。

RTMのJSONファイルのルール

RTMでは、JSONファイルについて独自のルールがあります。
これは、RTMが開発された当初は現在のJSON標準であるRFC8259が発表されていなかったためです。

文字エンコーディングは、基本的にUTF-8のBOMなし（UTF-8Nとも）を使用する
BOMつきのUTF-8は正常に解釈されない場合があり、エラーを発生させる可能性があるため、使用できません。
（必要に応じてShift-JISを使用することもあります。）
定義されていないキーがあってもよい（本来不要なキーを追加してもエラーにならない）

JSONの文法

JSONは「オブジェクト」と「配列」でデータを記述します。

1. オブジェクト

オブジェクトは、「名前（キー）」と「値（バリュー）」のペアを持つデータのまとまりです。
キーと値は:（コロン）で区切り、各ペアは,カンマで区切ります。
そして、1つまたは複数のペアを{ }（波括弧）でまとめたものが、「オブジェクト」です。

{
  "name": "Diamond Pickaxe",
  "enchantments": ["silk-touch", "mending"],
  "durability": 1239,
  "isHolding": true
}

この例において、コロンの左側にある"name"や、"enchantments"などが「キー」です。
キーは"（ダブルクォーテーション）で囲む必要があります。

コロンの右側にある"Diamond Pickaxe"や、["silk-touch", "mending"]などが「値」です。
「値」には、様々な種類（データ型）があり、後述します。

2. 配列

配列は、複数の「値」を順番に並べたデータのリストです。
「値」と「値」の間は,カンマで区切り、複数の値を[ ]（角括弧）でまとめたものが、「配列」です。

[
  "Stone Block",
  "Diamond Pickaxe",
  "Iron Ingot"
]

この例において、"Stone Block"や、"Diamond Pickaxe"などが「値」です。
オブジェクトと同様に、「値」には様々なデータ型を使用することができます。

オブジェクトと配列の違い

オブジェクトは、どのようなものでも一つにまとめられるのに対し、配列は同種、同質のものをまとめることが多いです。
例えば、上記のオブジェクトの例では、"name"や"enchantments"など、全く異なる種類の情報を一つにまとめていますが、配列の例では、すべてが「アイテム名」という同じ種類の情報をまとめています。

データ型

JSONには、値の種類を示す「データ型」があります。

文字列（string）
文字列は、"（ダブルクォーテーション）で囲まれたいくつかの文字です。
例えば、"Minecraft"や、"Hello, World!"などがあります。
数値（number）
整数は、数値のデータとしてとして扱われる文字です。
例えば、100や、3.14、-42などがあります。
真偽値（boolean）
真偽値は、true（真）またはfalse（偽）のいずれかです。
ある物事がそうであるか、そうでないかということを示すもので、平たく言えばマル（trueに対応）やバツ（falseに対応）というようなものです。
オブジェクト（Object）
オブジェクトは、「名前（キー）」と「値（バリュー）」のペアを持つデータのまとまりです。
先ほど説明したJSONの構造である「オブジェクト」も、データ型の一つです。
配列（Array）
配列は、複数の「値」を順番に並べたデータのリストです。
先ほど説明したJSONの構造である「配列」も、データ型の一つです。
null
nullは、値が存在しないことを示します。

データの組み合わせ

これらのデータを組み合わせることで、様々な情報を表現することができます。

例えば、以下の例ではそれぞれのデータ型を組み合わせて、プレイヤーの情報を表現しています。

{
  "name": "Steve",
  "health": 20,
  "items": [
    {
      "name": "Stone Block",
      "qty": 64
    },
    {
      "name": "Diamond Pickaxe",
      "enchantments": ["silk-touch", "mending"],
      "durability": 1239,
      "isHolding": true
    }
  ],
  "position": {
    "x": 2147483647,
    "y": 320,
    "z": 29999872
  },
  "isOnline": true
}

この例で分かるように、大きな構造として「オブジェクト」や「配列」などを持ちます。
そして、その中のより小さな構造として「名前と値のペア」や、「ペアの値としてのオブジェクトや配列」などを組み合わせることで、複雑なデータ構造を表現します。