Local Area Spawner

The Local Area Spawner is a helper component used to define custom biomes / regions within your game world. Each region can provide its own set of Spawn Entries and its own local population targets, which only apply while the player is inside the volume.

LocalAreaSpawner does not spawn on its own. It is driven by the RuntimeSpawner’s Region Spawn Loop whenever the region is considered inside / active.

---

Fundamentals

Use LocalAreaSpawner when you want:

• Different spawn sets per area (streets vs interiors, forest vs town, etc.)

• Local population caps that only apply while the player is nearby

• Region-aware systems (e.g., “this biome should feel denser than that one”)

• Deterministic “player is inside” behavior for networking (via External mode)

---

Requirements

• Must have a BoxCollider on the same GameObject.

• Collider must be set to isTrigger = true.

• For Unity trigger events to fire, one collider must have a Rigidbody (typically the player).

• A RuntimeSpawner must exist in the scene; LocalAreaSpawner will auto-register with it at runtime.

---

Responsibilities

• Defines a 3D region volume where region-based spawning can occur

• Exposes a per-region min/max population target

• Holds region-specific SpawnEntry assets used while the player is inside

• Emits a canonical static event when the player enters/exits the region

• Exposes UnityEvents for designers (enter/exit/stay and region lifecycle)

• Automatically registers/unregisters itself with the RuntimeSpawner

---

Properties (Inspector)

Min Object Count / Max Object Count

Defines the region’s local population window while active.

• The Region Spawn Loop maintains a population between Min and Max while the player is inside.

• These are authoring-time values and are used unless overridden at runtime.

Restrict to NavMesh Areas (Optional)

Optionally constrain spawn placement inside this region to specific NavMesh area names.

• This applies at the region level and can be used to override broader/global constraints.

Region Spawners (Custom Region Spawners)

A list of SpawnEntry assets used only while the player is inside this region.

• Add entries via the inspector list.

• See the Spawn Entry docs for details.

Activation

New in 1.6.0:

• Activation Layers: only colliders on these layers can activate the region

• Player Tag: tag used to identify the player

• Trigger Driver Mode:

  • UnityPhysics: uses OnTriggerEnter/Exit/Stay

  • External: presence is driven by an external system (Fusion/PUN drivers)

---

Key Runtime Properties

These are the properties teams are most likely to read or modify at runtime.

Region definition

BoxCollider ThisCollider The collider that defines the region. Assigned automatically in OnEnable().

List<string> RestrictToNavmeshAreas Optional list of NavMesh area names used to constrain spawn placement in this region.

List<SpawnEntry> CustomRegionSpawners Spawn entries used only while the player is inside this region.

Population targets

int MinObjectCount Minimum number of objects the region tries to maintain while active.

int MaxObjectCount Maximum number of objects the region is allowed to maintain while active.

Runtime state

bool IsInside (preferred) True when the region is currently considered active/inside.

bool IsActiveSpawner() (back-compat helper) Legacy-style helper that returns the same value as IsInside.

Optional runtime controls

float DensityMult { get; set; } = 1f A runtime-only scalar intended for higher-level systems (director, difficulty, telemetry/UI). Not used directly by the spawn loop unless your own systems apply it.

(int min, int max) DesiredRangeOverride { get; set; } = (-1, -1) Optional runtime override for the region’s population window.

• When both min and max are non-negative, Region Spawn Loop uses this range instead of authored Min/Max.

• Set to (-1, -1) to revert to authored values.

---

Events

Static C# Event (systems)

public static event Action<LocalAreaSpawner, bool> onPlayerIsInRegion;

Raised when the player enters or exits any LocalAreaSpawner.

• LocalAreaSpawner: the region instance

• bool: true on enter, false on exit

Important behavior change from 1.5.x: In 1.6.0 this event fires only when the inside state changes (edge-triggered), not continuously every trigger stay callback.

UnityEvents (designers)

LocalAreaSpawner now provides two categories of UnityEvents:

Trigger Events (generic occupancy)

• OnTriggerEnterEvent

• OnTriggerStayEvent (invoked every frame while inside)

• OnTriggerExitEvent

• OnTriggerStateChanged(bool inside)

Region Events (domain-specific)

• OnRegionEntered

• OnRegionExited

• OnRegionStateChanged(bool inside)

---

Runtime Behavior & Lifecycle

Discovery and registration

On Start():

• Finds a RuntimeSpawner in the scene

• Pulls PlayerTag from the spawner (falls back to "Player" safely)

• Calls spawner.RegisterRegion(this)

OnDisable / OnDestroy():

• If previously registered, calls spawner.UnregisterRegion(this)

This makes it safe to enable/disable regions at runtime or load/unload them via additive scenes.

Player presence

UnityPhysics mode

When Mode == ActivationMode.UnityPhysics:

• Unity trigger callbacks call EnterRegion() / ExitRegion()

• OnTriggerStay includes a safety net for missed enters / teleports

External mode (networking)

When Mode == ActivationMode.External:

• Unity trigger callbacks are ignored

• An external driver (Fusion/PUN) is responsible for calling:

region.SetPlayerInRegion(true);  // enter
region.SetPlayerInRegion(false); // exit

---

Public API (Drivers + Designers)

These are the canonical calls for state changes:

region.EnterRegion();            // UnityEvent-friendly helper
region.ExitRegion();             // UnityEvent-friendly helper
region.SetPlayerInRegion(bool);  // canonical driver entry point

---

Typical Usage Patterns

1) Simple Region Setup (Designer Workflow)

1. Add a RuntimeSpawner to your scene and configure global settings.

2. Create an empty GameObject (e.g., Downtown Region).

3. Add:

   • BoxCollider (set isTrigger = true)

   • LocalAreaSpawner

4. Resize the BoxCollider to cover the region.

5. In the LocalAreaSpawner inspector:

   • Set Min Object Count / Max Object Count (e.g., 5–25)

   • Add SpawnEntry assets to Custom Region Spawners

6. Press Play:

   • When the player enters, the region becomes active.

   • The Region Spawn Loop maintains population between min/max while inside.

No scripting required.

---

2) Hooking into Region Enter/Exit (Music, UI, Difficulty)

using UnityEngine;
using MegaCrush.Spawner;

public class RegionHUD : MonoBehaviour
{
    private void OnEnable()
    {
        LocalAreaSpawner.onPlayerIsInRegion += HandleRegionPresence;
    }

    private void OnDisable()
    {
        LocalAreaSpawner.onPlayerIsInRegion -= HandleRegionPresence;
    }

    private void HandleRegionPresence(LocalAreaSpawner region, bool isInside)
    {
        if (isInside)
        {
            Debug.Log($"Entered region: {region.name}");
        }
        else
        {
            Debug.Log($"Left region: {region.name}");
        }
    }
}

Use this pattern for:

• “Now entering Downtown” banners

• Ambient audio switching

• Threat level / director tuning

If you need continuous “while inside” behavior, use OnTriggerStayEvent or poll region.IsInside.

---

3) Dynamic Density / Population Control (DesiredRangeOverride)

using UnityEngine;
using MegaCrush.Spawner;

public class SimpleRegionPopulationScaler : MonoBehaviour
{
    [SerializeField] private float denseMultiplier = 1.5f;
    [SerializeField] private float sparseMultiplier = 0.5f;

    public void MakeRegionDense(LocalAreaSpawner region)
    {
        region.DensityMult = denseMultiplier;

        var baseMin = region.MinObjectCount;
        var baseMax = region.MaxObjectCount;

        int scaledMin = Mathf.RoundToInt(baseMin * denseMultiplier);
        int scaledMax = Mathf.RoundToInt(baseMax * denseMultiplier);

        region.DesiredRangeOverride = (scaledMin, scaledMax);
    }

    public void MakeRegionSparse(LocalAreaSpawner region)
    {
        region.DensityMult = sparseMultiplier;

        var baseMin = region.MinObjectCount;
        var baseMax = region.MaxObjectCount;

        int scaledMin = Mathf.RoundToInt(baseMin * sparseMultiplier);
        int scaledMax = Mathf.RoundToInt(baseMax * sparseMultiplier);

        region.DesiredRangeOverride = (scaledMin, scaledMax);
    }

    public void ResetRegion(LocalAreaSpawner region)
    {
        region.DensityMult = 1f;
        region.DesiredRangeOverride = (-1, -1);
    }
}

---

4) Programmatically Creating a Region at Runtime

using UnityEngine;
using MegaCrush.Spawner;

public class RuntimeRegionBuilder : MonoBehaviour
{
    [SerializeField] private RuntimeSpawner spawner;

    public LocalAreaSpawner CreateRegion(Vector3 position, Vector3 size)
    {
        var go = new GameObject("Runtime Region");
        go.transform.position = position;

        var collider = go.AddComponent<BoxCollider>();
        collider.isTrigger = true;
        collider.size = size;

        var region = go.AddComponent<LocalAreaSpawner>();

        // Optional: assign spawner entries, caps, etc.
        // region.CustomRegionSpawners.Add(...);

        // Registration will happen automatically in Start().
        // If you need it immediately (before Start), you can register explicitly:
        if (spawner != null)
            spawner.RegisterRegion(region);

        return region;
    }
}

---

Editor-Only Helpers

public void ShowHide(bool showHide) Controls whether this region’s gizmo volume is drawn in the Scene view.

OnDrawGizmos():

• Draws the BoxCollider volume using RuntimeSpawnerSettings colors

• Uses a different color when IsInside is true