# Atmospheric encounters

Configure seven doorstep scenes, scare intensity and private particle effects.

## How a scene works

A player knocks and stays nearby until the resident responds. Encounters add a short scene before the response, typically lasting two to six seconds. Players can walk away at any time. No extra controls or fear meter are required.

| Scene | What happens |
| --- | --- |
| `FOOTSTEPS` | Steps approach from inside, stop at the door and fall silent |
| `FALSE_ALARM` | A creak and movement resolve into a harmless cat sound |
| `UNANSWERED` | An empty doorway, knocks from behind and a brief silhouette |
| `WATCHER` | A distant figure disappears when examined or approached |
| `FALSE_NEIGHBOUR` | A resident briefly becomes an uncanny dark figure |
| `DOUBLE_KNOCK` | Knocks at the door receive an answer behind the visitor |
| `LIGHTS_OUT` | A short blackout, heartbeat and fleeting figure |

Ordinary `QUIET_VISIT` scenes provide recovery between encounters.

## Default settings

```yaml
Horror:
  enabled: true
  intensity: BALANCED
  chance: 65
  volume: 0.7
  darkness: true
  particles:
    enabled: true
    density: 0.7
  strong_cooldown_seconds: 90
  quiet_visits_after_strong: 2
  max_distance: 8
  weights:
    FOOTSTEPS: 4
    FALSE_ALARM: 2
    UNANSWERED: 3
    WATCHER: 3
    FALSE_NEIGHBOUR: 2
    DOUBLE_KNOCK: 2
    LIGHTS_OUT: 2
```

`chance` is the percentage of eligible visits considered for a scene, **not** the percentage of visits that become strong scares. First visits are ordinary. After a strong scare, the player gets two quiet visits and a 90-second strong-scare cooldown. Recent scenes are excluded to reduce repetition. Each player has independent pacing.

## Choose an intensity

- `GENTLE` excludes the two strong scene types.
- `BALANCED` uses the configured weights.
- `INTENSE` doubles strong-scene weights while keeping cooldown and recovery rules.

Set a scene's weight to zero to disable it. Set `Horror.enabled: false` for ordinary visits. Personal encounter audio can be silenced with `volume: 0`; darkness can be disabled independently.

## Private visual effects

Supernatural scenes can use curved soul wisps, broken ritual circles, inward smoke spheres, knock echoes and ash trails. These particles are private to the visitor and stop with the visit. Ordinary visits, footsteps and false alarms do not use spell formations.

`particles.density` ranges from zero to one. Changing it affects visual density, not timing, sound or rewards. `particles.enabled: false` disables encounter particles.

## Leaving and interrupted rewards

Moving beyond `max_distance`, dying, leaving the world or event, disconnecting, reloading or disabling the plugin cancels the active visit. Scares do not damage players, alter the camera or teleport them.

Sweets, ingredient assignments/deliveries and costume-history settlement happen once when the response resolves. Discovery credit and ordinary admission cooldowns are still applied on knock. Thief losses remain a separate option; a scare by itself does not take sweets.

## Existing configuration files

Missing encounter settings use defaults without overwriting your existing configuration. Copy the `Horror` section into the existing file when you want to tune it. Older message files use English fallbacks for missing encounter hints until you add the corresponding localized messages.