Unity JsonUtilityの使い方 | JSONでデータ保存

PlayerPrefsでは、スコア1つや音量設定くらいなら十分です。

一方で、プレイヤー名・レベル・所持アイテムの一覧までまとめて残したいときは、データの形を決めて保存する必要があります。
そのとき役立つのが、Unity標準のJsonUtilityです。

この記事では、[Serializable]属性付きクラスを定義し、ToJsonで文字列化、FromJsonで復元する流れを解説します。
ファイル保存との組み合わせや、配列を扱うときのWrapperクラスも触れます。

JsonUtilityとは何か

JsonUtilityは、Unityに組み込まれているJSONシリアライズ用APIです。
C#のオブジェクトをJSON文字列に変換し、ファイルやPlayerPrefsに書き込めます。
外部ライブラリなしで、個人開発のセーブデータ作成に使えます。

ただし、任意のクラスがそのまま使えるわけではありません。
[System.Serializable]属性を付けたクラス、かつpublicフィールド（または[SerializeField]）が対象です。
制約を理解したうえで設計しましょう。

セーブ用クラスを定義する

まず、保存したいデータの入れ物となるクラスを作ります。

[System.Serializable]
public class PlayerSaveData
{
    public string playerName;
    public int level;
    public int gold;
    public bool tutorialDone;
}

プロパティ（get/setのみ）はシリアライズ対象外です。
フィールドとして宣言するか、[SerializeField]を付けてください。
辞書（Dictionary）も直接は扱えないため、必要なら別のリスト形式に落とし込みます。

ToJsonとFromJsonの基本

オブジェクト→JSONはJsonUtility.ToJson、JSON→オブジェクトはJsonUtility.FromJsonです。

// 保存
PlayerSaveData data = new PlayerSaveData;
data.playerName = "Hero";
data.level = 5;
data.gold = 320;
string json = JsonUtility.ToJson(data, true); // trueで整形出力

// 読み込み
PlayerSaveData loaded = JsonUtility.FromJson<PlayerSaveData>(json);
Debug.Log(loaded.playerName); // Hero

ToJsonの第2引数をtrueにすると、人間が読みやすい改行付きJSONになります。
デバッグ中はtrue、本番のファイル保存はfalseで容量を抑える、という使い分けもできます。

ファイルに保存する最小実装

JSON文字列をApplication.persistentDataPath配下のファイルに書き込む例です。
OSごとに安全な保存場所が自動で決まります。

using System.IO;

public class SaveManager : MonoBehaviour
{
    private string savePath;

    void Awake
    {
        savePath = Path.Combine(Application.persistentDataPath, "save.json");
    }

    public void SaveGame(PlayerSaveData data)
    {
        string json = JsonUtility.ToJson(data);
        File.WriteAllText(savePath, json);
    }

    public PlayerSaveData LoadGame
    {
        if (!File.Exists(savePath))
            return new PlayerSaveData;

        string json = File.ReadAllText(savePath);
        return JsonUtility.FromJson<PlayerSaveData>(json);
    }
}

ゲーム開始時にLoadGame、チェックポイントや終了時にSaveGameを呼ぶ構成が基本です。
ファイルが無い初回は、新しいPlayerSaveDataを返すようにしておきましょう。

PlayerPrefsとの組み合わせ

データ量が小さければ、JSON文字列をPlayerPrefs.SetStringに入れる方法もあります。

string json = JsonUtility.ToJson(data);
PlayerPrefs.SetString("PlayerSave", json);
PlayerPrefs.Save;

// 読み込み
string loadedJson = PlayerPrefs.GetString("PlayerSave", "");
if (!string.IsNullOrEmpty(loadedJson))
{
    data = JsonUtility.FromJson<PlayerSaveData>(loadedJson);
}

PlayerPrefsにはサイズ上限があるため、大きなセーブデータはファイル保存の方が無難です。
設定＋軽い進行データ程度なら、SetStringでも十分なことが多いです。

配列とListの制限・Wrapperで回避

JsonUtilityは、トップレベルの配列やListを直接シリアライズできません。
アイテム一覧を保存したいときは、配列を包むWrapperクラスを用意します。

[System.Serializable]
public class ItemData
{
    public int id;
    public int count;
}

[System.Serializable]
public class ItemListWrapper
{
    public ItemData[] items;
}

// 保存
ItemListWrapper wrapper = new ItemListWrapper;
wrapper.items = itemArray;
string json = JsonUtility.ToJson(wrapper);

// 読み込み
ItemListWrapper loaded = JsonUtility.FromJson<ItemListWrapper>(json);

データ型	JsonUtilityでの扱い
publicフィールドのクラス	[Serializable]を付ければToJson/FromJson可能
クラス内の配列	親クラス経由ならシリアライズできる
トップレベルのList	直接不可。 Wrapperか配列に変換が必要
Dictionary	非対応。 キーと値のリストに分解するなど別設計が必要

よくあるエラーと対処

FromJsonの結果がnullになるときは、JSON文字列が空か、クラス定義とキー名が一致していない可能性があります。
Debug.Log(json)で保存内容を確認し、フィールド名の綴りを見直してください。

「Serialization depth limit」系の警告は、クラス同士が循環参照しているときに出ます。
親子関係を一方向に整理するか、参照ではなくIDだけを保存する設計に変えましょう。

日本語を含むプレイヤー名を保存するときは、ファイルのエンコーディングに注意が必要です。
WriteAllTextはUTF-8がデフォルトですが、環境によってはBOM付きになるため、読み込み側も同じ設定に揃えてください。

本格運用時の選択肢

JsonUtilityは軽量で学習コストが低い反面、柔軟性に限界があります。
ネストが深いJSON、スキーマの厳密な検証、大規模なデータ移行が必要なら、Newtonsoft Json.NETなどのサードパーティライブラリも検討対象です。

個人の学習作品や小規模リリースなら、まずJsonUtilityで「名前・レベル・アイテム数件」を保存できる状態を作るのが現実的です。
必要になったタイミングでライブラリを足せば大丈夫です。

まとめ

JsonUtilityは、[Serializable]クラスをToJsonで文字列化し、FromJsonで復元するUnity標準のJSON保存手段です。
ファイル保存と組み合わせれば、プレイヤーの進行データを構造化して残せます。

配列はWrapperクラスで包み、Dictionaryは別設計が必要——この2点を押さえれば、多くのインディーゲームのセーブ要件に対応できます。
まずは小さなSaveDataクラスから試してみてください。

ゲーム全体のデータ設計を学びたい方は、Unity入門の森の講座も参考になります。
セーブ機能を動かしたら、次はシーン遷移やUIとつなげて完成度を上げていきましょう。