# Enemy perception and investigation settings

Source reviewed: 15 October 2026, against the current working implementation.
This is a tuning reference, not test evidence or human gameplay acceptance.
Examples illustrate the controls; they are not claims about current preset values.

A **prediction** is somewhere the player might be hiding. A **viewpoint** is
somewhere the enemy can stand to inspect one or more predictions. An inspection
can check several predictions; visiting every marker is not the search policy.

## Find and apply the settings

The manual shooter sandbox has Weak, Ordinary and Persistent search presets.
Its definitions are under `Assets/_Project/Debug/EnemyBehavior/`:

| Preset | Perception asset | Investigation asset |
|---|---|---|
| Weak | [WeakShooterPerception.asset](../Assets/_Project/Debug/EnemyBehavior/WeakShooterPerception.asset) | [WeakInvestigation.asset](../Assets/_Project/Debug/EnemyBehavior/WeakInvestigation.asset) |
| Ordinary | [OrdinaryShooterPerception.asset](../Assets/_Project/Debug/EnemyBehavior/OrdinaryShooterPerception.asset) | [OrdinaryInvestigation.asset](../Assets/_Project/Debug/EnemyBehavior/OrdinaryInvestigation.asset) |
| Persistent | [PersistentShooterPerception.asset](../Assets/_Project/Debug/EnemyBehavior/PersistentShooterPerception.asset) | [PersistentInvestigation.asset](../Assets/_Project/Debug/EnemyBehavior/PersistentInvestigation.asset) |

Select the appropriate asset in Unity's Project window and edit its Inspector.
For another enemy, use the definitions assigned to that enemy's Perception and
Positioning components rather than assuming these sandbox presets apply.

Values are captured when the enemy initializes. **Reset/respawn to apply edits**;
changing an asset does not update an existing enemy's captured settings. Sandbox
reset also replaces/repositions actors; do not confuse it with continuing the
same search episode.

## Enemy Perception Definition

Defined by [EnemyPerceptionDefinition.cs](../Assets/_Project/Features/Enemies/Perception/EnemyPerceptionDefinition.cs).
Runtime behavior is in [EnemyPerception.cs](../Assets/_Project/Features/Enemies/Perception/EnemyPerception.cs),
[EnemyObservationRules.cs](../Assets/_Project/Features/Enemies/Perception/EnemyObservationRules.cs)
and [EnemyTargetSelection.cs](../Assets/_Project/Features/Enemies/Perception/EnemyTargetSelection.cs).

| Inspector setting | What it does |
|---|---|
| **Perception Interval** | Seconds between visual sensing passes. `0.15` means roughly 6–7 checks per second. Lower values update sight and observed movement more frequently, with more processing work. Actual timing follows frame/sample cadence. |
| **Visual Reaction Delay** | How long a newly seen target must remain observed before becoming reaction-ready. Evaluated on perception passes. Once acquired, readiness survives brief occlusion while the memory remains fresh; it is not a new delay on every peek. |
| **Target Hold Seconds** | How long the enemy prefers its current target over another with equally strong evidence. Reduces switching between similarly visible players. Better evidence or an invalid target can override the hold immediately. |
| **Personal evidence retention (seconds)** | Internally named `investigationSeconds`. How long the last genuine sighting remains usable, measured from that sighting. Caps the personal search deadline. The current implementation also uses this duration for freshness of reported and heard evidence, measured from their original observation times. |
| **Sight Range** | Maximum visual detection distance in metres. The target must still pass field-of-view and actual sight checks. Does not set weapon range. |
| **Field Of View** | Full angular opening around the eye's forward direction. `180` means 90 degrees either side; `360` removes the angular restriction. The implementation checks a 3D angle, not only horizontal yaw. Walls still block sight. |
| **Hearing Range** | Maximum distance to an emitted coarse noise region's centre. Currently receives accepted weapon-shot noise, not general footsteps or every game sound. This hearing check is not blocked by walls and provides a region rather than an exact hidden position. |

Target evidence preference is: visible personal sight, remembered personal sight,
squad visual report, then heard region. Target Hold Seconds preserves an
equal-quality preference; it does not make weaker evidence override stronger
evidence. Hearing is described in [EnemyCombatNoise.cs](../Assets/_Project/Features/Enemies/Perception/EnemyCombatNoise.cs).

## The three different time controls

| Setting | Purpose |
|---|---|
| **Personal evidence retention (seconds)**, on the perception definition | Lifetime of the original sighting. |
| **Maximum Search Seconds**, on the investigation definition | Maximum elapsed search allowance from that same sighting. |
| **Inspection Seconds**, on the investigation definition | Oriented dwell before checking visible predictions at each inspection. Still requires a fresh real perception pass. |

The episode deadline is:

```text
last genuine sight time + min(personal evidence retention, maximum search seconds)
```

For example, 9 seconds of retention and 20 seconds of search allowance permit
at most 9 seconds after last sight, not 20. The clocks do not restart when the
enemy starts moving, reaches a viewpoint or begins an inspection. Travel,
planning, turning and inspection consume the available window.

**Inspection Seconds = 0** removes the extra dwell, but does not make inspection
instant or bypass the fresh perception/visibility checks. It does not extend the
memory or overall deadline. Attempts, completed inspections and cumulative travel
have separate limits and can end a search sooner.

## Advanced sampling and scoring

These are the fields in the **Advanced sampling and scoring** Inspector foldout,
defined in [EnemyInvestigationDefinition.cs](../Assets/_Project/Features/Enemies/Investigation/EnemyInvestigationDefinition.cs).
Selection and scoring are implemented in [EnemyInvestigationPlanner.cs](../Assets/_Project/Features/Enemies/Investigation/EnemyInvestigationPlanner.cs);
inspection completion is in [EnemyPositioning.cs](../Assets/_Project/Features/Enemies/Navigation/EnemyPositioning.cs).

| Inspector setting | What it does |
|---|---|
| **Observation Facing Tolerance Degrees** | Allowed horizontal yaw error from the chosen inspection look target. Outside this tolerance, inspection progress resets. Smaller values require more precise facing; larger values permit looser alignment. Does not widen sight FOV. |
| **Maximum Vertical Offset** | Maximum height difference, in metres, between a prediction/viewpoint and the last-seen player's feet. Larger values permit candidates on more vertically separated surfaces. Does not grant climbing ability or bypass route safety. |
| **Viewpoint Stand Off** | Extra metres beyond Search Radius where new viewing positions may be generated. Radius `5` plus stand-off `1.5` allows new viewpoints up to `6.5 m` from the anchor. Does not expand the prediction radius. |
| **Viewpoint Merge Distance** | Minimum 3D spacing within the prediction set and within the viewpoint set. Nearby entries are treated as duplicates. Larger values reduce density; smaller values preserve more nearby alternatives but require more planning work. Must be positive and smaller than Search Radius. |
| **Direction Sample Maximum Gap** | Maximum seconds between the two consecutive successful sight samples used to estimate player velocity. A larger gap rejects the estimate. Increasing this does not permit tracking movement through an unseen interval. |
| **Direction Minimum Displacement** | Minimum horizontal movement, in metres, between those two samples before accepting a velocity estimate. Higher values ignore small movements or jitter; lower values recognize slower movement more readily. |
| **Direction Prediction Seconds** | How far ahead to extrapolate the last observed velocity. For example, `4 m/s × 0.75 s` proposes a point `3 m` ahead, clipped to Search Radius. `0` disables that extrapolated prediction, not every other use of observed direction. |
| **Maximum Inferred Speed** | Maximum accepted motion estimate in metres per second. Estimates above it are discarded, including apparent teleport motion. Does not limit actual player or enemy movement speed. |
| **Near Cover Weight** | Adds priority to predictions near the last-seen anchor that are judged blocked from the captured viewing position. The bonus fades toward the search-radius edge. `0` removes this bonus; it does not disable wall predictions. |
| **Observed Direction Weight** | Adds priority to predictions aligned with the last verified movement direction. Higher values make search more direction-biased. `0` removes this bonus without disabling the extrapolated prediction itself. |
| **Travel Cost Weight** | Penalizes longer routes when choosing between useful viewpoints. The penalty is proportional to route length divided by Maximum Search Travel Distance. Higher values favour shorter routes; `0` removes this scoring penalty while hard travel/time limits remain. |
| **Minimum Information Gain** | Minimum new weighted coverage a viewpoint must provide, divided by the original total prediction weight. `0.1` means at least 10%. A remaining prediction worth 6% cannot justify a viewpoint by itself. Lower values permit smaller remaining possibilities. Must be greater than `0` and no greater than `1`. |
| **Blocked Viewpoint Retry Seconds** | Minimum wait before a failed viewpoint may be reconsidered within an active episode. The current implementation also requires the world-geometry signature to change: elapsed time alone does not trigger a retry. Does not restart a finished search. |

### Important interactions

- **Height is relative to the last-seen floor, not the enemy's current floor.**
  Last-seen feet at height `3` with Maximum Vertical Offset `2` permits candidate
  heights approximately `1–5`. This does not itself prohibit a stair route from
  height `0` to height `3`.
- **Motion estimation must pass all three gates:** acceptable sample gap,
  sufficient horizontal displacement and acceptable inferred speed. Losing sight
  breaks the consecutive sample pair. No hidden live movement updates the frozen
  estimate.
- **Weights change priority, not prediction count.** Every admitted prediction
  starts with weight `1`, then receives any cover/direction bonuses. Strengthening
  some predictions can make others a smaller fraction of the original total,
  potentially putting them below Minimum Information Gain when considered alone.
- **Travel Cost Weight chooses between eligible viewpoints; Minimum Information
  Gain determines eligibility.** The gain threshold is checked before subtracting
  the travel penalty. A negative final score is not itself a stop condition.

The planner uses:

```text
gain = newly visible unchecked prediction weight / original total prediction weight
score = gain - travelCostWeight × routeLength / maximumSearchTravelDistance
```

Actual support, collision, native route, remaining time/travel and destination
claim checks still determine whether a viewpoint can be admitted.

## Why predictions can remain unchecked

There is no existing **check every prediction** switch. Search chooses useful,
safe viewpoints within finite allowances. A marker being close to the actual
hidden player does not give the enemy knowledge of that position or guarantee
that it can inspect it.

The main controls affecting thoroughness are the two overall time allowances,
Maximum Viewpoint Attempts, Maximum Viewpoints To Inspect, Maximum Search Travel
Distance, Maximum Viewpoint Candidates and Minimum Information Gain. More
inspection attempts do not translate one-to-one into more checked markers.

The observation window's Search phase/reason, effective deadline and
attempt/inspection/travel counters help distinguish expiry or a spent limit from
`NoUsefulViewpoint`. NoUsefulViewpoint can mean no sufficiently informative safe
route/view remains; it is not proof that every prediction was checked.

Wall-derived predictions still require a real wall hit and valid far-side floor.
Increasing density or weights cannot bypass geometry or create a guaranteed
checking route. Guaranteed exhaustive coverage would require a different bounded
coverage policy; unreachable or fully occluded points could still remain.

## Reference maintenance and evidence limits

Scope: documentation only; low-risk explanation of existing behavior. Lead review
checked the seven perception fields, thirteen advanced fields, timer semantics
and source/asset links. No runtime/tuning files changed and no Unity operations,
tests or builds were run for this documentation change. Earlier implementation
proof and open acceptance remain in the [project brief](PROJECT_PLAN.md) and
linked task records; this reference supplies no new gameplay acceptance.