Smart Visibility System: Spoiler-Free Storytelling

Control what the AI can use, when secrets fully reveal, and how near-miss actions create spoiler-safe suspense.

The Problem with "Helpful" AI

We’ve all been there: You create a complex character with a dark secret. Let's say, a loyal Cylon sleeper agent hidden within the crew. This secret is the core of your plot twist. However, standard AI models often try to be too helpful. They might accidentally hint at the secret in the very first turn or offer dialogue options that give the game away, completely breaking the immersion you worked so hard to build.

The WorldForge Solution

To protect your narrative, WorldForge separates visibility evaluation from narration so the engine can either reveal a secret now or hold the line and build tension:

Visibility Evaluation (The Gatekeeper)

Before any narration is generated, the Logic Engine checks every hidden or conditional piece of knowledge against the current scene. A condition can either fully trigger a reveal or be marked as relevant because the player is getting close.

Content Generation (The Storyteller)

The Narrative AI writes using only visible knowledge plus any temporary suspense boundaries. It never receives the hidden content itself until the reveal condition is fully satisfied.

The New Mechanic: Near Miss vs. Full Reveal

Visibility evaluation now returns two kinds of outcomes. That gives you finer control over pacing: the story can feel close to a secret without actually spilling it.

is_triggered Full reveal

When `is_triggered` is true

The player has explicitly satisfied the reveal condition. The hidden knowledge becomes available immediately, so the narrator can use it in that same turn.

is_relevant Spoiler-safe suspense

When `is_relevant` is true

The player is approaching the right topic, place, or action, but has not completed the unlock condition yet. The AI does not receive the hidden knowledge itself; it only receives the hidden knowledge name as a spoiler-safe topic label and the unlock condition plus explicit instructions not to invent related facts on its own. That lets it offer guiding options without spoilers while also avoiding story beats that contradict the hidden knowledge before the reveal.

Think of `is_relevant` as "close enough to tease" and `is_triggered` as "close enough to reveal." Hidden knowledge names act as spoiler-safe topic labels during near-miss states, so authors should keep those names suggestive rather than explicit.

How to Configure Your "Knowledge"

In the editor, you can assign a Reveal Logic to any Entity, NPC, Item, Location, or Lore entry:

always_reveal✓ Always visible

Best for: Character appearances, public locations, core world rules. The AI always has access to this information.

to_be_revealedHidden → Revealed

Best for: Secret identities, hidden chambers, plot twists, and boss reveals. The secret stays filtered out until the condition is fully met, but near-miss actions can still create tension using the hidden knowledge name as a spoiler-safe topic label.

to_be_hiddenVisible → Hidden

Best for: Character creation steps, setup instructions, and temporary system rules. The AI can use this during setup, then it is hidden permanently once the condition is met. This mode does not create suspense boundaries.

check_per_turn🔄 Dynamic

Best for: Hallucinations, magical senses, stealthy threats, or proximity-based discoveries. The system re-checks it every turn, and near-miss actions can add atmosphere before the player truly perceives it.

hidden✗ Never visible

The AI never sees this. Use it for creator notes or content that should stay outside the narrator entirely.

How to Write Better Reveal Conditions

The mechanic works best when your hidden knowledge name is a spoiler-safe topic label and your conditions describe concrete, observable player actions. The relevance pass can use the name for consistency, but the actual reveal still depends on clear fulfillment.

Write conditions like this

• "Player opens the sealed compartment beneath the altar."
• "Player speaks the captain's true name in the throne room."

Avoid conditions like this

• "Player gets close to learning the truth."
• "Something important about the altar happens."

Example: A Near Miss That Builds Tension

You create a "Hidden Reliquary" lore entry with:

• Reveal logic: to_be_revealed
• Condition: "Player opens the sealed compartment beneath the altar"

Step 1

is_relevant

The player investigates the altar

The player circles the altar, notices scratch marks, and presses on the stonework, but never opens the compartment.

The system marks the condition as relevant. The narrator can describe cold air, strange seams, or a hollow echo, but it cannot reveal the reliquary yet.

Step 2

is_triggered

The player opens the compartment

The player pries the panel loose and explicitly completes the condition.

The system marks the condition as triggered. The hidden reliquary enters the narrator's context and can appear immediately in that same turn.

Takeaway: WorldForge can make secrets feel close before they are visible. You get foreshadowing without spoilers, and the actual reveal still lands at the exact moment the player earns it.