FFSPeak

FFSPeak

Version: 0.9.0

Compatible with: PEAK 1.65.a

FFSPeak is a multiplayer observer and synchronization system for PEAK. It consists of a BepInEx plugin (Unity mod) and a Python WebSocket server that enables real-time spectating, lobby management, and item spawn synchronization.

Features

• Observer System: Watch multiple players in real-time with configurable lobbies
• Lobby Management: Create password-protected lobbies with player and time limits
• State Synchronization: Real-time player position, animation, and status updates
• Item Spawn Sync: Synchronized item spawning across all players
• API Integration: REST and SSE endpoints for score tracking and event monitoring
• Recording/Playback: Session recording and replay (⚠️ experimental, not yet complete)

Quick Start

Running Multiple PEAK Instances

To test or run multiple PEAK clients simultaneously:

• Navigate to your PEAK installation directory (e.g., SteamLibrary\steamapps\common\PEAK\)
• Create a file named steam_appid.txt next to the PEAK executable
• Add the following content:

3527290

• Launch PEAK.exe directly (not through Steam) — you can now run multiple instances

Server Setup

The Python server requires Redis as a message broker and data store.

Prerequisites

• Python: 3.10 or later
• Redis: 7.0 or later
• Windows: Redis on Windows (Memurai) or Redis via WSL
• Linux: Official Redis installation guide
• Docker (all platforms):

docker run -d --name redis -p 6379:6379 redis:7

Installation

Note: The Python server files are included package under the server/ directory. After installing the mod, you can find them in your BepInEx plugins folder at BepInEx/plugins/FFSPeak/server.

• Navigate to the server directory:

If installed

cd BepInEx/plugins/FFSPeak/server

Or if cloning from repository

cd FFSPeakServer

• Install Python dependencies:

pip install -r requirements.txt

• Start Redis (if not already running):

docker run -d --name redis -p 6379:6379 redis:7

• Launch the WebSocket server:

python server_ws.py --api-key-file api_key.txt --port 4000 --http-port 4001

Command Line Options

The server accepts the following arguments:

| Option | Default | Description |

|--------|---------|-------------|

| --port | 4000 | WebSocket server port |

| --http-port | 4001 | HTTP REST API and SSE port |

| --api-key-file | — | Path to file containing API key (recommended) |

| --api-key | — | API key as plain string (⚠️ insecure, visible in process list) |

Environment variables can also be used:

• WS_PORT, HTTP_PORT: Override default ports
• SSE_API_KEY_FILE: Path to API key file

Configuration File

Server behavior is configured via environment variables. See FFSPeakServer/docs/configuration.md for details on:

• Redis connection settings (REDIS_HOST, REDIS_PORT)
• Pub/Sub channels (REDIS_STATE_CHANNEL, REDIS_EVENTS_CHANNEL)
• Performance tuning (observer tick rates, LOD settings)

Client Configuration

Command Line Options

The FFSPeak client plugin supports several command line options for easier testing and configuration:

| Option | Aliases | Description |

|--------|---------|-------------|

| -observer | — | Force observer mode (disables player mode) |

| -player | — | Force player mode (disables observer mode) |

| -serverurl | --server-url, --serverurl, -url, --url | Override WebSocket server URL |

| -port | --port, -wsport, --ws-port, --wsport | Override WebSocket server port |

Example usage:

Launch as observer connecting to a custom server

PEAK.exe -observer -serverurl ws://example.com:4000

Launch as player with custom port

PEAK.exe -player -port 8080

Using FFSPeak (Observer Workflow)

Creating a Game (as Observer)

• Start an offline game
• Create a lobby:
• Set an optional password
• Select a level from the dropdown
• Set player limit (max players allowed)
• Set time limit (match duration)
• Freeze on Join: Toggle whether players should be frozen when they connect
• Observers can unfreeze players later