godot-rpg-stats

利用可能なスクリプト

シナリオに応じて必ず実施してください。実装前にお読みください。

• テンプレート／基本属性 → base_stats_resource.gd
• 実行時スタック＋リアクティブな再計算 → stats_component_reactive.gd ＋ stat_modifier_stacking.gd
• バフ／デバフのデータ → status_effect_data.gd（Type.ADDITIVE／MULTIPLICATIVE／OVERRIDE）
• 戦闘計算 → damage_formula_handler.gd

base_stats_resource.gd

基本属性（Str、Dex、Int）と派生スケーリングルールの中核となるデータコンテナです。

status_effect_data.gd

StatusEffectData.Type { ADDITIVE, MULTIPLICATIVE, OVERRIDE } を使用した、シリアライズ可能なバフ／デバフの定義です。

stats_component_reactive.gd

アクティブなモディファイアのスタック処理を備えた、JIT（Just-In-Time）ステータス計算のオーケストレーターです。

exp_progression_resource.gd

成長係数と基本XPを使用した、データ駆動型のレベルアップ曲線の定義です。

dynamic_stat_label_sync.gd

ポーリングを行わずにステータスの変更をLabelに同期する、リアクティブなUIフックです。

damage_formula_handler.gd

複雑な戦闘計算とダメージ計算を集約した、RefCountedユーティリティです。

stat_modifier_stacking.gd

固有バフとスタック可能なバフの処理、および持続時間の更新を行うロジックです。

resource_stat_inheritance.gd

基本ステータスを属性耐性などの特殊な属性で拡張するパターンです。

persistent_character_stats.gd

キャラクターの成長データを.tresファイルにシリアライズする処理を管理します。

level_up_system.gd

経験値の付与とレベルアップ時の恩恵の発動を行うロジックです。

rpg_stat_resource.gd

セッターで値をクランプし、stat_changedシグナルを備えた、上限付きの基本ステータスResourceです。

derived_stat_resource.gd

基本ステータスの依存関係が変化したときに再計算される派生ステータスです。

equipment_tooltip_helper.gd

装備のBBCode比較ツールチップ（_make_custom_tooltip）です。

RPG Statsで絶対にしてはいけないこと

• パーセンテージに整数を絶対に使わないでください — 切り捨てを避けるため、常にfloat（0.0～1.0または0.0～100.0）を使用してください。
• シグナルを発行せずにcurrent_healthを絶対に変更しないでください — 通知がなければUIとの同期がずれます。
• 加算モディファイアだけに絶対に頼らないでください — 長期的な成長には、乗算またはハイブリッドのスケーリングを使用してください。
• 固有のIDまたはKeyなしでモディファイアを絶対に追加しないでください — 特定の効果を削除するために必要です。
• 成長上限のない指数関数的なXP式を絶対に使用しないでください — 上限のないpow()はオーバーフローやレベル進行の停止を引き起こします。
• 派生値のクランプを絶対に忘れないでください — 生命力が負の値でも最大HPが負にならないようにします（maxi(val, 1)）。
• _process()内で負荷の高いステータス再計算を絶対に行わないでください — モディファイアまたは基本ステータスの変更時のみ再計算してください（リアクティブ）。
• ロジック内でステータス名を絶対にハードコードしないでください — StringNamesまたはenumを使用してください。
• 一時的な実行時バフを永続保存用のResourceに絶対に保存しないでください — シリアライズ前に短時間のモディファイアを取り除いてください。
• Characterスクリプト内でダメージを絶対に直接計算しないでください — damage_formula_handler.gdに集約してください。
• 例でDictionary限定のモディファイアAPIを絶対に新設しないでください — StatusEffectData.Typeおよびスタック処理スクリプトに合わせてください。

---

決定木

レイヤー	責務	スクリプト
リソーステンプレート	デザイナーが定義する基本属性、曲線、継承	base_stats_resource.gd、exp_progression_resource.gd、resource_stat_inheritance.gd
ランタイムのStatsComponent	テンプレートを複製・インスタンス化し、修飾子を適用・削除し、シグナルを発行し、派生ステータスをJIT計算します	必須 stats_component_reactive.gd + stat_modifier_stacking.gd
StatusEffectData	型付きバフ行（ADDITIVE / MULTIPLICATIVE / OVERRIDE）	status_effect_data.gd
DamageFormula（RefCounted）	Player/NPCで共有する純粋な戦闘計算	必須 damage_formula_handler.gd
永続化	進行状況を保存します。まずランタイムバフを取り除きます	persistent_character_stats.gd
UI同期	ラベルはシグナルを監視します。ポーリングは不要です	dynamic_stat_label_sync.gd

初歩的なclass_name StatsやDictionaryを使った装備チュートリアルは貼り付けないでください。上記のスクリプトを参照してください。

---

APIの整合性（StatusEffectData）

# Author buffs as Resources — not ad-hoc Dictionary modifiers
var haste := StatusEffectData.new()
haste.name = "Haste"
haste.type = StatusEffectData.Type.MULTIPLICATIVE
haste.attribute = "speed"
haste.value = 1.25
haste.duration = 8.0

var flat_str := StatusEffectData.new()
flat_str.type = StatusEffectData.Type.ADDITIVE
flat_str.attribute = "strength"
flat_str.value = 5.0

var break_def := StatusEffectData.new()
break_def.type = StatusEffectData.Type.OVERRIDE
break_def.attribute = "defense"
break_def.value = 0.0

スタック／更新／ユニークとスタック可能の挙動には、必須のstat_modifier_stacking.gdを使用します。派生ステータスが変更ごとに1回だけ再計算されるよう、stats_component_reactive.gdを通して適用してください。

---

エリート向けの注意点（スクリプトに基づく）

1. 上限 — rpg_stat_resource.gd。セッターでクランプし、属性のオーバーフローは決して許可しないでください。
2. 依存関係グラフ — derived_stat_resource.gd。基礎値が変化したとき、派生ステータスはシグナルを通じて再計算します。_processは決して使用しないでください。
3. 装備 — スタックAPIを通じて、装備時／解除時に修飾子IDを登録・削除します。ツールチップにはequipment_tooltip_helper.gdを使用します。

詳細（必要に応じて読み込み）

装備フック、ダメージ計算式、スキルゲート、エリート向けの上限／派生／ツールチップのパターンについては、references/elite-stat-patterns.mdを参照してください。

リファレンス

段階的な情報開示：特定のAPIを調査するときに限り、公式ドキュメントへのリンクを開いてください。関連する別ドメインへ案内するときは、関連スキルを読み込んでください。依存関係の全体を事前に読み込まないでください。

公式ドキュメント

• リソース — 基本ステータス、曲線、状態効果を、キャラクターごとに複製またはインスタンス化する Resource テンプレートに保持する理由を説明します。
• Resource — duplicate()、resource_local_to_scene、共有と個別のセマンティクスについて説明し、すべての敵が同じ HP Resource を共有してしまうのを防ぎます。
• GDScript のエクスポートプロパティ — @export / @export_group を使うことで、コードを変更せずにデザイナーがインスペクターで属性やスケーリングを調整できます。
• シグナルの使用 — stat_changed / stats_recalculated を使うことで、_process によるポーリングを行わずに UI や派生ステータスを更新できます。
• ゲームの保存 — 進行状況の Resource をシリアライズし、書き込み前に実行時のみのバフを取り除きます。
• Godot プロジェクトのファイルパス — キャラクターの永続的な .tres セーブデータにおける user:// と res:// の違いを説明します。
• ResourceSaver — レベルアップ後にキャラクターステータスの Resource をディスクに書き込みます。
• ResourceLoader — 起動時に進行状況を復元する際の exists / パスの読み込みについて説明します。
• RefCounted — ダメージ計算式や純粋な戦闘計算をシーンツリーから切り離します。
• 乱数生成 — バランステストで再現性を保てる、シード付きのクリティカルヒット／ばらつきのロールについて説明します。
• Label — シグナル駆動の属性更新にテキストをバインドし、HUD を同期します。
• SceneTree — エフェクトごとに Node を用意せず、時間制限付きバフの期限切れに create_timer を使います。

関連スキル

前提条件

• godot-project-foundations — CharacterStats アセットを作成する前に、シーンツリー、Resource、プロジェクトの構成を学びます。
• godot-gdscript-mastery — リアクティブなステータスコンポーネントで使用する、型付きゲッター、セッター、シグナル接続について学びます。
• godot-resource-data-patterns — 属性データの継承、.tres テンプレート、コンポジションのパターンについて学びます。
• godot-signal-architecture — hp_changed / level_up によって UI の循環依存が生じないよう、所有権と配信のルールを学びます。

補完

• godot-ability-system — レベルや属性を条件とし、一時的な修正値を適用するアビリティです。
• godot-inventory-system — 装備時と解除時に修正値 ID を登録・削除する装備ボーナスです。
• godot-combat-system — このスタックの攻撃力、防御力、クリティカル値を使用して命中判定を解決します。
• godot-save-load-systems — 進行データの ResourceSaver を中心とした完全なセーブ処理パイプラインです。
• godot-ui-containers — 再計算されたステータスを監視するキャラクターシートとツールチップです。
• godot-economy-system — レベル曲線や装備のステータス予算と連動するゴールド／XP の消費要素です。
• godot-monte-carlo-balancer — リリース前に、パワー曲線、修正値のスタック、ダメージのばらつきをマトリックステストします。

下流／利用側

• godot-genre-action-rpg — 属性、装備の修正値、派生する戦闘ステータスに依存する ARPG ビルドです。
• godot-genre-roguelike — ランごとにリセットされる、ラン単位の修正値とスケーリングです。
• godot-turn-system — 共通のステータスからダメージ計算式を用いてダメージを解決するターン制戦闘です。

マスター

• godot-master — スキル間の探索に使うライブラリルーター兼、ミラーされたモジュールエントリです。