Skip to content

API zh

Jump to bottom Edit New page
mouse114514 edited this page Sep 12, 2026 · 2 revisions

API 参考

English

本文档详细说明 CuBlocky 后端 REST API 的所有端点、请求参数和响应格式。

基础信息

  • 基础 URL： http://localhost:5099
  • 协议： HTTP
  • 数据格式： JSON（除非特别说明）

端点列表

方法 路径 说明
GET /api/catalog 获取积木目录
POST /api/build 构建模组 DLL
POST /api/compile/project 预览生成文件
POST /api/compile/register 编译注册代码
GET /api/projects 列出所有项目
POST /api/projects 创建新项目
GET /api/projects/{name} 加载项目
PUT /api/projects/{name} 保存项目
DELETE /api/projects/{name} 删除项目
GET /api/projects/{name}/assets 列出项目素材
POST /api/projects/{name}/assets/upload 上传精灵图
DELETE /api/projects/{name}/assets/{file} 删除素材
GET /api/projects/{name}/assets/raw/{file} 获取素材原始文件

详细说明

GET /api/catalog

返回所有可用积木的目录，用于前端积木调色板。

请求：

GET /api/catalog

响应：

{
  "nodes": [
    { "type": "cu_register_item", "category": "Register" },
    { "type": "cu_register_recipe", "category": "Register" },
    { "type": "cu_eat", "category": "Body" },
    { "type": "cu_drink", "category": "Body" },
    { "type": "cu_set_happiness", "category": "Body" },
    ...
  ]
}

响应字段：

字段 类型 说明
nodes Array 积木节点列表
nodes[].type String 积木类型标识
nodes[].category String 积木所属分类

POST /api/build

从蓝图构建模组 DLL。这是主要的构建端点。

请求：

POST /api/build
Content-Type: application/json

{
  "mod": {
    "name": "MyMod",
    "id": "com.example.mymod",
    "version": "1.0.0",
    "description": "My first mod"
  },
  "items": [...],
  "recipes": [...],
  "eventHandlers": "...",
  "eventHandlersXml": "...",
  "assets": [...]
}

请求体字段：

字段 类型 必填 说明
mod Object 是 模组元数据
mod.name String 是 模组名称
mod.id String 是 模组 GUID
mod.version String 是 版本号
mod.description String 否 模组描述
items Array 否 物品列表
recipes Array 否 配方列表
eventHandlers String 否 事件处理代码
eventHandlersXml String 否 Blockly 工作区 XML
assets Array 否 素材列表

响应：

{
  "success": true,
  "message": "Build succeeded!",
  "dllPath": "D:\\...\\builds\\MyMod\\bin\\Release\\MyMod.dll",
  "buildDir": "D:\\...\\builds\\MyMod"
}

响应字段：

字段 类型 说明
success Boolean 构建是否成功
message String 构建结果消息
dllPath String DLL 文件路径（成功时）
buildDir String 构建目录路径（成功时）

构建流程：

  1. 生成 C# 源文件（Plugin.cs, RegisterContent.cs, EventHandlers.cs）
  2. 写入 builds/{ModName}/ 目录
  3. 复制项目素材到 Sprites/ 子目录
  4. 运行 dotnet build -c Release
  5. 返回构建结果

错误响应：

{
  "success": false,
  "message": "Build failed: error CS0246: The type or namespace name 'xxx' could not be found"
}

POST /api/compile/project

预览将要生成的文件（不实际写入磁盘）。用于调试和检查。

请求：

POST /api/compile/project
Content-Type: application/json

{ ... Blueprint JSON ... }

响应：

{
  "files": {
    "MyMod.csproj": "<?xml version=\"1.0\" encoding=\"utf-8\"?>...",
    "Plugin.cs": "using BepInEx;...",
    "RegisterContent.cs": "using CUCoreLib;...",
    "EventHandlers.cs": "using HarmonyLib;..."
  }
}

响应字段：

字段 类型 说明
files Object 生成的文件内容
files.MyMod.csproj String 项目文件内容
files.Plugin.cs String 插件入口代码
files.RegisterContent.cs String 注册内容代码
files.EventHandlers.cs String 事件处理代码（可选）

POST /api/compile/register

仅编译注册代码，返回生成的 RegisterContent.cs 内容。

请求：

POST /api/compile/register
Content-Type: application/json

{ ... Blueprint JSON ... }

响应：

{
  "registerContent": "using CUCoreLib;\n\npublic static class RegisterContent\n{\n    public static void Register()\n    {\n        // 注册代码...\n    }\n}"
}

GET /api/projects

列出服务器 projects/ 目录下的所有项目。

请求：

GET /api/projects

响应：

[
  { 
    "name": "MyMod", 
    "cbpFile": "D:\\...\\projects\\MyMod\\MyMod.cbp" 
  },
  {
    "name": "AnotherMod",
    "cbpFile": "D:\\...\\projects\\AnotherMod\\AnotherMod.cbp"
  }
]

响应字段：

字段 类型 说明
name String 项目名称
cbpFile String 蓝图文件路径

POST /api/projects

创建新项目。

请求：

POST /api/projects
Content-Type: application/json

{
  "mod": {
    "name": "MyMod",
    "id": "com.example.mymod",
    "version": "1.0.0",
    "description": "My first mod"
  }
}

响应：

{ "name": "MyMod" }

GET /api/projects/{name}

加载指定项目的蓝图数据。

请求：

GET /api/projects/MyMod

响应：

{
  "mod": {
    "name": "MyMod",
    "id": "com.example.mymod",
    "version": "1.0.0",
    "description": "My first mod"
  },
  "items": [...],
  "recipes": [...],
  "eventHandlers": "...",
  "eventHandlersXml": "...",
  "assets": [...]
}

PUT /api/projects/{name}

保存项目蓝图数据。

请求：

PUT /api/projects/MyMod
Content-Type: application/json

{ ... Blueprint JSON ... }

响应：

{ "success": true }

DELETE /api/projects/{name}

删除项目及其所有文件。

请求：

DELETE /api/projects/MyMod

响应：

{ "success": true }

GET /api/projects/{name}/assets

列出项目的素材文件。

请求：

GET /api/projects/MyMod/assets

响应：

[
  { 
    "name": "sprite.png", 
    "size": 12345, 
    "uploaded": "2026-09-06T00:00:00Z" 
  }
]

响应字段：

字段 类型 说明
name String 文件名
size Number 文件大小（字节）
uploaded String 上传时间（ISO 8601）

POST /api/projects/{name}/assets/upload

上传精灵图文件。

请求：

POST /api/projects/MyMod/assets/upload
Content-Type: multipart/form-data

file: [二进制文件数据]

支持格式： .png, .jpg, .jpeg, .bmp

响应：

{ 
  "assetId": "sprite.png", 
  "name": "sprite.png", 
  "originalName": "my sprite.png" 
}

DELETE /api/projects/{name}/assets/{file}

删除指定素材文件。

请求：

DELETE /api/projects/MyMod/assets/sprite.png

响应：

{ "success": true }

GET /api/projects/{name}/assets/raw/{file}

获取素材原始文件（用于前端预览）。

请求：

GET /api/projects/MyMod/assets/raw/sprite.png

响应：

返回文件的二进制内容，Content-Type 为对应的 MIME 类型。

数据模型

Blueprint

蓝图是 CuBlocky 项目的核心数据结构。

interface Blueprint {
  mod: {
    name: string;           // 模组名称
    id: string;             // 模组 GUID
    version: string;        // 版本号
    description: string;    // 模组描述
  };
  items: ItemEntry[];       // 物品列表
  recipes: RecipeEntry[];   // 配方列表
  eventHandlers: string;    // 事件处理代码
  eventHandlersXml: string; // Blockly 工作区 XML
  assets: AssetEntry[];     // 素材列表
}

ItemEntry

物品条目定义。

interface ItemEntry {
  id: string;                    // 物品 ID
  fullName: string;              // 显示名称
  description: string;           // 物品描述
  category: string;              // 物品分类
  spriteRef?: string;            // 精灵图引用
  isAdvanced?: boolean;          // 是否为高级物品
  useAction?: string;            // 使用行为代码
  limbUseAction?: string;        // 肢体使用行为代码
  container?: ContainerProps;    // 容器属性
  tool?: ToolProps;              // 工具属性
  wearable?: WearableProps;      // 可穿戴属性
  liquidContainer?: LiquidContainerProps; // 液体容器属性
  battery?: BatteryProps;        // 电池属性
  light?: LightProps;            // 光源属性
  bandage?: BandageProps;        // 绷带属性
  syringe?: SyringeProps;        // 注射器属性
}

RecipeEntry

配方条目定义。

interface RecipeEntry {
  result: string;      // 产出物品 ID
  amount: number;      // 产出数量
  condition: number;   // 耐久度 (0~1)
  isLiquid: boolean;   // 是否为液体配方
  consume: boolean;    // 是否消耗材料
  ingredients: Array<{
    id: string;        // 材料物品 ID
    amount: number;    // 材料数量
    condition: number; // 材料最低耐久
    isLiquid: boolean; // 是否为液体
  }>;
}

构建产物

构建后在 builds/{ModName}/ 目录生成以下文件：

MyMod/
├── MyMod.csproj           # .NET 4.7.2 项目文件
├── Plugin.cs              # BepInEx 插件入口
├── RegisterContent.cs     # 物品/配方/建筑/地块/液体注册
├── EventHandlers.cs       # Harmony 补丁（使用事件时）
├── Sprites/               # 精灵图资源
│   ├── myItem.png
│   └── ...
└── README.md              # 自动生成的文档

文件说明

文件 说明
MyMod.csproj .NET 项目文件，定义依赖和编译选项
Plugin.cs BepInEx 插件入口点，处理插件生命周期
RegisterContent.cs 所有注册代码，包括物品、配方、建筑等
EventHandlers.cs Harmony 补丁代码，处理游戏事件钩子
Sprites/ 存放所有精灵图资源
README.md 自动生成的模组说明文档

错误处理

所有 API 端点在出错时返回统一的错误格式：

{
  "success": false,
  "message": "错误描述信息"
}

常见错误类型：

HTTP 状态码 说明
400 请求参数错误
404 资源不存在
500 服务器内部错误

使用示例

cURL 示例

创建项目：

curl -X POST http://localhost:5099/api/projects \
  -H "Content-Type: application/json" \
  -d '{
    "mod": {
      "name": "MyMod",
      "id": "com.example.mymod",
      "version": "1.0.0",
      "description": "My first mod"
    }
  }'

构建模组：

curl -X POST http://localhost:5099/api/build \
  -H "Content-Type: application/json" \
  -d @blueprint.json

上传素材：

curl -X POST http://localhost:5099/api/projects/MyMod/assets/upload \
  -F "file=@sprite.png"
Add a custom footer
Add a custom sidebar

Clone this wiki locally