subnautica-ii-coop-deep-synergy-mod

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Subnautica II Deep Synergy Co-op Mod

Subnautica 2 Deep Synergy合作模组

Skill by ara.so — Devtools Skills collection.

由 ara.so 开发的技能工具 — 属于Devtools Skills合集。

Overview

概述

The Deep Synergy Multiplayer Mod transforms Subnautica 2 into a synchronized cooperative experience using BepInEx framework. It implements deterministic session synchronization (DSS) where game state, inventory, base-building, and creature AI are shared across clients without central servers.

Key Architecture:

Peer-to-peer WebRTC connectivity with NAT punch-through
Blockchain-inspired Merkle tree inventory verification
Hot-reloadable BepInEx plugin modules
Adaptive dynamic scaling based on player count
Optional AI narrative integration (OpenAI/Claude APIs)

Deep Synergy多人游戏模组借助BepInEx框架将Subnautica 2转变为同步合作体验。它实现了确定性会话同步（DSS），无需中央服务器即可在客户端之间共享游戏状态、物品栏、基地建造和生物AI数据。

核心架构：

支持NAT穿透的点对点WebRTC连接
类区块链的Merkle树物品栏验证机制
可热重载的BepInEx插件模块
基于玩家数量的自适应动态缩放
可选的AI叙事集成（OpenAI/Claude API）

Installation

安装步骤

Prerequisites

前置要求

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

通过Steam/GOG安装Subnautica 2
适用于Unity游戏的BepInEx 6.0.x IL2CPP版本

Setup Steps

设置流程

bash

undefined

bash

undefined

1. Download BepInEx 6.0.x for IL2CPP from GitHub

1. 从GitHub下载适用于IL2CPP的BepInEx 6.0.x版本

Extract to Subnautica 2 game directory (where Subnautica2.exe is located)

解压到Subnautica 2游戏目录（即Subnautica2.exe所在目录）

2. Run the game once to generate BepInEx folders

2. 启动游戏一次以生成BepInEx文件夹

Close the game after main menu loads

主菜单加载完成后关闭游戏

3. Download Deep Synergy mod from the project repository

3. 从项目仓库下载Deep Synergy模组

Extract contents to: Subnautica2/BepInEx/plugins/DeepSynergy/

将内容解压至：Subnautica2/BepInEx/plugins/DeepSynergy/

Verify directory structure:

验证目录结构：

Subnautica2/ ├── BepInEx/ │ ├── config/ │ │ └── synergy_profile.json │ ├── core/ │ └── plugins/ │ └── DeepSynergy/ │ ├── DeepSynergy.dll │ ├── SessionManager.dll │ └── StateSynchronizer.dll └── Subnautica2.exe

undefined

undefined

First Launch

首次启动

bash

undefined

bash

undefined

Launch game normally - BepInEx will load automatically

正常启动游戏 - BepInEx会自动加载

Look for console window showing:

查看控制台窗口输出：

[Info : BepInEx] BepInEx 6.0.0-pre.1 - Subnautica2 [Info : DeepSynergy] Deep Synergy Mod v1.0 loaded [Info : DeepSynergy] Multiplayer hooks initialized

undefined

[Info : BepInEx] BepInEx 6.0.0-pre.1 - Subnautica2 [Info : DeepSynergy] Deep Synergy Mod v1.0 loaded [Info : DeepSynergy] Multiplayer hooks initialized

undefined

Configuration

配置说明

Session Profile (synergy_profile.json)

会话配置文件（synergy_profile.json）

Create or edit

BepInEx/config/synergy_profile.json

json

{
  "session_name": "DeepDiveSquad",
  "max_players": 4,
  "difficulty_scale": "adaptive",
  "resource_multiplier": 1.5,
  "oxygen_consumption": 0.85,
  "creature_spawn_divider": 1.5,
  "enable_pvp": false,
  "friendly_fire": false,
  "shared_blueprints": true,
  "ping_locations_shared": true,
  "time_of_day_sync": "host",
  "voice_chat_integration": "discord_rpc",
  "network": {
    "port_range": "7777-7780",
    "max_latency_ms": 250,
    "packet_loss_tolerance": 0.05
  },
  "api_integration": {
    "openai": {
      "enabled": false,
      "api_key_env": "OPENAI_API_KEY",
      "role": "narrator",
      "model": "gpt-4"
    },
    "claude": {
      "enabled": false,
      "api_key_env": "ANTHROPIC_API_KEY",
      "role": "lore_engine",
      "model": "claude-3-sonnet"
    }
  },
  "sync_settings": {
    "tick_rate": 20,
    "state_hash_interval_ms": 500,
    "inventory_verify_frequency": 5
  },
  "locale": "en-US"
}

创建或编辑

BepInEx/config/synergy_profile.json

：

json

{
  "session_name": "DeepDiveSquad",
  "max_players": 4,
  "difficulty_scale": "adaptive",
  "resource_multiplier": 1.5,
  "oxygen_consumption": 0.85,
  "creature_spawn_divider": 1.5,
  "enable_pvp": false,
  "friendly_fire": false,
  "shared_blueprints": true,
  "ping_locations_shared": true,
  "time_of_day_sync": "host",
  "voice_chat_integration": "discord_rpc",
  "network": {
    "port_range": "7777-7780",
    "max_latency_ms": 250,
    "packet_loss_tolerance": 0.05
  },
  "api_integration": {
    "openai": {
      "enabled": false,
      "api_key_env": "OPENAI_API_KEY",
      "role": "narrator",
      "model": "gpt-4"
    },
    "claude": {
      "enabled": false,
      "api_key_env": "ANTHROPIC_API_KEY",
      "role": "lore_engine",
      "model": "claude-3-sonnet"
    }
  },
  "sync_settings": {
    "tick_rate": 20,
    "state_hash_interval_ms": 500,
    "inventory_verify_frequency": 5
  },
  "locale": "en-US"
}

Configuration Fields

配置字段说明

Field	Type	Description
`resource_multiplier`	float	Scales harvestable resources (1.5 = 50% more)
`oxygen_consumption`	float	Oxygen drain modifier (0.85 = 15% slower)
`creature_spawn_divider`	float	Reduces creature counts (1.5 = 33% fewer)
`difficulty_scale`	string	`"fixed"` , `"adaptive"` , or `"manual"`
`tick_rate`	int	State sync updates per second
`state_hash_interval_ms`	int	Inventory verification interval

字段	类型	描述
`resource_multiplier`	浮点数	可采集资源的缩放比例（1.5 = 增加50%）
`oxygen_consumption`	浮点数	氧气消耗 modifier（0.85 = 降低15%消耗速度）
`creature_spawn_divider`	浮点数	减少生物生成数量（1.5 = 减少33%）
`difficulty_scale`	字符串	可选值： `"fixed"` 、 `"adaptive"` 或 `"manual"`
`tick_rate`	整数	状态同步每秒更新次数
`state_hash_interval_ms`	整数	物品栏验证间隔时长

Console Commands

控制台命令

Access via BepInEx console (F12 by default):

通过BepInEx控制台访问（默认快捷键F12）：

Session Management

会话管理

bash

undefined

bash

undefined

Start hosting a session

开始主持会话

/start_server

Returns: Server created: session code = 9B2A-4C7D-E8F1

返回：Server created: session code = 9B2A-4C7D-E8F1

Join existing session

加入现有会话

/join_session 9B2A-4C7D-E8F1

Check connection status

检查连接状态

/synergy_status

Output:

输出：

Connected peers: 3

State sync: 100% complete

Inventory hash: 0xFA342B1E

Average latency: 42ms

Packet loss: 0.02%

Disconnect from session

断开会话连接

/leave_session

undefined

/leave_session

undefined

Session Scaling

会话缩放

bash

undefined

bash

undefined

Temporarily adjust difficulty

临时调整难度

/synergy_scale 1.8

Scales creature/resource parameters by factor

按比例缩放生物/资源参数

Override world seed for consistency

覆盖世界种子以保持一致性

/seed_override 8251

Forces same procedural generation across clients

强制所有客户端使用相同的 procedural generation

Reset to config defaults

重置为配置默认值

/synergy_reset

undefined

/synergy_reset

undefined

AI Integration

AI集成

bash

undefined

bash

undefined

Trigger narrative generation (requires API keys)

触发叙事生成（需要API密钥）

/api_narrate "discovering the precursor facility"

OpenAI/Claude generates contextual journal entry

OpenAI/Claude生成上下文相关的日志条目

Generate species description for scanned creature

为扫描到的生物生成物种描述

/api_lore creature_reaper_001

Returns procedural biology report

返回程序化生物学报告

undefined

undefined

Code Integration Patterns

代码集成模式

Plugin Development Hook

插件开发钩子

For extending the mod with custom BepInEx plugins:

csharp

using BepInEx;
using BepInEx.IL2CPP;
using DeepSynergy.Core;
using DeepSynergy.Sync;

namespace MyCustomExtension
{
    [BepInPlugin("com.myname.custommod", "Custom Synergy Extension", "1.0.0")]
    [BepInDependency("com.deepsynergy.core", BepInDependency.DependencyFlags.HardDependency)]
    public class CustomSynergyPlugin : BasePlugin
    {
        public override void Load()
        {
            // Hook into session events
            SessionManager.OnSessionStarted += OnSessionStart;
            StateSynchronizer.OnInventorySync += OnInventoryUpdated;
            
            Log.LogInfo("Custom extension loaded");
        }
        
        private void OnSessionStart(SessionContext context)
        {
            Log.LogInfo($"Session {context.SessionCode} started with {context.PlayerCount} players");
            
            // Apply custom scaling logic
            if (context.PlayerCount >= 3)
            {
                context.ApplyDifficultyModifier(1.2f);
            }
        }
        
        private void OnInventoryUpdated(InventoryState state)
        {
            // Verify custom item sync
            var merkleRoot = state.ComputeMerkleRoot();
            Log.LogInfo($"Inventory hash: {merkleRoot}");
        }
    }
}

用于通过自定义BepInEx插件扩展模组功能：

csharp

using BepInEx;
using BepInEx.IL2CPP;
using DeepSynergy.Core;
using DeepSynergy.Sync;

namespace MyCustomExtension
{
    [BepInPlugin("com.myname.custommod", "Custom Synergy Extension", "1.0.0")]
    [BepInDependency("com.deepsynergy.core", BepInDependency.DependencyFlags.HardDependency)]
    public class CustomSynergyPlugin : BasePlugin
    {
        public override void Load()
        {
            // 挂钩会话事件
            SessionManager.OnSessionStarted += OnSessionStart;
            StateSynchronizer.OnInventorySync += OnInventoryUpdated;
            
            Log.LogInfo("Custom extension loaded");
        }
        
        private void OnSessionStart(SessionContext context)
        {
            Log.LogInfo($"Session {context.SessionCode} started with {context.PlayerCount} players");
            
            // 应用自定义缩放逻辑
            if (context.PlayerCount >= 3)
            {
                context.ApplyDifficultyModifier(1.2f);
            }
        }
        
        private void OnInventoryUpdated(InventoryState state)
        {
            // 验证自定义物品同步
            var merkleRoot = state.ComputeMerkleRoot();
            Log.LogInfo($"Inventory hash: {merkleRoot}");
        }
    }
}

Custom Session Event Listener

自定义会话事件监听器

csharp

using DeepSynergy.Events;
using UnityEngine;

public class BaseConstructionSyncer : MonoBehaviour
{
    void Start()
    {
        // Subscribe to base building events
        ConstructionSync.OnBasePiecePlaced += HandlePiecePlaced;
        ConstructionSync.OnBasePieceRemoved += HandlePieceRemoved;
    }
    
    void HandlePiecePlaced(ConstructionPiece piece, ulong playerId)
    {
        // Broadcast to peers with timestamp
        var syncPacket = new SyncPacket
        {
            Type = SyncType.ConstructionAdd,
            Timestamp = NetworkTime.CurrentTimestamp(),
            PlayerId = playerId,
            Data = piece.Serialize()
        };
        
        SessionManager.Broadcast(syncPacket);
    }
    
    void HandlePieceRemoved(Vector3 position, ulong playerId)
    {
        var syncPacket = new SyncPacket
        {
            Type = SyncType.ConstructionRemove,
            Timestamp = NetworkTime.CurrentTimestamp(),
            PlayerId = playerId,
            Data = position.Serialize()
        };
        
        SessionManager.Broadcast(syncPacket);
    }
}

csharp

using DeepSynergy.Events;
using UnityEngine;

public class BaseConstructionSyncer : MonoBehaviour
{
    void Start()
    {
        // 订阅基地建造事件
        ConstructionSync.OnBasePiecePlaced += HandlePiecePlaced;
        ConstructionSync.OnBasePieceRemoved += HandlePieceRemoved;
    }
    
    void HandlePiecePlaced(ConstructionPiece piece, ulong playerId)
    {
        // 带时间戳广播给其他节点
        var syncPacket = new SyncPacket
        {
            Type = SyncType.ConstructionAdd,
            Timestamp = NetworkTime.CurrentTimestamp(),
            PlayerId = playerId,
            Data = piece.Serialize()
        };
        
        SessionManager.Broadcast(syncPacket);
    }
    
    void HandlePieceRemoved(Vector3 position, ulong playerId)
    {
        var syncPacket = new SyncPacket
        {
            Type = SyncType.ConstructionRemove,
            Timestamp = NetworkTime.CurrentTimestamp(),
            PlayerId = playerId,
            Data = position.Serialize()
        };
        
        SessionManager.Broadcast(syncPacket);
    }
}

AI Narration Integration

AI叙事集成

csharp

using DeepSynergy.AI;
using System.Threading.Tasks;

public class NarrativeController
{
    private AIIntegrationService aiService;
    
    public async Task GenerateDiscoveryNarrative(string eventDescription)
    {
        if (!aiService.IsEnabled("openai")) return;
        
        var prompt = $@"
            Context: Multiplayer Subnautica 2 session
            Event: {eventDescription}
            Generate a 2-3 sentence journal entry from the player's perspective.
        ";
        
        var narrative = await aiService.CallOpenAI(
            model: "gpt-4",
            prompt: prompt,
            maxTokens: 150,
            temperature: 0.7f
        );
        
        // Display in-game PDA
        PDAManager.AddJournalEntry(narrative);
    }
    
    public async Task<string> GenerateSpeciesDescription(string creatureId)
    {
        if (!aiService.IsEnabled("claude")) return null;
        
        var prompt = $@"
            Generate a fictional marine biology report for creature ID: {creatureId}
            Include: Classification, behavior patterns, threat level, ecosystem role
            Format: Scientific database entry style
        ";
        
        return await aiService.CallClaude(
            model: "claude-3-sonnet-20240229",
            prompt: prompt,
            maxTokens: 400
        );
    }
}

csharp

using DeepSynergy.AI;
using System.Threading.Tasks;

public class NarrativeController
{
    private AIIntegrationService aiService;
    
    public async Task GenerateDiscoveryNarrative(string eventDescription)
    {
        if (!aiService.IsEnabled("openai")) return;
        
        var prompt = $@"
            Context: Multiplayer Subnautica 2 session
            Event: {eventDescription}
            Generate a 2-3 sentence journal entry from the player's perspective.
        ";
        
        var narrative = await aiService.CallOpenAI(
            model: "gpt-4",
            prompt: prompt,
            maxTokens: 150,
            temperature: 0.7f
        );
        
        // 在游戏内PDA显示
        PDAManager.AddJournalEntry(narrative);
    }
    
    public async Task<string> GenerateSpeciesDescription(string creatureId)
    {
        if (!aiService.IsEnabled("claude")) return null;
        
        var prompt = $@"
            Generate a fictional marine biology report for creature ID: {creatureId}
            Include: Classification, behavior patterns, threat level, ecosystem role
            Format: Scientific database entry style
        ";
        
        return await aiService.CallClaude(
            model: "claude-3-sonnet-20240229",
            prompt: prompt,
            maxTokens: 400
        );
    }
}

Common Usage Patterns

常见使用模式

Hosting a Session

主持会话

bash

undefined

bash

undefined

1. Configure session in synergy_profile.json

1. 在synergy_profile.json中配置会话

2. Launch game

2. 启动游戏

3. In BepInEx console:

3. 在BepInEx控制台中输入：

/start_server

4. Share session code with friends (displayed in console)

4. 将会话代码分享给好友（控制台会显示）

Session code: A7B3-9D2E-F1C4

5. Friends join via:

5. 好友通过以下命令加入：

/join_session A7B3-9D2E-F1C4

undefined

/join_session A7B3-9D2E-F1C4

undefined

Debugging Sync Issues

调试同步问题

bash

undefined

bash

undefined

Check state synchronization

检查状态同步情况

/synergy_status

Force inventory re-sync

强制物品栏重新同步

/synergy_resync inventory

Dump current session state to log

将当前会话状态转储到日志

/synergy_dump_state

Check for Merkle tree mismatches

检查Merkle树是否匹配

/synergy_verify_integrity

undefined

/synergy_verify_integrity

undefined

Performance Tuning

性能调优

json

{
  "sync_settings": {
    "tick_rate": 15,              // Reduce for lower bandwidth
    "state_hash_interval_ms": 750, // Less frequent checks
    "inventory_verify_frequency": 10 // Verify every 10th sync
  },
  "network": {
    "max_latency_ms": 300,         // Allow higher latency
    "packet_loss_tolerance": 0.08   // Tolerate more loss
  }
}

json

{
  "sync_settings": {
    "tick_rate": 15,              // 降低数值以减少带宽占用
    "state_hash_interval_ms": 750, // 减少验证频率
    "inventory_verify_frequency": 10 // 每10次同步验证一次
  },
  "network": {
    "max_latency_ms": 300,         // 允许更高延迟
    "packet_loss_tolerance": 0.08   // 容忍更高丢包率
  }
}

Troubleshooting

故障排除

"Session Code Invalid" Error

"Session Code Invalid" 错误

Cause: Mismatched mod versions or network timeout

bash

undefined

原因： 模组版本不匹配或网络超时

bash

undefined

Verify mod version

验证模组版本

/synergy_version

Both host and client must match

主机和客户端版本必须一致

Check network connectivity

检查网络连通性

/synergy_ping <host_ip>

Regenerate session with explicit port

使用指定端口重新生成会话

/start_server --port 7777

undefined

/start_server --port 7777

undefined

Inventory Desynchronization

物品栏不同步

Symptoms: Items appear duplicated or missing

bash

undefined

症状： 物品重复或丢失

bash

undefined

Force full state reconciliation

强制进行全状态协调

/synergy_reconcile_state

Check Merkle tree integrity

检查Merkle树完整性

/synergy_verify_integrity

Look for "Hash mismatch detected" warnings

查找"Hash mismatch detected"警告

If corrupted, reset to last checkpoint

如果数据损坏，回滚到最近检查点

/synergy_rollback_checkpoint

undefined

/synergy_rollback_checkpoint

undefined

Creature AI Conflicts

生物AI冲突

Symptoms: Creatures behave erratically or freeze

json

// Increase AI sync frequency in config
{
  "sync_settings": {
    "ai_state_interval_ms": 200  // Default: 500
  }
}

bash

undefined

症状： 生物行为异常或冻结

json

// 在配置中提高AI同步频率
{
  "sync_settings": {
    "ai_state_interval_ms": 200  // 默认值：500
  }
}

bash

undefined

Debug creature state lattice

调试生物状态

/synergy_debug_ai creature_stalker_032

undefined

/synergy_debug_ai creature_stalker_032

undefined

High Latency/Packet Loss

高延迟/丢包

bash

undefined

bash

undefined

Check network metrics

检查网络指标

/synergy_netstat

Output shows per-peer latency and packet loss

输出显示每个节点的延迟和丢包情况

Reduce tick rate for slower connections

为慢速连接降低tick rate

/synergy_tickrate 12

Enable aggressive compression

启用高压缩率

/synergy_compression lz4

undefined

/synergy_compression lz4

undefined

API Integration Failures

API集成失败

OpenAI/Claude not responding:

bash

undefined

OpenAI/Claude无响应：

bash

undefined

Verify environment variables are set

验证环境变量是否设置

echo $OPENAI_API_KEY echo $ANTHROPIC_API_KEY

Test API connectivity

测试API连通性

/api_test openai /api_test claude

Check logs for error details

查看日志中的错误详情

tail -f BepInEx/LogOutput.log | grep API

undefined

tail -f BepInEx/LogOutput.log | grep API

undefined

Session Migration After Host Disconnect

主机断开后的会话迁移

Automatic recovery:

bash

undefined

自动恢复：

bash

undefined

Monitor migration status

监控迁移状态

/synergy_status

Output shows "Migrating session to peer 2..."

输出显示"Migrating session to peer 2..."

Manually force migration to specific peer

手动强制迁移到指定节点

/synergy_migrate_host <peer_id>

undefined

/synergy_migrate_host <peer_id>

undefined

Advanced Configuration

高级配置

Custom Difficulty Profiles

自定义难度配置文件

json

{
  "difficulty_profiles": {
    "casual": {
      "resource_multiplier": 2.0,
      "oxygen_consumption": 0.6,
      "creature_spawn_divider": 2.5,
      "damage_taken_multiplier": 0.7
    },
    "hardcore": {
      "resource_multiplier": 0.8,
      "oxygen_consumption": 1.3,
      "creature_spawn_divider": 0.7,
      "damage_taken_multiplier": 1.5,
      "permadeath": true
    }
  },
  "active_profile": "casual"
}

json

{
  "difficulty_profiles": {
    "casual": {
      "resource_multiplier": 2.0,
      "oxygen_consumption": 0.6,
      "creature_spawn_divider": 2.5,
      "damage_taken_multiplier": 0.7
    },
    "hardcore": {
      "resource_multiplier": 0.8,
      "oxygen_consumption": 1.3,
      "creature_spawn_divider": 0.7,
      "damage_taken_multiplier": 1.5,
      "permadeath": true
    }
  },
  "active_profile": "casual"
}

Locale-Specific Settings

本地化特定设置

json

{
  "locale": "ja-JP",
  "localization_override": {
    "console_commands": "ja-JP",
    "ui_elements": "ja-JP",
    "api_prompts": "en-US"  // Keep AI prompts in English
  }
}

json

{
  "locale": "ja-JP",
  "localization_override": {
    "console_commands": "ja-JP",
    "ui_elements": "ja-JP",
    "api_prompts": "en-US"  // 保持AI提示为英文
  }
}

WebRTC Configuration

WebRTC配置

json

{
  "network": {
    "webrtc": {
      "ice_servers": [
        "stun:stun.l.google.com:19302",
        "stun:stun1.l.google.com:19302"
      ],
      "enable_turn": false,
      "turn_server_env": "TURN_SERVER_URL",
      "turn_credentials_env": "TURN_CREDENTIALS"
    }
  }
}

json

{
  "network": {
    "webrtc": {
      "ice_servers": [
        "stun:stun.l.google.com:19302",
        "stun:stun1.l.google.com:19302"
      ],
      "enable_turn": false,
      "turn_server_env": "TURN_SERVER_URL",
      "turn_credentials_env": "TURN_CREDENTIALS"
    }
  }
}

Best Practices

最佳实践

Always backup saves before using multiplayer sessions
Match mod versions across all players to prevent sync issues
Use adaptive scaling for dynamic player counts
Set realistic latency tolerances based on geographic distances
Enable AI features sparingly to avoid API rate limits
Monitor console logs during first session for configuration errors
Use checkpoint systems via
```
/synergy_checkpoint
```
every 15-20 minutes

使用多人会话前务必备份存档
所有玩家使用相同版本的模组以避免同步问题
使用自适应缩放应对动态玩家数量
根据地理距离设置合理的延迟容忍度
谨慎启用AI功能以避免API速率限制
首次会话期间监控控制台日志排查配置错误
每隔15-20分钟使用
/synergy_checkpoint
创建检查点

Environment Variables

环境变量

bash

undefined

bash

undefined

Optional API integrations

可选API集成

export OPENAI_API_KEY="sk-..." export ANTHROPIC_API_KEY="sk-ant-..."

Optional TURN server for restricted NAT

受限NAT环境下可选TURN服务器

export TURN_SERVER_URL="turn:turnserver.example.com:3478" export TURN_CREDENTIALS="username:password"

undefined

export TURN_SERVER_URL="turn:turnserver.example.com:3478" export TURN_CREDENTIALS="username:password"

undefined