Add player position tracking

This commit is contained in:
Danielv123 committed 2025-08-10 00:28:48 +02:00
1 parent 57f89de746
commit 047d3c22f5
8 files changed
+850 -16

No files matched your search

@@ -0,0 +1,111 @@
# Player Position Tracking
## Overview
Tracks player positions across the map, streams live movements to web clients, and stores compressed historical data for timeline playback.
## Architecture
### Event Flow
```mermaid
sequenceDiagram
participant Lua as Factorio Lua (minimap.lua)
participant Host as Host/Instance plugin (instance.ts)
participant Ctl as Controller plugin (controller.ts)
participant UI as Web clients
Lua->>Host: ipc-minimap:player_position (JSON)
Host->>Ctl: PlayerPositionEvent
Ctl-->>UI: PlayerPositionEvent (broadcast)
UI->>Ctl: GetPlayerPathRequest (HTTP / cluster bus)
Ctl-->>UI: compressed path data (.positions)
```
### Messages
| Message | Direction | Purpose |
| ------------------------------- | --------------------------- | ----------------------- |
| `PlayerPositionEvent` | instance → controller → web | Live position update |
| `GetPlayerPathRequest/Response` | web → controller | Fetches historical path |
## Storage Format
### Coordinate Encoding
- **Map size**: 2m × 2m (2 000 000 × 2 000 000 tiles)
- **Resolution**: 1 tile
- **Encoding**: 24-bit signed integers per coordinate (±8,388,608 tiles)
- **Storage**: 3 bytes per coordinate (x_tiles, y_tiles) (24 bits)
### Binary Record Format (append-only)
| Bytes | Field | Description |
| -------------------- | -------------------- | ---------------------------------------------- |
| 1 | `type` | `0=Position`, `1=SessionStart`, `2=SessionEnd` |
| **Position (0)** | | |
| 4 | `t_sec` (uint32) | Seconds since epoch |
| 4 | `sec` (uint32) | Seconds since map started (ticks / 60⌋) |
| 3 | `x_tiles` (int24) | X coordinate in tiles |
| 3 | `y_tiles` (int24) | Y coordinate in tiles |
| 2 | `player_id` (uint16) | Player dictionary ID |
| **SessionStart (1)** | | |
| 4 | `t_ms` (uint32) | Session start time |
| 2 | `player_id` (uint16) | Player dictionary ID |
| 1 | `name_len` (uint8) | UTF-8 byte length of player name |
| n | `name` bytes | Player name string |
| **SessionEnd (2)** | | |
| 4 | `t_ms` (uint32) | Session end time |
| 2 | `player_id` (uint16) | Player dictionary ID |
### File Organization
- Filename: `<instance>_<surface>.positions`
- Location: `database_directory/minimap_player_positions/`
- Format: Append-only binary records
### Compression Strategy
1. **Dictionary compression**: Player names stored once per session
2. **Temporal compression**: Modified Ramer-Douglas-Peucker algorithm
- ε = 15cm maximum deviation
- Min Δt = 5s when stationary
- Linear interpolation for playback
3. **Coordinate packing**: 24-bit integers instead of 32-bit floats
## Streaming Protocol
### Live Updates
- **Trigger**: Position change ≥1 tile OR 250ms timeout
### Message Format (WebSocket)
```typescript
interface PlayerPositionEvent {
playerId: string;
instanceId: string;
surface: string;
x: number; // tiles
y: number; // tiles
sec: number; // seconds since map started (⌊tick / 60⌋)
}
```
## Playback System
### Live Mode
- Web UI maintains per-player tween buffer (last 2 points)
- Canvas interpolation every animation frame
- Smooth movement without server round-trips
### Timeline Mode
- When opening the timeline, the client downloads the compressed path data for the player
- The client then interpolates the path for display
## Implementation Notes
### Saving Process
```
1. Queue position updates in positionBuffer
2. Every 250ms, process queued positions:
- Check movement threshold
- Broadcast live updates
- Buffer for compression
3. After session end:
- Run RDP downsampling
- Write compressed records
- Update session metadata
```