星火 2.0 开发文档

主题

快速开始 ​

本文档将帮助您快速创建并运行第一个星火编辑器2.0项目。

新建项目 ​

2.0版本的编辑器在新建项目时提供多个模板。具体列表以编辑器当前版本显示为准，常见模板包括：

空项目模板（game_entry） ​

创建一个最小可运行项目，默认使用编辑器生成的 MapGameMode。它已经与地形编辑器、玩家队伍设置和场景配置联动，适合从头制作正式项目。

game_entry 的“空项目”是指最小可运行骨架，并不代表运行后完全没有界面。当前模板在客户端触发器 游戏开始时初始化 中预置了两条 GameSystemUI 动作：

  • 创建并启用移动控件
  • 创建并启用技能摇杆

如果项目不需要这些默认 UI，请在触发编辑器的客户端环境中打开 游戏开始时初始化，删除对应的动作；如果该触发器没有其它初始化逻辑，也可以直接删除整条触发器。也可以让 AI 助手代劳，例如告诉它“删除 game_entry 默认的 GameSystemUI 移动控件和技能摇杆”。AI 应通过触发器工具修改并保存，不应直接编辑 editor/trigger/**/*.json。

除非确实需要在同一项目里维护多个玩法模式，否则不要为了开始写逻辑而新建游戏模式或修改 GlobalConfig.cs。

数据示例模板（data_sample） ​

创建一个带数据编辑器示例数据的项目，适合学习数编 JSON、ScopeData 生成代码和运行时 GameData 的对应关系。

代码示例模板（code_sample） ​

创建一个包含大量示例玩法的项目。示例索引通常在项目的 docs/examples-index.md 或 src/EXAMPLES_INDEX.md 中；GlobalConfig.cs 里会列出可用示例模式，并指定测试时默认启动的模式。

编辑器功能 ​

图形化编辑器 ​

在图形化编辑器中，您可以像以前一样进行：

  • 地形编辑 - 创建和编辑游戏地图
  • 玩家队伍设置 - 配置玩家和队伍
  • 项目设置 - 配置基础的项目参数

触发编辑器、数据编辑器和 UI 编辑能力已经进入 2.0 工具链，但它们和 1.0 的成熟度、覆盖范围、操作习惯并不完全等价。遇到复杂逻辑时，当前仍建议把 C# 代码、数据编辑器、生成的 ScopeData 和必要的 AI/MCP 工具结合使用。

文档和API列表 ​

通过解决方案管理器访问 ​

在编辑器中新建或打开项目后，项目根目录通常会带有本地文档副本：

  • docs/sdk/ - SDK 文档
  • docs/api/ - 简化 API 声明
  • docs/schemas/ - JSON Schema
  • docs/resources/ - 官方资源索引
  • docs/examples-index.md - 示例索引（如果模板包含示例）

同时，C# 解决方案里也可能出现 Docs 目录链接，方便在 IDE 里直接阅读。

在Visual Studio或Rider中：

  • 打开解决方案后，可以直接在解决方案管理器中看到Docs链接
  • 点击即可浏览文档和API列表

在VSCode或Cursor中：

  • 需要在 .sln 文件上右键，选择"打开解决方案"
  • 然后在解决方案管理器(Solution Explorer)中才能看到Docs链接

手动查找文档目录 ​

如果无法通过解决方案管理器访问，可以手动定位文档：

  1. 打开项目的 src/WasiCoreSDK.props 文件
  2. 查看 WasiCoreSDKPath 属性，它定义了SDK的实际安装路径：
xml
<!-- src/WasiCoreSDK.props -->
<Project>
  <PropertyGroup>
    <WasiCoreSDKPath>SDK的实际路径</WasiCoreSDKPath>
  </PropertyGroup>
</Project>
  1. SDK路径会随安装目录变化，也会随着编辑器的更新而变化，请始终从该文件读取实际路径。要刷新最新的SDK路径，请在编辑器中打开一次项目，然后再次查看该文件。
  2. SDK 原始文档和 API 在该路径下的 api 和 docs 目录中；项目内的 docs/sdk、docs/api 是更适合当前项目和 AI 工具读取的本地副本

文档内容 ​

文档目录包含：

  • 框架概述和核心概念
  • 各系统的详细文档
  • 完整的API参考
  • 最佳实践指南
  • 常见问题解答

AI辅助开发 ​

如果您希望使用AI辅助开发，可以让AI助手熟悉该目录下的文档和API列表，以便在开发过程中提供帮助。

项目根目录的 AGENTS.md、CLAUDE.md 和 docs/ 目录已经是面向 AI Agent 的主要入口。若这些文件缺失或 SDK 路径发生变化，可以在项目根目录运行：

bash
pwsh -File "<sdk-path>/tools/setup-ai-context.ps1" -ProjectPath .

⚠️ 文档质量说明：部分文档和示例仍会随着 SDK 更新而调整。遇到冲突时，优先相信当前 docs/README.md、docs/api/、api/ 生成声明和项目模板中的实际代码。

构建项目 ​

2.0版本使用.NET 9.0，构建时需要指定配置标志。

编译服务端调试版本 ​

bash
dotnet build src/GameEntry.csproj -c Server-Debug

编译客户端调试版本 ​

bash
dotnet build src/GameEntry.csproj -c Client-Debug

如果有编译错误，请修正后再次编译验证。 在编辑器中点击调试按钮，编辑器会自动编译这两个版本。因此这里列出的构建命令仅供参考。

开发环境 ​

IDE配置建议 ​

使用支持C#语言的IDE可以：

  • 查看自动生成的代码
  • 使用智能提示和类型推断
  • 通过鼠标悬停查看类型信息
  • 快速导航到定义和引用

下一步 ​

环境准备就绪后，建议继续阅读：

常见问题 ​

Q: 示例代码在哪里？ ​

A: 选择 code_sample 模板后，示例代码在 src/ 下。优先阅读 docs/examples-index.md 或 src/EXAMPLES_INDEX.md，再根据需要查看 GlobalConfig.cs 中的模式列表和默认测试模式。