godot-mechanic-secrets

决策树 — 选择哪种秘密触发方式？

玩家操作 / 设计目标	选择	必须使用的脚本
精确按键组合 / Konami	限时输入序列	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
在不同存档槽间保留解锁状态	Meta 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

使用缓冲区匹配器实现经典 Konami 代码的专用脚本。

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。
• 绝不为“注视目标”类秘密使用复杂的射线检测——如果每面墙都在检测，物理射线检测的开销会很大。使用 secret_visibility_detector.gd 中的点积方法，以提高开销效率。
• 绝不让“隐藏墙壁”与真实墙壁完全相同——玩家需要看到细微的“微光”或纹理差异。完全不可见就不是秘密，而是让玩家觉得有问题的 Bug。

持久化与元进度

• 绝不在主存档槽中保存“已发现的秘密”——如果玩家删除存档以尝试不同的构筑，其元进度（图鉴、成就标记）应该保留。使用 secret_meta_persistence.gd。
• 绝不在点对点模式中信任客户端的作弊验证——如果秘密会提供属性加成，其他对等端应验证“解锁”，以防止简单的内存修改作弊。
• 绝不使用 PlayerPrefs（Godot 中相当于设置的功能）保存秘密——使用专用的 user://secrets.cfg。

用户体验与防暴力破解

• 绝不允许无限次快速尝试作弊码——简单的宏就能在几秒内暴力破解一个 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，以及用于作弊码缓冲区的回声过滤。
• 输入示例 — 多步骤序列的实用 InputMap 操作模式，无需通过 _process 轮询。
• 控制器、游戏手柄和摇杆 — 将经典 Konami 风格代码映射到手柄的 D-pad／面部按钮，并使用一致的操作名称。
• InputMap — 序列匹配器使用的运行时操作枚举（get_actions / event.is_action_pressed）。
• 保存游戏 — 标准持久化流程；不要将元解锁内容放入按存档槽分组的保存数据中。
• Godot 中的文件路径 — user://secrets.cfg / user://meta_secrets.cfg 在不同平台上的存放位置。
• ConfigFile — 使用 INI 风格的专用秘密标记，将其与 Settings 和主要 SaveManager 负载分开。
• 资源 — SecretData Resource 模式、emit_changed 和成就桥接。
• 向量数学 — 使用点积检测视线方向，以发现隐藏墙壁，无需逐帧进行射线检测。
• 随机数生成 — 秘密商贩的加权稀有遭遇判定和保底计时器。
• 音频总线 — 进入封闭秘密区域时使用总线效果／遮挡效果。
• 单例（Autoload） — 在场景切换期间托管 SecretPersistence／元解锁管理器。

相关技能

前置要求

• godot-input-handling — 操作缓冲区、回声过滤和 InputMap 重映射；作弊序列监听器必须与游戏输入共用这些机制。
• godot-signal-architecture — 使用 sequence_matched / secret_spam_triggered 信号总线，让 UI、音频和成就系统可以响应，而无需将检测器硬编码在一起。
• 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 — 无需 AnimationPlayer 开销，即可实现微光能量脉冲和幽灵般秘密的淡出补间。
• godot-particles — 可选的闪光/尘埃效果层，用于暗示可互动对象，但不会揭露秘密。
• godot-shaders-basics — 用于注视触发揭示过渡的微妙墙面微光/溶解材质。

下游 / 使用方

• godot-quest-system — 将发现标记传递到任务阶段、日志和真结局门槛。
• godot-monte-carlo-balancer — 在发布前模拟稀有遭遇权重、刷取阈值和完成度解锁概率。
• godot-adapt-single-to-multiplayer — 当秘密带来战斗或经济优势时，进行服务端/对等方验证。
• godot-theme-easter — 添加使用相同解锁和提示音流程的季节性/主题彩蛋内容。

主技能

• godot-master — 库路由器和镜像模块入口；查找负责秘密而非输入、存档或音频的领域技能时，请打开此项。