Global Config, Runtime, and File Map

DuckShell becomes much easier to reason about once you stop treating config.yml as one giant NPC file. The plugin is built around a split between global runtime policy, per-type definitions, world content files, and cached presentation data.

The core files

config.yml

This is the real runtime brain. It covers:

• presentation strategy
• shell spawn safety
• hint and bubble rendering
• AI Director defaults
• companion systems
• combat-driver policy
• shell-type definitions and per-type overrides

This is where you shape server-wide expectations first.

patrols.yml

This file stores:

• waypoint routes
• patrol spawn entries
• wait times
• route loop settings
• optional boundary data

Use it when a shell should belong to a route in the world.

spawners.yml

This file stores:

• persistent spawner IDs
• target alive counts
• activation radius rules
• respawn delays
• optional boundary zones

Use it when the world should maintain encounter presence over time.

head_cache.yml

This file is not encounter design. It is cache data used to avoid constantly rebuilding head and skin profile data.

The most important config lanes

Inside config.yml, these sections matter first:

• presentation.*
• shell.spawn.*
• shell.hints.*
• shell.ai.*
• shell.ai.companion.*
• shell.patrol.*
• shell.internal-engine.*
• shell.shell-types.*

That split is deliberate. The plugin expects:

• global defaults once
• per-type overrides only when the type actually needs to differ

Shell-type authoring versus runtime defaults

A good rule of thumb:

• use shell.ai.* for the baseline behavior you want most NPCs to share
• use shell.shell-types.<Type>.* only for identity, role, loadout, and exceptions

That keeps the roster readable as it grows. It also matches the Duck Shot documentation pattern of setting plugin-wide rules before item-specific overrides.

Runtime systems that are easy to overlook

These systems are part of the live runtime even if you are focused on combat:

• civilian arming and companion conversion
• corpse handling and dead-body loot
• status-effect compatibility
• sound and investigation response
• external bridges such as Duck Shot, SoundLogic, and server event systems

Those systems should be understood before you start calling a shell type "done".

The content-authoring split

Think of DuckShell content in four layers:

1. global runtime defaults
2. shell-type definitions
3. world content such as patrols and spawners
4. live-server debug and performance operations

If one page or one config edit starts mixing all four, you are probably authoring in the wrong place.

Recommended next pages

• shell Types, AI Director, and Combat Behavior
• patrols, Spawners, and Persistence
• debug, Performance, Corpses, and Live Ops