Hide & Seek

IState + StateMachine — Plain Classes, Not MonoBehaviours

StateMachine and BaseState live in Infrastructure/StateMachine/ with no Unity dependency — they're plain C# classes that could run in a test harness without an editor. StateMachine holds the current IState, calls Exit() then Enter() on transition, and exposes Tick(). EnemyController owns one instance, calls Tick() from Update(), and constructs each concrete state with a reference to itself. The states get everything they need through that owner reference — no singletons, no FindObjectOfType.

// Infrastructure/Interfaces/IState.cs
public interface IState
{
    void Enter();
    void Tick();
    void Exit();
}

// Infrastructure/StateMachine/StateMachine.cs
public class StateMachine
{
    IState _currentState;
    public IState CurrentState => _currentState;

    public void ChangeState(IState newState)
    {
        _currentState?.Exit();
        _currentState = newState;
        _currentState?.Enter();
    }

    public void Tick() => _currentState?.Tick();
}

// Infrastructure/StateMachine/BaseState.cs
public abstract class BaseState : IState
{
    public virtual void Enter() { }
    public virtual void Tick()  { }
    public virtual void Exit()  { }
}

// AI/Enemy/EnemyController.cs (simplified)
public class EnemyController : MonoBehaviour
{
    StateMachine _stateMachine = new();

    void Start() => _stateMachine.ChangeState(new EnemyPatrolState(this));
    void Update() => _stateMachine.Tick();

    public void ChangeState(IState newState) => _stateMachine.ChangeState(newState);
}

SuspicionMeter — Continuous Float with Hysteresis

SuspicionMeter is a MonoBehaviour on the enemy that accumulates suspicion each FixedUpdate. The visual delta from EnemyDetection.ComputeVisualDelta() applies three modifiers: distance falloff, angle falloff, and a crouch stealth multiplier. The result is a per-frame rate — not a spike — so suspicion rises smoothly and the player has time to react.

ComputeTargetState() uses separate rising and falling thresholds per state. The gap between them is the hysteresis band: you need to lose suspicion past the falling threshold to revert a state, not just dip below the threshold that triggered it. Without that gap, a player hovering at the boundary would flicker the enemy between states on every frame.

// Detection/SuspicionMeter.cs
public class SuspicionMeter : MonoBehaviour
{
    public event Action<float>            OnSuspicionChanged;
    public event Action<SeekState, SeekState> OnStateChanged;
    public event Action                   OnPlayerCaught;

    public float     Suspicion           { get; private set; }  // 0–100
    public float     SuspicionNormalized => Suspicion / 100f;
    public SeekState State               { get; private set; }
    public float     Phase2SuspicionFloor { get; set; }         // set by LevelPhaseManager

    // Called each FixedUpdate by EnemyDetection
    public void Tick(float visualDeltaPerSec, float audioSpike,
                     bool hasLoS, float proximityDeltaPerSec,
                     bool playerInCatchRadius) { /* ... */ }

    SeekState ComputeTargetState()
    {
        // Rising thresholds (from EnemyData ScriptableObject):
        //   Unaware → Alert:     suspicion >= alertThreshold     (25f)
        //   Alert   → Searching: suspicion >= searchingThreshold (60f)
        //   Searching → Chase:   suspicion >= chaseThreshold     (85f)
        //
        // Falling thresholds (hysteresis gap prevents flickering):
        //   Chase   → Searching: suspicion < chaseRevertThreshold     (75f)
        //   Searching → Alert:   suspicion < searchingRevertThreshold  (50f)
        //   Alert   → Unaware:   suspicion < alertRevertThreshold      (15f)
        // ...
    }
}

// AI/Enemy/EnemyDetection.cs — visual delta per GDD formula F2
float ComputeVisualDelta(float distance, float angleToPlayer)
{
    // distanceFactor: falloff using distanceFalloffExponent (2f) over detectionRange (15f)
    // angleFactor:    falloff using angleFalloffExponent (2f)   over fieldOfViewAngle/2 (45°)
    // crouchModifier: crouchStealthMultiplier (0.4f) when player is crouching
    // stateMultiplier: searchingVisualDetectionMultiplier (1.5f) when Searching
    return data.baseDetectionRate * distanceFactor * angleFactor
               * crouchModifier * stateMultiplier;
}

EnemyNavigation — NavMeshAgent Behind an Interface

States never touch NavMeshAgent directly. EnemyNavigation wraps it and exposes only what states need: SetDestination(), Stop(), IsNear(), and RotateToward(). That last one is the non-obvious method — EnemyAlertState uses it to smoothly scan toward the last-known position, and it returns true when the rotation is within 1° of the target so the state knows when to stop waiting. Wrapping the agent means you can swap the navigation backend or mock it in tests without touching any state logic.

NoiseEmitter — Static Event Bus with Zero Allocation

NoiseEmitter is a static class that fires a readonly struct — NoiseEvent — carrying world position, intensity, and a source tag. Emitters call NoiseEmitter.Emit() and forget it. Each enemy's NoiseListener subscribes on OnEnable, unsubscribes on OnDisable, and filters incoming events by _hearingRadius before raising its own local event. The struct allocates nothing on the heap: no boxing, no list allocation per broadcast. Adding a new noise source — a door slam, a grenade — means one Emit() call. Nothing else changes.

// AI/Enemy/EnemyNavigation.cs
[RequireComponent(typeof(NavMeshAgent))]
public class EnemyNavigation : MonoBehaviour
{
    NavMeshAgent _agent;

    public bool IsAtDestination { get; }

    public void SetDestination(Vector3 position) => _agent.SetDestination(position);
    public void SetSpeed(float speed)            => _agent.speed = speed;
    public void Stop()                           => _agent.ResetPath();

    public bool IsNear(Vector3 position, float threshold) =>
        Vector3.Distance(transform.position, position) <= threshold;

    // Used by EnemyAlertState to scan toward last-known-position
    public bool RotateToward(Vector3 target, float degreesPerSecond) { /* returns true when < 1° */ }
}

// Detection/NoiseSystem/NoiseEvent.cs — heap-free event payload
public readonly struct NoiseEvent
{
    public Vector3 WorldPosition { get; init; }
    public float   Intensity     { get; init; }
    public string  SourceTag     { get; init; }
}

// Detection/NoiseSystem/NoiseEmitter.cs — static fire-and-forget bus
public static class NoiseEmitter
{
    public static event Action<NoiseEvent> OnNoiseEmitted;
    public static void Emit(NoiseEvent e) => OnNoiseEmitted?.Invoke(e);
}

// Detection/NoiseSystem/NoiseListener.cs — per-enemy filtered subscriber
public class NoiseListener : MonoBehaviour
{
    [SerializeField] float _hearingRadius;
    public event Action<NoiseEvent> OnNoiseHeard;

    void OnEnable()  => NoiseEmitter.OnNoiseEmitted += HandleNoise;
    void OnDisable() => NoiseEmitter.OnNoiseEmitted -= HandleNoise;

    void HandleNoise(NoiseEvent e)
    {
        if (Vector3.Distance(transform.position, e.WorldPosition) <= _hearingRadius)
            OnNoiseHeard?.Invoke(e);
    }
}

LevelBuilder — Nine Custom Editor Tools

The Editor/LevelBuilder/ directory is nine tools designed to hand off to each other across the full layout workflow. Placement (SurfaceDropTool, BoundsSnapTool, PrefabPaletteWindow), alignment and distribution (BoundsAlignTool, DistributeTool, ScatterTool), and auditing (OverlapChecker, ComponentAuditTool) — you scatter props with ScatterTool, snap them to geometry with SurfaceDropTool, then run OverlapChecker to catch collider intersections before hitting play. LevelBuilderUtility provides the shared selection queries, undo helpers, and gizmo drawing that all nine tools depend on.

// Editor/LevelBuilder/ — all tools live here as EditorWindow or static utility classes
// Example: SurfaceDropTool drops selected transforms onto the nearest surface below

// Representative pattern (actual implementation details [VERIFY]):
public class SurfaceDropTool : EditorWindow
{
    [MenuItem("Level Builder/Surface Drop Tool")]
    static void Open() => GetWindow<SurfaceDropTool>("Surface Drop");

    void OnGUI()
    {
        if (GUILayout.Button("Drop to Surface"))
        {
            Undo.RecordObjects(Selection.transforms, "Surface Drop");
            foreach (var t in Selection.transforms)
                LevelBuilderUtility.DropToSurface(t);
        }
    }
}