Merge pull request #2 from stinowdev/develop

feat:  collectible behavior for brandishing lit torches and update docs

Author: stinowdev

CHANGELOG.md

@@ -4,15 +4,15 @@ All notable changes to this project will be documented in this file.
 
 Feature (F) and decision (D) numbers refer to [FEATURES.md](FEATURES.md).
 
-## [v0.1.0]
+## [Unreleased]
 
 ### Added
 
 - Initial Pyrophobia project scaffold.
 - Universal client and server mod entry point.
 - F01: hold right-click with no block targeted to brandish a lit main-hand
-  torch, with third- and first-person raise animations. Block-targeted
-  right-clicks keep vanilla placement, relighting, and ignition.
+  torch (collectible behavior), with third- and first-person raise animations.
+  Block-targeted right-clicks keep vanilla placement, relighting, and ignition.
 - Initial design baseline for torch, fire, and wildlife interactions.
 - Local build and packaging script.
 - GitHub Actions build and draft-release workflow.

FEATURES.md

@@ -49,23 +49,13 @@ is in the main hand. Scoping the stance to actual threats is F02/F03 work.
 | D05 | Planned | A scare probability is evaluated on controlled intervals, not every game tick. |
 | 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. |
 
-## Design notes
+## Extension inventory
 
-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
-
-The scaffold has no runtime configuration yet. Add serialized settings only
+| 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).

resources/modinfo.json

@@ -8,7 +8,6 @@
   "side": "universal",
   "requiredOnClient": true,
   "requiredOnServer": true,
-  "networkVersion": "1.0.0",
   "dependencies": {
     "game": "1.22.3"
   }

src/Behaviors/CollectibleBehaviorBrandishTorch.cs

@@ -0,0 +1,176 @@
+using System;
+using System.Collections.Concurrent;
+using Vintagestory.API.Common;
+using Vintagestory.API.Common.Entities;
+using Vintagestory.GameContent;
+
+namespace Pyrophobia.Behaviors;
+
+/// <summary>
+/// F01 / D08: brandish a lit main-hand torch (universal, main thread).
+/// Prepended ahead of <c>CanIgnite</c>; stance is in-memory, not Attributes.
+/// </summary>
+public class CollectibleBehaviorBrandishTorch : CollectibleBehavior
+{
+    public const string ClassName = "BrandishTorch";
+    private const string TorchBrandishAnimation = "pyrophobia-brandishtorch";
+
+    // Cleared in ModSystem.Dispose.
+    private static readonly ConcurrentDictionary<long, byte> BrandishingByEntityId = new();
+
+    public CollectibleBehaviorBrandishTorch(CollectibleObject collObj)
+        : base(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>
+    public override void OnHeldInteractStart(
+        ItemSlot slot,
+        EntityAgent byEntity,
+        BlockSelection blockSel,
+        EntitySelection entitySel,
+        bool firstEvent,
+        ref EnumHandHandling handHandling,
+        ref EnumHandling handling)
+    {
+        if (!IsBrandishableTorch(slot, byEntity))
+        {
+            return;
+        }
+
+        if (byEntity.Controls.ShiftKey || blockSel != null)
+        {
+            SetBrandishing(byEntity, false);
+            return;
+        }
+
+        SetBrandishing(byEntity, true);
+        handHandling = EnumHandHandling.PreventDefault;
+        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,
+        EntityAgent byEntity,
+        BlockSelection blockSel,
+        EntitySelection entitySel,
+        ref EnumHandling handling)
+    {
+        if (!IsBrandishing(byEntity))
+        {
+            return false;
+        }
+
+        handling = EnumHandling.PreventSubsequent;
+        return true;
+    }
+
+    /// <summary>
+    /// Accept cancellation (release / swap) and ease the stance out.
+    /// </summary>
+    public override bool OnHeldInteractCancel(
+        float secondsUsed,
+        ItemSlot slot,
+        EntityAgent byEntity,
+        BlockSelection blockSel,
+        EntitySelection entitySel,
+        EnumItemUseCancelReason cancelReason,
+        ref EnumHandling handled)
+    {
+        if (!IsBrandishing(byEntity))
+        {
+            return true;
+        }
+
+        SetBrandishing(byEntity, false);
+        handled = EnumHandling.PreventSubsequent;
+        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,
+        EntityAgent byEntity,
+        BlockSelection blockSel,
+        EntitySelection entitySel,
+        ref EnumHandling handling)
+    {
+        if (!IsBrandishing(byEntity))
+        {
+            return;
+        }
+
+        SetBrandishing(byEntity, false);
+        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,
+        ref EnumHandling bhHandling)
+    {
+        if (forEntity is EntityAgent agent &&
+            IsBrandishing(agent) &&
+            IsBrandishableTorch(activeHotbarSlot, forEntity))
+        {
+            bhHandling = EnumHandling.PreventDefault;
+            return TorchBrandishAnimation;
+        }
+
+        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 ||
+            torch.IsExtinct ||
+            collObj.Code?.Path.Contains("torch", StringComparison.OrdinalIgnoreCase) != true ||
+            slot.Itemstack?.Collectible != collObj ||
+            byEntity is not EntityPlayer entityPlayer ||
+            !ReferenceEquals(slot, entityPlayer.RightHandItemSlot))
+        {
+            return false;
+        }
+
+        return true;
+    }
+
+    private static bool IsBrandishing(EntityAgent byEntity) =>
+        BrandishingByEntityId.ContainsKey(byEntity.EntityId);
+
+    private static void SetBrandishing(EntityAgent byEntity, bool value)
+    {
+        if (value)
+        {
+            BrandishingByEntityId[byEntity.EntityId] = 0;
+        }
+        else
+        {
+            BrandishingByEntityId.TryRemove(byEntity.EntityId, out _);
+        }
+    }
+}