godot-mechanic-secrets

Decision Tree — Which Secret Trigger?

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

Core Components

[secretmetapersistence.gd](scripts/secretmetapersistence.gd)

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

[secretvisibilitydetector.gd](scripts/secretvisibilitydetector.gd)

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

[secretsequencecombomatcher.gd](scripts/secretsequencecombomatcher.gd)

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

[secretinteractionspamtracker.gd](scripts/secretinteractionspamtracker.gd)

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

[secretaudioenvironmentoccluder.gd](scripts/secretaudioenvironmentoccluder.gd)

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

[secretprogressthresholdunlocker.gd](scripts/secretprogressthresholdunlocker.gd)

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

[secretrandomencounterspawner.gd](scripts/secretrandomencounterspawner.gd)

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

[secretlockoutcheatguard.gd](scripts/secretlockoutcheatguard.gd)

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

[secretvfxdiscoveryglimmer.gd](scripts/secretvfxdiscoveryglimmer.gd)

Subtle procedural visual cues for hinting at hidden interactables.

[secretkonamilegacycode.gd](scripts/secretkonamilegacycode.gd)

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

[secretpersistencehandler.gd](scripts/secretpersistencehandler.gd) / [inputsequencewatcher.gd](scripts/inputsequencewatcher.gd) / [interactionthresholdtrigger.gd](scripts/interactionthresholdtrigger.gd)

DEPRECATED — legacy helpers superseded by secret* scripts. Do not wire new scenes here; migrate to [secretsequencecombomatcher.gd](scripts/secretsequencecombomatcher.gd), [secretinteractionspamtracker.gd](scripts/secretinteractionspamtracker.gd), and [secretmetapersistence.gd](scripts/secretmeta_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 secretsequencecombomatcher.gd.
• NEVER use complex Raycasts for 'LookingAt' secrets — Physics raycasts are expensive if every wall is checking. Use the Dot Product method in secretvisibilitydetector.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 secretmetapersistence.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 secretlockoutcheat_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 secretaudioenvironment_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](references/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 / unhandledinput), isaction_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 (getactions / event.isactionpressed).
• Saving games — Canonical persist loop; keep meta-unlocks out of per-slot save groups.
• File paths in Godot — user://secrets.cfg / user://metasecrets.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 — sequencematched / secretspam_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.