godot-mechanic-secrets

Decision Tree — Which Secret Trigger?

Player action / design goal	Choose	MANDATORY script
Exact button combo / Konami	Time-windowed input sequence	secret_sequence_combo_matcher.gd (+ secret_konami_legacy_code.gd for classic mapping)
Mash / click N times on a prop	Spam threshold	secret_interaction_spam_tracker.gd
Face a wall / look at a spot	Dot-product look-at (not ray spam)	secret_visibility_detector.gd
Clear X% of content / true ending	Progress % unlock	secret_progress_threshold_unlocker.gd
Rare vendor / ghost encounter	Weighted random encounter	secret_random_encounter_spawner.gd
Persist unlock across save slots	Meta secrets.cfg	secret_meta_persistence.gd
Stop macro brute-force	Lockout guard	secret_lockout_cheat_guard.gd
Secret grants stats/items in P2P	Server/peer validation	godot-adapt-single-to-multiplayer — validate unlock before applying combat/economy advantages

Do NOT invent a fourth custom detector until the table above fails.

Core Components

secret_meta_persistence.gd

Expert logic for saving global unlocks and discovery flags across all save profiles.

secret_visibility_detector.gd

View-dependent hidden wall detection using optimized Dot Product calculations.

secret_sequence_combo_matcher.gd

MANDATORY for combos — Time-sensitive input buffer with suffix/window match (not full-buffer equality).

secret_interaction_spam_tracker.gd

Logic for tracking repetitive player actions to trigger curiosity-based Easter Eggs.

secret_audio_environment_occluder.gd

Spatial logic for dynamically adjusting AudioBus effects in sealed or hidden areas.

secret_progress_threshold_unlocker.gd

Percentage-based unlocker for meta-content and 'True Ending' triggers.

secret_random_encounter_spawner.gd

Weighted random system for rarest-tier entities and secret vendor encounters.

secret_lockout_cheat_guard.gd

Anti-brute-force lockout manager to protect secret integrity.

secret_vfx_discovery_glimmer.gd

Subtle procedural visual cues for hinting at hidden interactables.

secret_konami_legacy_code.gd

Specialized implementation of the iconic Konami code using the buffer matcher.

secret_persistence_handler.gd / input_sequence_watcher.gd / interaction_threshold_trigger.gd

DEPRECATED — legacy helpers superseded by secret_* scripts. Do not wire new scenes here; migrate to secret_sequence_combo_matcher.gd, secret_interaction_spam_tracker.gd, and secret_meta_persistence.gd.

Usage Example (Cheat Code)

# 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

NEVER Do (Expert Secret Rules)

Discovery & Triggers

• NEVER hardcode input checks in _process — Frame-dependent polling is unreliable for fast combos. Always use an event-based buffer like secret_sequence_combo_matcher.gd.
• NEVER use complex Raycasts for 'LookingAt' secrets — Physics raycasts are expensive if every wall is checking. Use the Dot Product method in secret_visibility_detector.gd for overhead efficiency.
• NEVER make 'Hidden Walls' identical to real walls — Players need a subtle "Glimmer" or texture discrepancy. Total invisibility isn't a secret; it's a bug to the player.

Persistence & Meta

• NEVER save "Secrets Found" in the main Save Slot — If the player deletes their save to try a different build, their meta-progress (Gallery, Achievement flags) should persist. Use secret_meta_persistence.gd.
• NEVER trust client-side cheat validation in Peer-to-Peer — If a secret grants a stat boost, other peers should validate the "Unlock" to prevent simple memory-editing cheats.
• NEVER use PlayerPrefs (Godot's equivalent of Settings) for secrets — Use a dedicated user://secrets.cfg.

UX & Anti-Brute Force

• NEVER allow unlimited rapid-fire cheat attempts — A simple macro can brute-force a 4-button combo in seconds. Use secret_lockout_cheat_guard.gd to add a penalty for excessive failures.
• NEVER trigger a secret without an 'Aha!' audio/visual cue — The reward for finding a secret is the feeling of discovery. Use secret_audio_environment_occluder.gd to change the atmosphere.

Best Practices

1. Event-Based Combo Detection - Avoid polling in _process.
2. Subtle Cues - Secrets should be hinted at, not invisible.
3. Global Persistence - Use separate save files for meta-progress.

---

Elite Meta Patterns (galleries / lore / ghosting)

MANDATORY when building achievement galleries, lore journals, or ghosted-secret visibility: read secrets-meta-patterns.md. Do NOT Load for basic combo/spam/look-at triggers — use the decision tree scripts above.

Reference

Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

Official Documentation

• Using InputEvent — Event pipeline (_input / _unhandled_input), is_action_pressed, and echo filtering for cheat buffers.
• Input examples — Practical InputMap action patterns for multi-step sequences without _process polling.
• Controllers, gamepads, and joysticks — Map classic Konami-style codes to pad D-pad/face buttons with consistent action names.
• InputMap — Runtime action enumeration used by sequence matchers (get_actions / event.is_action_pressed).
• Saving games — Canonical persist loop; keep meta-unlocks out of per-slot save groups.
• File paths in Godot — user://secrets.cfg / user://meta_secrets.cfg placement across platforms.
• ConfigFile — INI-style dedicated secret flags separate from Settings and main SaveManager payloads.
• Resources — SecretData Resource patterns, emit_changed, and achievement bridges.
• Vector math — Dot-product look-at detection for hidden walls without per-frame raycasts.
• Random number generation — Weighted rare-encounter rolls and pity timers for secret vendors.
• Audio buses — Bus effects / occlusion when entering sealed secret areas.
• Singletons (Autoload) — Host SecretPersistence / meta unlock managers across scene changes.

Related Skills

Prerequisites

• godot-input-handling — Action buffers, echo filtering, and InputMap remaps that cheat-sequence watchers must share with gameplay input.
• godot-signal-architecture — sequence_matched / secret_spam_triggered buses so UI, audio, and achievements react without hard-wiring detectors.
• godot-autoload-architecture — SecretPersistence and meta-unlock Autoloads need boot order and scene-change survival rules.

Complements

• godot-save-load-systems — Keep gallery/meta flags in user://meta_secrets.cfg while run progress stays in versioned save slots.
• godot-resource-data-patterns — Typed SecretData / lore Resources with emit_changed for achievement and journal bridges.
• godot-audio-systems — Bus effects and stingers for sealed-room occlusion and the discovery “Aha!” cue.
• godot-ui-rich-text — BBCode lore journals that append discovered secret descriptions.
• godot-tweening — Glimmer energy pulses and ghosted-secret fade tweens without AnimationPlayer overhead.
• godot-particles — Optional sparkle/dust layers that hint at interactables without spoiling the secret.
• godot-shaders-basics — Subtle wall-glimmer / dissolve materials for look-at reveal transitions.

Downstream / consumers

• godot-quest-system — Route discovery flags into quest stages, journals, and true-ending gates.
• godot-monte-carlo-balancer — Simulate rare-encounter weights, spam thresholds, and completion-% unlock odds before shipping.
• godot-adapt-single-to-multiplayer — Server/peer validation when a secret grants combat or economy advantages.
• godot-theme-easter — Seasonal/themed Easter content that consumes the same unlock and cue pipeline.

Master

• godot-master — Library router and mirrored module entry; open when discovering which Domain Skill owns secrets vs input, save, or audio.