subnautica-ii-coop-multiplayer-mod

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Subnautica II Deep Synergy Multiplayer 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 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

Deep Synergy多人游戏模组借助BepInEx的IL2CPP模组框架，将Subnautica 2转变为合作生存体验。它实现了确定性会话同步、基于WebRTC的点对点网络，以及可选的AI集成用于叙事生成。

核心功能：

同步多人会话（2-8名玩家）
带冲突解决机制的共享背包与基地建造
基于玩家数量的自适应难度调整
跨平台支持（Windows、Linux、macOS）
BepInEx插件架构（无需修改游戏文件）
可选的OpenAI/Claude API集成，用于动态叙事

Installation

安装

Prerequisites

前置要求

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

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

Step-by-Step Installation

分步安装指南

bash

undefined

bash

undefined

1. Navigate to Subnautica 2 installation directory

1. 导航到Subnautica 2安装目录

cd "C:\Program Files (x86)\Steam\steamapps\common\Subnautica2"

2. Install BepInEx (if not already installed)

2. 安装BepInEx（若未安装）

Download BepInEx_UnityIL2CPP_x64 from https://github.com/BepInEx/BepInEx/releases

从https://github.com/BepInEx/BepInEx/releases下载BepInEx_UnityIL2CPP_x64

Extract to game root directory

解压到游戏根目录

3. Download Deep Synergy mod from release page

3. 从发布页面下载Deep Synergy模组

Extract DeepSynergy.dll to BepInEx/plugins/

将DeepSynergy.dll解压到BepInEx/plugins/

4. Verify installation structure

4. 验证安装结构

BepInEx/ ├── plugins/ │ └── DeepSynergy.dll ├── config/ │ └── synergy_profile.json (created on first run) └── core/ └── (BepInEx core files)

undefined

BepInEx/ ├── plugins/ │ └── DeepSynergy.dll ├── config/ │ └── synergy_profile.json（首次运行时创建） └── core/ └── (BepInEx核心文件)

undefined

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

创建

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`

字段	类型	说明	有效值
`session_name`	string	会话显示名称	任意字符串
`max_players`	int	玩家上限	2-8
`difficulty_scale`	string	难度调整方式	`adaptive` , `static` , `manual`
`resource_multiplier`	float	资源生成倍率	0.5-3.0
`oxygen_consumption`	float	氧气消耗速率 modifier	0.5-2.0
`creature_spawn_divider`	int	减少生物生成数量	1-4
`shared_blueprints`	bool	共享已发现蓝图	`true` / `false`
`time_of_day_sync`	string	时间同步策略	`host` , `all` , `independent`

AI Integration Configuration

AI集成配置

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

undefined

要启用AI叙事（可选）：

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
    }
  }
}

启动前设置环境变量：

bash

undefined

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

undefined

export OPENAI_API_KEY=your_key_here export ANTHROPIC_API_KEY=your_key_here

undefined

Console Commands

控制台命令

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

通过BepInEx终端访问（默认游戏内按F12）：

Session Management

会话管理

bash

undefined

bash

undefined

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

undefined

/synergy_status

undefined

Gameplay Modifiers

游戏玩法调整

bash

undefined

bash

undefined

Adjust difficulty scaling (1.0 = normal, 1.5 = 50% harder)

调整难度缩放（1.0=正常，1.5=难度提升50%）

/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

undefined

/tp_to_player PlayerName

undefined

AI Narration

AI叙事

bash

undefined

bash

undefined

Trigger AI-generated narrative about current context

触发AI生成当前场景的叙事内容

/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

undefined

/api_hint

undefined

Key Patterns

核心使用模式

Starting a Co-op Session

开启合作会话

Host workflow:

bash

undefined

主机流程：

bash

undefined

1. Launch game with mod installed

1. 安装模组后启动游戏

2. Open console (F12)

2. 打开控制台（F12）

/start_server

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

输出："Server created: session code = 9B2A-4C7D-E8F1"

3. Share code with friends

3. 将代码分享给好友

4. Wait for players to connect

4. 等待玩家连接

/synergy_status


**Client workflow:**

```bash

/synergy_status


**客户端流程：**

```bash

1. Launch game with mod installed

1. 安装模组后启动游戏

2. Open console (F12)

2. 打开控制台（F12）

/join_session 9B2A-4C7D-E8F1

Output: "Connected to host. Syncing world state..."

输出："Connected to host. Syncing world state..."

3. Wait for synchronization to complete

3. 等待同步完成

undefined

undefined

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.

模组使用默克尔树进行背包验证：

json

// /synergy_status输出的背包同步状态
{
  "connected_peers": 3,
  "latency_avg_ms": 45,
  "inventory_hash": "0xFA342B1E",
  "sync_progress": "100%",
  "conflicts_resolved": 2
}

冲突解决： 如果两名玩家同时拾取同一物品，模组会使用时间戳确定所有权。“失败”玩家的操作会被回滚。

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)

4人会话中

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

公式：

adjusted_value = base_value * (1 + (player_count - 1) * scaling_factor)

BepInEx Plugin Integration

BepInEx插件集成

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}");
        }
    }
}

供开发者扩展模组使用：

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()
        {
            // 钩子到Deep Synergy事件
            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

undefined

问题： "Failed to establish peer connection"

bash

undefined

Check firewall settings (allow UDP ports 7777-7787)

检查防火墙设置（允许UDP端口7777-7787）

Windows Firewall example:

Windows防火墙示例：

netsh advfirewall firewall add rule name="Subnautica2 Coop" dir=in action=allow protocol=UDP localport=7777-7787

Verify NAT type

验证NAT类型

/synergy_status

Look for "NAT Type: Symmetric" (problematic) vs "Moderate/Open" (good)

查看"NAT Type: Symmetric"（有问题） vs "Moderate/Open"（正常）

Force relay mode if direct connection fails

如果直接连接失败，强制使用中继模式

In synergy_profile.json:

在synergy_profile.json中：

{ "network": { "force_relay": true, "relay_server": "turn:relay.example.com:3478" } }


**Problem:** "Inventory desync detected"

```bash

{ "network": { "force_relay": true, "relay_server": "turn:relay.example.com:3478" } }


**问题：** "Inventory desync detected"

```bash

Force full resynchronization

强制完全同步

/sync_inventory --full

Check for conflicting mods

检查冲突模组

Disable all other BepInEx plugins temporarily

暂时禁用所有其他BepInEx插件

Verify mod version matches across all clients

验证所有客户端的模组版本一致

/synergy_status

All players must show same "Mod Version: x.x.x"

所有玩家必须显示相同的"Mod Version: x.x.x"

undefined

undefined

Performance Issues

性能问题

Problem: Low FPS in multiplayer vs single-player

bash

undefined

问题： 多人模式下FPS低于单人模式

bash

undefined

Reduce creature AI sync frequency in synergy_profile.json:

在synergy_profile.json中降低生物AI同步频率：

{ "performance": { "creature_ai_sync_rate_ms": 500, // Default: 250 "position_sync_rate_ms": 100, // Default: 50 "inventory_sync_rate_ms": 1000 // Default: 500 } }

{ "performance": { "creature_ai_sync_rate_ms": 500, // 默认值：250 "position_sync_rate_ms": 100, // 默认值：50 "inventory_sync_rate_ms": 1000 // 默认值：500 } }

Disable AI integration if enabled

若已启用AI集成，将其禁用

{ "api_integration": { "openai": {"enabled": false}, "claude": {"enabled": false} } }

undefined

{ "api_integration": { "openai": {"enabled": false}, "claude": {"enabled": false} } }

undefined

Session Code Not Working

会话代码无法使用

Problem: "Invalid session code"

bash

undefined

问题： "Invalid session code"

bash

undefined

Ensure exact format: XXXX-XXXX-XXXX (4 hex chars per segment)

确保格式正确：XXXX-XXXX-XXXX（每段4个十六进制字符）

Codes are case-insensitive

代码不区分大小写

Check if host session is still active

检查主机会话是否仍在运行

Host should see:

主机执行：

/synergy_status

Output: "Session State: Active, Accepting Connections: Yes"

输出应包含："Session State: Active, Accepting Connections: Yes"

Regenerate session code if corrupted

如果代码损坏，重新生成会话代码

Host runs:

主机执行：

/restart_server

undefined

/restart_server

undefined

Mod Not Loading

模组无法加载

Problem: Mod doesn't appear in BepInEx console

bash

undefined

问题： 模组未出现在BepInEx控制台中

bash

undefined

1. Verify BepInEx installation

1. 验证BepInEx安装

Check for BepInEx/LogOutput.log

检查是否存在BepInEx/LogOutput.log

2. Enable verbose logging

2. 启用详细日志

Edit BepInEx/config/BepInEx.cfg:

编辑BepInEx/config/BepInEx.cfg：

[Logging.Console] Enabled = true LogLevels = All

3. Check for IL2CPP compatibility

3. 检查IL2CPP兼容性

Ensure you downloaded BepInEx IL2CPP version, not Mono

确保下载的是BepInEx IL2CPP版本，而非Mono版本

4. Verify file structure

4. 验证文件结构

BepInEx/plugins/DeepSynergy.dll # Must be directly in plugins/

undefined

BepInEx/plugins/DeepSynergy.dll # 必须直接位于plugins目录下

undefined

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!");
    }
});

通过BepInEx日志监控模组事件：

csharp

using DeepSynergy.Events;

EventBus.Subscribe<BasePartPlacedEvent>(evt => 
{
    Log.LogInfo($"Base part placed: {evt.PartType} at {evt.Position}");
    // 自定义逻辑
});

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

undefined

用于24/7托管（实验性）：

json

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

运行命令：

bash

undefined

Linux

./Subnautica2.x86_64 -batchmode -nographics

Windows

Subnautica2.exe -batchmode -nographics

undefined

Subnautica2.exe -batchmode -nographics

undefined

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

覆盖UI语言：

json

{
  "locale": "ja_JP",  // 日语
  "locale_fallback": "en_US"
}

支持的语言：

en_US

zh_CN

ja_JP

de_DE

fr_FR

pt_BR

ru_RU

es_ES

ko_KR

API Reference

API参考

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

```
OPENAI_API_KEY
```
- 用于叙事功能的OpenAI API密钥
```
ANTHROPIC_API_KEY
```
- 用于背景故事生成的Anthropic API密钥
```
SYNERGY_DEBUG
```
- 设置为
```
1
```
启用详细调试日志
```
SYNERGY_RELAY_SERVER
```
- 覆盖默认TURN服务器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/

Windows：

%USERPROFILE%\AppData\Roaming\Subnautica2\BepInEx\config\

Linux：

~/.config/unity3d/UnknownWorlds/Subnautica2/BepInEx/config/

macOS：

~/Library/Application Support/UnknownWorlds/Subnautica2/BepInEx/config/