Awareness, Investigation, Cover, and Personality Presets

DuckShell combat is not only about firing a weapon. The behavior quality comes from how awareness, search, cover, engagement, and role presets work together.

The main state flow

At a high level, DuckShell rotates between:

• idle or patrol
• investigate
• search or linger
• return
• combat

This means you should not test combat in isolation. A shell that shoots well but never investigates or never returns cleanly is still unfinished.

Awareness and investigation

The awareness layer under shell.ai.awareness.* governs how NPCs:

• move toward sound origins
• linger and search
• decide when a path is still valid
• return to normal behavior after the search window ends

This is the lane to tune when the feedback is about:

• not entering buildings during a noise test
• over-pooling outside doors
• investigating too slowly
• giving up too early

Vision and reacquire logic

Vision and reacquire are separate from raw sound pull. The relevant global lanes include:

• shell.ai.vision.*
• shell.ai.engagement.*
• combat-facing and no-line-of-sight persistence rules

This is the layer to revisit when players can break line of sight too easily, or when an NPC should still be able to lock onto an obvious visible shooter from farther away.

Cover and peek behavior

DuckShell includes a real cover lane rather than faking all movement as direct rushing. That includes:

• reload-trigger cover entry
• health or hit based retreat triggers
• hide and peek durations
• cover cycles
• return windows

The goal is to preserve human-like combat without creating nonstop jitter.

Secondary weapon and reload policy

Modern DuckShell combat also supports:

• secondary switch policy
• switch-on-reload behavior
• close-range panic switching
• reload timing and lock behavior

These controls matter a lot for NPCs that should feel like real players rather than zombies with guns.

Personality presets

Personality presets are additive behavior templates. They are there to fill unset knobs, not to erase deliberate manual edits.

Examples already exposed by the current runtime include roles such as:

• default
• flanker
• marksman
• assaulter
• skirmisher
• sentinel
• berserker
• hunter

Use them as a starting shape, then tune only the shell types that still need more identity.

Testing profile behavior the right way

A practical test pass should compare:

1. default shell type
2. preset variant
3. same map location
4. same range and noise trigger
5. same debug logs

That is how you tell the difference between a real preset effect and a general AI regression.

Recommended next pages

• patrol Editor and Spawner Workflows
• debug, Performance, Corpses, and Live Ops