# SurvivalcraftSuAPI

**Repository Path**: SC-SPM/survivalcraft-su-api

## Basic Information

- **Project Name**: SurvivalcraftSuAPI
- **Description**: Survivalcraft 2 SuMod 开发框架，用于创建第三方 Mod。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2025-10-02
- **Last Updated**: 2026-09-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Survivalcraft SuAPI

Survivalcraft 2 的 SuAPI 增强版，基于 .NET 8，支持 Windows 和 Android 双平台，内置 Mod 框架。

## 项目特性

- **双平台** — Windows（net8.0 self-contained）+ Android（net8.0-android APK）
- **SuAPI Mod 框架** — 内置 Mod 系统，支持 6 种核心组件、3 种注入模式
- **双 csproj 双 sln** — Windows 和 Android 各有独立的项目和解决方案
- **3 DLL 合并架构** — Engine.dll / GameEntitySystem.dll / Survivalcraft.dll
- **IsMergeLib 合并库模式** — 所有 Mod 统一 `IsMergeLib=true`、程序集扁平放 `Lib/`；**禁止**平台分目录（`Lib/X64/`、`Lib/Arm64/`），双端共用同一份平台无关 DLL
- **ModDns 模组索引** — 短码下载、平台标签、来源授权表、多语言显示名（第 6 段 `lang=名称`，`*lang=` 为强制语言）
- **中文支持** — 内置中文字体（`SuAPIFonts`）、`内容 → 管理` 本地化、输入框中文 IME 连打（`SuAPITextInput`）
- **平台差异按需生效** — 条件编译区分 Windows / Android（如可视距离档位、水平创造飞行面板）
- **SDK 版本分工** — **Mod 制作可用 .NET SDK 10**（TFM 是 `net8.0`，输出仍是 .NET 8 程序集）；**主程序编译必须 .NET 8 SDK**（`net8.0-android` 的工作负载只随 .NET 8 SDK 分发）。`global.json` = `8.0.402 + latestMajor`

## 使用方法

### 前置要求

- .NET SDK：**Mod 制作** 8.0 或 10 均可；**主程序编译必须 .NET 8 SDK**（Android 工作负载只随它分发）
- Android 工作负载（构建 Android 版时需要；**只有 .NET 8 SDK 能装 net8.0-android 的那一套**）
- Android SDK（平台 34 + build-tools 34.0.0，签名 APK 时需要）

### 编译

从项目根目录运行：

```bash
# Windows 桌面版
dotnet build Survivalcraft.sln

# Android 版
dotnet build SurvivalcraftAn.sln
```

### 发布

```bash
# Windows（self-contained）
dotnet publish Survivalcraft/Survivalcraft.csproj -c Release -r win-x64 --self-contained true -o publish/win-x64

# Android
dotnet publish Survivalcraft/SurvivalcraftAndroid.csproj -c Release -f net8.0-android -o publish/android
```

### APK 签名

`dotnet publish` 产出的 `<AppId>-Signed.apk` 用的是 **Android Debug 证书**，不能用于发布 —— 必须用发布 keystore 重新签名：

```bash
cd publish/android
zipalign -f 4 com.candyrufusgames.survivalcraft2su.apk aligned.apk
apksigner sign --ks <keystore路径> --ks-key-alias <alias> \
  --ks-pass pass:<store口令> --key-pass pass:<key口令> \
  --out signed.apk aligned.apk
apksigner verify -v --print-certs signed.apk     # 必须核对证书指纹
```

- keystore 路径、store/key 口令、alias、证书指纹与完整流程见 **`AGENTS.local.md`**（私有文件，不纳入版本控制）
- 含 `[]` 的文件名必须用 `-LiteralPath` 操作，`Move-Item -Path` 会当通配符
- 只改口令不改密钥时用 `keytool -storepasswd` / `-keypasswd`：证书指纹不变，已安装用户仍可覆盖升级

### 安装 Mod

将 .scmod 文件放入游戏 Mods 目录：
- Windows：`publish/win-x64/Mods/`
- Android：`/sdcard/Download/Survivalcraft2/Mods/`

### 开发 Mod（推荐：NuGet 方式，无需提交本仓库）

Mod 编译依赖已发布到 CNB NuGet 制品库，开发/编译 **Mod 只需拉取 NuGet 包，不需要克隆本引擎仓库、不需要从零构建**。

```bash
# 配置 NuGet 源（一次）
dotnet nuget add source \
  https://nuget.cnb.cool/suceru.cb/SuAPICore/-/packages/v3/index.json \
  --name cnb-nuget
```

csproj 中引用核心三件套（传递依赖自动解析）：

```xml
<ItemGroup>
  <PackageReference Include="Engine" Version="0.1.6.0" />
  <PackageReference Include="EntitySystem" Version="0.1.6.0" />
  <PackageReference Include="Survivalcraft" Version="0.1.6.0" />
</ItemGroup>
```

编译：`dotnet restore` → `dotnet build -c Debug`，产物在 `bin/Debug/net8.0/ModName.dll`。

> **重要**：Mod 源码与产物归 Mod 作者所有，**不需要也不应提交到本仓库**。本仓库只托管引擎核心依赖制品，不是 Mod 代码仓库。详细流程见 `doc/mod-nuget-compile-guide.md` 与 `doc/mod-development-guide.md`。

## SuAPI Mod 框架

### 六种核心组件

| 组件 | 接口 | 作用 |
|------|------|------|
| ModLoader | IModLoader | 加载 .scmod/.dll，解析依赖拓扑排序 |
| ModEventBus | IModEventBus | 发布/订阅事件 |
| ModInjector | IModInjector | 类名映射替换 |
| ModParentField | IModParentField | 反射读写私有字段 |
| ModParentMethod | IModParentMethod | 反射调用私有/父类方法 |
| ModResource | IModResource | 资源 KV 存储 + Content 目录加载 |

### 三种注入模式

| 模式 | 适用场景 |
|------|---------|
| 数据库替换 (EventBus) | Subsystem/Component 替换，新增实体模板 |
| Injector 类名映射 | IUpdateable/Block 类型替换 |
| Loading 注入 | Screen 替换，新增加载步骤 |

## 项目结构

```
项目根目录/
├── Engine/
│   ├── Engine/               # Windows 版引擎
│   └── Engine.Android/       # Android 版引擎
├── EntitySystem/
│   ├── GameEntitySystem/     # ECS 系统（含 SuAPI + TemplatesDatabase + XmlUtilities 合并）
│   └── SuAPI/                # Mod 框架接口与实现
├── Survivalcraft/
│   ├── Survivalcraft.csproj        # Windows 主项目
│   └── SurvivalcraftAndroid.csproj # Android 主项目
├── Mod/                      # Mod 示例源码（独立 git 仓库）
├── publish/
│   ├── win-x64/              # Windows 发布输出
│   └── android/              # Android 发布输出
├── Survivalcraft.sln         # Windows 解决方案
├── SurvivalcraftAn.sln       # Android 解决方案
└── global.json               # SDK 8.0.402 + rollForward: latestMajor
```

## 条件编译

| 定义 | 说明 |
|------|------|
| `WINDOWS` | Windows 桌面版编译时自动定义 |
| `ANDROID` | Android 版编译时自动定义 |

## 相关仓库

- Mod 示例集：https://gitee.com/SC-SPM/su-api-example-mod-set
- Gitee：https://gitee.com/SC-SPM/survivalcraft-su-api
- GitHub：https://github.com/SCAPI24/SurvivalcraftMonoWin