主题
WasiCore 开发排错与参考
开发入口、运行边界和依赖配置见 SKILL.md。本页保留资源与本地缓存的查找方法，并按问题链接到专题。
编译与运行
在编辑器创建的游戏项目根目录编译，而不是修改 SDK 或框架内部工程：
powershell
dotnet build src/GameEntry.csproj -c Server-Debug
dotnet build src/GameEntry.csproj -c Client-Debug两端分别检查条件编译代码；普通 Debug 不能替代它们。项目结构见游戏项目结构，真实连服、UI、多人和发布包验证见游戏项目验证。
按问题读取
| 问题 | 专题 |
|---|---|
| 需要组合 SCE Unit、GameGraph 或 Canvas 能力 | 游戏架构路线 |
| 注册入口、模式判断、UI 初始化顺序 | 生命周期 |
| 未识别游戏模式、事件数据丢失、玩家身份错误 | 常见开发陷阱 |
| 线程池异常、异步等待和取消 | WASM 异步与游戏时间 |
| 控件布局、文本溢出、字体太小 | 流式布局、字号与可读性 |
| Canvas 绘制、输入坐标与交互 | Canvas 游戏指南 |
| 3D 坐标轴与高度 | 坐标系统 |
| 日志、异常和运行现场 | 日志系统 |
游戏模式优先使用项目已有的 MapGameMode 及编辑器生成的玩家、队伍和场景设置。排查模式问题时，先检查双端可见性和初始化时机，不为调试重新创建另一套模式配置。
项目资源路径规则
AI 生成涉及资源的代码时，必须先区分“引擎资源加载”和“脚本直接读取文件”。完整说明见 docs/guides/ResourcePathGuide.md 与 docs/guides/ProjectFileAccess.md。
| 场景 | 文件位置 | 代码路径 |
|---|---|---|
UI 图片、Canvas Image、图标、精灵图 | ui/image/abc.png | image/abc.png |
official-icons.json 中的官方图标素材 | ui/icon/buff/_0000_水晶能量.png | icon/buff/_0000_水晶能量.png |
| UI Spine | ui/Spine/hero/hero.skel + .atlas + .png | Spine/hero/hero |
| GameGraph 2D 动画（Spriter / Spine） | Spriter/序列帧放 ui/image/Animated/coin.scml，Spine 放 ui/spine/hero/hero.skel；旧项目可继续用 res/... | AnimationSet2D.Load("image/Animated/coin.scml") 或 AnimationSet2D.Load("spine/hero/hero.skel") |
| 未上传云但需要随包的模型、粒子、音频等 | res/effect/custom/particle.effect 或 res/sound/custom/click.wav | effect/custom/particle.effect 或 sound/custom/click.wav |
| 脚本直接读取 JSON、文本、配置等普通文件 | 客户端 ui/AppBundle/user_files/...，服务端 AppBundle/user_files/... | user_files/... |
常见错误：不要写 new Image("ui/image/abc.png")，正确是 new Image("image/abc.png")；不要写 spine.Resource = "ui/Spine/hero/hero.skel"，正确是 spine.Resource = "Spine/hero/hero"；不要把 UI Spine.Resource 路径照搬给 AnimationSet2D.Load(...)，GameGraph 2D 动画需要写 .scml、.skel 或 .json 扩展名，且 UI 路径同样不写 ui/ 前缀；不要把引擎图片、Spine 或音频放到 user_files。AnimationSet2D 的 image/... / spine/... 路径会按依赖库优先级查找，找不到再 fallback 当前项目 res/...。resources/ui-images.json 来自 GameSystemUI，可以直接引用；需要先看原图时，从编辑器下载缓存 <EditorUpdateRoot>/res/_m/maps/gamesystemui/<version>/gamesystemui/ui/{path} 读取，多个版本优先看最大版本号。resources/official-icons.json 中的图标必须先复制到项目 ui/icon/...，代码或数据里仍写 icon/...；需要先看原图时，从 <EditorUpdateRoot>/res/icon/{sourceRelativePath} 读取。如果复制源不存在，告知用户打开编辑器美术资源库，点击左侧「图标」节点，等待右侧缩略图正常显示后再复制。自定义音频放在项目 res/sound/...，代码写 sound/...；SoundResource.Load 的参数类型是 GameCore.ResourceType.Sound，Sound 支持从 string 和 UTF8String 隐式转换；支持 WAV/OGG。需要发布统计的自定义音频，确保同一路径也出现在 GameDataSound.Asset 或其他 Sound / IFile 类型字段中，并优先直接写字面量路径；不要只靠运行时 new GameDataSound 批量注册音效，必须确认 Client-Resource 后 ref/objref.txt 包含路径。自定义模型、第一人称手臂、枪械视图或其他随包 3D 资源，如果不是云端资源库自动同步得到，也要进入可分析的数据链或显式资源清单。完整 3D 场景 2D 动画说明见 docs/systems/GameGraph2DAnimation.md。
自定义模型等资源通常在资源库中修改后会上传到云端，代码使用资源库路径即可。只有明确需要离线随包、暂时不走云端下载的资源，才放项目 res/。
自定义托管程序集
项目需要拆分业务代码或引入项目自有托管 DLL 时，优先通过 src/GameEntry.csproj 的普通 .NET 依赖管理：ProjectReference、PackageReference，或带明确来源的 Reference。编辑器正常编译、调试和发布流程会把项目产物部署到运行时 AppBundle。
项目自有 DLL 与对应运行端的 GameEntry.dll 同级：服务端放 AppBundle/managed/，客户端放 ui/AppBundle/managed/。程序集名称应使用项目自己的唯一名称，不要与 SDK 自带程序集名称或项目依赖库 ID 同名；若 DLL 名称对应某个依赖库 ID，该 DLL 由对应依赖库提供，不由主项目提供。SDK 与运行时组件由当前编辑器、SDK 和依赖库版本统一提供。
如果用户说自定义 DLL 已经放到 managed 目录但没有生效，AI 应先提醒检查 DLL 文件名是否与 SDK 自带程序集或项目依赖库 ID 重名；重名时应改用项目自己的唯一程序集名。使用 debug_start_no_compile 或直接启动纯客户端调试时，AI 还需要确认已经用对应配置构建，并把最新 GameEntry.dll 和项目自有输出 DLL 复制到对应端的 managed 目录。完整规则、示例和排查清单见 docs/guides/CustomManagedAssemblies.md。
本地模板与依赖库源码缓存
项目内 docs/examples-index.md 会指向可读的 map_templates/code_sample/src/ 示例源码；先按索引定位，再读取对应示例目录。GameSystemUI 和 GameSparkCore 依赖库也会以明文地图库形式出现在编辑器下载缓存中。
| 项目/库 | 职责 | 何时查看源码/数据 |
|---|---|---|
map_templates | 编辑器新建项目模板和完整示例集合；不是运行时依赖库。 | 选模板、搭骨架、参考完整示例时看 docs/examples-index.md 指向的 map_templates/code_sample/src/。 |
GameSystemUI | 通用 UI/输入依赖库，提供移动摇杆/键盘适配、技能摇杆、商店、背包、Buff/聊天等 UI 系统和内置 UI 图片。 | 看 <EditorUpdateRoot>/res/_m/maps/gamesystemui/<version>/gamesystemui/，例如 E:/WasmSCE/update/editor-master.spark.xd.com/res/_m/maps/gamesystemui/114/gamesystemui。 |
GameSparkCore | 通用玩法数据与辅助逻辑依赖库，提供预置 ScopeData、AI/属性/生命值/血条等默认数据和部分扩展方法。 | 看 <EditorUpdateRoot>/res/_m/maps/gamesparkcore/<version>/gamesparkcore/，例如 E:/WasmSCE/update/editor-master.spark.xd.com/res/_m/maps/gamesparkcore/163/gamesparkcore。默认数编源数据通常在 editor/data/gamesparkcore/ScopeData/ 和 editor/data/gamesparkcore/ScopeDataTemplate/。 |
同一库存在多个数字版本时，优先看版本号最大的目录。这些路径只用于阅读参考；项目代码仍应使用 SDK API、docs/api/ 声明、依赖库引用和正式资源路径，不要写入下载缓存绝对路径，也不要直接修改缓存内容。