docs/plans/metadata_enumification_analysis.md

metadata.json と Enumification 分析レポート

概要

このレポートでは、data/metadata.json がシステム全体にどのように供給されているか、そして「enumification」（列挙型化）がまだ必要な箇所を特定します。

---

1. metadata.json の構造

セクション	用途	エントリ数
triggers	能力の発動タイミング	11
targets	効果の対象	14
opcodes	バイトコード命令	67
phases	ゲームフェーズ	15
conditions	条件チェック命令	54
costs	コスト種別	95
choices	選択タイプ	28
zones	ゾーン識別	11
extra_constants	ビットマスク定数	76+

---

2. metadata.json のフロー

flowchart TD
    A[data/metadata.json] --> B[tools/sync_metadata.py]
    B --> C[engine_rust_src/src/core/generated_constants.rs]
    B --> D[engine_rust_src/src/core/enums.rs]
    B --> E[frontend/web_ui/js/generated_constants.js]
    B --> F[engine/models/generated_metadata.py]
    B --> G[engine_rust_src/src/core/shader_constants.wgsl]

---

3. 現在のEnumification状態

✅ 既にEnum化されている箇所

ファイル	内容	状態
engine/models/opcodes.py	Opcode enum	✅ generated_metadata.py から自動生成
engine/models/generated_metadata.py	定数辞書 (OPCODES, TRIGGERS, etc.)	✅ 自動生成
engine/models/enums.py	CardType, HeartColor, Area, Group, Unit	✅ 手動管理だが独立
frontend JS	TriggerType, EffectType, ActionBases	✅ generated_constants.js から import

❌ Enumification がまだ必要な箇所

ファイル	クラス	問題点
engine/models/ability.py:27	TriggerType	generated_metadata.py 已有りの重複、手動管理
engine/models/ability.py:42	TargetType	generated_metadata.py 已有りの重複、手動管理
engine/models/ability.py:59	EffectType	generated_metadata.py 已有りの重複、手動管理
engine/models/ability.py:347	AbilityCostType	101+ エントリ、手動管理、generated_metadata.py の COSTS と重複
Rust engine	各種 enum	enums.rs に重複定義の可能性

---

4. 具体的な重複例

4.1 TriggerType の重複

# engine/models/ability.py (手動管理)
class TriggerType(IntEnum):
    NONE = 0
    ON_PLAY = 1
    # ...

# engine/models/generated_metadata.py (自動生成)
TRIGGERS = {
    "NONE": 0,
    "ON_PLAY": 1,
    # ...
}

4.2 AbilityCostType の問題

metadata.json の costs セクションには 95エントリ がありますが、ability.py の AbilityCostType には 101+ エントリ があり、値が重複或多すぎます。

# ability.py からの例
class AbilityCostType(IntEnum):
    NONE = 0
    ENERGY = 1
    TAP_SELF = 2
    # ... 101+ entries
    # 多くは自動生成されたプレースホルダー

---

5. 推奨されるEnumification計画

5.1 短期 (高優先度)

1. ability.py の enum を generated_metadata.py から import

   • TriggerType, TargetType, EffectType を削除
   • from .generated_metadata import TRIGGERS, TARGETS, OPCODES を使用
   • または generated_metadata.py に IntEnum クラスを追加生成

2. AbilityCostType の整理

   • metadata.json の costs と 完全一致させる
   • 余分なエントリを削除
   • または sync_metadata.py を拡張して AbilityCostType enum を自動生成

5.2 中期 (中優先度)

3. Rust engine の enum 統一

   • engine_rust_src/src/core/enums.rs を generated_constants.rs から自動生成
   • 重複定義の排除

4. Frontend JS の enum 統一

   • generated_constants.js に IntEnum 相当のオブジェクトを追加

---

6. 関連ファイル一覧

ファイル	役割
data/metadata.json	マスターデータ
tools/sync_metadata.py	同期スクリプト
engine/models/generated_metadata.py	自動生成の定数
engine/models/ability.py	能力定義 (enum 重複問題)
engine/models/opcodes.py	Opcode enum (OK)
engine/models/enums.py	ゲーム基本enum
engine_rust_src/src/core/generated_constants.rs	Rust定数
frontend/web_ui/js/generated_constants.js	Frontend定数

---

7. 結論

enumification が最も必要な箇所:

1. engine/models/ability.py - TriggerType, TargetType, EffectType, AbilityCostType の4つのenum
2. Rust engine - 手動管理されている enum の自動生成化

現在のシステムは 部分的に enumification されていますが、ability.py には古い手動管理のenumが残っており、これらは generated_metadata.py と重複しています。将来的な一貫性のためには、これらのenumを自動生成システムに統合する必要があります。