feat: implement brandish scare mechanic for hostiles targeting players

Author: stinowdev

CHANGELOG.md

@@ -13,16 +13,17 @@ Feature (F) and decision (D) numbers refer to [FEATURES.md](FEATURES.md).
 - F01: hold right-click with no block targeted to brandish a lit main-hand
   torch (collectible behavior), with third- and first-person raise animations.
   Block-targeted right-clicks keep vanilla placement, relighting, and ignition.
+- F02a: brandishing has a periodic chance to make nearby hostiles that are
+  targeting the player flee (vanilla AI).
 - Initial design baseline for torch, fire, and wildlife interactions.
 - Local build and packaging script.
 - GitHub Actions build and draft-release workflow.
 - Starter project, design, release, and testing documentation.
 
 ### Known limitations
 
-- Animals do not react to the brandished torch yet.
+- Only brandish scare so far - ground fires and richer reactions are later.
 - Aiming at an entity with a lit main-hand torch brandishes instead of
   running right-click entity interactions such as boarding a boat.
 - Runtime configuration does not exist yet.
-- Entity targeting, fire-source integration, and animal reaction rules remain
-  planned work.
+- Dedicated-server brandish->scare sync still needs a playtest confirmation.

FEATURES.md

@@ -9,7 +9,7 @@ history belongs in [CHANGELOG.md](CHANGELOG.md).
 | ID | Status | Feature | Config key | Default | Authority |
 |---|---|---|---|---|---|
 | F01 | Implemented | Hold right-click to brandish a lit main-hand torch | - | - | Universal |
-| F02 | Planned | Fire sources, including a brandished torch, influence nearby animal behavior | - | - | Server |
+| F02 | In progress | Fire sources influence nearby animals — F02a brandish scare done; ground fires later | - | range 12 / chance 0.25 / 1s | Server |
 | F03 | Planned | Animals can flee, disengage, investigate, or ignore fire | - | - | Server |
 | F04 | Planned | Configure fire sources, ranges, probabilities, and reactions | - | - | Server |
 
@@ -46,16 +46,39 @@ is in the main hand. Scoping the stance to actual threats is F02/F03 work.
 | D02 | Active | Release metadata is owned by `resources/modinfo.json`. |
 | D03 | Active | The server is authoritative for animal reactions and probability checks. |
 | D04 | Active | The first scope is hostile animals targeting or aggressive toward the player. |
-| D05 | Planned | A scare probability is evaluated on controlled intervals, not every game tick. |
+| D05 | Active | Scare checks run on a server tick interval (~1s), not every frame. |
 | D06 | Planned | Fire reactions are configurable per fire source and animal behavior profile. |
 | D07 | Active | Brandishing uses the interact (right-click) channel and only begins with no block targeted, because vanilla assigns every block-targeted right-click of a lit torch: plain right-click places it and `CanIgnite` owns the shift ignite gesture. Block-targeted input reaches the mod untouched. |
 | D08 | Active | F01 is a `CollectibleBehavior` prepended onto lit torches in `AssetsFinalize` (both sides), not Harmony. Must run before `CanIgnite` and use `PreventSubsequent` while raised so aim-crossing a block cannot start fires. Code attach (not a JSON patch) so we can skip extinct / non-torch `BlockTorch` assets. |
+| D09 | Active | F02 ships in slices. F02a: brandished torch only — no ground fires, no config. Later: placed fire sources (F02b), richer reactions (F03). |
+| D10 | Active | F02a calls vanilla `AiTaskFleeEntity` / `AiTaskFleeEntityR`.InstaFleeFrom when an active aggressive targetable task is targeting the brandishing player. No custom AI task. |
 
 ## Extension inventory
 
 | Kind | Type | Side | Feature | Notes |
 |---|---|---|---|---|
 | CollectibleBehavior | `BrandishTorch` | Universal | F01 | Prepended in `AssetsFinalize` on lit `BlockTorch`. Stance is in-memory, not `Attributes`. |
-erialized settings only
-when a feature uses them, define ownership and synchronization here, and
-document user-facing values in [README.md](README.md).
+| Server tick | `BrandishScareService` | Server | F02a | 1s interval; range 12; flee chance 0.25. |
+
+## F02a (done)
+
+Brandishing players: nearby hostiles actively targeting them get a periodic chance to flee via `InstaFleeFrom`. No network channel — relies on use sync for server brandish state (confirm on dedicated server).
+
+**Later:** F02b ground fires, F03 reaction profiles, F04 config.
+## Design notes
+
+Fire is treated as a signal, not a universal fear effect. A torch held up by
+the player may be more immediate and threatening than a distant firepit. Some
+predatory animals may investigate an isolated fire, creating a configurable
+counter-effect rather than a guaranteed safety zone.
+
+The first release should distinguish between:
+
+- fleeing from the player;
+- abandoning an active pursuit without fleeing;
+- investigating a fire source; and
+- remaining unaffected.
+
+## Configuration contract
+
+No runtime config yet. F04 adds it when reactions need knobs.

README.md

@@ -4,9 +4,9 @@ Pyrophobia is a universal code Vintage Story mod about the relationship between
 wildlife: raise a torch to deter hostile animals, while torches and fires in
 the world influence how nearby animals behave.
 
-The mod currently implements the brandish stance: holding right-click with a
-lit torch in the main hand raises it defensively, in first and third person.
-Animal reactions to the raised torch are the next implementation step.
+The mod currently implements the brandish stance and a first animal reaction:
+holding right-click with a lit torch raises it, and nearby hostiles that are
+targeting you may flee while it is raised.
 
 ## Compatibility
 

src/Behaviors/CollectibleBehaviorBrandishTorch.cs

@@ -25,11 +25,10 @@ public CollectibleBehaviorBrandishTorch(CollectibleObject collObj)
 
     internal static void ResetStanceState() => BrandishingByEntityId.Clear();
 
-    /// <summary>
-    /// PreventDefault marks the use as handled so the caller sets
-    /// <c>Controls.HandUse</c>. With a block targeted or Shift held we
-    /// PassThrough, which keeps placement, relighting, and CanIgnite vanilla.
-    /// </summary>
+    /// <summary>Query for F02 scare checks (populated on both sides via use sync).</summary>
+    internal static bool IsBrandishing(EntityAgent byEntity) =>
+        BrandishingByEntityId.ContainsKey(byEntity.EntityId);
+
     public override void OnHeldInteractStart(
         ItemSlot slot,
         EntityAgent byEntity,
@@ -55,10 +54,6 @@ public override void OnHeldInteractStart(
         handling = EnumHandling.PreventDefault;
     }
 
-    /// <summary>
-    /// Keep HandUse active for the hold duration, even when aim later crosses
-    /// a block. PreventSubsequent stops CanIgnite from treating that as ignite.
-    /// </summary>
     public override bool OnHeldInteractStep(
         float secondsUsed,
         ItemSlot slot,
@@ -76,9 +71,6 @@ public override bool OnHeldInteractStep(
         return true;
     }
 
-    /// <summary>
-    /// Accept cancellation (release / swap) and ease the stance out.
-    /// </summary>
     public override bool OnHeldInteractCancel(
         float secondsUsed,
         ItemSlot slot,
@@ -98,11 +90,6 @@ public override bool OnHeldInteractCancel(
         return true;
     }
 
-    /// <summary>
-    /// Brandishing produces no effect on stop. PreventSubsequent keeps
-    /// CanIgnite's stop handler from starting fires after a long hold that
-    /// began as a brandish and later aimed at a block.
-    /// </summary>
     public override void OnHeldInteractStop(
         float secondsUsed,
         ItemSlot slot,
@@ -120,10 +107,6 @@ public override void OnHeldInteractStop(
         handling = EnumHandling.PreventSubsequent;
     }
 
-    /// <summary>
-    /// Only active brandishes get the stance animation; vanilla uses such as
-    /// the ignite gesture keep their own animation.
-    /// </summary>
     public override string GetHeldTpUseAnimation(
         ItemSlot activeHotbarSlot,
         Entity forEntity,
@@ -140,10 +123,6 @@ public override string GetHeldTpUseAnimation(
         return null!;
     }
 
-    /// <summary>
-    /// Lit main-hand torch only. Slot identity keeps mirrored calls for other
-    /// slots or entities on their vanilla path.
-    /// </summary>
     private bool IsBrandishableTorch(ItemSlot slot, Entity byEntity)
     {
         if (collObj is not BlockTorch torch ||
@@ -159,9 +138,6 @@ byEntity is not EntityPlayer entityPlayer ||
         return true;
     }
 
-    private static bool IsBrandishing(EntityAgent byEntity) =>
-        BrandishingByEntityId.ContainsKey(byEntity.EntityId);
-
     private static void SetBrandishing(EntityAgent byEntity, bool value)
     {
         if (value)

src/PyrophobiaModSystem.cs

@@ -1,5 +1,6 @@
 using System;
 using Pyrophobia.Behaviors;
+using Pyrophobia.Scare;
 using Vintagestory.API.Client;
 using Vintagestory.API.Common;
 using Vintagestory.API.Server;
@@ -9,11 +10,16 @@ namespace Pyrophobia;
 
 /// <summary>
 /// Pyrophobia entry point. F01 attaches in <see cref="AssetsFinalize"/> (D08).
+/// F02a scare tick is server-only (D03).
 /// </summary>
 public class PyrophobiaModSystem : ModSystem
 {
     public const string ModId = "pyrophobia";
 
+    private ICoreServerAPI? sapi;
+    private BrandishScareService? scare;
+    private long scareListenerId;
+
     public override void Start(ICoreAPI api)
     {
         base.Start(api);
@@ -77,11 +83,24 @@ public override void StartClientSide(ICoreClientAPI api)
     public override void StartServerSide(ICoreServerAPI api)
     {
         base.StartServerSide(api);
-        api.Logger.Notification("[{0}] server side loaded.", ModId);
+        sapi = api;
+        scare = new BrandishScareService(api);
+        scareListenerId=api.Event.RegisterGameTickListener(scare.OnTick,
+            e => api.Logger.Error("[{0}] brandish scare tick failed: {1}", ModId, e),
+            BrandishScareService.IntervalMs);
+        api.Logger.Notification("[{0}] server side loaded (F02a scare every {1}ms).", ModId, BrandishScareService.IntervalMs);
     }
 
     public override void Dispose()
     {
+        if (sapi != null && scareListenerId != 0)
+        {
+            sapi.Event.UnregisterGameTickListener(scareListenerId);
+            scareListenerId = 0;
+        }
+
+        scare = null;
+        sapi = null;
         CollectibleBehaviorBrandishTorch.ResetStanceState();
         base.Dispose();
     }

src/Scare/BrandishScareService.cs

@@ -0,0 +1,103 @@
+using Pyrophobia.Behaviors;
+using Vintagestory.API.Common;
+using Vintagestory.API.Common.Entities;
+using Vintagestory.API.Server;
+using Vintagestory.GameContent;
+
+namespace Pyrophobia.Scare;
+
+/// <summary>
+/// F02a / D03–D05 / D09–D10: server tick - brandishing players periodically
+/// scare hostiles that are actively targeting them via vanilla InstaFleeFrom.
+/// (Main thread. Hardcoded knobs until F04)
+/// </summary>
+internal sealed class BrandishScareService
+{
+    internal const float Range = 12f;
+    internal const float FleeChance = 0.25f;
+    internal const int IntervalMs = 1000;
+
+    private readonly ICoreServerAPI sapi;
+
+    public BrandishScareService(ICoreServerAPI sapi)
+    {
+        this.sapi = sapi;
+    }
+
+    public void OnTick(float dt)
+    {
+        foreach (IPlayer player in sapi.World.AllOnlinePlayers)
+        {
+            if (player.Entity is not EntityPlayer playerEntity || !playerEntity.Alive)
+            {
+                continue;
+            }
+
+            if (!CollectibleBehaviorBrandishTorch.IsBrandishing(playerEntity))
+            {
+                continue;
+            }
+
+            ScareAround(playerEntity);
+        }
+    }
+
+    private void ScareAround(EntityPlayer playerEntity)
+    {
+        long playerId = playerEntity.EntityId;
+        Entity[] nearby = sapi.World.GetEntitiesAround(
+            playerEntity.Pos.XYZ,
+            Range,
+            Range,
+            e => e is EntityAgent agent && agent.Alive && agent.EntityId != playerId);
+
+        foreach (Entity entity in nearby)
+        {
+            EntityBehaviorTaskAI? taskAi = entity.GetBehavior<EntityBehaviorTaskAI>();
+            if (taskAi == null)
+            {
+                continue;
+            }
+
+            if (!IsAggressivelyTargeting(taskAi.TaskManager, playerId))
+            {
+                continue;
+            }
+
+            if (sapi.World.Rand.NextDouble() >= FleeChance)
+            {
+                continue;
+            }
+
+            TryInstaFlee(taskAi.TaskManager, playerEntity);
+        }
+    }
+
+    private static bool IsAggressivelyTargeting(AiTaskManager tasks, long playerEntityId)
+    {
+        foreach (IAiTask? task in tasks.ActiveTasksBySlot)
+        {
+            if (task is AiTaskBaseTargetable targetable &&
+                targetable.AggressiveTargeting &&
+                targetable.TargetEntity?.EntityId == playerEntityId)
+            {
+                return true;
+            }
+
+            if (task is AiTaskBaseTargetableR targetableR &&
+                targetableR.AggressiveTargeting &&
+                targetableR.TargetEntity?.EntityId == playerEntityId)
+            {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    private static void TryInstaFlee(AiTaskManager tasks, Entity playerEntity)
+    {
+        tasks.GetTask<AiTaskFleeEntity>()?.InstaFleeFrom(playerEntity);
+        tasks.GetTask<AiTaskFleeEntityR>()?.InstaFleeFrom(playerEntity);
+    }
+}