SuperAPI AI Directory
Partner中文AI newsFavorites
Skillssubnautica-2-coop-mod-bepinex

subnautica-2-coop-mod-bepinex

General & other

View repository

Updated 10-15 22:32

About this skill

Subnautica 2 Deep Synergy Multiplayer Mod

Skill by ara.so — Devtools Skills collection.

Overview

The Deep Synergy Multiplayer Mod transforms Subnautica 2 into a synchronized cooperative experience using the BepInEx modding framework. It implements deterministic session synchronization, adaptive difficulty scaling, and peer-to-peer networking to enable multiple players to explore, build bases, and survive together in Subnautica 2's alien oceans.

Key Features:

  • Deterministic Session Synchronization (DSS) for conflict-free shared world state
  • Adaptive Dynamic Scaling that adjusts difficulty based on player count
  • BepInEx IL2CPP-level hooking with hot-reloadable plugin architecture
  • Shared inventory using Merkle tree verification
  • Cross-platform multiplayer via NAT punch-through and WebRTC
  • Session migration on host disconnect with zero data loss

Installation

Prerequisites

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

Step-by-Step Installation

# 1. Install BepInEx 6.0.x for Subnautica 2
# Download from: https://github.com/BepInEx/BepInEx/releases
# Extract to your Subnautica 2 game directory

# 2. Verify BepInEx installation structure
# Your game directory should have:
# Subnautica2/
#   ├── BepInEx/
#   │   ├── core/
#   │   ├── plugins/
#   │   └── config/
#   ├── Subnautica2.exe (Windows)
#   └── ...

# 3. Download Deep Synergy Mod
# Extract the mod files to: Subnautica2/BepInEx/plugins/

# 4. Directory structure after installation:
# BepInEx/
#   ├── plugins/
#   │   ├── DeepSynergy.dll
#   │   ├── DeepSynergy.Core.dll
#   │   └── DeepSynergy.Network.dll
#   └── config/
#       └── synergy_profile.json

Verify Installation

Launch Subnautica 2. You should see BepInEx console output indicating the mod loaded:

[Info   : BepInEx] BepInEx 6.0.0 - Subnautica2
[Info   : BepInEx] Running under Unity 2022.3.x
[Info   : DeepSynergy] Deep Synergy Multiplayer Mod v1.0.0 loaded
[Info   : DeepSynergy] Session Manager initialized
[Info   : DeepSynergy] WebRTC transport ready

Configuration

Basic Configuration File

Create or edit BepInEx/config/synergy_profile.json:

{
  "session_name": "Ocean Explorers",
  "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": "all",
  "voice_chat_integration": "none",
  "locale": "auto",
  "api_integration": {
    "openai": {
      "enabled": false,
      "api_key_env": "OPENAI_API_KEY",
      "role": "narrator"
    },
    "claude": {
      "enabled": false,
      "api_key_env": "ANTHROPIC_API_KEY",
      "role": "lore_engine"
    }
  },
  "network": {
    "port": 7777,
    "use_upnp": true,
    "max_latency_ms": 150,
    "packet_loss_tolerance": 0.05
  },
  "session_recovery": {
    "auto_save_interval_seconds": 60,
    "enable_migration": true,
    "backup_count": 3
  }
}

Configuration Options Explained

Option Type Default Description
max_players int 4 Maximum players per session (2-8)
difficulty_scale string "adaptive" "fixed", "adaptive", or "progressive"
resource_multiplier float 1.0 Resource node spawn rate (0.5-3.0)
oxygen_consumption float 1.0 Oxygen drain rate (0.5-2.0)
creature_spawn_divider int 1 Divide creature counts by this value
shared_blueprints bool true All players unlock blueprints together
time_of_day_sync string "all" "all", "host", or "independent"

Advanced Session Configuration

{
  "session_name": "Hardcore Survival",
  "max_players": 2,
  "difficulty_scale": "progressive",
  "resource_multiplier": 0.7,
  "oxygen_consumption": 1.3,
  "creature_spawn_divider": 1,
  "enable_pvp": false,
  "friendly_fire": true,
  "shared_blueprints": false,
  "death_penalty": "inventory_drop",
  "respawn_delay_seconds": 30,
  "shared_storage": {
    "enabled": true,
    "max_shared_lockers": 10,
    "require_proximity": false
  },
  "base_building": {
    "collaborative_placement": true,
    "require_consensus": false,
    "power_sharing": true
  }
}

Console Commands

Access the BepInEx console (default: F12 in-game) to use these commands:

Session Management

# Start hosting a new session
/start_server
# Output: Server created: session code = 9B2A-4C7D-E8F1

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

# Get current session status
/synergy_status
# Output:
# Connected peers: 2/4
# State sync: 100% complete
# Inventory hash: 0xFA342B1E
# Latency: Player1: 45ms, Player2: 67ms

# Disconnect from session
/leave_session

# Force session migration (transfer host)
/migrate_host Player2

Runtime Configuration

# Temporarily adjust difficulty scaling
/synergy_scale 1.5

# Change resource multiplier mid-session
/set_resource_multiplier 1.2

# Override world seed for new playthroughs
/seed_override 8251

# Toggle debug mode
/synergy_debug true

# Check synchronization health
/sync_health
# Output:
# Merkle tree integrity: OK
# Pending conflicts: 0
# Timestamp drift: +2ms

AI Integration Commands (Optional)

# Trigger OpenAI narrative generation
/api_narrate "exploring the underwater caves"

# Request Claude lore generation for current location
/api_lore current_biome

# Get AI-generated base naming suggestions
/api_suggest_name base

# Generate creature analysis
/api_analyze_creature reaper_leviathan

Core Patterns and Usage

Starting a Co-op Session (Host)

// In-game: Press configured hotkey (default: F9) to open multiplayer menu
// Or use console:

// 1. Start server
/start_server

// 2. Configure session (optional, uses synergy_profile.json by default)
/set_max_players 3
/set_difficulty_scale adaptive

// 3. Share the displayed session code with friends
// Session code appears in chat: "9B2A-4C7D-E8F1"

// 4. Wait for players to connect
// Connection messages appear in chat:
// "Player2 joined the session"
// "Player3 joined the session"

Joining a Co-op Session (Client)

# 1. Open multiplayer menu (F9) or use console
/join_session 9B2A-4C7D-E8F1

# 2. Wait for synchronization
# Progress appears in UI:
# "Synchronizing world state... 45%"
# "Downloading inventory data... 78%"
# "Syncing base structures... 100%"

# 3. Spawn into the world
# You'll appear at the host's current location or a designated spawn point

Shared Base Building

When collaborative_placement is enabled, base building is synchronized:

# Player 1 places a foundation
# Action: Place Foundation at coordinates (100, -50, 200)

# Player 2 sees foundation immediately and can build on it
# Action: Place Corridor connecting to Player 1's foundation

# Both players see the same structure in real-time
# Power generation and resource consumption are shared

Inventory Synchronization

The mod uses Merkle tree verification for inventory integrity:

# Check inventory sync status
/sync_health

# If desync detected:
# "Warning: Inventory hash mismatch with Player2"
# "Initiating reconciliation..."

# Force inventory resync (rarely needed)
/force_resync inventory

# Check specific item counts across all players
/debug_item titanium
# Output:
# Host: 47 titanium
# Player2: 47 titanium
# Player3: 47 titanium (shared storage)

Session Recovery and Migration

If the host disconnects, the mod automatically migrates:

# Automatic migration occurs
# Console output:
# "Host disconnected. Initiating session migration..."
# "Player2 elected as new host"
# "Restoring session state from backup..."
# "Migration complete. Session restored."

# Players can continue without interruption
# All progress, bases, and inventory are preserved

Plugin Development (Advanced)

Creating Custom BepInEx Plugins for the Mod

using BepInEx;
using BepInEx.IL2CPP;
using HarmonyLib;
using DeepSynergy.Core;
using DeepSynergy.Network;

namespace CustomSynergyPlugin
{
    [BepInPlugin("com.example.customsynergy", "Custom Synergy Plugin", "1.0.0")]
    [BepInDependency("com.deepsynergy.core")]
    public class CustomSynergyPlugin : BasePlugin
    {
        private Harmony harmony;

        public override void Load()
        {
            harmony = new Harmony("com.example.customsynergy");
            harmony.PatchAll();

            // Subscribe to Deep Synergy events
            SessionManager.OnPlayerJoined += OnPlayerJoined;
            SessionManager.OnPlayerLeft += OnPlayerLeft;
            StateSync.OnInventoryChanged += OnInventoryChanged;

            Log.LogInfo("Custom Synergy Plugin loaded!");
        }

        private void OnPlayerJoined(string playerId, string playerName)
        {
            Log.LogInfo($"Player joined: {playerName} ({playerId})");
            
            // Example: Send custom welcome message
            NetworkManager.SendMessage(playerId, new WelcomeMessage
            {
                Text = $"Welcome to the session, {playerName}!",
                ShowNotification = true
            });
        }

        private void OnPlayerLeft(string playerId)
        {
            Log.LogInfo($"Player left: {playerId}");
        }

        private void OnInventoryChanged(string playerId, InventoryDelta delta)
        {
            // React to inventory changes
            if (delta.ItemAdded == "titanium" && delta.Count >= 10)
            {
                Log.LogInfo($"{playerId} collected 10+ titanium!");
            }
        }
    }
}

Hooking into Base Building Events

using HarmonyLib;
using DeepSynergy.Core;

[HarmonyPatch(typeof(BaseManager), "PlaceBaseComponent")]
public class BaseComponentPatch
{
    static void Postfix(BaseComponent component, Vector3 position, Quaternion rotation)
    {
        // Called after any base component is placed
        Log.LogInfo($"Base component placed: {component.Type} at {position}");

        // Sync to all connected clients
        StateSync.BroadcastBaseChange(new BaseChangeEvent
        {
            ComponentType = component.Type,
            Position = position,
            Rotation = rotation,
            PlayerId = SessionManager.LocalPlayerId,
            Timestamp = NetworkTime.CurrentTimestamp()
        });
    }
}

Troubleshooting

Common Issues

1. "Session Code Invalid" Error

# Symptom: Cannot join session, "Invalid session code" error

# Solution 1: Verify session code format
# Correct format: XXXX-XXXX-XXXX (12 characters with dashes)

# Solution 2: Check if host is still running
/synergy_status
# If host offline: "Error: Cannot connect to session"

# Solution 3: Verify network connectivity
/net_test <host_ip>
# Should show: "Connection successful: <latency>ms"

# Solution 4: Check firewall rules
# Ensure UDP port 7777 (or configured port) is open

2. Inventory Desynchronization

# Symptom: Different item counts between players

# Solution 1: Check sync status
/sync_health
# Output shows: "Inventory hash mismatch detected"

# Solution 2: Force reconciliation
/force_resync inventory
# Wait for: "Inventory reconciliation complete"

# Solution 3: If persistent, restart session with backup
/restore_backup 0  # Most recent backup

3. High Latency / Lag

# Symptom: Delayed actions, rubber-banding

# Check current latency
/synergy_status
# Look for: "Latency: 300ms+" (problematic)

# Solution 1: Adjust network settings in config
{
  "network": {
    "max_latency_ms": 200,  // Increase tolerance
    "packet_loss_tolerance": 0.1  // Allow more packet loss
  }
}

# Solution 2: Enable compression
/set_compression true

# Solution 3: Reduce sync frequency for non-critical data
{
  "sync_intervals": {
    "position_ms": 50,  // Increase from 33ms
    "inventory_ms": 500,  // Increase from 200ms
    "world_state_ms": 2000  // Increase from 1000ms
  }
}

4. Base Parts Not Appearing for Other Players

# Symptom: One player places base parts, others don't see them

# Solution 1: Check base sync status
/debug_base
# Output: Lists all base components and which players see them

# Solution 2: Force base state resync
/force_resync base

# Solution 3: Verify collaborative_placement setting
{
  "base_building": {
    "collaborative_placement": true,  // Must be true
    "require_consensus": false
  }
}

# Solution 4: Check for conflicts
/base_conflicts
# Resolves any placement conflicts automatically

5. Mod Fails to Load

# Symptom: BepInEx console shows no Deep Synergy messages

# Check BepInEx log
# Location: BepInEx/LogOutput.log

# Common causes:
# 1. Missing dependencies
#    Error: "Could not load [DeepSynergy.Core.dll]"
#    Solution: Reinstall mod, ensure all DLLs are present

# 2. Incompatible BepInEx version
#    Error: "BepInEx version mismatch"
#    Solution: Update to BepInEx 6.0.x

# 3. Game update broke IL2CPP hooks
#    Error: "Failed to hook [MethodName]"
#    Solution: Wait for mod update or downgrade game version

# 4. Conflicting mods
#    Disable other mods one by one to identify conflicts

Debug Mode

Enable verbose logging for troubleshooting:

{
  "debug": {
    "enabled": true,
    "log_level": "verbose",
    "log_network_traffic": true,
    "log_state_changes": true,
    "dump_sync_conflicts": true
  }
}

# Enable debug mode at runtime
/synergy_debug true

# View detailed sync logs
/show_sync_log

# Monitor network packets
/net_monitor true
# Output: Real-time packet flow with sizes and types

Environment Variables

The mod respects these environment variables:

# OpenAI API key (for narrative generation)
export OPENAI_API_KEY=sk-your-key-here

# Anthropic Claude API key (for lore engine)
export ANTHROPIC_API_KEY=sk-ant-your-key-here

# Override config file location
export SYNERGY_CONFIG_PATH=/custom/path/synergy_profile.json

# Set log level without editing config
export SYNERGY_LOG_LEVEL=debug

# Force specific network port
export SYNERGY_PORT=8888

# Disable UPnP/NAT-PMP
export SYNERGY_NO_UPNP=1

Performance Optimization

For Low-End Systems

{
  "performance": {
    "sync_intervals": {
      "position_ms": 100,
      "inventory_ms": 1000,
      "world_state_ms": 5000
    },
    "reduce_creature_ai_sync": true,
    "compress_network_traffic": true,
    "limit_visual_effects": true
  }
}

For High-Performance Sessions (4+ players)

{
  "performance": {
    "sync_intervals": {
      "position_ms": 33,
      "inventory_ms": 200,
      "world_state_ms": 1000
    },
    "predictive_sync": true,
    "delta_compression": true,
    "prioritize_nearby_players": true
  }
}

Best Practices

  1. Always use session codes: Avoid direct IP connections for better NAT traversal
  2. Configure difficulty scaling: Set difficulty_scale to "adaptive" for balanced gameplay
  3. Enable session backups: Set auto_save_interval_seconds to 60 or less
  4. Test network before inviting friends: Use /net_test command
  5. Coordinate resource gathering: Use shared_blueprints: true to avoid duplicate research
  6. Designate a stable host: Player with best connection should host
  7. Use voice chat integration: Set voice_chat_integration to "discord_rpc" for proximity audio

Additional Resources

  • BepInEx Documentation: https://docs.bepinex.dev/
  • Subnautica Modding Wiki: Community-maintained mod compatibility lists
  • Discord Server: 24/7 support and troubleshooting assistance
  • GitHub Issues: Bug reports and feature requests (if public repository exists)