Npcs/Combat/CombatEngageSchedule.cs

An NPC combat schedule that engages a visible player: sets look target, optionally plays spot/taunt lines, moves to weapon range, fires, waits between bursts and sometimes repositions to a flank. It cancels if the target or weapon become invalid or the target has been out of sight longer than a grace period.

NetworkingFile Access
using Sandbox.Npcs.Tasks;

namespace Sandbox.Npcs.CombatNpc;

/// <summary>
/// Engages a visible player: close the gap, fire a burst, pause, then reposition to a flanking point.
/// Cancels immediately if the target leaves sight.
/// </summary>
public class CombatEngageSchedule : ScheduleBase
{
	private static readonly string[] SpotLines =
	{
		"#npc.speech.combat.spot.1",
		"#npc.speech.combat.spot.2",
		"#npc.speech.combat.spot.3",
		"#npc.speech.combat.spot.4",
		"#npc.speech.combat.spot.5",
		"#npc.speech.combat.spot.6",
		"#npc.speech.combat.spot.7",
	};

	private static readonly string[] TauntLines =
	{
		"#npc.speech.combat.taunt.1",
		"#npc.speech.combat.taunt.2",
		"#npc.speech.combat.taunt.3",
		"#npc.speech.combat.taunt.4",
		"#npc.speech.combat.taunt.5",
		"#npc.speech.combat.taunt.6",
		"#npc.speech.combat.taunt.7",
		"#npc.speech.combat.taunt.8",
	};

	/// <summary>
	/// The player to engage.
	/// </summary>
	public GameObject Target { get; set; }

	/// <summary>
	/// Weapon to fire. Should be a child component on the NPC's GameObject. Its NPC usage decides
	/// the engagement range, burst length and the rest between bursts.
	/// </summary>
	public BaseSandboxWeapon Weapon { get; set; }

	/// <summary>
	/// Speed the NPC moves when engaging.
	/// </summary>
	public float EngageSpeed { get; set; } = 180f;

	/// <summary>
	/// Speed the NPC strafes at when it repositions without sprinting.
	/// </summary>
	public float StrafeSpeed { get; set; } = 85f;

	/// <summary>
	/// Chance to reposition after a burst. Otherwise the NPC holds its ground and fires again.
	/// </summary>
	public float RepositionChance { get; set; } = 0.35f;

	/// <summary>
	/// Seconds to react before the first burst - set for a fresh contact, zero while a fight is
	/// already going. The NPC calls the contact out, turns to face it and brings its weapon up in
	/// this time, and won't fire before it's up however quickly those finish.
	/// </summary>
	public float ReactionTime { get; set; }

	private TimeUntil _reacted;

	/// <summary>
	/// How long the target can drop out of sight (ducking behind something, a glimpse through a
	/// gap) before we give up on this engagement and go searching instead.
	/// </summary>
	public float LostSightGrace { get; set; } = 0.75f;

	private TimeSince _timeSinceVisible;

	/// <summary>
	/// Radius around the current position to pick a flanking point.
	/// </summary>
	public float FlankRadius { get; set; } = 250f;

	public override int Priority => SchedulePriority.Combat;

	// Stay focused while fighting -- we end via ShouldCancel (lost sight) or when the
	// task sequence finishes, not because of incidental stimuli.
	public override NpcAwareness InterruptedBy => NpcAwareness.None;

	protected override void OnStart()
	{
		if ( !Target.IsValid() || !Weapon.IsValid() )
			return;

		// Set look target now so the NPC tracks the player through all tasks,
		// movement, firing, waiting, and repositioning.
		Npc.Animation.SetLookTarget( Target );

		_timeSinceVisible = 0;

		// A fresh contact gets called out (if the speech system lets us), then we hold fire until
		// the reaction time is up - counted from now, so the callout and the turn eat into it
		var freshContact = ReactionTime > 0f;
		_reacted = ReactionTime;

		if ( freshContact && Npc.Speech.CanSpeak )
			AddTask( new Say( Game.Random.FromArray( SpotLines ), 1.5f, Target )
			{
				Tags = ["combat", "spot"],
				Priority = 2000
			} );

		AddTask( new LookAt( Target ) );

		if ( freshContact )
			AddTask( new AwaitReaction( this ) );

		// Advance to comfortably inside the weapon's reach, not right on the edge of it.
		AddTask( new MoveTo( Target, Weapon.Npc.MaxRange * 0.8f ) { Speed = EngageSpeed, FaceTarget = Target } );
		AddTask( new FireWeapon( Weapon, Target ) );

		// Rest between bursts, as the weapon dictates - with a random combat taunt sometimes
		var rest = Game.Random.Float( Weapon.Npc.RestMin, Weapon.Npc.RestMax );
		if ( Npc.Speech.CanSpeak && Game.Random.Float() < 0.4f )
			AddTask( new Say( Game.Random.FromArray( TauntLines ), rest, Target )
			{
				Tags = ["combat", "taunt"]
			} );
		else
			AddTask( new Wait( rest ) );

		// Now and then, strafe to a new spot - most of the time hold position and keep shooting
		if ( Game.Random.Float() < RepositionChance )
			AddTask( new MoveTo( GetFlankPosition(), 20f ) { Speed = StrafeSpeed, FaceTarget = Target } );
	}

	protected override void OnEnd()
	{
		Npc.Animation.ClearLookTarget();
	}

	protected override bool ShouldCancel()
	{
		if ( !Target.IsValid() || !Weapon.IsValid() )
			return true;

		if ( Npc.Senses.VisibleTargets.Contains( Target ) )
			_timeSinceVisible = 0;

		return _timeSinceVisible > LostSightGrace;
	}

	/// <summary>
	/// Holds until the schedule's reaction time is up, however long the tasks before it took.
	/// </summary>
	private sealed class AwaitReaction : TaskBase
	{
		private readonly CombatEngageSchedule _engage;

		public AwaitReaction( CombatEngageSchedule engage ) => _engage = engage;

		protected override TaskStatus OnUpdate() => _engage._reacted ? TaskStatus.Success : TaskStatus.Running;
	}

	/// <summary>
	/// Pick a random position perpendicular to the NPC→target axis at <see cref="FlankRadius"/>.
	/// Snaps to navmesh if possible.
	/// </summary>
	private Vector3 GetFlankPosition()
	{
		Vector3 toTarget = Target.IsValid()
			? (Target.WorldPosition - Npc.WorldPosition).WithZ( 0 ).Normal
			: Npc.WorldRotation.Forward;

		// Perpendicular + slight forward bias, randomized left/right
		var perp = new Vector3( -toTarget.y, toTarget.x, 0 );
		var side = Game.Random.Float() > 0.5f ? 1f : -1f;
		var flankDir = (perp * side + toTarget * 0.3f).WithZ( 0 ).Normal;
		var candidate = Npc.WorldPosition + flankDir * Game.Random.Float( FlankRadius * 0.5f, FlankRadius );

		if ( Npc.Scene.NavMesh.GetClosestPoint( candidate ) is { } nav )
			return nav;

		return candidate;
	}
}