# ZaraSuApiMod

**Repository Path**: Zaranpc/ZaraSuApiMod

## Basic Information

- **Project Name**: ZaraSuApiMod
- **Description**: zarasuapimod
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-20
- **Last Updated**: 2026-09-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ZaraSuApiMod

Survivalcraft 2（SuAPI 版）模组开发仓库。当前包含公共前置库 **ZaraLib**，以及 **SuMiniMap 小地图**、**Display 注视信息**、**Clothing 斗笠与毛皮靴**。

## Display 注视信息（类 Minecraft Jade / WAILA）

屏幕上方居中显示**十字准星指向的目标信息**，2~3 帧刷新一次；没有目标（或目标被挡、打开容器/面板、死亡）时自动隐藏。

- **瞄准方式与游戏"挖掘"完全一致**：`ComponentMiner.Raycast<TerrainRaycastResult>(ray, RaycastMode.Digging)`，
  射线取当前活动相机的 `ViewPosition/ViewDirection`（同 `ComponentBlockHighlight`），
  触及距离也照游戏：生存 5 格、创造 `SettingsManager.CreativeReach`（默认 7.5 格）。
- **水 / 岩浆永远不显示**：挖掘模式的射线本身就穿过液体（`FluidBlock.IsDiggingTransparent = true`），
  代码里再额外判一次 `FluidBlock` / `BlocksManager.FluidBlocks` 兜底 —— 所以泡在海里也不会满屏"Water"。
- **生物**：另外做一次 `RaycastMode.Interaction` 的实体射线（`SubsystemBodies.Raycast`），与方块取更近的那个；
  显示 玩家名 / `ComponentCreature.DisplayName`、分类（LandPredator 等）、血量百分比（`ComponentHealth.Health` 是 0~1）、距离。
- **不同类型的方块有不同解释**（`DisplayProbeComponent.DescribeBlockState`）：
  - 黑麦 `RyeBlock`：`Growing 3/7`（7 = `Ripe`）+ `(wild)`；棉花 `CottonBlock`：`0~2`，2 = Ripe；南瓜 `BasePumpkinBlock`：`0~7`
  - 树苗 `SaplingBlock` / 花草 `CrossBlock`：显示所属分类
  - 耕地 `SoilBlock`：`Wet farmland` / `Dry farmland`
  - 熔炉 `FurnaceBlock`：`Burning 42%`（读 `ComponentFurnace.HeatLevel/SmeltingProgress`）或 `Not burning`
  - 箱子 `ChestBlock`：`Has items` / `Empty`
  - 普通方块：不加额外说明（面板尽量小）
- HUD 面板：贴屏幕最上框的长方形小面板（半透明黑底 + 描边），`IsHitTestVisible = false` 不挡挖掘/点击；
  宽度按内容实测尺寸收缩。**从地形切到生物（或反过来）时，面板尺寸会按固定速度线性拉伸到新尺寸，
  拉伸到位后才用 `IsVisible` 切换左侧的方块图标 ↔ 生物模型（以及血量槽）**，避免瞬间变形。
  想调速度/位置/尺寸：`DisplayWidget.cs` 顶部的 `SizeStretchRate / TopMargin / BlockIconSize / ModelWidth / ModelHeight / BarWidth / BarSegments / LineHeight`。

> 想加新种类的解释：改 `Component/DisplayProbeComponent.cs` 的 `DescribeBlockDetail`（照现有 `is XxxBlock` 分支加即可）。

## ZaraLib 公共前置库

`ZaraLib` 是后续模组共用的运行库、网络基础设施和跨 API 资源扫描层，当前包含：

- 低频/高频包管理、批次合并、Loopback、UDP Bridge、官方 Comms 端点；
- 保持现有 PBRK/SUMP 协议和 Raw=0、Death=1、PlayerColor=2 包编号；
- `ZaraLegacyModScanner`：扫描其它 API 的 scmod/DLL，检测入口类型、资源和依赖；
- 对识别出的另一套 `Game.ModLoader` 模组先输出兼容性结果，ABI 不兼容时安全跳过，不强行塞进当前 SuAPI 进程；
- 扫描旧模组的 `Assets/`、`Content/` 和可识别的资源键，但未修改的旧 DLL 仍不能凭同名类自动重定向到当前 `ContentManager`。

`SuMiniMap` 通过 `ModInfo.xml` 声明 `ZaraLib` 前置依赖。ZaraLib 和 SuMiniMap 是两个独立的 `.scmod`，不替换官方 `ScMultiplayer`。

当前 `src/ScCsgoKnives` 属于另一套 SurvivalcraftApi/Game.ModLoader ABI，仓库里只有源码/资源，没有可直接加载的成品 DLL。ZaraLib 会先识别并报告；后续可继续做当前 SuAPI 迁移适配。

## SuMiniMap 小地图

### 功能

- **HUD 小地图**：右/左侧可放置的实时小地图（俯视正交相机把世界渲染到纹理后贴到 UI）
  - 俯视相机固定在世界最顶层（Y=255），地形不会被近裁剪面切出黑洞；渲染地图时临时关闭雾/霾，没有远距离遮挡效果
  - **两种地图样式**（面板里的 `Change Style` 按钮切换，会保存到设置）：`Square` 方框（默认）/ `Circle` 圆形裁剪（三角扇采样内接圆，标记与点击判定都按圆形处理）
  - **玩家标记是游戏自带的小星星贴图**（`Textures/Gui/RatingStar`，尺寸很小不挡地图），并整体按该玩家**面朝方向旋转**；**自己固定红色**，其他玩家用自己的专属颜色
- **设置面板**（按 `U` 或点击小地图打开）：
  - 通过 `ComponentGui.ModalPanelWidget` 显示（游戏原生模态面板槽：自动居中 + 弹出动画 + 接管输入），**关闭 = 清空该槽**
  - 界面**完全由 XML 描述**：`SuMiniMap/Content/Widgets/SuMapDialog.xml`（游戏原版控件格式），改布局不用改代码
  - 面板尺寸 614 × 382（虚拟单位），设置卡片：HUD 开关、地图大小滑块、显示范围滑块（数值直接显示在滑块文本上）、`Set Position`、`Change Style`
  - 玩家卡片：`ScrollPanelWidget + StackPanelWidget` 滚动列表，每行 = 颜色条 + 头像 + 名字 + 实时坐标；列表高度自动拉伸到卡片底部
- **玩家颜色**（存在世界存档里，见 `SuPlayerColorSubsystem`）：
  - 内置 **20 个固定初始颜色**，20 人以内的玩家各占唯一颜色；房主固定红色
  - 选色优先按**名字哈希**（与"此刻认识多少玩家"无关，各端推导结果稳定一致），槽位被占用再顺延，20 个槽位用完后取随机色
  - **服务端（房主）是颜色权威**：颜色表一有变化（有人进房、分配了新颜色）就立即下发一次；人数超过 20（出现随机色）时另外按 3 秒周期重发，兜底重连的客户端
  - 客户端收到颜色表后直接覆盖本地推导结果，因此**服务端与客户端颜色保持一致**（之前只在超过 20 人时才发包，会出现两端不一致的问题）
- **死亡标记**：
  - 死亡即记录坐标，**按玩家分别存储**在世界存档的子系统里（切换存档不会串数据）
  - HUD 小地图显示骷髅图标，并标注距离；其他玩家的标记用其专属颜色区分
  - 走近约 5 格自动清除对应标记
- **联机同步**：经由联机模组的公开连接（Comms）在玩家之间同步死亡标记与颜色表；定期 + 有人进房时立即下发（后进房也能拿到完整列表）

### 操作方式

| 操作 | 作用 |
|---|---|
| `U` | 打开设置面板（唯一快捷键） |
| 点击小地图 | 打开设置面板 |
| 面板内 `U` / `Esc` / `Close` | 关闭面板 |
| 面板内的滑块 / 开关 | 地图大小、显示范围、HUD 显示开关、设置地图位置 |

> 说明：早期版本的 `M`（显示/隐藏）、`Alt`+方向键（移动）、`Alt`+`+`/`-`（改大小）、滚轮（改范围）等快捷键已全部移除，这些功能都改到设置面板里操作。

### 构建与打包

```cmd
:: 一键：编译 → Obfuscar 混淆 → 打包 .scmod → 安装到游戏 Mods 目录
Mod\Tools\build_mod.cmd SuMiniMap
```

- 目标框架 `net8.0`，通过 NuGet 源 `https://nuget.cnb.cool/suceru.cb/SuAPICore/...` 引用 `Engine` / `EntitySystem` / `Survivalcraft` 0.1.6（见 `NuGet.config`）
- 打包工具 `Tools\PackTool` 生成 `[SuAPI]SuMiniMap.scmod`：`ModInfo.xml` 在 zip 根目录、DLL 放 `Lib/`、**模组 `Content/` 目录（含界面 XML）原样打进 zip**；VS 里 F5 或生成项目也会自动打包安装

### 安装

把 `[SuAPI]SuMiniMap.scmod` 放进 `Survivalcraft/Mods/` 即可（`IsMergeLib=true`）。

## 联机同步设计说明

联机通道调研结论（供后续开发参考）：

- **SuAPI 本体不含任何网络代码**；联机能力全部来自 `ScMultiplayer` 模组与其 `Comms` 连接库
- 游戏里发布的 `ScMultiplayer.dll` 是**混淆过的**：`Message` 的 `protected` 成员及 `SuReader/SuWriter` 类型名被改成不可见字符，外部模组**无法在 C# 中继承 `Message`**
- `Comms.dll` **未混淆**，其 `Comms.Drt.Client` 暴露了可用的公开收发接口：
  - 发送：`Client.SendDirectInput(target, bytes, sequenced, latest)`
  - 接收：`Client.DirectInput` 事件（`Action<int, byte[]>`）
- 本模组通过**反射仅用于取到 `Client` 实例**（官方 DLL 中该静态字段名被混淆，按类型查找），拿到后即用类型化 API 收发；找不到（单机/未装联机模组）时自动回退到自有 UDP 旁路或本地回环，不会导致模组加载失败

另有 `SuNetworkManager` 提供通用的**发包管理器**：

- 低频通道：可靠即时发送
- 高频通道：入队 → 按窗口**合并成最终效果包**后一次发出（`SuPacket.TryMergeInto` 可自定义合并规则）
- 传输层可插拔：官方通道 / 自有 UDP 桥 / 本地回环（`SuAutoEndpoint` 自动择优）

## 目录结构

```
Mod/SuMiniMap/
  Plug/            模组入口（GameDatabase 注册组件与子系统模板）
  Component/       相机、组件、子系统、网络、UI 控件
  Content/         嵌入资源（按钮与骷髅图标）
  Lib/             联机连接库引用（Comms.dll）
  Tools/           构建打包脚本（build_and_pack.cmd / pack.cs）
screenshots/       开发过程中的截图与测试分析脚本
```