Add spawn radius and pool-based NPC spawning

[AngeloTadeucci]

Apply random offset within a SpawnRadius when spawning NPCs and snap the resulting position to the navmesh using DotRecast (with logging). Refactor TriggerContext spawn logic to build a per-spawn pool from NpcList, shuffle and cap to NpcCount, validate metadata, pass the SpawnPointNPC to SpawnNpc, and broadcast spawned NPCs. Also add required using imports and minor cleanup around spawn position handling and logging.

Summary by CodeRabbit

• Bug Fixes
  • Enhanced NPC spawn positioning to utilize designated spawn radius zones for more varied placement.
  • Improved spawn animation consistency when spawning multiple NPCs from a single spawn point.
  • Strengthened validation to ensure NPCs spawn in valid game world locations.

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request enhances NPC spawning by introducing spawn radius support with navmesh validation in the field manager, and implementing NPC pool shuffling with improved spawn animation handling in the trigger system. Method signatures are updated to pass spawn point metadata through the spawning pipeline.

Changes

Cohort / File(s)	Summary
Spawn Radius Validation Maple2.Server.Game/Manager/Field/FieldManager/FieldManager.State.cs	Added DotRecast imports and modified SpawnNpc to compute random offsets within spawn radius, validate positions against the navmesh, and snap to valid navmesh points; falls back to original position on validation failure with appropriate logging.
NPC Pool Shuffling & Signature Update Maple2.Server.Game/Trigger/TriggerContext.Npc.cs	Refactored SpawnNpc to build and shuffle an NPC ID pool, spawn up to NpcCount NPCs from shuffled selection, compute unified spawn animation strings, and pass spawnPointNpc parameter through Field.SpawnNpc call; enhanced logging for spawn details and error handling.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Adjust spawn count on triggers #622: Modifies trigger-based NPC spawning logic and EventSpawnPointNPC NpcCount usage with coordinated Field.SpawnNpc callsite changes.
• Fix: NPC spawn animation #473: Updates spawn animation determination and passes spawn-related method signatures in TriggerContext.Npc.cs.

Suggested reviewers

• Zintixx

Poem

🐰 Spawning NPCs in fields so wide,
With nav-mesh paths and shuffle as guide,
Radius checked, positions aligned,
Each bunny's placement thoughtfully designed!
The pool now dances, a random ballet,
Creating wonder in every way! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely summarizes the main changes: adding spawn radius functionality and implementing pool-based NPC spawning logic.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch spawnpoints

---

No actionable comments were generated in the recent review. 🎉

🧹 Recent nitpick comments

Maple2.Server.Game/Manager/Field/FieldManager/FieldManager.State.cs (1)

110-117: Non-uniform spatial distribution: NPCs will cluster near the center of the spawn radius.

distance = Random * radius produces a linear distribution, which biases spawn positions toward the center of the circle (the probability density per unit area decreases with distance). For a uniform distribution over the disk area, use sqrt(Random) * radius:

♻️ Suggested fix

-            float distance = Random.Shared.NextSingle() * spawnPointNpc.SpawnRadius;
+            float distance = MathF.Sqrt(Random.Shared.NextSingle()) * spawnPointNpc.SpawnRadius;

This may or may not matter depending on the desired game feel — center-biased spawning could be intentional. Flagging for awareness.

Maple2.Server.Game/Trigger/TriggerContext.Npc.cs (1)

312-316: spawnAnimationString is loop-invariant — consider hoisting it above the loop.

The animation string doesn't depend on npcId and is recomputed identically each iteration.

♻️ Suggested fix

+        string spawnAnimationString = string.Empty;
+        if (!string.IsNullOrEmpty(spawn.SpawnAnimation) && useSpawnAnimation) {
+            spawnAnimationString = spawn.SpawnAnimation;
+        }
+
         foreach (int npcId in npcIdsToSpawn) {
             if (!Field.NpcMetadata.TryGet(npcId, out NpcMetadata? npc)) {
                 logger.Error("[SpawnNpc] Invalid npcId:{NpcId}", npcId);
                 continue;
             }
 
-            string spawnAnimationString = string.Empty;
-            if (!string.IsNullOrEmpty(spawn.SpawnAnimation) && useSpawnAnimation) {
-                spawnAnimationString = spawn.SpawnAnimation;
-            }
             FieldNpc? fieldNpc = Field.SpawnNpc(npc, spawn.Position, spawn.Rotation, spawnPointNpc: spawn, spawnAnimation: spawnAnimationString);

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}