[Plugin] Streamer Plugin v3.0.0 — 2026 Edition

[carlosmcgrimes]

Code:

# Streamer Plugin v3.0.0 — 2026 Edition
**Full compatibility with SA-MP 0.3.7 and open.mp.**

A high-performance streaming plugin that dynamically streams objects, pickups, checkpoints, map icons, 3D text labels, areas, and actors based on player proximity — bypassing the 1000-object SA-MP engine limit.

---

## What's New in v3.0.0

| System | Description |
|--------|-------------|
| **Predictive Streaming** | Tracks player velocity and pre-streams items ahead of movement direction, reducing visible pop-in at high speeds |
| **LOD (Level of Detail)** | Assign lower-detail substitute models that appear automatically beyond configurable distances |
| **Statistics** | Real-time metrics: frame-time, cache hit ratio, and per-type object counters |
| **Named Zones** | Tag map regions by name and group items inside them — toggle entire zones with a single call |
| **Batch Operations** | Create or destroy hundreds of items in a single tick, ideal for loading large maps on startup |
| **Config File** | `streamer.cfg` in the server root for operator tuning without recompiling; hot-reload via PAWN |
| **Logger** | Levelled (INFO/WARN/ERROR), file-backed, thread-safe logging for production diagnostics |
| **Camera Culling** | Per-player option to skip objects outside the camera frustum, reducing load in dense scenes |

---

## Predictive Streaming

Analyzes recent player positions to estimate future position and dynamically expand the streaming radius in the direction of travel.

**How it works:**
- Samples each player's position every tick and computes average velocity
- Projects future position: `predictedPos = pos + velocity × lookaheadTime`
- Expands the streaming radius in that direction up to a configurable maximum (`maxLookahead`)
- No extra radius is applied when the player is stationary

**Configuration (`streamer.cfg`):**
```ini
predictorEnabled    = 1      # 1 = active, 0 = disabled
predictorLookahead  = 1.5    # look-ahead time in seconds
```

Works automatically — no extra PAWN code required.

---

## LOD — Level of Detail

Assign alternative models to objects that are shown automatically when the player exceeds a certain distance. Multiple levels can be chained per object.

**PAWN functions:**
```pawn
Streamer_SetObjectLOD(objectid, lodModelId, distance);
Streamer_RemoveObjectLOD(objectid);
```

**Example:**
```pawn
new obj = CreateDynamicObject(1337, 0.0, 0.0, 3.0, 0.0, 0.0, 0.0);

// Beyond 150 units → model 1338 (simpler)
Streamer_SetObjectLOD(obj, 1338, 150.0);

// Beyond 400 units → model 1339 (minimum detail)
Streamer_SetObjectLOD(obj, 1339, 400.0);
```

Levels are sorted automatically by distance. The engine picks the correct model based on the real player–object distance each frame.

---

## Named Zones

Group streamer items under named map regions. Ideal for interiors, districts, or event areas that need to be toggled on/off as a group.

**PAWN functions:**
```pawn
new zoneid = Streamer_CreateZone("ZoneName", minX, minY, maxX, maxY);
Streamer_AddItemToZone(zoneid, STREAMER_TYPE_OBJECT, objectid);
Streamer_ToggleZone(zoneid, false);  // hide everything in zone
Streamer_ToggleZone(zoneid, true);  // show everything in zone
Streamer_DestroyZone(zoneid);
```

**Example:**
```pawn
new zone = Streamer_CreateZone("PvP_Arena", -500.0, -500.0, 500.0, 500.0);
Streamer_AddItemToZone(zone, STREAMER_TYPE_OBJECT, obj1);
Streamer_AddItemToZone(zone, STREAMER_TYPE_PICKUP, pickup1);

// When the event ends:
Streamer_ToggleZone(zone, false); // clears the entire scene at once
```

---

## Batch Operations

Create or destroy large numbers of items in a single tick, avoiding the overhead of processing each item individually.

**PAWN functions:**
```pawn
new batchid = Streamer_BeginBatch();
Streamer_BatchCreateObject(batchid, modelid, x, y, z);
new ids[MAX], count = Streamer_CommitBatch(batchid, ids);
```

**Example:**
```pawn
new batch = Streamer_BeginBatch();
for (new i = 0; i < 500; i++)
    Streamer_BatchCreateObject(batch, 1337, float(i) * 5.0, 0.0, 3.0);

new ids[500];
printf("%d objects created", Streamer_CommitBatch(batch, ids));
```

---

## Config File (streamer.cfg)

Place in the server root. All parameters are optional — defaults are used if the file is absent.

```ini
# Core
tickRate            = 50      # ms between streamer updates
cellSize            = 300.0    # spatial grid cell size (SA-MP units)
cellDistance        = 600.0    # default max streaming distance

# Predictive streaming
predictorEnabled    = 1
predictorLookahead  = 1.5

# Logging
logLevel            = 1        # 0=off  1=info  2=warn  3=error
logFile            = streamer.log
```

**Hot-reload from PAWN:**
```pawn
Streamer_ReloadConfig(); // re-reads streamer.cfg without restarting
```

---

## Statistics

Exposes real-time performance metrics accessible from PAWN or printed to the server console.

```pawn
Streamer_PrintStats(); // prints full report to server console
```

Metrics include: active items per type, cache hit/miss ratio, average frame-time over the last second, and peak frame-time.

---

## Installation

### SA-MP
1. Copy `streamer.dll` (Windows) or `streamer.so` (Linux) to `server/plugins/`
2. Add to `server.cfg`: `plugins streamer`
3. Optionally place `streamer.cfg` in the server root
4. Copy `streamer.inc` to `pawno/include/`

### open.mp
1. Copy the plugin binary to `plugins/`
2. Add to `config.json`: `"plugins": ["streamer"]`
3. Optionally place `streamer.cfg` in the server root

---

## Credits

- **Original plugin:** Incognito
- **v2.9.7 improvements & v3.0.0 systems:** eLdarQo
- **License:** Apache License 2.0

https://github.com/DarkCarlox/samp-strea.../tag/3.0.0