godot-mechanic-secrets

決定木 — どのシークレットトリガーを選ぶか？

プレイヤーの操作／設計目標	選択するもの	必須スクリプト
正確なボタンの組み合わせ／コナミコマンド	時間制限付き入力シーケンス	secret_sequence_combo_matcher.gd（従来のマッピングには secret_konami_legacy_code.gd も使用）
小道具を連打／N 回クリック	連打のしきい値	secret_interaction_spam_tracker.gd
壁に向く／特定の場所を見る	ドット積による注視判定（レイキャストの連打ではありません）	secret_visibility_detector.gd
コンテンツの X％をクリア／トゥルーエンド	進行率によるアンロック	secret_progress_threshold_unlocker.gd
レアな商人／幽霊との遭遇	重み付けされたランダムエンカウント	secret_random_encounter_spawner.gd
セーブスロット間でアンロック状態を保持	メタ secrets.cfg	secret_meta_persistence.gd
マクロによる総当たりを防止	ロックアウトガード	secret_lockout_cheat_guard.gd
P2P でシークレットがステータス／アイテムを付与する	サーバー／ピア検証	godot-adapt-single-to-multiplayer — 戦闘／経済上の優位性を適用する前に、アンロックを検証してください

上の表で対応できない場合を除き、カスタム検出器を新たに作成しないでください。

コアコンポーネント

secret_meta_persistence.gd

すべてのセーブプロフィール間で、グローバルなアンロック状態と発見フラグを保存するための高度なロジックです。

secret_visibility_detector.gd

最適化されたドット積計算を使用し、視点に応じて隠し壁を検出します。

secret_sequence_combo_matcher.gd

コンボには必須 — サフィックス／時間枠で照合する時間制限付き入力バッファーです（バッファー全体の一致判定ではありません）。

secret_interaction_spam_tracker.gd

プレイヤーの反復操作を追跡し、好奇心を刺激するイースターエッグを発動するロジックです。

secret_audio_environment_occluder.gd

密閉エリアや隠しエリアで AudioBus エフェクトを動的に調整するための空間ロジックです。

secret_progress_threshold_unlocker.gd

メタコンテンツや「トゥルーエンド」のトリガーを、進行率に基づいてアンロックします。

secret_random_encounter_spawner.gd

最上位のレア度を持つエンティティや、秘密の商人との遭遇に使用する重み付けランダムシステムです。

secret_lockout_cheat_guard.gd

シークレットの完全性を保護する、総当たり防止用のロックアウトマネージャーです。

secret_vfx_discovery_glimmer.gd

隠されたインタラクト可能オブジェクトのヒントとなる、控えめなプロシージャル視覚効果です。

secret_konami_legacy_code.gd

バッファーマッチャーを使用した、象徴的なコナミコマンドの専用実装です。

secret_persistence_handler.gd / input_sequence_watcher.gd / interaction_threshold_trigger.gd

非推奨 — secret_* スクリプトに置き換えられた従来のヘルパーです。新しいシーンでは使用せず、secret_sequence_combo_matcher.gd、secret_interaction_spam_tracker.gd、secret_meta_persistence.gd に移行してください。

使用例（チートコード）

# Attach SecretSequenceComboMatcher (class_name) as a child of GameManager / Player
@onready var combo: SecretSequenceComboMatcher = $SecretSequenceComboMatcher

func _ready() -> void:
    # Default sequences Dictionary already includes "Konami"; override or add:
    combo.sequences = {
        "GodMode": ["ui_up", "ui_up", "ui_down", "ui_down", "ui_left", "ui_right", "ui_left", "ui_right"]
    }
    combo.combo_achieved.connect(_on_cheat_unlocked)

func _on_cheat_unlocked(combo_name: String) -> void:
    print("Unlocked: ", combo_name)
    # Meta flag — NOT the per-slot SaveManager payload
    SecretMetaPersistence.unlock_secret("god_mode")  # via secret_meta_persistence.gd API

絶対にしてはいけないこと（シークレットに関する専門ルール）

検出とトリガー

• _process 内に入力チェックを絶対にハードコードしないでください — フレーム依存のポーリングは、素早いコンボの検出に適していません。必ず secret_sequence_combo_matcher.gd のようなイベントベースのバッファーを使用してください。
• 「LookingAt」シークレットに複雑なレイキャストを絶対に使用しないでください — すべての壁でチェックすると、物理レイキャストは高コストになります。処理効率を高めるため、secret_visibility_detector.gd の内積方式を使用してください。
• 「Hidden Walls」を本物の壁と同一に絶対にしないでください — プレイヤーが気づけるよう、さりげない「きらめき」やテクスチャの違いが必要です。完全に見えない状態は、プレイヤーにとってシークレットではなくバグです。

永続化とメタデータ

• 「発見済みのシークレット」をメインのセーブスロットに絶対に保存しないでください — 別のビルドを試すためにセーブデータを削除しても、メタ進行状況（ギャラリー、実績フラグ）は保持されるべきです。secret_meta_persistence.gd を使用してください。
• ピアツーピアで、クライアント側のチート検証を絶対に信用しないでください — シークレットでステータスが強化される場合、簡単なメモリ改ざんによるチートを防ぐため、ほかのピアが「Unlock」を検証する必要があります。
• シークレットに PlayerPrefs（Godot における設定の同等機能）を絶対に使用しないでください — 専用の user://secrets.cfg を使用してください。

UX と総当たり攻撃対策

• チートの試行を短時間に無制限で繰り返せる状態に絶対にしないでください — 単純なマクロでも、4 ボタンのコンボを数秒で総当たりできます。secret_lockout_cheat_guard.gd を使用して、失敗が続いた場合にペナルティを設けてください。
• 「あっ！」という気づきを促す音声・視覚効果なしに、シークレットを絶対に発動させないでください — シークレットを発見する報酬は、発見したときの喜びです。secret_audio_environment_occluder.gd を使用して、雰囲気を変えてください。

ベストプラクティス

1. イベントベースのコンボ検出 - _process でのポーリングを避けます。
2. さりげない手がかり - シークレットは完全に見えない状態ではなく、ヒントを示す必要があります。
3. グローバルな永続化 - メタ進行状況には別のセーブファイルを使用します。

---

上級メタパターン（ギャラリー／ロア／ゴースト表示）

実績ギャラリー、ロアジャーナル、またはゴースト表示されるシークレットの可視性を構築する場合は、必ず secrets-meta-patterns.md を読んでください。基本的なコンボ／連続入力／視線トリガーでは読み込まないでください — 上記の決定木スクリプトを使用してください。

リファレンス

段階的な情報開示：特定の API を調査するときにのみ公式ドキュメントへのリンクを開き、関連分野に誘導するときにのみ関連スキルを読み込んでください — スキル全体を事前に読み込まないでください。

公式ドキュメント

• InputEvent の使用 — イベントパイプライン（_input / _unhandled_input）、is_action_pressed、チート用バッファのためのエコーイベントのフィルタリング。
• 入力の例 — _process でポーリングせずに複数ステップのシーケンスを実現する、実用的な InputMap アクションのパターン。
• コントローラー、ゲームパッド、ジョイスティック — クラシックなコナミコマンド風のコードを、パッドの十字キー／フェイスボタンに一貫したアクション名で割り当てます。
• InputMap — シーケンス照合で使用する実行時のアクション列挙（get_actions / event.is_action_pressed）。
• ゲームの保存 — 基本となる保存の流れです。メタアンロックはスロットごとの保存グループに含めないでください。
• Godot のファイルパス — プラットフォームごとの user://secrets.cfg / user://meta_secrets.cfg の配置。
• ConfigFile — Settings や SaveManager のメインペイロードとは別に、INI スタイルで専用のシークレットフラグを管理します。
• リソース — SecretData リソースのパターン、emit_changed、実績との連携。
• ベクトル演算 — フレームごとのレイキャストを使わず、内積で隠し壁を注視しているか検出します。
• 乱数生成 — シークレットベンダーの重み付きレア遭遇抽選と天井タイマー。
• オーディオバス — 封鎖されたシークレットエリアに入る際のバスエフェクト／遮音。
• シングルトン（Autoload） — シーン変更をまたいで SecretPersistence／メタアンロックマネージャーを保持します。

関連スキル

前提条件

• godot-input-handling — チートシーケンスの監視機能がゲームプレイの入力処理と共有する必要のある、アクションバッファ、エコーイベントのフィルタリング、InputMap の再マッピング。
• godot-signal-architecture — UI、オーディオ、実績が検出機能に直接依存せずに反応できるようにする、sequence_matched / secret_spam_triggered バス。
• godot-autoload-architecture — SecretPersistence とメタアンロックの Autoload に必要な起動順序と、シーン変更後も状態を維持するルール。

補完

• godot-save-load-systems — ギャラリー／メタフラグは user://meta_secrets.cfg に保持し、プレイ進行状況はバージョン管理されたセーブスロットに保存します。
• godot-resource-data-patterns — 実績やジャーナルとの連携には、emit_changed を備えた型付きの SecretData ／ロアのリソースを使用します。
• godot-audio-systems — 密閉された部屋での遮音や、発見時の「なるほど！」という合図に、バスエフェクトと短い効果音を使用します。
• godot-ui-rich-text — 発見した秘密の説明を追加する、BBCode形式のロアジャーナルです。
• godot-tweening — Glimmerのエネルギーパルスや、秘密をゴースト状にフェードさせるトゥイーンにより、AnimationPlayerのオーバーヘッドを避けます。
• godot-particles — 秘密のネタバレをせずに操作可能なオブジェクトの存在を示唆する、任意のきらめき／ほこりのレイヤーです。
• godot-shaders-basics — 見つめたときの表示遷移に使う、控えめな壁のきらめき／溶解マテリアルです。

下流／利用側

• godot-quest-system — 発見フラグをクエストの段階、ジャーナル、真のエンディングの条件に反映します。
• godot-monte-carlo-balancer — リリース前に、レア遭遇の重み付け、スパムのしきい値、達成率によるアンロック確率をシミュレーションします。
• godot-adapt-single-to-multiplayer — 秘密によって戦闘や経済面での優位性が得られる場合の、サーバー／ピアによる検証です。
• godot-theme-easter — 同じアンロックと合図のパイプラインを利用する、季節やテーマに合わせたイースターコンテンツです。

マスター

• godot-master — ライブラリのルーターおよびミラー化されたモジュールのエントリです。秘密と入力、セーブ、オーディオのどのドメインスキルが担当するかを確認するときに開きます。