Unity におけるアイテム処理と所持データ管理システム

2025年4月9日

1. システム概要

• 目的
  • シーン上に出現するアイテムの表示と出現アニメーションを実現
  • プレイヤーとの衝突時にアイテムを取得し、その所持数を管理・永続化する
• 特徴
  • 同一の Item スクリプトを複数種のアイテムプレハブ（例：Item_Wood、Item_Stone、Item_ThrowAxe）に使い回し、インスペクターで type を設定
  • DOTween を利用した直列化されたアニメーションで、見た目に魅力的な出現演出を実現
  • OwnedItemsData によるシングルトンパターンでのデータ管理と、PlayerPrefs を用いた永続化
• 使用ライブラリ
  • UnityEngine
  • DG.Tweening（DOTween）
  • PlayerPrefs および JsonUtility

2. アイテムクラス（Item.cs）の詳細

2.1 概要

• シーンに配置されたアイテムオブジェクト（例：Wood用プレハブなど）が持つスクリプト
• アイテム出現時のアニメーション（移動＆スケール変更）とプレイヤーとの衝突処理を担当
• [RequireComponent(typeof(Collider))] により、Collider コンポーネントの付与を保証

2.2 コード

using DG.Tweening;
using UnityEngine;

[RequireComponent(typeof(Collider))]
public class Item : MonoBehaviour
{
    /// <summary>
    /// アイテムの種類を列挙
    /// </summary>
    public enum ItemType
    {
        Wood,     // 木
        Stone,    // 石
        ThrowAxe  // 投げオノ（木と石で作る！）
    }

    // インスペクター上で種類を設定 (例: Wood / Stone / ThrowAxe)
    [SerializeField] private ItemType type;

    /// <summary>
    /// 初期化処理
    /// - 出現アニメーションを実行
    /// - アニメーション完了まではColliderを無効化
    /// </summary>
    public void Initialize()
    {
        Collider colliderCache = GetComponent<Collider>();
        colliderCache.enabled = false;

        // 出現位置をランダムにずらす
        Transform transformCache = transform;
        Vector3 dropPosition = transformCache.localPosition +
                               new Vector3(Random.Range(-1f, 1f), 0f, Random.Range(-1f, 1f));

        // DOTweenのSequenceで移動とスケールを連続アニメーション
        Sequence sequence = DOTween.Sequence();

        // 移動: 0.5秒かけてランダム座標へ
        sequence.Append(transformCache.DOLocalMove(dropPosition, 0.5f));

        // スケール: ゼロから元の大きさへ (Ease.OutBounceで弾むような演出)
        Vector3 defaultScale = transformCache.localScale;
        transformCache.localScale = Vector3.zero;
        sequence.Append(transformCache.DOScale(defaultScale, 0.5f).SetEase(Ease.OutBounce));

        // アニメーション完了後にColliderを有効化
        sequence.OnComplete(() =>
        {
            colliderCache.enabled = true;
        });
    }

    /// <summary>
    /// プレイヤーとの衝突判定
    /// </summary>
    /// <param name="other">衝突したCollider</param>
    private void OnTriggerEnter(Collider other)
    {
        // タグが"Player"でないなら処理しない
        if (!other.CompareTag("Player")) return;

        // アイテムをプレイヤーの所持データに加算して保存
        OwnedItemsData.Instance.Add(type);
        OwnedItemsData.Instance.Save();

        // 現在の所持アイテムをログ出力
        foreach (var item in OwnedItemsData.Instance.OwnedItems)
        {
            Debug.Log($"{item.Type}を{item.Number}個所持");
        }

        // このゲームオブジェクト(アイテム)を破棄
        Destroy(gameObject);
    }
}

public class Item : MonoBehaviour
{
    /// <summary>
    /// アイテムの種類を列挙（Item専用）
    /// </summary>
    public enum ItemType
    {
        Wood,     // 木
        Stone,    // 石
        ThrowAxe  // 投げオノ（木と石で作る！）
    }

    [SerializeField] private ItemType type;
    // 残りのコードは Item クラス内で利用
}

// Item クラス内や、Item クラスに強く関連する処理で利用
Item.ItemType currentType = Item.ItemType.Wood;

/// <summary>
/// アイテムの種類を列挙（グローバルに利用）
/// </summary>
public enum ItemType
{
    Wood,     // 木
    Stone,    // 石
    ThrowAxe  // 投げオノ（木と石で作る！）
}

using UnityEngine;

[RequireComponent(typeof(Collider))]
public class Item : MonoBehaviour
{
    [SerializeField] private ItemType type;
    // 残りのコードは Item クラス内で利用
}

// プロジェクト内のどこからでも単に ItemType として利用できる
ItemType someType = ItemType.Stone;

2.3 注意点

• Initialize() の呼び出しタイミング
  • プレハブを Instantiate した直後や、シーン配置時に Start()/Awake() で呼び出すと、アニメーション演出が適用されます。
• アイテムの種類設定
  • 各プレハブ（例：Item_Wood）にはインスペクターで type プロパティを設定し、適切なアイテム（例：Wood）として扱います。

3. 所持アイテムデータ管理クラス（OwnedItemsData.cs）の詳細

3.1 概要

• シングルトンパターンを用いて、ゲーム全体の所持アイテムデータを一元管理
• PlayerPrefs を利用したセーブ／ロードによって、ゲーム終了後もデータが保持される

3.2 コード

using System;
using System.Linq;
using System.Collections.Generic;
using UnityEngine;

[Serializable]
public class OwnedItemsData
{
    /// <summary>
    /// PlayerPrefsに保存する際のキー
    /// </summary>
    private const string PlayerPrefsKey = "OWNED_ITEMS_DATA";

    // シングルトンインスタンス
    private static OwnedItemsData _instance;

    /// <summary>
    /// OwnedItemsDataのインスタンス
    /// </summary>
    public static OwnedItemsData Instance
    {
        get
        {
            if (_instance == null)
            {
                // 保存済みデータがあれば読み込む
                if (PlayerPrefs.HasKey(PlayerPrefsKey))
                {
                    _instance = JsonUtility.FromJson<OwnedItemsData>(PlayerPrefs.GetString(PlayerPrefsKey));
                }
                else
                {
                    _instance = new OwnedItemsData();
                }
            }
            return _instance;
        }
    }

    /// <summary>
    /// 現在所持しているアイテムの配列
    /// </summary>
    public OwnedItem[] OwnedItems => ownedItems.ToArray();

    /// <summary>
    /// アイテムの所持データリスト
    /// </summary>
    [SerializeField] private List<OwnedItem> ownedItems = new List<OwnedItem>();

    /// <summary>
    /// コンストラクタは外部から new できないように private
    /// </summary>
    private OwnedItemsData() { }

    /// <summary>
    /// 現在の所持データをPlayerPrefsにセーブ
    /// </summary>
    public void Save()
    {
        string jsonString = JsonUtility.ToJson(this);
        PlayerPrefs.SetString(PlayerPrefsKey, jsonString);
        PlayerPrefs.Save();
    }

    /// <summary>
    /// （任意）データをロードするメソッド 
    /// シーン初期化時に呼び出すなどの用途に
    /// </summary>
    public static void Load()
    {
        if (PlayerPrefs.HasKey(PlayerPrefsKey))
        {
            _instance = JsonUtility.FromJson<OwnedItemsData>(PlayerPrefs.GetString(PlayerPrefsKey));
        }
        else
        {
            _instance = new OwnedItemsData();
        }
    }

    /// <summary>
    /// アイテムを追加する
    /// </summary>
    /// <param name="type">アイテムの種類</param>
    /// <param name="number">追加個数（デフォルトは1）</param>
    public void Add(Item.ItemType type, int number = 1)
    {
        var item = GetItem(type);
        // 該当データがなければ新規リストに追加
        if (item == null)
        {
            item = new OwnedItem(type);
            ownedItems.Add(item);
        }
        item.Add(number);
    }

    /// <summary>
    /// アイテムを消費する
    /// </summary>
    /// <param name="type">消費するアイテムの種類</param>
    /// <param name="number">使用する個数（デフォルト1）</param>
    /// <exception cref="Exception">所持数不足の場合に例外をスローする</exception>
    public void Use(Item.ItemType type, int number = 1)
    {
        var item = GetItem(type);
        if (item == null || item.Number < number)
        {
            throw new Exception("アイテムが足りません");
        }
        item.Use(number);
    }

    /// <summary>
    /// 指定のアイテム種類のデータを取得する
    /// </summary>
    /// <param name="type">アイテムの種類</param>
    /// <returns>該当の OwnedItem、存在しなければ null</returns>
    public OwnedItem GetItem(Item.ItemType type)
    {
        return ownedItems.FirstOrDefault(x => x.Type == type);
    }

    /// <summary>
    /// アイテム所持数管理用のモデル
    /// </summary>
    [Serializable]
    public class OwnedItem
    {
        [SerializeField] private Item.ItemType type;
        [SerializeField] private int number;

        /// <summary>
        /// アイテムの種類（読み取り専用）
        /// </summary>
        public Item.ItemType Type => type;

        /// <summary>
        /// 現在の所持数（読み取り専用）
        /// </summary>
        public int Number => number;

        public OwnedItem(Item.ItemType type)
        {
            this.type = type;
            this.number = 0;
        }

        /// <summary>
        /// 指定数だけ所持数を追加する
        /// </summary>
        public void Add(int number = 1)
        {
            this.number += number;
        }

        /// <summary>
        /// 指定数だけ所持数を消費する
        /// </summary>
        public void Use(int number = 1)
        {
            this.number -= number;
        }
    }
}

3.3 ポイント

• シーン開始時や必要なタイミングで Load() を呼び出すと、前回の所持情報を復元可能
• アイテム取得後に必ず Save() を呼ぶことで、最新データが PlayerPrefs に書き込まれ、ゲーム終了後も情報が維持されます

4. リファクタリングのポイント

今回のリファクタリングでは、主に以下の点に注目しています

1. DOTween Sequence の活用によるアニメーションの連結
   • 複数のアニメーション（移動とスケール）の実行順序を明示し、分かりやすいフローを実現
   • 連結した処理の終了タイミングで Collider の有効化を統一的に行うことで、コードの信頼性向上
2. シングルトンパターンの明確化
   • OwnedItemsData.Instance を通して、ゲーム全体で一つのデータ管理インスタンスを利用
   • 初期化やロード処理を明示的に分離し、後からのテストや拡張が容易に
3. データの保存／取得処理の整理
   • PlayerPrefs を使用した JSON 化／デシリアライズ処理をクラス内にカプセル化
   • アイテム追加、消費時のエラーチェックをシンプルに記述し、例外発生条件を明示
4. 再利用性と拡張性の向上
   • 同一の Item スクリプトをプレハブごとに使い回す設計により、インスペクター上での設定変更のみで動作を制御可能
   • 将来的な内部データ構造の改善（例：Dictionary への変更）も視野に入れる設計

5. 運用イメージ

1. プレハブ作成
   • 例: 「Wood」用のモデルやスプライトを使い、Item_Wood プレハブを作成
   • 各プレハブに Item スクリプトをアタッチし、インスペクター上で type を適切に設定（例：Wood、Stone、ThrowAxe）
2. シーン配置 / 生成
   • エディタ上で直接配置する場合、または Instantiate 後に GetComponent<Item>().Initialize() を呼び出す
   • これにより、出現時のアニメーションが実行され、プレイヤーが取得可能な状態となる
3. プレイヤーとの衝突
   • プレイヤーがアイテムに衝突すると OnTriggerEnter が発動し、アイテムが所持データに追加・保存される
4. データ活用
   • UI 表示やクラフトシステムなど、他のシステムから OwnedItemsData.Instance 経由で所持情報を参照可能

6. まとめ

• 同一の Item スクリプトを複数のアイテムプレハブに使い回す設計により、各アイテムがインスペクター上の設定で柔軟に管理できる
• DOTween Sequence によるアニメーション連結で、出現演出と Collider 制御を直感的かつ信頼性高く実現
• OwnedItemsData によるシングルトンでの所持データ管理と PlayerPrefs を用いた永続化により、ゲーム終了後もデータが維持される
• リファクタリングの各ポイントを押さえることで、今後の保守性・拡張性が向上し、UI や新たなゲームロジックへの対応が容易になる

以上が、リファクタリングのポイントを含めた「Unity におけるアイテム処理と所持データ管理システム」の資料およびコード全体になります。
この内容をもとに、各アイテムプレハブの設定や追加機能の実装を進めていただければと思います。