subnautica-ii-coop-multiplayer-mod

Subnautica II Deep Synergy Multiplayer Mod

Skill by 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

# 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:

{
  "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):

{
  "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:

# 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

# 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

# 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

# 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:

# 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:

# 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:

// 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":

{
  "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:

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"

# 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"

# 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

# 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"

# 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

# 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:

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):

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

Run with:

# Linux
./Subnautica2.x86_64 -batchmode -nographics

# Windows
Subnautica2.exe -batchmode -nographics

Localization

Override UI language:

{
  "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/