Shell Types, AI Director, and Combat Behavior

DuckShell works best when you treat the AI Director and the shell-type editor as two different layers.

• AI Director defines the shared runtime policy
• NPC Type Editor defines what makes one shell type distinct from another

That separation is one of the plugin's biggest strengths and it is the main thing to preserve as the roster grows.

What a shell type should own

A shell type is the identity layer for one NPC family. In practice that means:

• armor and visual identity
• allowed weapons and equipment pools
• throwables and consumables policy
• faction key and hostility rules
• companion settings where relevant
• per-type AI overrides only where that type truly needs them

Use shell types for role identity, not for replacing every global default one by one.

What the AI Director should own

The AI Director is the shared behavior layer under shell.ai.*. It governs things like:

• vision and stealth gating
• awareness and investigation
• engagement movement
• combat-facing checks
• cover behavior defaults
• companion rules
• status-effect compatibility
• global safety and sanity logic

If nearly every hostile should react the same way, it probably belongs here.

Per-type override philosophy

Good override candidates:

• a marksman that sees farther and holds distance
• a berserker that pushes harder and takes less cover
• a civilian that can be armed and converted
• a juggernaut that keeps a different offhand mode or heavier utility

Bad override candidates:

• copying every global value into every shell type
• setting one-off patrol or spawner behavior on the shell type when it belongs to world content

Loadouts, pools, and fail-closed weapon selection

DuckShell's current admin surface makes a clean distinction between:

• primary gun pool
• secondary gun pool
• melee or item pool
• consumables
• throwables

The important operational rule is that the per-type pool should be the source of truth. If a shell is not supposed to spawn with a given Duck Shot weapon, that weapon should not leak in through fallback behavior.

Factions, hostility, and role identity

Per-type targeting and faction controls belong with the shell type because they change what the NPC is, not how the entire server thinks.

Typical per-type targeting authoring includes:

• hostility mode
• faction key
• hostile faction matrix
• special companion assist rules

This lets you build raiders, soldiers, heroes, civilians, and event-only shells without flattening them into one generic behavior family.

Companion settings are part of authoring, not an afterthought

Shell types that can be claimed or converted should explicitly define:

• whether they can be recruited
• what item or action claims them
• follow and teleport policy
• assist logic
• corpse and drop expectations after conversion

This matters especially for civilians such as wanderers or prisoners that can be armed, converted, and later looted.

A safe authoring workflow

Use this order:

1. Set the shared AI defaults first.
2. Create one shell type family.
3. Test the weapon pools and targeting.
4. Test companion or civilian conversion if the type supports it.
5. Only then add patrols or spawners.

That sequence prevents world-content debugging from masking shell-definition problems.

Recommended next pages

• awareness, Investigation, Cover, and Personality Presets
• patrols, Spawners, and Persistence
• presentation, Skins, and integration bridges