# Subnautica Ii Coop Multiplayer Mod

> BepInEx-based multiplayer mod for Subnautica 2 enabling synchronized cooperative gameplay with shared inventory, base building, and AI integration

- Skill: `aradotso/subnautica-ii-coop-multiplayer-mod` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aradotso/subnautica-ii-coop-multiplayer-mod`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aradotso/subnautica-ii-coop-multiplayer-mod/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: aradotso (https://skillmd.com/u/aradotso)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aradotso/subnautica-ii-coop-multiplayer-mod

---


# Subnautica II Deep Synergy Multiplayer Mod

> Skill by [ara.so](https://ara.so) — Devtools Skills collection.

## Overview

The Deep Synergy Multiplayer Mod transforms Subnautica 2 into a cooperative survival experience using BepInEx's IL2CPP modding framework. It implements deterministic session synchronization, peer-to-peer networking via WebRTC, and optional AI integration for narrative generation.

**Key Capabilities:**
- Synchronized multiplayer sessions (2-8 players)
- Shared inventory and base building with conflict resolution
- Adaptive difficulty scaling based on player count
- Cross-platform support (Windows, Linux, macOS)
- BepInEx plugin architecture (no game file modification)
- Optional OpenAI/Claude API integration for dynamic narration

## Installation

### Prerequisites

1. **Subnautica 2** installed via Steam/GOG
2. **BepInEx 6.0.x** for Unity IL2CPP games

### Step-by-Step Installation

```bash
# 1. Navigate to Subnautica 2 installation directory
cd "C:\Program Files (x86)\Steam\steamapps\common\Subnautica2"

# 2. Install BepInEx (if not already installed)
# Download BepInEx_UnityIL2CPP_x64 from https://github.com/BepInEx/BepInEx/releases
# Extract to game root directory

# 3. Download Deep Synergy mod from release page
# Extract DeepSynergy.dll to BepInEx/plugins/

# 4. Verify installation structure
BepInEx/
├── plugins/
│   └── DeepSynergy.dll
├── config/
│   └── synergy_profile.json (created on first run)
└── core/
    └── (BepInEx core files)
```

## Configuration

### Basic Session Profile

Create `BepInEx/config/synergy_profile.json`:

```json
{
  "session_name": "MyCoopSession",
  "max_players": 4,
  "difficulty_scale": "adaptive",
  "resource_multiplier": 1.0,
  "oxygen_consumption": 1.0,
  "creature_spawn_divider": 1,
  "enable_pvp": false,
  "friendly_fire": false,
  "shared_blueprints": true,
  "ping_locations_shared": true,
  "time_of_day_sync": "host",
  "voice_chat_integration": "none",
  "api_integration": {
    "openai": {
      "enabled": false,
      "role": "narrator"
    },
    "claude": {
      "enabled": false,
      "role": "lore_engine"
    }
  }
}
```

### Configuration Fields

| Field | Type | Description | Valid Values |
|-------|------|-------------|--------------|
| `session_name` | string | Display name for session | Any string |
| `max_players` | int | Player limit | 2-8 |
| `difficulty_scale` | string | How difficulty adjusts | `adaptive`, `static`, `manual` |
| `resource_multiplier` | float | Resource spawn multiplier | 0.5-3.0 |
| `oxygen_consumption` | float | Oxygen drain rate modifier | 0.5-2.0 |
| `creature_spawn_divider` | int | Reduces creature spawns | 1-4 |
| `shared_blueprints` | bool | Share discovered blueprints | `true`/`false` |
| `time_of_day_sync` | string | Time sync strategy | `host`, `all`, `independent` |

### AI Integration Configuration

To enable AI narration (optional):

```json
{
  "api_integration": {
    "openai": {
      "enabled": true,
      "role": "narrator",
      "api_key_env": "OPENAI_API_KEY",
      "model": "gpt-4",
      "temperature": 0.7,
      "max_tokens": 150
    },
    "claude": {
      "enabled": true,
      "role": "lore_engine",
      "api_key_env": "ANTHROPIC_API_KEY",
      "model": "claude-3-sonnet-20240229",
      "max_tokens": 200
    }
  }
}
```

Set environment variables before launching:

```bash
# Windows
set OPENAI_API_KEY=your_key_here
set ANTHROPIC_API_KEY=your_key_here

# Linux/macOS
export OPENAI_API_KEY=your_key_here
export ANTHROPIC_API_KEY=your_key_here
```

## Console Commands

Access via BepInEx terminal (F12 in-game by default):

### Session Management

```bash
# Host a new session
/start_server

# Join existing session with code
/join_session 9B2A-4C7D-E8F1

# Leave current session
/disconnect

# Show session info
/synergy_status
```

### Gameplay Modifiers

```bash
# Adjust difficulty scaling (1.0 = normal, 1.5 = 50% harder)
/synergy_scale 1.5

# Override world seed for all clients
/seed_override 8251

# Force inventory synchronization
/sync_inventory

# Teleport to another player
/tp_to_player PlayerName
```

### AI Narration

```bash
# Trigger AI-generated narrative about current context
/api_narrate "exploring the kelp forest"

# Generate marine biology log for last scanned creature
/api_lore generate_species_log

# Get contextual survival hint
/api_hint
```

## Key Patterns

### Starting a Co-op Session

**Host workflow:**

```bash
# 1. Launch game with mod installed
# 2. Open console (F12)
/start_server

# Output: "Server created: session code = 9B2A-4C7D-E8F1"
# 3. Share code with friends
# 4. Wait for players to connect
/synergy_status
```

**Client workflow:**

```bash
# 1. Launch game with mod installed
# 2. Open console (F12)
/join_session 9B2A-4C7D-E8F1

# Output: "Connected to host. Syncing world state..."
# 3. Wait for synchronization to complete
```

### Shared Inventory Management

The mod uses Merkle trees for inventory verification:

```json
// Inventory sync status output from /synergy_status
{
  "connected_peers": 3,
  "latency_avg_ms": 45,
  "inventory_hash": "0xFA342B1E",
  "sync_progress": "100%",
  "conflicts_resolved": 2
}
```

**Conflict resolution:** If two players pick up the same item simultaneously, the mod uses timestamps to determine ownership. The "losing" player's action is rolled back.

### Dynamic Difficulty Scaling

Example scaling for a 4-player session with `"difficulty_scale": "adaptive"`:

```json
{
  "base_creature_spawn_rate": 1.0,
  "adjusted_spawn_rate": 0.75,
  "resource_nodes": 1.3,
  "oxygen_efficiency": 1.1,
  "damage_multiplier": 1.2
}
```

**Formula:** `adjusted_value = base_value * (1 + (player_count - 1) * scaling_factor)`

### BepInEx Plugin Integration

For developers extending the mod:

```csharp
using BepInEx;
using BepInEx.IL2CPP;
using DeepSynergy.Core;

namespace MyCustomExtension
{
    [BepInPlugin(GUID, Name, Version)]
    [BepInDependency("com.deepsynergy.mod", BepInDependency.DependencyFlags.HardDependency)]
    public class CustomExtension : BasePlugin
    {
        public const string GUID = "com.myname.customextension";
        public const string Name = "Custom Extension";
        public const string Version = "1.0.0";

        public override void Load()
        {
            // Hook into Deep Synergy events
            SessionManager.OnPlayerJoined += HandlePlayerJoined;
            InventorySync.OnItemPickup += HandleItemPickup;
        }

        private void HandlePlayerJoined(PlayerData player)
        {
            Log.LogInfo($"Player {player.Name} joined. ID: {player.Id}");
        }

        private void HandleItemPickup(ItemPickupEvent evt)
        {
            Log.LogInfo($"Item {evt.ItemId} picked up by {evt.PlayerId}");
        }
    }
}
```

## Troubleshooting

### Connection Issues

**Problem:** "Failed to establish peer connection"

```bash
# Check firewall settings (allow UDP ports 7777-7787)
# Windows Firewall example:
netsh advfirewall firewall add rule name="Subnautica2 Coop" dir=in action=allow protocol=UDP localport=7777-7787

# Verify NAT type
/synergy_status
# Look for "NAT Type: Symmetric" (problematic) vs "Moderate/Open" (good)

# Force relay mode if direct connection fails
# In synergy_profile.json:
{
  "network": {
    "force_relay": true,
    "relay_server": "turn:relay.example.com:3478"
  }
}
```

**Problem:** "Inventory desync detected"

```bash
# Force full resynchronization
/sync_inventory --full

# Check for conflicting mods
# Disable all other BepInEx plugins temporarily

# Verify mod version matches across all clients
/synergy_status
# All players must show same "Mod Version: x.x.x"
```

### Performance Issues

**Problem:** Low FPS in multiplayer vs single-player

```bash
# Reduce creature AI sync frequency in synergy_profile.json:
{
  "performance": {
    "creature_ai_sync_rate_ms": 500,  // Default: 250
    "position_sync_rate_ms": 100,      // Default: 50
    "inventory_sync_rate_ms": 1000     // Default: 500
  }
}

# Disable AI integration if enabled
{
  "api_integration": {
    "openai": {"enabled": false},
    "claude": {"enabled": false}
  }
}
```

### Session Code Not Working

**Problem:** "Invalid session code"

```bash
# Ensure exact format: XXXX-XXXX-XXXX (4 hex chars per segment)
# Codes are case-insensitive

# Check if host session is still active
# Host should see:
/synergy_status
# Output: "Session State: Active, Accepting Connections: Yes"

# Regenerate session code if corrupted
# Host runs:
/restart_server
```

### Mod Not Loading

**Problem:** Mod doesn't appear in BepInEx console

```bash
# 1. Verify BepInEx installation
# Check for BepInEx/LogOutput.log

# 2. Enable verbose logging
# Edit BepInEx/config/BepInEx.cfg:
[Logging.Console]
Enabled = true
LogLevels = All

# 3. Check for IL2CPP compatibility
# Ensure you downloaded BepInEx IL2CPP version, not Mono

# 4. Verify file structure
BepInEx/plugins/DeepSynergy.dll  # Must be directly in plugins/
```

## Advanced Usage

### Custom Event Hooks

Monitor mod events via BepInEx logging:

```csharp
using DeepSynergy.Events;

EventBus.Subscribe<BasePartPlacedEvent>(evt => 
{
    Log.LogInfo($"Base part placed: {evt.PartType} at {evt.Position}");
    // Custom logic here
});

EventBus.Subscribe<CreatureSpawnEvent>(evt => 
{
    if (evt.CreatureType == "Leviathan")
    {
        Log.LogWarning("Leviathan spawned nearby!");
    }
});
```

### Dedicated Server Mode

For 24/7 hosting (experimental):

```json
{
  "server_mode": {
    "enabled": true,
    "headless": true,
    "auto_save_interval_minutes": 15,
    "max_idle_time_minutes": 30,
    "restart_on_empty": true
  }
}
```

Run with:

```bash
# Linux
./Subnautica2.x86_64 -batchmode -nographics

# Windows
Subnautica2.exe -batchmode -nographics
```

### Localization

Override UI language:

```json
{
  "locale": "ja_JP",  // Japanese
  "locale_fallback": "en_US"
}
```

Supported locales: `en_US`, `zh_CN`, `ja_JP`, `de_DE`, `fr_FR`, `pt_BR`, `ru_RU`, `es_ES`, `ko_KR`

## API Reference

### Environment Variables

- `OPENAI_API_KEY` - OpenAI API key for narration features
- `ANTHROPIC_API_KEY` - Anthropic API key for lore generation
- `SYNERGY_DEBUG` - Set to `1` for verbose debug logging
- `SYNERGY_RELAY_SERVER` - Override default TURN server URL

### Configuration File Locations

- **Windows:** `%USERPROFILE%\AppData\Roaming\Subnautica2\BepInEx\config\`
- **Linux:** `~/.config/unity3d/UnknownWorlds/Subnautica2/BepInEx/config/`
- **macOS:** `~/Library/Application Support/UnknownWorlds/Subnautica2/BepInEx/config/`