# 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**: 1
- **Forks**: 0
- **Created**: 2025-10-02
- **Last Updated**: 2026-06-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Survivalcraft Unified (Win + Android)

Survivalcraft 2 跨平台统一项目，基于 .NET 8，合并自：
- `SurvivalcraftMonoWin-SuAPI-0119`（Windows 桌面版）
- `SurvivalcraftMonodroid-SuAPI-0119`（Android 版）

## 架构

采用 **双 csproj 双 sln** 方案（方案 C），Windows 和 Android 各有独立的 csproj 和 sln：

| 解决方案 | 主项目 | Engine | 目标框架 |
|----------|--------|--------|---------|
| `Survivalcraft.sln` | Survivalcraft.csproj | Engine.csproj | net8.0 |
| `SurvivalcraftAn.sln` | SurvivalcraftAndroid.csproj | EngineAndroid.csproj | net8.0-android |

### 项目结构

```
SurvivalcraftMonoWinAN/
├── Engine/
│   ├── Engine/                   # Engine.csproj (net8.0) — 预编译 OpenTK.dll
│   ├── Engine.Android/           # EngineAndroid.csproj (net8.0-android) — OpenTK 项目引用
│   ├── FluxJpeg/                 # JPEG 编解码 (InternalsVisibleTo: Engine, EngineAndroid)
│   ├── Hjg/                      # PNG 编解码
│   ├── NVorbis/                  # OGG/Vorbis 解码
│   └── OpenTK/                   # OpenGL ES 绑定 (net8.0 空壳; net8.0-android 完整)
├── EntitySystem/
│   ├── GameEntitySystem/         # ECS 系统
│   ├── SuMod/                    # Mod 框架（引用 Engine 而非 GameEntitySystem）
│   ├── TemplatesDatabase/
│   └── XmlUtilities/
├── Survivalcraft/
│   ├── Survivalcraft.csproj      # 纯 net8.0
│   ├── SurvivalcraftAndroid.csproj # 纯 net8.0-android (obj.android/bin.android)
│   └── Directory.Build.props     # Android 中间输出路径
├── Survivalcraft.sln             # Windows 版
├── SurvivalcraftAn.sln           # Android 版
├── global.json                   # SDK 8.0.402, rollForward: disable
└── Directory.Build.props         # AndroidSdkDirectory
```

### Android 变体文件

同目录下的 `*.Android.cs` 文件是 Android 版替代实现（如 `Storage.Android.cs` 替代 `Storage.cs`）：
- Engine.csproj 用 `<Compile Remove="**\*.Android.cs" />` 排除
- EngineAndroid.csproj 用 `<Compile Remove>` 排除对应的 Windows 版文件

## 条件编译

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

## 构建方式

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

### Android 版
```bash
dotnet build SurvivalcraftAn.sln
```

## SuMod Mod 框架

SuMod 是内置的 Mod 系统，支持六种核心组件和三种注入模式：

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

详细文档见 `doc/sumod-architecture.md` 和 `doc/mod-development-guide.md`。

## 已完成

- [x] 双 csproj 双 sln 架构（方案 C）
- [x] 双平台 0 错误编译
- [x] Windows 版成功运行
- [x] 2.4.10.1→2.4.10.8 版本升级精细合并
- [x] LoadingManager 分帧加载架构
- [x] 15 个 ElectricElement 枚举化 bug 修复
- [x] Android data: 路径统一架构
- [x] F11 全屏切换
- [x] 6 个 SuMod 迁移（ConsoleMod/MemoryBankDrawMod/RainWithoutDawn/StringInterceptor/MiniMap/ScMultiplayer）
- [x] Git 初始提交推送（Gitee + GitHub）

## 待完成

- [ ] Game 层 127 个差异文件条件编译
- [ ] Engine 层 52 个差异文件
- [ ] Content.pak 双平台条件嵌入
- [ ] Android 版完整运行验证

## MAUI 移植版 (net10.0)

基于本项目已完成 MAUI 移植，项目路径: `P:\UGIT\Survivalcraft`
- 三个子项目: Engine/EntitySystem/Survivalcraft，均为 MAUI 多目标(net10.0-android/windows/maccatalyst)
- Silk.NET 替代 SharpDX + OpenTK
- WindowsAppSDK SelfContained 部署
- Android 输入系统全面修复（触摸/手柄/键盘/鼠标）
- 双平台编译 0 错误通过

## 已完成

## 文档索引

| 文档 | 内容 |
|------|------|
| `SOUL.md` | 项目铁律（27 条） |
| `AGENTS.md` | 贡献规范与文档索引 |
| `doc/architecture.md` | 双 csproj 双 sln 架构详解、配置细节、SuMod 集成 |
| `doc/msbuild-traps.md` | 12 个 MSBuild/构建陷阱及解决方案 |
| `doc/decompilation-merge-guide.md` | 2.4.10.1→2.4.10.8 反编译合并经验 |
| `doc/sumod-architecture.md` | SuMod 六大组件、注入模式、常见陷阱 |
| `doc/mod-development-guide.md` | Mod 开发 5 步流程、项目模板、AOT 兼容 |

## 仓库

- Gitee: https://gitee.com/SC-SPM/survivalcraft-su-api
- GitHub: https://github.com/SCAPI24/SurvivalcraftMonoWin