快速开始

这篇指南面向第一次做星火 2.0 / WasiCore 项目的开发者，带你从安装线上编辑器开始，完成登录、新建项目、接入 AI 或 IDE、做出第一个可观察的小玩法，并用一局真实连服调试确认结果。真正的游戏工程来自编辑器模板，无需克隆 SDK 仓库。

在线阅读（星火 2.0 文档站）：<https://doc-sce.taptap.cn/guides/QuickStart.html>。

新作者默认使用线上版编辑器（production 渠道）。只有需要提前验证尚未进入线上的新能力，或按官方安排做外网测试时，才使用外网编辑器（alpha 外网公开测试渠道）。外网与线上的环境差异、项目迁移和数据隔离见部署环境与运行时环境指南；新项目不需要先从外网开始。

如果希望由 AI 从命令行创建项目，或当前没有图形界面，读用 AI 创建第一个游戏。两条路线最终都落在同一个 WasiCore 项目、同一套双端编译和日志上。

WasiCoreSDK 是文档、API 声明、分析器和工具包。真正的游戏工程由编辑器从模板创建，打开项目后再通过 src/WasiCoreSDK.props 引用当前编辑器随包的 SDK。

星火有单位、技能、物品和场景等现成系统，也能按需增加自定义引擎功能。第一次开发时，先定一个很小、能结束的目标，例如“屏幕上有可点击目标，每点一次加 1 分，累计 10 分胜利并能重开”，再逐步补齐玩法；不需要先学习完整架构。已有暴雪地图编辑器、星火 1.0 或 Unity / Urho 经验的读者，可选读理解星火，快速对应熟悉的概念。

完整路线

阶段	做什么	完成标志
1. 安装、登录与选择版本	从线上版下载页下载并安装线上版编辑器；首次启动登录后在“编辑器版本选择”中选择 2.0 实验版本和 API 2000	版本选择或设置中确认 2.0 实验版本（API 2000，显示名可能是 wasm），账号已登录，官方资源下载完成
2. 创建项目	新建项目并选择 `game_entry` 模板，用编辑器打开一次	项目根目录有 `AGENTS.md`、`src/WasiCoreSDK.props` 和 `docs/sdk/`
3. 接入 AI	用 AI 工具或 IDE 打开项目根目录，读取 `AGENTS.md`，需要时连接编辑器 MCP	AI 能调用只读工具并返回当前项目信息
4. 第一个小目标	先做首次调试链路检查，再完成点按计分到 10、胜利和重开的极小玩法	客户端画面、服务端状态和日志都能观察到结果
5. 双端调试	用标准调试完成保存、生成、双端编译、部署和开局	双端构建通过，真实连服客户端进入游戏
6. 发布与测试	发布项目、配置后台测试模式、创建内测码；需要时进入 TapTap 测试	见平台内测与内测码和 TapTap 测试与正式上线

每一步都以实际结果为准，不以命令返回或界面提示代替。

准备

从线上版下载页下载并安装线上版编辑器。官网下载入口也应以线上版为准；如果下载页同时提供外网版入口，只在前一段列出的特殊场景选择。
首次启动先登录，再选 2.0。 启动器登录星火账号后，会打开“编辑器版本选择”，默认停在标准版本 1.0（API 13）。把版本类型改成 2.0 实验版本，版本号选 API 2000 对应项（当前安装可能显示为 wasm；不要选 13），确定后编辑器会按新版本重启。
如果没有出现版本选择窗口，或之前保存过设置，从 设置 → 编辑器版本 打开版本设置，确认版本类型为“2.0 实验版本”、版本号为 API 2000；旧安装没有该设置项时，先按正常更新流程更新编辑器。
确定后编辑器按 2.0 重启并开始更新；等待官方资源和运行包下载完成。下载没有完成时，先不要创建或调试项目。
线上版/外网版是部署渠道，1.0/2.0 是 API 版本：下载线上包不等于已经进入 2.0。如果当前渠道的版本选择里没有“2.0 实验版本”或 API 2000，先更新编辑器或改用实际提供该版本的安装；不要按 2.0 假设继续创建项目。
新版安装根目录的 sce-installation.json 会记录安装渠道和安装 API；当前 GUI 使用的版本以“设置 → 编辑器版本”中的选择为准。不要为了绕开问题手工修改渠道或 API 记录，也不要把线上项目和外网对战平台混用。
如果只使用编辑器内的标准调试流程，可以先不单独安装本机 .NET SDK；编辑器会使用随包的绿色版本 SDK 完成项目编译。
如果要手写 C# 代码，并希望在 IDE、终端或 AI 工具里自行执行 dotnet build 验证，再安装 .NET 9 SDK。
需要手写代码时，选择一个 C# 编辑器，例如 Visual Studio、Rider 或 VS Code。
如果使用 AI 辅助开发，让 AI 打开游戏项目根目录，不要只打开 SDK 目录。

可以用下面的表快速判断哪些东西已经随编辑器提供，哪些需要自己安装：

用途	编辑器已自带	通常需要另装
项目模板、SDK、文档、构建工具、AI 上下文	是	否
手写 C# 和浏览源码	模板与源码	C# 编辑器，例如 Visual Studio、Rider 或 VS Code
命令行 `dotnet build`	标准调试使用的随包 SDK	系统 .NET 9 SDK，仅在需要自行命令行编译时安装
AI 通过 MCP 开发	编辑器 MCP 服务	支持 MCP 的 AI 客户端
终端与脚本体验	Windows PowerShell 5.1 可用	PowerShell 7 推荐但可选；`rg`、coreutils 按需

Windows 下仍建议用户和 AI 助手安装并优先使用 PowerShell 7 (pwsh) 运行脚本和 AI 工具；但未安装 pwsh 不应影响项目刷新、资源统计或发布流程。这些流程里的脚本入口必须能回退到系统自带的 Windows PowerShell 5.1。Windows PowerShell 5.1 可能让中文日志和 UTF-8 输出乱码；需要诊断时参考 PowerShell 7 环境诊断 Skill。

需要大量终端操作时，优先补装 PowerShell 7，并让 AI 检查实际宿主版本。代码和日志搜索工具 rg、文本处理工具集 coreutils 均按需补充，先检查助手是否已提供；它们不是创建和运行第一个游戏的前置要求。coreutils 不会让 PowerShell 支持 Bash 脚本。

创建项目

打开星火编辑器，确认当前版本为 2.0（API 2000）。
进入新建项目菜单。
选择一个模板：
- game_entry：最小可运行项目，包含默认移动控件、技能摇杆和一个双端事件示例，适合做首次调试链路检查，也可以作为极小玩法的起点。
- data_sample / code_sample：学习数据编辑器、UI 和完整示例；目标接近时可以直接复用其中的场景、数据或组件。
- 专项模板：例如 3D 单位移动、对战/生存玩法等。如果已经有玩法目标，优先选择最接近的官方模板并复用其内容；具体以当前编辑器显示为准。
创建后用编辑器打开项目一次。

game_entry 适合确认最小链路；如果已经有明确的玩法目标，也可以直接从最接近的现有官方模板开始，复用它的场景、数据和组件。不要为了统一流程先清空成空项目，也不要私建一套框架层。

第一次打开项目很重要。编辑器会刷新 SDK 路径和 AI 上下文，包括：

src/WasiCoreSDK.props
AGENTS.md / CLAUDE.md
docs/sdk/
docs/api/
docs/schemas/
docs/examples-index.md
ai/tools/
纯客户端调试配置

不要把模板里的 src/WasiCoreSDK.props 当成稳定配置手工维护；它由编辑器按当前安装环境更新。

AI 复制模板的备用路线

首选仍然是用编辑器新建项目。只有在自动化、批量初始化或编辑器 UI 不方便操作时，才让 AI 从当前编辑器随包的 map_templates 复制模板。

让 AI 走这条路线时，要求它遵守下面几条：

从当前版本的 map_templates 复制，例如 game_entry、data_sample、code_sample 或专项模板，不要从一个旧项目倒推模板。
复制后更新 project/map_settings.json 里的项目标识，例如 ProjectName 和 MapDisplayName；TemplateName 通常保留为来源模板名。
不要手工固定 src/WasiCoreSDK.props 中的 SDK 缓存路径；复制完成后仍要用编辑器打开项目一次，让编辑器刷新 SDK 路径和 AI 上下文。
选择玩法起点时先读 wasicore-game-scaffold Skill，再决定是从空项目、代码示例还是完整模板改。

打开项目

用你的 IDE 或 AI 工具打开游戏项目根目录，然后先读项目根目录的 AGENTS.md。这个文件会告诉 AI 当前项目的 SDK 路径、模板来源、构建命令、日志位置和本项目的额外规则。

如果项目根目录还没有 AI 上下文，可以在编辑器里重新打开项目，或手动运行：

powershell

$PowerShellExe = (Get-Command pwsh -ErrorAction SilentlyContinue | Select-Object -First 1 -ExpandProperty Source)
if (-not $PowerShellExe) { $PowerShellExe = (Get-Command powershell -ErrorAction Stop | Select-Object -First 1 -ExpandProperty Source) }
& $PowerShellExe -ExecutionPolicy Bypass -File "<sdk-path>/tools/setup-ai-context.ps1" -ProjectPath .

<sdk-path> 可以从 src/WasiCoreSDK.props 读取。通常不需要手动运行这条命令；编辑器打开项目时已经会做。

确认 AI 读到的是当前项目：项目根目录、SDK 路径、构建命令和日志位置都应来自本项目的 AGENTS.md 和 docs/sdk/，不要沿用另一个项目的路径。

连接 AI 工具与 MCP

日常开发优先复用已经打开目标项目的图形编辑器。AI 工具通过编辑器 MCP 读取项目、编辑数据与触发器、构建和调试；接入方式见 SCE Editor MCP 接入指南。

连接后先让 AI 调用一个只读工具，例如 editor_get_context 或 data_list_tables，并返回当前项目信息。只显示“已连接”、但工具调用没有结果，不能算 MCP 可用。
如果 AI 客户端没有直接暴露编辑器 MCP 工具，而编辑器已经用 --mcp-port 启动，可以使用项目生成的 ai/tools/Invoke-SceEditorMcp.ps1 做健康检查和工具发现：

powershell

& ./ai/tools/Invoke-SceEditorMcp.ps1 -HealthOnly -Pretty
& ./ai/tools/Invoke-SceEditorMcp.ps1 -Tool editor_get_context -Pretty

项目里没有这个脚本时，先用编辑器重新打开项目刷新 AI 上下文；旧项目可能没有该入口。
如果希望 AI 自己创建项目、当前没有图形界面，或需要编排多个客户端，改用无头编辑器，按用 AI 创建第一个游戏的 sce.cmd init 和项目辅助入口执行。
图形编辑器和无头宿主不要同时写同一个项目。切换入口前先保存、结束正在进行的调试，并正常关闭原宿主。

本机命令行编译（可选）

编辑器的标准调试按钮会保存、生成、编译并部署项目，编译时使用编辑器随包的绿色版本 SDK。下面的命令行编译主要用于手写代码后在 IDE / 终端 / AI 工具里提前检查语法和双端 API 边界。

WasiCore 项目是客户端和服务端双端单源码。自行编译时，至少确认两个调试配置都能通过：

powershell

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

不要只编译一个端。#if SERVER 和 #if CLIENT 里的 API 可见性不同，只编译一端很容易漏掉另一端的错误。

第一次运行

用户已经打开目标项目的可视化编辑器时，优先复用，除非用户主动要求隔离。没有已打开的 GUI 或用户要求隔离时，AI 可优先通过无头编辑器完成项目创建、数据与触发器编辑、构建和单客户端连服调试。具体选择见开发入口规则；下面介绍图形编辑器的首次运行。

带服务端逻辑、玩家、Unit、Entity、CloudData、匹配、结算或多人同步的项目，优先用编辑器的标准调试按钮启动。标准调试会走保存、生成、编译、部署和调试 Host 流程，最接近发布和内测环境，也不要求用户自己提前安装本机 .NET SDK。

标准调试会依次完成保存、生成、双端编译、部署、开局和客户端接入。等待这些阶段都完成，不要在看到编译成功或客户端进程启动后立刻判定运行成功。

首次调试链路检查

先用未修改的 game_entry 确认编辑器、双端构建、客户端接入和服务端日志这条链路：

打开 game_entry 项目，点击标准调试。
等待游戏窗口出现。未修改的模板会创建默认移动控件和技能摇杆，先不要改它们。
在游戏窗口按 E。
服务端日志应出现 Hello,world!。模板里的客户端触发器把 测试双端事件 发给服务端，服务端触发器用 Game.Logger 记录内容。
如果按 E 后没有记录，按下面的“运行失败时先看哪里”排查。

这一步只验证链路，不是可玩目标；下一步做一个能计分、胜利和重开的小玩法。

如果已经自行编译并部署了最新 GameEntry.dll，也可以使用编辑器里的“调试（不编译）”命令跳过编译步骤。这个入口要求你自己保证服务端和客户端 AppBundle 中的 DLL 都是最新的；第一次上手通常不需要用它，细节见星火 2.0 发布、调试与 AI 辅助开发流程。

如果本轮只是在调 UI、Canvas、客户端 GameGraph 场景、模型预览或本地工具，可以使用纯客户端调试。纯客户端调试不会启动服务端，因此不能替代整局验证。详细路线见星火 2.0 发布、调试与 AI 辅助开发流程、纯客户端调试指南和 Runtime MCP 调试指南。

运行时日志通常在编辑器安装目录的 logs/ 下，而不是项目根目录：

客户端日志：<EditorRoot>/logs/client
服务端日志：<EditorRoot>/logs/server
编辑器 Lua 日志：<EditorRoot>/logs/lua
项目编译日志：<EditorRoot>/logs/build，新版编辑器同时在信息面板“编译”模块显示具体错误；AI 可用 build_diagnostics 获取文件与行列

旧项目根目录里的 Client-Debug.log / Server-Debug.log 可能是旧版编译输出，新版编辑器的实际构建日志路径以 build_status 为准。

编译失败或超时时，新版编辑器会打开“信息列表”，切到“编辑器”页并选择“编译”来源，清空搜索条件并显示全部严重级别。具体错误行右侧的源码路径及行列可点击，构建阶段消息右侧的日志路径也可点击。源码由系统关联程序打开，暂不自动跳到对应行；完整定位与 AI 重试流程见编译失败时查看错误和日志。

运行失败时先看哪里

**双端编译没有通过：**看信息列表的“编辑器 / 编译”来源，或用 build_diagnostics 取得文件与行列；先修编译错误，不要继续判断运行结果。
**构建成功但没有进入游戏：**先核对调试操作是否完成、游戏局和客户端是否属于同一轮。需要按目标关联客户端时，按 Runtime MCP 调试指南和星火 2.0 发布、调试与 AI 辅助开发流程检查；只看“客户端已启动”不够。
**进入游戏但行为没有变化：**确认本次使用标准调试，或确认“调试（不编译）”之前确实重新构建并部署了双端 AppBundle。
**画面黑屏、模型缺失或字体异常：**先确认官方资源和运行包已经下载完成，再判断是否为代码问题。
**提示项目被其他宿主占用：**不要结束不属于本轮的编辑器进程；先保存并正常关闭原宿主，再切换入口。

第一个可玩的小目标

首次调试链路只证明编辑器、双端构建、客户端接入和日志能工作。接下来做一个能开始、推进、结束和重开的极小玩法：

屏幕显示一个可点击目标和当前分数（例如 0/10）。
每点一次，客户端把一次命中发给服务端；服务端按玩家维护本局分数和进行中/胜利状态，客户端显示服务端返回的分数。
分数达到 10 时，服务端判定胜利，客户端显示胜利结果；胜利后继续点击不再加分。
提供“重开”按钮；重开后服务端分数和结果清零，可以再玩一局。
客户端只负责输入和显示，服务端维护分数与结果，不用客户端分数作为权威结果。

下面的任务可以直接交给 AI。它只给出目标和验收，不提供实现代码；AI 应优先复用当前项目的官方模板、触发器、双端事件和 GameSystemUI / GameUI 等现有能力，按项目已有模式实现。

交给 AI 的任务

text

项目路径：D:/Games/FirstGame。
先读项目根目录的 AGENTS.md 和 docs/sdk/ai/skills/sce-first-game/SKILL.md，再查看当前项目的模板、触发器、数据和 UI 结构。
在这个项目上完成一个极小的可玩玩法：
- 屏幕显示一个可点击目标和当前分数（例如 0/10）。
- 每次点击，客户端向服务端发送一次命中；服务端按玩家累加本局分数并保存进行中/胜利状态，客户端显示服务端返回的分数。
- 分数达到 10 时服务端判定胜利，客户端显示胜利结果；胜利后继续点击不改变结果。
- 提供重开按钮；重开后服务端分数和结果清零，可以再玩一局。
客户端只负责输入和显示，不要用客户端分数作为权威结果。优先复用现有官方模板/组件和项目已有的触发器、双端事件、GameSystemUI / GameUI 能力，保持本轮目标小，避免无关重构；不新建私有框架。
完成后编译 Server-Debug 和 Client-Debug，启动一局真实连服调试，验证：初始 0 分；点击后分数增加且客户端与服务端一致；达到 10 分显示胜利；重开后回到 0 分并能再次得分。给出构建结果、画面截图和双端日志路径。
最后停止本轮调试并确认清理；不要发布游戏。

任务里限定了目标、权威端、可观察结果、双端构建、运行证据和停止条件。模板选择应服从项目目标：如果已有接近的完整模板，可以直接复用；game_entry 只用于最小链路检查或极小玩法起点。

验收标准

检查	预期结果
初始状态	客户端显示 0/10，服务端日志或状态显示本局分数为 0
点击计分	每次点击只增加 1 分，客户端显示与服务端记录一致
胜利	第 10 分后服务端判定胜利，客户端显示胜利；继续点击不改变结果
重开	服务端分数和结果清零，客户端回到初始状态，可以再次完成一局
编译	`Server-Debug` 和 `Client-Debug` 都通过；失败时给出文件与行列
运行	标准调试进入真实游戏局，画面、客户端和服务端日志能对应
收尾	停止本轮调试并确认客户端与进程清理，不自动发布

以下目标是给 AI 的任务和验收标准，不代表本文已经用一个新项目真实跑通；具体 UI、事件名和触发器写法以当前项目和官方能力为准。没有双端构建结果、运行画面或日志，不能算完成。

手动改代码

如果你更想先手写代码，可以从这个最小的 IGameClass 开始。它只验证注册和双端日志，不涉及上面的小游戏。在 src/HelloStartup.cs 中添加：

csharp

using GameCore.GameSystem.Data;

namespace GameEntry;

public class HelloStartup : IGameClass
{
    public static void OnRegisterGameClass()
    {
        if (GameDataGlobalConfig.TestGameMode != ScopeData.GameDataGameMode.MapGameMode)
        {
            return;
        }

        Game.OnGameTriggerInitialization += OnGameTriggerInitialization;
    }

    private static void OnGameTriggerInitialization()
    {
        new Trigger<EventGameStart>(static async (s, d) =>
        {
#if SERVER
            Game.Logger.LogInformation("Hello from server.");
#elif CLIENT
            Game.Logger.LogInformation("Hello from client.");
#endif
        }).Register(Game.Instance);
    }
}

注意几点：

OnRegisterGameClass() 由框架自动发现并调用，不要手动调用。
游戏模式判断放在注册逻辑里，避免把代码接到错误的测试模式。
日志使用 Game.Logger，不要用 Console.WriteLine。
双端差异写在 #if SERVER / #if CLIENT 中。

需要帮助

编辑器或 2.0 版本问题（版本选择、安装更新、构建或运行异常）：加入星火 2.0 反馈与支持 QQ 群 1021737313。
发行支持（项目发布、发行流程）：加入发行支持 QQ 群 710734685；该群由 1.0 / 2.0 共用。
TapTap 测试与正式上线接洽：读 TapTap 测试与正式上线的联系支持说明，按其中入口联系；当前接洽 QQ 为 619956807，如有更新以该指南为准。

自助内测仍按正常发布和后台模式配置执行；没有额外测试准入不等于跳过这些步骤。

下一步

发布前先结束本轮调试并确认清理。 发布准备会独占项目，不要在调试会话未结束时开始发布。
**发布并创建内测码：**读平台内测与内测码。项目正常发布后，在创作者中心配置测试模式并创建内测码；内测码测试没有额外的测试准入条件，但仍需完成正常发布和后台模式配置。内测运行在 test 环境，只能消耗已有星火币、不能充值；项目上线（formal）后可以在星火对战平台充值。TapTap App 内嵌启动仍需另行开通 TapTap 测试。
**TapTap 测试与正式上线：**读 TapTap 测试与正式上线。这条路线可以验证星火币充值和 TapTap App 内嵌启动，但测试开通需要联系工作人员，不能自行开通；它不是开始内测的前置步骤，需要验证这些能力时再进入。
日常开发闭环：星火 2.0 发布、调试与 AI 辅助开发流程。
按需选架构：游戏架构路线与空间模型，或 wasicore-game-scaffold Skill。第一个目标跑通后再读，不要提前堆架构。
查看完整示例：官方示例画廊。
发布前检查：游戏完整性检查清单。

第一次运行成功不等于发布；发布、后台模式配置和内测码创建是另外的步骤。

快速开始 ​

完整路线 ​

准备 ​

创建项目 ​

AI 复制模板的备用路线 ​

打开项目 ​

连接 AI 工具与 MCP ​

本机命令行编译（可选） ​

第一次运行 ​

首次调试链路检查 ​

运行失败时先看哪里 ​

第一个可玩的小目标 ​

交给 AI 的任务 ​

验收标准 ​

手动改代码 ​

需要帮助 ​

下一步 ​

快速开始

完整路线

准备

创建项目

AI 复制模板的备用路线

打开项目

连接 AI 工具与 MCP

本机命令行编译（可选）

第一次运行

首次调试链路检查

运行失败时先看哪里

第一个可玩的小目标

交给 AI 的任务

验收标准

手动改代码

需要帮助

下一步