# Config Knobs - load-bearing settings

YAML configs live in `overwrite/SKSE/Plugins/SkyrimNet/config/` (with active edits) and `mods/SkyrimNet/SKSE/Plugins/SkyrimNet/config/` (shipped baselines). 38 YAML files total, plus `defaults_manifest.json`.

This document focuses on the **load-bearing** settings - ones we've discovered have outsized effects on behavior. Full enumeration would be brittle and date-sensitive; the goal here is to capture the gotchas.

## SkyrimNet.yaml - the central config

`[verified]` Direct observations from this install + log/trace correlation.

| Setting | This install | What it controls | Gotcha |
|---|---|---|---|
| `dialogue.embedActionsInDialogue` | `true` | Lets the Dialogue model emit `ACTION:` lines inline after speech. | When `true`, the native_action_selector may be bypassed - and bug #2 (malformed markers) surfaces. When `false`, actions are strictly post-hoc via native selector. |
| `dialogue.eligibilityCheckTimeoutMs` | `2500` | Bounds the `wait_eligibility_results` span. | Slow Papyrus eligibility callbacks (>2.5s) get dropped from the available action list for that turn. |
| `dialogue.interruptDialogueOnVoiceStart` | `true` | Player STT triggers a barge-in on the NPC. | Distinct from TTS-side interrupts; affects whose voice cuts off whom. |
| `dialogue.maxSegmentWords` (`tts.maxSegmentWords`) | `4` | TTS chunk size for streaming. | Was raised by us as part of the first-sentence-drop fix. Small chunks can amplify chunker race conditions; suspected innocent in NPC-NPC restatement. |
| `gamemaster.enabled` | `true` | Master switch for the GM. | - |
| `gamemaster.agentEnabled` | `true` | `[unknown]` Distinct from `enabled`? Both default `true`; toggling untested. | See open-questions.md. |
| `gamemaster.continuousSceneCooldownSeconds` | `30` | Minimum gap between GM polling ticks in continuous mode. | Lower = more LLM cost, more "alive" feel. Higher = cheaper, quieter scenes. |
| `gamemaster.actionCooldownSeconds` | `180` | Per-NPC action cooldown. | Prevents the same NPC from being action-targeted repeatedly. |
| `gamemaster.nearbyActorRadius` | `600` | Radius around player the GM considers. | Skyrim units (~10cm each, so ~60m). |
| `gamemaster.recentEventsCount` | `25` | How much event history goes into the GM prompt. | Higher = more context, more tokens, more cost. |
| `gamemaster.requestTimeoutSeconds` | `30` | Per-call LLM timeout for the GM. | - |
| `gamemaster.continuousSceneCooldownSeconds` | `30` | (duplicate row - see above) | - |
| `interaction.maxDistance` | `250` | Default interaction distance. | Affects who hears what. |
| `interaction.normalMaxDistance` | `250` | Normal speech audibility. | - |
| `interaction.whisperMaxDistance` | `100` | Whisper audibility. | - |
| `events.preloadCount` | `1000` | Events warmed at startup. | Affects load time + initial memory query corpus. |
| `narration.enabled` | `false` | Suppresses asterisk-style narration globally. | Referenced by `is_narration_enabled()` decorator in many prompts; toggling changes prompt content materially. |
| `subtitles.enableNPCSubtitles` | `true` | Whether NPC subtitles render. | - |
| `dbvo.enabled` | `true` | Dialogue Background Voice Over - routes TTS through vanilla Skyrim dialogue topics. | The "first-sentence-dropped" bug we hit was traced to this. Disabling skips lip-sync and topic-coupling. |
| `shouldSilenceActors` | `true` | Silences actors before TTS plays (prevents vanilla audio overlap). | Can race the first audio chunk and silence it. |

`[verified]` `enableNPCNodeUpdates: true` and `dbvo.fixSubtitleDuringTTS: true` were the toggles that fixed the user's "first sentence not played" issue (see `bugs-and-fixes.md` historical context).

## Agents.yaml

Defines per-agent variant assignments and behavior. Each agent has:
- `variant` - which OpenRouter variant to use (cross-references `OpenRouter.yaml`)
- `enabled` - master toggle for the agent
- Possibly `cooldown`, `timeout`, model-specific overrides

`[hypothesis]` Editing `Agents.yaml` is how a user changes which model handles which agent (e.g., "use Claude for dialogue too, not just GM"). Confirm by inspection.

## OpenRouter.yaml

Variant → model + endpoint + per-call defaults. See `agent-pipelines.md` for the full table extracted from this install.

Key sections:
- `default_params` per variant - `max_tokens`, `temperature`, `top_p`, etc.
- `endpoint` - the URL the OpenRouter routing layer sends to. In this install, mostly local IPs (`10.0.30.x`) plus a Claude proxy on `127.0.0.1:8000`.
- `model` - the OpenRouter alias or local model ID.

## Actions.yaml

`[hypothesis]` Defines global action-system policies: which categories are enabled, default priorities, eligibility-check defaults. Doesn't define individual actions - those come from `config/actions/*.yaml` in *contributing mods'* folders (see `action-system.md`).

## Events.yaml

~40 event types, each with toggles:
- `enabled` - does SkyrimNet listen for this event at all
- `persistent` - does the event get stored in the long-term log
- `shortLivedEnabled` - short-lived event variant
- `allowNPCReaction` - can NPCs react to this event via the GM
- `npcReactionCooldown` - per-NPC cooldown for reacting
- `interrupt` - does this event interrupt ongoing dialogue

**Currently disabled in user's config** `[verified]` from the user's install:
- `quest_stage`
- `cell_attach_detach`
- `quest_objective_state`
- `scene*` (multiple scene_* event types)

These were likely disabled to cut event noise. Re-enabling would feed more triggers to the GM and increase LLM call frequency.

## Memory.yaml

Controls the vector memory system (semantic embeddings via all-MiniLM-L6-v2):
- Embedding model selection
- Memory retention windows
- Number of memories retrieved per query
- Memory generation thresholds

`[hypothesis]` These tune the RAG-for-NPCs behavior. Defaults probably reasonable for most users.

## OmniSight.yaml

Vision-agent settings - when to capture screenshots, how often, scene description verbosity.

## MCP.yaml

`[hypothesis]` Model Context Protocol integration? Not yet inspected. Could be relevant if SkyrimNet exposes MCP servers/clients for external tool integration.

## Per-TTS provider configs

One YAML per supported TTS backend:
- `XTTS.yaml`, `Zonos.yaml`, `Chatterbox.yaml`, `Piper.yaml`, `PocketTTS.yaml`, `ElevenLabs.yaml`, `Inworld.yaml`, `VastAI.yaml`

Active backend selected by `tts.engine` in `SkyrimNet.yaml`. This install uses `pocket_tts`.

Streaming params worth knowing (in `PocketTTS.yaml`):
- `streaming.max_words_to_process: 32` - max chunk size
- `streaming.min_words_to_process_initial: 16` - first-chunk minimum (was a suspect for the first-sentence-drop bug)
- `streaming.process_on_sentence_boundary: true`
- `streaming.process_on_word_count: true`
- `streaming.max_buffers_per_actor: 4`

## STT.yaml

Speech-to-text settings (whisper.cpp local). VAD thresholds, language, sample rate, voice activity gate.

## defaults_manifest.json

`[hypothesis]` JSON dump of every config key with its default value, structured by section name. Looks like the **schema the DLL seeds first-run config from** - when a YAML doesn't exist, the DLL writes one populated from this manifest.

**Sections present** (28 total): `ActorFilter`, `Agents`, `BardSinging`, `ChatUI`, `Chatterbox`, `DialogueFilter`, `Diary`, `DynamicBio`, `ElevenLabs`, `Entity`, `Events`, `Hotkey`, `Inworld`, `Memory`, `MemoryFilter`, `OmniSight`, `OpenRouter`, `Piper`, `PlayerDialogue`, `PocketTTS`, `STT`, `UniversalTranslator`, `VastAI`, `VirtualEntities`, `VoiceSamples`, `WebServer`, `XTTS`, `Zonos`.

Each section name matches a YAML file. Verify role by deleting a YAML and watching what regenerates.

## Plugins subtree

`config/plugins/IntelEngine/` - the IntelEngine sibling plugin keeps its config under SkyrimNet's config root. Notable files: `factions.yaml`, `settings.yaml`. `[unknown]` exact contents.

## Editing safety

- **Always edit `overwrite/.../config/`**, never `mods/.../config/` directly. The overwrite layer is what the game reads.
- **Most settings hot-reload.** Restart only needed for backend swaps (TTS engine, STT) or fundamental architecture changes.
- **Backup before changes:** `cp foo.yaml foo.yaml.backup` is the pattern we've used.
- **The in-game MCM (Mod Configuration Menu)** writes back to these YAMLs - UI tweaks persist as YAML edits, which is convenient but means the UI is yet another writer to be aware of.
