# Core Concepts

## Runtime Spawner 2.0 - System Overview

Runtime Spawner 2.0 is built as a **modular spawning framework** composed of a small number of core systems and optional addons.

Instead of a single tightly-coupled system, 2.0 separates responsibilities into:

* A **Core execution pipeline**
* **Addons** that define spawning behavior
* **Factories & networking layers** that control instantiation

This allows you to mix and match systems depending on your game’s needs.

### 1. Runtime Spawner (Core)

The Runtime Spawner is the **execution engine** of the system.

It is responsible for:

* Tracking active spawned instances
* Enforcing population limits
* Running the spawn pipeline
* Coordinating placement, validation, and retries
* Executing spawns via factories

Think of it as:

> “The system that actually performs spawns — everything else feeds into it.”

### 2. Spawn Entries

Spawn Entries define **what can be spawned**.

Each entry typically includes:

* Prefab (or prefab collection for randomization)
* Weight / probability
* Optional tags or categories
* Placement rules (NavMesh, hints, etc.)

Spawn Entries are :

* **Data-driven**
* Provided by addons or custom systems

### 3. The Spawn Pipeline

At runtime, spawning follows a structured pipeline:

1. **Entries are requested** (from addons or systems)
2. **A location is selected** (via hints / sampling)
3. **Placement is validated**
4. **Spawn is executed via a factory**
5. **Result is tracked and reported**

This pipeline is:

* Deterministic (when seeded)
* Extensible
* Shared across all addons

### 4. Addons (Behavior Layers)

Addons define **when, where, and why things spawn**.

They plug into the Runtime Spawner and provide spawn requests.

#### Core Addons

**Global Spawner**

* Maintains a **persistent population**
* Ideal for open-world or ambient spawning

**Local Area Spawner**

* Activates based on **player presence in a region**
* Good for encounter zones or proximity-based spawning

**Waves**

* Structured, timed spawning patterns
* Useful for combat encounters or survival modes

**Spawnpoints (New in 2.0)**

* Explicit, authored spawn locations
* Category-based matching between entries and points
* Deterministic placement (no sampling ambiguity)

> Addons can be combined — for example:
>
> * Waves inside a Local Area
> * Global population with Spawnpoint overrides

### 5. Prefab Sources & Extensibility

2.0 introduces a more flexible system for defining spawnable content:

* Addons and systems can implement:
  * `IRuntimeSpawnerPrefabSource`
  * `IRuntimeSpawnerAddon`

This allows:

* Dynamic prefab discovery
* Custom spawn systems layered on top of the core
* Clean separation between **data** and **execution**

### 6. Placement & Spawn Hints

The system supports multiple placement strategies:

* Procedural sampling (NavMesh-based)
* Spawn hints (optional scene markers)
* Spawnpoints (explicit authored placement)

Placement can be:

* Strict (exact position required)
* Flexible (best valid location)
* Ignored (for non-NavMesh objects)

### 7. Object Factory System

All spawning goes through the **Object Factory system**.

Factories control:

* How objects are instantiated
* Whether pooling is used
* Whether spawning is networked

Built-in examples:

* Local pooled factory
* Networking factories (PUN / Fusion)

You can implement your own via:

* `IObjectFactory`

### 8. Networking Layer

2.0 introduces a **shared networking abstraction layer**.

Instead of hardcoding networking logic:

* The spawner interacts with:
  * `INetworkAuthority`
  * `INetworkSpawnHandle`

Backends (like Photon PUN or Fusion) implement these interfaces.

This results in:

* Consistent behavior across networking solutions
* Cleaner separation between gameplay and networking

### 9. Population & Execution Control

The Runtime Spawner enforces:

* Global and local population limits
* Spawn cooldowns and retry logic
* Deferred spawning when placement fails

This ensures:

* Stable performance
* Predictable behavior under load
* Controlled pacing

### 10. Deterministic Behavior

The system supports deterministic seeding:

* Same seed + setup = same results

Useful for:

* Debugging
* Replays
* Network synchronization
* Procedural generation

### 11. How Everything Fits Together

At a high level:

* **Addons** decide *when and why* to spawn
* **Spawn Entries** define *what* to spawn
* **Placement systems** decide *where*
* **Factories** decide *how*
* **Runtime Spawner** executes and tracks everything

### Key Differences from 1.x

Compared to 1.x ():

* No monolithic “director-driven” system
* No tightly coupled waves + specials structure
* No implicit prefab or networking assumptions

Instead, 2.0 is:

* Modular
* Extensible
* Data-driven
* Network-agnostic

### Mental Model Shift

**1.x**

> “Configure a system that controls spawning behavior.”

**2.0**

> “Compose a pipeline using modular systems that request and execute spawns.”


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://megacrush.gitbook.io/megacrush-unity-assets/runtime-spawner/runtime-spawner-user-manual/introduction/core-concepts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.