更新日志

本页汇总星火 2.0（WasiCore）跨端——客户端 / 编辑器 / 服务端 / 框架 / SDK——的对外更新说明，按发布周期倒序排列（最新在最上）。右侧「版本」目录可快速跳到各发布周期。

发布状态说明

• 已发布至外网测试环境：已上线 alpha 外网公开测试环境，可在外网体验。
• 已发布至线上正式环境：已进入 production 线上生产环境，玩家可在 TapTap 正式渠道游玩。
• 线上可用时间以当前发布状态为准：外网与线上按各自发布计划更新；同一能力进入线上还需要对应平台和客户端版本覆盖，具体以各周期标题中的发布状态、官方公告和编辑器提示为准，不按固定滞后天数推算。

2026-10-27 ～ 2026-11-03（已发布到线上正式环境）

当前客户端能力版本：10（本期从 9 提升至 10）。粒子确定性回放需要客户端能力 10；其他更新不增加客户端能力要求。

本期重点速览

本期客户端能力版本从 9 提升到 10。粒子确定性回放支持按种子和固定步长定位播放时刻，便于逐帧评审和问题复现；多个 AI 会话可共用无头项目，多开调试自动安排连接端口；数编 UI 字体自动收集到发布清单，并完善项目发布校验、编辑器启动及跨端稳定性。

粒子确定性回放

粒子效果过去每次挂载都从引擎随机源取初始状态，同一 .effect 和目标时刻不能稳定复现。现在可在挂载时指定实例种子，或用节点/发射器 API 固定种子、恢复初始状态并按固定步长推进到指定播放秒。

• 挂载时固定种子： ParticleSystem.AddToNode(node, randomSeed) 按节点已有发射器数量和 effect 序号派生种子；需要绝对时刻时调用 static ParticleSystem.Replay(node, seed, absoluteTimeSeconds, fixedStepSeconds)。
• 单发射器与手动步进： ParticleEmitter.RandomSeed、DeterministicMode/TrySetDeterministicMode、Advance、Replay 可用于单独控制发射器；Advance 从当前状态继续，Replay 从 seed 初始状态重放。RandomSeed 读取旧挂载实例时返回 mount seed，只有显式设置才作为 Reset 恢复目标。
• 确定性模式播放： 在确定性模式中，Play/Reset 只重置发射器，不会恢复自动播放；先关闭确定性模式再 Play，才会恢复每帧自动推进。
• 同一资源的多实例播放： 修复自定义 burst 触发标志和粒子灯光累计状态共享时，多个实例可能互相影响的问题；各发射器分别保存并重置这些运行状态。
• 时间与步长： 参数是播放秒，实际时间乘当前 TickSpeed；Advance/Replay 要求有限、非负时间和正步长，单次最多 100000 步，默认 0.05 秒。Seek 仍是增量推进，但非有限、非正或超过 100000 个 0.1 秒步的请求会被忽略且状态不变。
• 种子与结构： 设置 RandomSeed 后需 Reset/Play/Replay 才重算已有粒子；节点级种子按发射器组件顺序分配，增删或重排后需要重新设置。排序/动态合批身份不随种子改变。
• 能力与验收： 需要客户端能力 10，使用前检查 ClientEnvironment.Runtime.Supports(ClientRuntimeFeature.ParticleDeterminism)；旧客户端的可用范围见客户端二进制兼容与能力版本。相同种子、步长、TickSpeed 和渲染配置会按相同步骤推进；不同 GPU/平台不承诺逐像素一致。首期不支持带 EmitterHierarchy 的效果，相关模式设置/推进/回放返回 false 或拒绝，普通自动播放不受影响。

编辑器启动与版本选择

• 修复 Windows 图形界面编辑器启动器可能将同一安装目录下正常运行的无头编辑器及其辅助进程、调试客户端当作残留进程关闭的问题。需更新启动器。
• 修复 Windows 图形界面编辑器通过启动器连续多开时，新实例可能将先前正常运行的实例误判为残留进程并强制关闭的问题。需更新编辑器二进制。
• 无头编辑器提示二进制更新： sce.cmd serve 启动时检查当前安装渠道、API 版本和发布标签的编辑器版本；也可使用 sce.cmd check-update 单独查询。AI 可通过启动事件和能力查询读取结果。有更新或查询失败时仍可继续使用，离线明确跳过检查；当前仅检测提示，需关闭宿主后经正常编辑器更新流程安装完整配套程序。需更新编辑器、安装根入口和 SDK helper。
• 首次启动时选择编辑器版本： 未保存编辑器版本设置时，启动后显示版本选择窗口，可选择 1.0 正式版本或 2.0 实验版本；首次默认选中 1.0 正式版本（API 13）。完成选择后按保存设置启动，也可勾选每次启动询问。需更新启动器、编辑器及配套启动脚本。
• 修复 Windows 编辑器启用 WARP 软件渲染兼容模式时可能在初始化阶段崩溃的问题，包括自动兼容路径和 -force_warp 启动方式。
• 收窄自动软件渲染范围： 仅在电脑只有一块显卡，且显卡名称为 Intel(R) Graphics 时自动启用 WARP，不限定设备 ID 或驱动版本；多显卡电脑及其他显卡名称保持原有渲染方式。可用 -disable_warp 或 -no_warp 强制关闭 WARP，关闭参数优先于 -force_warp。

编辑器菜单与帮助入口

从编辑器进入文档、示例和反馈渠道时，可直接访问 2.0 对应入口。

• 帮助菜单新增 2.0 交流群： 编辑器在帮助菜单提供“2.0 交流群”，打开已上线的 2.0 帮助入口并显示群号。需更新编辑器脚本（热更）。
• 加载页提供 2.0 新手入口： 加载页提供 2.0 文档站 doc-sce.taptap.cn、更新日志、快速开始和示例入口，并显示 2.0 支持群。加载页属于远程前端，更新后直接生效，不要求更新编辑器。
• 快速开始补充停止调试规则： 快速开始与AI 快速开始补充“发布前先结束本轮调试并确认清理”，说明发布准备会独占项目。本项为文档更新。

多个 AI 会话共用无头项目

多个 AI 会话可以连接同一个无头编辑器宿主，在共享项目中分工编辑，无需为每个会话重复启动宿主。各会话分别接收自己的请求结果，单个连接断开后，其它会话可以继续工作。

• 分别连接同一个项目： HTTP 客户端分别初始化并保留各自的 Mcp-Session-Id，WebSocket 每条连接建立独立会话；请求 ID 与请求取消按会话隔离。数据、触发器及资源读取由宿主统一排队，项目切换后会重新校验请求。需更新完整配套无头编辑器包，并通过 headless_get_capabilities 确认多会话支持。
• 交接长任务的控制权： 持久会话启动的构建、调试和发布等任务记录所属会话，其它会话可查询状态。需要交接或断线重连后继续控制时，使用 headless_takeover_operation 指定操作 ID、当前所属会话及原因，再执行正常的停止或取消；断线和接管都不会自动终止任务。接管父操作会同步交接其子任务；只接管子任务时，原父操作所属会话仍可控制它，整条任务链交接应选择父操作。
• 按文件和功能分工： 各会话共用项目数据、选择状态与撤销历史，磁盘源码修改仍需约定负责人，不会自动合并冲突。保存生成、构建、调试和发布应统一安排；GUI 多会话协同不在此次支持范围。同步更新无头编辑器指南与操作 Skill。

AI 调试与多开连接

多开项目时，AI 可明确选择编辑器及本次调试客户端，减少手工安排端口，并在连接变化后重新确认目标。

• 修复无头编辑器生成触发器代码时，将有效数编引用生成为 null、导致编译失败或运行时无法取得配置的问题；按当前项目及依赖库解析实际数编引用，无法解析时明确报告错误。需更新无头编辑器二进制，并重新生成触发器代码。
• 修复无头调试停止后，远程游戏局销毁确认晚于本地清理时，状态快照仍显示租约被占用的问题；收到精确销毁确认后，租约字段同步更新。需更新配套无头编辑器及原生辅助程序。
• 修复 Runtime MCP 的 debug.ping 将项目父目录作为 map_path 返回的问题，改为返回所选游戏实例实际加载的完整项目路径，便于区分同目录下的多个项目。需更新客户端或编辑器二进制。
• 修复部分 Windows 系统区域设置下，无头调试查找含中文路径的客户端日志时可能导致辅助进程异常退出的问题；统一按 UTF-8 读取及返回路径，日志查找失败时保留具体步骤和系统错误码，并继续客户端状态与 Runtime 探测。需更新完整配套编辑器包。
• 修复 Windows 无头编辑器启动时，因崩溃上报初始化与系统硬件栈保护兼容不当而可能异常退出的问题；启动兼容配置与 GUI 编辑器保持一致。需更新无头编辑器二进制。
• 开发前准备项目 SDK 与文档： 更新无头编辑器指南及 AI Skill：已知编辑器安装路径时，开发前先通过该安装的 sce.cmd prepare 准备所选渠道、API 和项目版本约束对应的 SDK、文档及 AI 上下文；本轮已准备成功的项目无需重复。安装路径无法确定时明确说明尚未刷新，不将启动宿主或二进制版本检查当作准备完成。本项为文档与 AI 指引更新。
• 修正无头项目准备与客户端选择： AI 上下文准备优先使用已安装的 PowerShell 7，并保留系统 PowerShell 回退；失败诊断补充实际执行路径和脚本异常。切换编辑器安装或 API 时，默认连服启动记录跟随当前安装刷新，自定义客户端路径、参数及显式覆盖继续保留。同步补充准备与启动器更新排查指南、AI Skill；需更新完整编辑器包和配套 SDK。
• 解除无头辅助程序的 WinUI 启动依赖： 原生无头辅助程序启动时不再要求加载 WinUI，GUI 消息处理仍按需加载对应组件。需更新完整配套编辑器二进制；托管 .NET 和可视化调试客户端的系统要求保持原有范围。
• 补齐无头宿主故障诊断： 默认保存托管与原生辅助进程日志，记录早期启动阶段、标准输出与错误输出、进程 ID 和十六进制退出码，便于排查编译成功后客户端仍未就绪的问题；配套接入 Themis 崩溃上报并区分进程角色，补齐原生辅助程序与诊断模块的匹配调试符号，帮助定位崩溃调用栈。启动回执给出实际日志路径及上报初始化状态，SDK 不可用时仍保留本地日志。同步补充排查文档与 AI Skill；需更新完整配套编辑器二进制。
• 同账号同时调试不同项目： 2.0 GUI 与无头编辑器支持按账号和项目分别分配远程调试 Host；启动另一个项目的调试可保留原项目的游戏局，同账号同项目重新调试仍会结束上一局。需配套更新 Host 分配服务、编辑器和脚本；旧客户端保持原分配方式。每个项目仍占用独立 Host，受可用服务资源限制。同步补充多开指南与调试 AI Skill。
• 通过 MCP 启动独立客户端调试： 调试启动工具支持选择编辑器内调试或连接服务端的独立客户端，并可为本次调试覆盖 Runtime MCP 端口。编辑器启动时设置的 Runtime 端口也会传递给后续调试；单次覆盖不改变下次默认值。
• 明确游戏设置的调试范围： 编辑器内调试首次读写 ClientSettings 时，每个游戏局提示一次保存与读回支持不完整，部分设置仍可能影响编辑器进程。请使用独立客户端调试验证画质、音频和本地偏好，包括无头编辑器启动的独立调试客户端。同步补充 API 注释、文档和 AI Skill；运行时提示需更新编辑器二进制，现有调用行为保持不变。
• 多开时自动安排 MCP 连接： GUI 编辑器和调试 Runtime 默认使用可用端口，提供实际连接地址与实例 ID。AI 可列出编辑器实例并选择目标；Runtime 转发自动读取所属调试的连接信息，同进程多个玩家继续通过 target_id 选择。显式固定端口被占用时报告失败，避免请求误入其它调试实例。
• 无头调试与发布自动安排内部控制端口： 原生辅助进程默认直接绑定系统分配的空闲端口，并将实际连接回报给无头编辑器，减少多个宿主之间的端口冲突；--native-service-port、--publish-service-port 可设为 0 使用自动模式，也可指定固定端口。固定端口被占用时明确失败，启动校验失败或取消时清理本次辅助进程。同步更新文档与 AI Skill；需更新配套无头编辑器及原生辅助程序。
• 修复无头辅助进程关闭时因会话清理顺序可能触发崩溃的问题，并避免固定控制端口监听失败后弹出阻塞后台流程的错误对话框。
• 修复正常保存、生成或双端编译时将项目自定义调试用户 ID 集合重置为默认值的问题；已有 config.ini 的 [debug_setting].user_ids 表会保留，未配置时才生成默认集合。无头客户端接入时，显式 user_id 与开局冻结的槽位身份不一致会明确报错；省略时使用该槽位的冻结 ID。更换集合需停止旧局，在新开局前修改配置。ID 范围为 1～2147483647，同局不可重复，支持 1111 等自定义值。需更新配套无头编辑器与原生辅助程序。
• 修复无头调试查询可接入槽位时读取已转移的 JSON 数组的问题，避免 Debug 构建触发断言弹窗，并修正可接入状态的计算。需更新原生辅助程序。
• 通过 AI 配置项目横竖屏： GUI 编辑器新增 project_get_orientation / project_set_orientation，可读取或设置横屏、竖屏并保存至项目配置，同步项目设置面板；面板中已有未保存的方向修改时提示先保存或取消，避免覆盖手动选择。需更新编辑器。配套补充无头项目横竖屏配置及首次上手、调试 AI Skill，说明 [map].is_landscape、保存编译时的保留规则，以及项目方向与桌面调试窗口尺寸的区别。
• 更新项目内调试 helper、多开编辑器与 MCP 调试连接、Runtime 调试指南及配套 AI Skill，补充自动连接、固定端口、启动参数继承、单次覆盖和实例变化后的恢复流程。无头编辑器指南补充双项目、自定义 ID 集合与独立客户端端口的完整编译调试示例，以及按项目停止和清理的步骤。需更新编辑器、配套启动脚本与 SDK，并重新生成已有项目的 AI 上下文。
• 优先复用编辑器登录，设备授权直接给带码链接： AI 先复用所选编辑器在同一安装、同一 editor server 下已有的有效登录；隔离项目或测试不因此默认强制重新登录。确需 TapTap 设备授权时，展示当前有效的完整授权链接与到期时间；TapTap 只有基础 verification_url 和 user_code 时按 qrcode=1&user_code 安全合并并编码，不再要求用户在裸 /device 页面手工输入短码。同步更新无头编辑器指南与 AI Skill；现有认证方式和权限校验不变，本项为指引修正。

项目模板

• 修复代码示例（code_sample）中测试游戏模式的场景引用失效，以及三个镜头继承不存在的数据、无法正确生成配置的问题；镜头改为继承公开镜头模板并保留各自配置。同时清理 code_sample、空项目（game_entry）和 3D 移动模板（unit_movement_3d_template）中无等待操作的异步回调警告。需更新项目模板；已有项目需同步对应源文件后重新生成、编译。
• 修复 GameSparkCore 中对话样例及模板的头像左右位置引用、文字表现模板的颜色格式导致 GDATA001 警告并遗漏赋值的问题；同时修正通用近战攻击模板的目标搜索范围字段，保留原有 200 范围。需更新 GameSparkCore 依赖库；已复制到项目中的数据需同步修正后重新生成、编译。
• 修复战场模板（battle_grounds_template）中英雄的死亡移除延迟配置无法生成、出现 GDATA001 警告并遗漏赋值的问题，恢复死亡后保留英雄等待复活的配置。需更新项目模板；已有项目可将 BattleGroundsHero.Root.DeathRemovalDelay 改为 "-00:00:00.0010000"（等价于 Timeout.InfiniteTimeSpan），再重新生成、编译。
• 修复数据示例（data_sample）中部分技能的公式与校验器引用失效、生成时出现 GDATA001 警告并遗漏字段赋值的问题，恢复伤害、治疗、弹射与冲锋等样例的对应配置；移除火龙无效的单位筛选标签，并修正冲锋速度的未使用变量及火龙移动的过时销毁调用。需更新项目模板；已有项目需将公式引用中的 data_sample.Validator 改为 GameEntry.Validator，移除火龙的 UnitFilter.Ranged 配置并同步对应触发器修改，再重新生成、编译。
• 修复使用战场模板（battle_grounds_template）新建项目后，因校验器引用失效的异步结果构造方法而导致触发器生成代码无法编译、阻止调试的问题。需更新项目模板；已有项目需修正“拾取函数”、ClearMagicOrbHashSet 和 MagicOrbRecordUnit 中的 ValueTask.FromResult 引用后重新生成代码。
• 模板资源基线随包更新： 官方模板补齐各场景真实的 ref/ 资源基线（objref.txt、dataref.txt、fontref.txt 等），code_sample 的资源引用同步更新；新建项目和示例在生成、发布准备时可以直接读取真实资源统计，不再依赖占位清单。需更新项目模板。

UI 字体与资源收集

数编 UI 里的字体设置以前需要作者手工维护 ref/fontref.txt，漏行时只会 fallback 到默认字体，很难发现。现在保存并生成项目时会从真实的数编字段收集字体 family，项目私有字体仍按随包资源处理。

• 数编 UI 字体自动写入 fontref： GameDataControl 及其派生控件的 Font，以及 GameCore.ResourceType.Font 类型资源，会在保存生成时收集到当前地图的 ref/fontref.txt。支持 font/...、ui/font/...、带 res/ 前缀和旧逻辑允许的字体文件写法（按父目录取 family）；已有条目保留，重复 family 去重。共享别名 Regular、MiSans、Microsoft Yahei、Custom、SourceHanSerif、NoWarRounded、ALiMaMa、LXGWWenKai 归一为对应 family，表外裸名不会自动收集。C# 代码里手写的 family 仍需手工补行。需更新编辑器二进制。
• 项目字体不进入云资源统计： 项目 res/font 下的私有字体只登记到 fontref.txt，不会写入记录云资源依赖的 ref/dataref.txt；随包字体与云端下载字体的边界保持不变。
• 同步更新自定义字体指南与字体 AI Skill，补充自动收集范围、可接受的写法和别名列表。本项为文档与 AI 指引更新。

SDK 文档与开发指引

• 首页入口明确排错用途： 文档网站首页将“了解编码规范与命名约定”改为“查找框架约束与常见陷阱”，链接名称同步改为“框架约束与排错入口”，保留原页面地址。
• 按实际问题查找框架约束： 原“编码规范”改为框架约束与排错入口，删除通用 C# 命名、排版和设计模式要求；初始化、WASM 异步、序列化、资源路径与运行验证分别链接到对应专题，原页面地址保留。
• 保留陷阱案例，精简重复说明： 重整常见开发陷阱、异步、Link 比较和 UI 文档，保留错误原因与修正方法，纠正过时 API 说明；项目结构和测试指南改为面向游戏作者的双端编译与真实运行验证。同步精简 AI 指南，移除通用提示词模板及强制使用链式 UI API 等要求，命名、代码组织与视觉设计由项目自行决定。本项为文档与 AI 指引更新。
• 按真实创建与目标解析流程排错： 精简 GameData 与运行时对象、Entity/Actor 分工和 TargetType 指南，保留派生实例创建接线、服务端通过 Scope 发起表现、单位与坐标目标转换等约束；移除重复的设计模式议论及武断的技能设计规则。CloudData 指南改为集中说明身份、初始化、原子事务、失败结果、分页和限额，替换拆分转账后手工退款、仅捕获异常进行重试等不可靠示例。本项为文档修正，不改变运行时行为。
• 精简 UI 与发布前检查： 流式布局教程和配套 AI Skill 删除通用代码风格要求、重复宣传与无依据的效果承诺，说明链式调用和属性赋值可混用；游戏检查清单聚焦实际运行、输入、清理、联机与发布验证。已弃用的 Simple2DMultiplayer 模板入口改为存量项目参考，新项目导航指向当前架构与同步方案。本项为文档与 AI 指引更新。

云数据与邮件排障指引

• 补充 CloudData、运营邮件和调试 AI Skill，说明修改项目 ID 或将项目迁往另一个部署环境、且尚未在目标环境发布时，可能出现 TableNotFound。编辑器正常新建项目及目标环境首次成功发布会创建配套邮件数据表，prepare 与编译不会替代建表。指引先核对项目、部署环境和发布记录，在获得发布授权后按正常流程发布并复测；缺表继续保留为读取失败，避免误当作无领取记录继续发奖。本项为现有行为的文档说明，未修改邮件读写逻辑。

模型预览与重定向

• 修复模型重定向等预览窗口中，镜头接近水平时平移可能突然飞远的问题；平移沿屏幕平面进行，滚轮缩放步长随观察距离调整，减少近距离观察时一步越过模型的情况。
• 修复多个预览窗口的镜头聚焦状态可能互相影响的问题，并处理聚焦对象销毁后的状态清理。以上修复需更新编辑器二进制。

云端资源保存与上传

• 保留个人云资源缓存： 编辑器启动时的预览过期清理会保留 _user 目录下的个人云资源包及其依赖，不再因超过 30 天未预览而删除；旧版本包清理保持原有规则。需更新编辑器配套脚本。
• 修复预览过期清理读取已下载资源保留名单时使用错误字段的问题，避免主动下载的资源包及其依赖被当作过期预览缓存删除。需更新编辑器配套脚本。
• 修复美术资源预览窗口中，点击“保存”或“保存并上传”时，若需补下载资源，可能出现 Lua 协程错误并中断操作的问题。资源下载或复制到本地失败时提示并停止后续操作；等待期间切换资源或关闭窗口时取消本次保存。需更新编辑器配套脚本。

模型几何更新与诊断

• 修复静态顶点和索引缓冲区在拒绝更新时仍改写 CPU 几何副本的问题，避免 CPU 查询使用的数据与实际渲染数据因此不一致；不支持的局部更新会明确报告失败。静态缓冲区首次完整上传、已有几何读取、动态缓冲区和纯 CPU 缓冲区更新保持可用。需更新客户端或编辑器二进制。
• 补充几何缓冲区失败信息： 上传、分配或锁定失败时，日志包含可用的模型资源标识、缓冲区类型与规模、请求范围及动态或静态状态；Windows 还记录每个缓冲区首次失败的调用栈，便于按失败资源和调用位置排查。需更新客户端或编辑器二进制。

项目发布

• 修复直接按 Texture2D 加载部分发布纹理时，因文件内容为 KTX 等纹理容器而读取失败的问题；按实际文件头选择容器读取方式，保留普通 PNG/JPG 的原有加载流程。需更新客户端或编辑器二进制。CPU Image.Load(...) 仍不适合作为发布 UI 图片能否显示的判断依据。
• 修复发布过程中切换当前项目时，可能将原项目的内容上传到另一个项目的问题。发布项目和同步引用会固定本次上传目标；检测到项目或项目 ID 变更、发布包与目标 ID 不一致时停止上传并提示重新发布。需更新编辑器配套脚本。
• 避免发布后误判 UI 图片缺失： 更新项目资源路径指南及 Canvas、UI 布局和开发基础 AI Skill，说明 PC 与手机发布包都可能使用 KTX 等纹理容器，不能用 CPU Image.Load(...) 的解码结果决定是否绘制 UI 图片。补充独立散图通过 Texture2D.Load(...) 预加载与失败回落的示例，以及图集子图和旧客户端的适用边界；建议在目标平台发布包中验证实际显示。本项为文档与 AI 指引更新，已有项目需调整相应加载检查逻辑。
• 无头发布目标环境跟随安装渠道： 线上安装发布到 pd；历史安装清单中的 production 会归一为 pd，不存在独立的 production 发布后端。显式 --publish-environment 优先；未显式指定时宿主会从 --install-root 或程序目录读取安装清单环境，能解析就不需要额外参数，只有无法解析时才返回 publish_environment_required；工具请求的环境与宿主已配置环境不一致时在上传前返回 publish_environment_mismatch。需更新无头编辑器配套二进制。
• 结果未知时保留上传受理证据： 无法确认终态时，已观测到的上传受理保留为 upload_accepted=true 且不会回退，只说明上传可能已被服务受理，不会当作成功或清除 unknown，字段缺失或 false 也不能证明没有上传；上传尚未发出时，project_publish_finalize 可以先释放本宿主的原生侧车与租约并重试清理。需更新无头编辑器配套二进制。
• 同步更新无头编辑器指南与调试 AI Skill 的发布环境、未知终态和收口说明。

PC 单人内测快捷启动

• test 渠道可直接进入指定单人模式的内测局： 线上对战平台的 test 渠道已更新 lib_lobby，支持 -wx_lobby=app_box -tag=test -author_test_project=<项目ID> -author_test_mode=<模式ID> 冷启动直达测试局；formal 渠道仍是旧版本，暂不可用。只支持单人（SINGLE）模式，项目 ID 必须等于实际地图名；同一进程只执行一次，已经运行的平台不会接收新参数，也不能绕开内测资格和模式可见性。以 AUTHOR_TEST_LAUNCH 回执的 result=success、actual_session_id、实际模式信息和场景加载为准，mode_confirmed 恒为 false。需更新对战平台 lib_lobby 热更包，不依赖客户端或编辑器二进制；仅加入内测列表不等于实际进局。同步更新平台内测与内测码与调试、作者后台 AI Skill。
• 明确星火币充值边界： 星火对战平台内测运行在 test 环境，只能消耗账号已有星火币，不能充值；项目上线后运行在 formal 环境，对战平台支持正常的星火币充值。同步修正平台内测、TapTap 测试对照、快速开始、发布流程文档与支付 Skill，避免把“内测不能充值”写成“平台不能充值”。

Canvas 多边形填充

• 修复 Canvas 绘制部分复杂、凹多边形或自交多边形时，可能出现填充缺失或超出轮廓的问题；修复一种特定复杂轮廓可能引发崩溃的问题。需更新客户端或编辑器二进制。

地形编辑

• 修复使用裂缝画刷时，未采集到有效地形边端点可能导致编辑器崩溃的问题。

Windows 图形稳定性

• 修复 Windows 编辑器在硬件 Direct3D 11 设备创建失败后，WARP 软件渲染回退因参数错误而失败的问题；保留 Direct3D 11 默认渲染路径。需更新编辑器二进制。
• 修复数据编辑器等网页面板在独立 Direct3D 11 设备创建失败时可能黑屏的问题；增加兼容参数重试和 WARP 软件渲染回退。需更新编辑器配套二进制。
• 修复部分 Intel 显卡设备上，Windows 客户端或编辑器退出时，因图形驱动过早卸载可能导致崩溃的问题。需更新 Windows 客户端或编辑器二进制。

Shader 缓存加载

• 增加 Shader 缓存字典的长度、编码位宽和符号数量检查，修复部分异常字典可能触发越界读取或异常内存分配的问题；缺失文件或读取不完整时明确报告加载失败。需更新客户端或编辑器二进制。

动画资源加载

• 修复加载包含零关键帧轨道的动画资源时，删除空轨道后仍访问失效轨道、可能导致崩溃的问题。需更新客户端或编辑器二进制。
• 修复 AnimatedModelComponent.GetSocket 无法读取官方预制体挂点的问题，查询时保留挂点相对骨骼的位移、旋转和缩放，并继续支持模型 XML 挂点。同步纠正样例：挂点名使用 GetSocket，真实骨骼名使用 GetBoneNode。需更新客户端或编辑器二进制。

安卓内嵌客户端

• 修复安卓内嵌客户端切换或重新进入游戏时，因跨线程处理启动请求可能导致崩溃的问题。需更新安卓内嵌客户端。
• 修复安卓客户端在界面销毁或重建时，渲染 Surface 可能被重复销毁的问题，降低切换界面或退出时的崩溃风险。需更新安卓客户端二进制，内嵌客户端需更新集成包。
• 补充客户端退出清理的阶段、线程和耗时日志，便于定位退出等待；安卓客户端支持按资源名称筛选引用追踪，记录资源引用变化和析构调用栈。引用追踪默认关闭，通过启动参数 -resource_ref_trace=资源名称片段 启用，单次运行的追踪文件容量约 3 MiB，并随 Themis 崩溃日志上传。需更新客户端二进制。

iOS 网页界面

• 修复 iOS 客户端打开内嵌网页界面时，可能因原生宿主视图缺失、网页位置计算异常而崩溃的问题。需更新 iOS 客户端。

iOS 故障排查

• 修复 iOS 独立客户端启动时，旧异常处理器覆盖崩溃收集处理器、可能干扰崩溃上报的问题。需更新 iOS 独立客户端。
• iOS 内嵌客户端交付库保留源码与行号所需的调试信息，并在打包时检查；随包补充宿主生成和上传匹配 dSYM 的说明，便于在宿主崩溃平台定位引擎调用栈。需更新内嵌库，并由宿主配套生成、上传符号。

编辑器故障排查

• 崩溃报告保留项目逻辑： Windows 编辑器调试 WASM 项目时，Themis 崩溃日志可附带本次实际加载的 GameEntry.dll 与项目依赖 DLL 的压缩快照，以及项目、来源和哈希信息，便于还原程序集并排查用户逻辑。超出采集额度时记录遗漏原因。需更新编辑器二进制。
• 跟踪窗口对象的生命周期： Windows 编辑器的引用计数诊断扩展至具名窗口，可记录引用变化、窗口销毁与对象析构的调用栈和线程，帮助排查窗口对象失效相关崩溃。默认关闭；排查血条编辑窗口时，可使用启动参数 -resource_ref_trace=BloodStripWindow 启用，诊断日志随 Themis 崩溃报告上传。
• 修复 UI 渲染遇到无效或未完成的顶点缓冲区间时仍提交绘制请求的问题，降低该路径触发访问冲突的风险。
• 修复场景中删除或切换当前控制对象后结束移动、旋转或缩放拖拽时访问失效节点的问题。

响应配置与玩法排查

• 修复单位死亡响应忽略响应侧的问题：Location = Attacker 在宿主作为击杀者时触发，Location = Defender 在宿主死亡时触发；无击杀者的死亡不触发主动方响应，附加效果默认指向原事件的另一方。
• 正确配置反伤、自疗与死亡复活： 补充响应系统指南及配套 AI Skill，说明主动方与被动方、响应宿主与所有者、原效果链与响应附加效果链的 Caster/Target 差异。补充响应侧对应的默认目标、Buff 施加者与宿主的区别、死亡响应的击杀者回退规则，以及枚举名称与生成结果的核对方法；同步完善 API 注释。

附加模型

• 通过 GameGraph 控制附加外观： 补充附加模型挂载指南及配套 AI Skill，明确它是“自动挂载模型表现”的下钻接口：复用挂载、骨骼跟随与可选宿主网格裁剪，由代码显式选择 Prefab 主骨骼宿主并管理挂载句柄；Actor 上层继续通过 ActorArray 自动维护表现。补齐资源要求、换装与解除示例、客户端范围及发布验收说明。
• 修复附加模型开启 CullHostMesh 裁剪宿主网格时，宿主模型缺少切线等顶点属性可能导致客户端或编辑器崩溃的问题。需更新客户端或编辑器二进制。

GameGraph 对象生命周期

• 修复按组件 ID 查询时可能将其他类型组件误包装为目标类型、后续读取模型等属性可能导致崩溃的问题；SceneGraph.GetComponent<T>(id) 会核对原生类型名，类型不匹配时返回 null。支持自定义原生类型名，按精确类型匹配，不进行继承类型转换。需更新依赖库。
• 对象包装增加依赖库层的指针对齐检查：遇到明显未对齐的原生对象指针时，在增加引用前报告包含对象类型和指针值的脚本错误，降低旧客户端直接触发原生崩溃的风险。需更新依赖库；该检查不覆盖地址对齐的悬空指针。
• 增加对象引用操作的非法指针检查，降低增加或释放引用时因明显损坏的指针触发原生崩溃的风险。检查按宿主架构处理，保留 ARM64 指针标签；发现错误时记录引用操作和指针值并中止当前调用。需更新客户端、编辑器或服务端二进制。该检查不覆盖地址形式合法的悬空指针。
• 修复对象构造失败后仍可能尝试释放未取得引用的指针的问题，并在释放引用报错时清理失效的对象包装缓存。需更新依赖库。
• 修复主动创建的 GameGraph 对象未正确进入包装缓存、旧包装对象释放时可能误删新缓存项的问题；重复查询可复用有效包装对象，减少额外的对象创建和引用计数调用。需更新依赖库。

2026-10-20 ～ 2026-10-27（已发布到线上正式环境）

当前客户端能力版本：9（本期由 8 提升至 9）。新增 NativeClientServices 与 GameRenderSettings，最低能力版本均为 9，需配套更新客户端二进制与框架依赖库。本期未新增已确认的客户端强更基线，实际可用能力以本机客户端报告为准。

本期重点速览

本期重点是让 AI 从尚未创建项目开始，连续完成无头创作、构建、单客户端连服调试与发布，让游戏按需控制窗口、移动端清晰度和实时画质，并让技能在目标出射程后重新接近、完整起手。编辑器新增依赖库模板入口，可直接创建可复用的依赖库项目。数据编辑与运行快照补齐技能、AI 和 Buff 的排查信息；同时完善图形化触发器的官方类型声明、项目 Shader 工作流，以及多端稳定性修复。

用 AI 创建第一个游戏

Windows 完整编辑器包提供安装根入口 sce.cmd 与 AI_START_HERE.md。用户可以先把安装位置、项目保存位置和玩法目标交给 AI，再由 AI 创建项目、读取项目规则并进入开发，详见用 AI 创建第一个游戏。需更新包含这些入口的完整编辑器包。

• 一条命令准备新项目： sce.cmd init <目录> 按安装渠道与 API 准备 SDK、模板、依赖和随包构建工具，完成必要的账号授权与项目身份申请，生成 SDK 绑定、文档、Skills 和 AI 规则，并检查项目就绪状态。无头入口最低支持 API2000，不会沿用图形编辑器的 1.0 默认版本。无需先在 GUI 创建项目，也无需另行安装系统 .NET SDK 或 PowerShell 7；初始化完成后再明确执行构建和调试。
• 准备默认字体与运行依赖： 初始化准备默认 regular 字体、关键运行包、编辑器 Shader 缓存及项目依赖，后续可通过 prepare 修复这些包的缺件。本期测试版要求安装已完成官方资源下载，场景、地形、模型等素材使用现有安装资源。
• 原地继续准备并保留用户修改： doctor 提供只读诊断，prepare 修复已有项目环境。准备失败时保留项目，生成过的规则、工具和 Skills 被用户修改后会保留并报告冲突；身份申请结果未知时停止自动重试，便于核对原申请。
• 让 AI 连接正确的项目宿主： 项目内 ai/tools/Invoke-SceHeadlessMcp.ps1 可发现、启动和复用匹配项目、安装与 API 的 HTTP 宿主；停止操作限于该辅助入口管理的宿主。GUI 与 Headless 通过项目写锁避免同时修改同一项目，交接前需先保存并关闭原宿主中的项目。

无头编辑器与登录复用

Windows 无头编辑器通过 HTTP/WebSocket MCP 提供项目创建、数据与触发器编辑、保存生成、双端构建、单客户端连服调试和发布，无需启动图形编辑器界面；游戏调试仍使用配套客户端。需更新编辑器完整包，并按目标环境配置登录服务、资源与调试依赖，详见无头编辑器使用指南。

• 减少重复安装文件： 无头程序移至 version-<api>/SCE.HeadlessEditor.exe，与图形编辑器共用运行时及依赖 DLL，并统一依赖版本，减少安装占用。sce.cmd 保持原有用法，并兼容旧版 headless/ 子目录布局。需更新完整编辑器包。

• 一次登录，连续开发： 无头宿主与图形编辑器按同一安装目录、同一编辑器服务器共享账号缓存。使用 --login 时优先验证有效缓存，缺少有效账号时才显示二维码或授权链接；宿主重启后可继续复用，运行期间切换项目和重复构建、调试无需重新扫码。

• 空闲时主动重新授权或换号： 通过 headless_account_status 查询账号，使用 headless_account_switch_start、headless_account_switch_status、headless_account_switch_cancel 发起、查询或取消换号。授权完成后更新宿主身份和共享缓存，无需重启；处理中重复请求复用同一操作。构建、调试或尚未清理的发布操作占用期间不允许换号，失败或提交前取消保留当前身份。

• 超时后继续核对原发布结果： project_publish_reconcile 只读核对历史记录，project_publish_finalize 将后台确认的成功结果写回当前宿主并清理资源。超时或断连后可继续处理原操作，无需重新上传；结果须匹配原项目、请求、环境及产物身份。跨宿主写回前，需先退出旧宿主并交接操作目录。

• 无头统计资源并生成动画、碰撞： 新增异步资源准备工具，保存并生成代码、重新统计资源清单，合并项目与依赖库的动画请求，通过独立辅助进程生成 Humanoid 动画及模型预烘焙碰撞。支持查询、等待和取消，无需登录、启动游戏或上传；也可完成后直接进入调试。需更新完整编辑器包及配套 SDK 资源分析器。

单人独立客户端调试与停止

• 从菜单启动独立调试窗口： 新增“调试 → 独立客户端调试”和“调试 → 独立客户端调试(不编译)”，无需修改编辑器启动参数。两项均为连接调试服务器的单人调试；不编译选项复用已有脚本产物，仍执行地图保存与调试准备。需更新编辑器及配套脚本。
• 修复调试客户端退出时，停止通知可能指向其他调试局、影响新局身份与日志的问题，改为使用该客户端启动时关联的游戏局。多人内嵌调试关闭部分窗口时保留对局，最后一个窗口关闭后再通知停止。
• 修复无头调试客户端在就绪前退出时，可能继续等待就绪超时的问题，改为提前报告客户端退出并清理本次调试资源。

依赖库创建、资源构建与发布

• 从模板创建依赖库： 星火 2.0 首次开放依赖库项目创建入口。在项目管理器的“新建项目”窗口选择“依赖库模板”，即可创建用于封装可复用功能、供其他项目引用的依赖库项目。
• 配置地图与本地依赖库联调： 补充依赖库项目指南及 AI Skill，说明同时维护 libs.json 与 csproj 编译引用、本地 local_libs.json 和无头 --lib 的作用，以及双端构建、程序集身份和发布包加载方式。库源码可放在编译机可访问的任意位置，csproj 路径仅用于编译，运行时按依赖库包加载。
• 按库项目身份生成程序集： GUI 和无头新建依赖库时，将工程文件及程序集名称与库项目 ID 对齐，正确生成可由引用项目加载的同名 DLL；普通游戏项目继续使用 GameEntry。修复库模板缺少 GameSystemUI 引用，可能导致首次编译失败的问题。需更新编辑器及项目模板。
• 修复依赖库资源构建可能编译成功却没有刷新资源与动画清单的问题；资源统计会重新执行编译。需更新配套 SDK 资源分析器及编辑器。
• 修复 GUI 上传预制功能前可能沿用旧依赖信息，或在保存、资源统计失败后继续上传的问题。动画生成失败时会报告错误，并保留尚未清理的已有动画，便于修复后重试。

客户端显示、平台服务与实时渲染

游戏可以制作自己的分辨率、画质与输入设置界面，并读取设备信息辅助诊断。窗口和设备服务由 ClientPlatform 提供，当前游戏的渲染细项由 GameRenderSettings 管理；调用时需按客户端能力版本判断支持情况。

• 移动端默认保留高分屏清晰度： Android 和 iOS 启动时保留系统默认的应用渲染尺寸，不再自动套用已保存的分辨率档位，避免平板等高分屏默认被降分辨率。仍可在设置中手动调整分辨率。此项通过启动资源热更新生效。
• 控制桌面分辨率与移动端清晰度： 新增 ClientPlatform，可读取显示器及带刷新率的模式列表，切换窗口/独占全屏/无边框模式并控制窗口；移动端可读取默认应用 Surface 与当前渲染像素，设置或恢复默认 Surface，并请求方向及 iOS Home Indicator 行为。请求结果区分受理、宿主控制和不支持，实际尺寸以变化后读回为准。
• 读取屏幕密度与估算物理尺寸： ClientPlatform.GetDisplayDpi 提供显示器横向、纵向 DPI；GetAndroidScreenMetrics 和 GetIOSScreenMetrics 分别提供 Android、iOS 的系统屏幕像素与窗口 dp/point 信息，并按可用 DPI 估算对角线英寸数。补充近年来 iPhone 与 iPad 的型号密度数据，并修正 iPad Air 第三代的密度值。接口名称与 XML 注释标明适用平台，其他平台返回不可用；厂商上报或型号估算存在误差，结果不等同实测尺寸。此项需更新客户端二进制及框架依赖库。
• 独立调整当前游戏画面： GameRenderSettings 提供阴影、Cluster、AO、蒙皮、粒子、点光、后处理、Shader 宏排除和绘制距离等实时设置，支持同一 Gameplay 的快照恢复与阴影刷新请求。托管单位调试层提供半径、模型包围盒和足印网格，安全区支持像素边距模拟。
• 制作完整的本地设置与诊断界面： 提供独立帧调度、设备与构建信息、64 位原生内存诊断、可用的性能采集请求、手柄状态与事件、二维码生成/可取消扫码、资源校验和依赖资源包版本查询。本地选项补齐项目/设备作用域、默认值、会话临时覆盖与变化通知；托管对象及 GC 快照按当前端采样，未采集原生字段保留不可用状态。使用方式见客户端窗口、Surface 与原生服务。

技能重新接近与阶段动画

目标在技能起手期间移出射程时，可让施法者重新接近目标，再执行完整前摇与出手。动画和阶段表现随这一过程停止、重建，资源与冷却在最终发动时结算。此能力需配套更新客户端与服务端框架依赖库。

• 出射程后重新接近并起手： 启用 AbilityExecuteFlags.Reapproachable 后，技能在进入 Channel 前发现目标超出射程时，会回到 Approach，接近后重新执行完整前摇和出手；只有最终发动时扣除资源、启动冷却并执行效果，进入 Channel 后不再回跳。同一条指令保留首次前摇锁定的辅助瞄准快照。
• 按施法阶段驱动自定义动画： IAnimationSwingController 提供 Preswing()、Cast()、Channel()、Backswing() 四段通知，分别对应前摇、出手、引导和后摇；原 Swing() 更名为 Cast()，自定义实现需同步调整。CreateSwingController 只创建控制器，三类内置动画统一在收到前摇通知时启动；首次收到后续阶段时也能启动并处理当前阶段，提前停止则不播放。重新接近时停止本轮控制器，再次起手时重新创建。此项需更新客户端框架依赖库。
• 同步重启施法表现： 重新接近时停止本轮动画，清理通用 StagedSpawns 中仍受阶段生命周期管理的表现，重新起手时再次创建。普通瞬态表现仍按自身生命周期结束。
• 处理可能重复的阶段事件： 每次重新起手都会发送 Preswing、Cast 阶段事件；自定义回调已产生的游戏逻辑不会自动撤销，需按可能重复起手编写。
• 掌握从指令到表现的完整流程： 新增指令、施法与技能动画的完整生命周期，通过流程图说明普通与瞬态指令、完整施法阶段、目标快照、重新接近、三类内置动画控制器和通用 StagedSpawns 的创建与清理。指南包含继承 GameDataAnimation、重写 CreateSwingController 的自定义控制器接入方式，以及扇形 AoE 预警示例与排查方法；同时说明瞬态技能在移动或引导其他技能期间直接生效，以及排队、执行检查和效果干扰的边界。
• 修复点目标、向量目标技能使用单位辅助瞄准时，目标在前摇期间移动可能导致施法停滞的问题。此类技能在进入前摇时锁定本次瞄准位置；单位目标技能与交互技能继续追踪单位。

数据编辑与玩法排查

技能、AI 或 Buff 配置后未生效时，可以逐步核对源数据、继承结果、代码生成和当前对局状态。已声明字段的生成失败会提供明确诊断；未知 JSON 字段仍可作为项目和编辑器的辅助数据。

• 正常编辑坐标与尺寸等复合字段： 修复部分使用官方类型的数编字段无法展开编辑的问题。粒子控件的偏移 ParticleOffset 与参考尺寸 ParticleReferenceSize 现在可分别编辑 X/Y、Width/Height，并正确生成对应配置。
• 直接发现未生效的字段： 已声明字段的值无法生成时，编辑器日志、生成工具和生成后的编译警告提供 GDATA001 诊断，标明条目、字段路径、预期类型、平台与原始值。未知 JSON 字段仍可用于项目和编辑器辅助数据，并按设计静默跳过生成。此项需更新编辑器。
• 核对继承结果和技能连接关系： 字段设置工具返回本地、继承和有效值；校验增加 AI 技能未挂载、激活/施法效果连接及重复 Actor 的非阻断提醒。引用对象的新建对话框补充空白对象、模板与复用现有对象的提示，函数字段说明创建与绑定入口。此项需更新编辑器。
• 修复直接创建或修改数据条目时，文件内 $this 引用未规范化，可能导致生成代码省略有效引用的问题。此项需更新编辑器。
• 读取实际玩法状态： 扩展 gameplay.snapshot，提供 AI 范围来源、最近验证节点结果、指令目标与瞄准快照、技能挂载和 Buff 属性修改信息；调试局可按单位短时开启命令结果与阶段追踪。需配套更新客户端与服务端框架依赖库。新增技能、AI 与表现排查指南及配套 AI Skill，说明公式创作、扩展字段、继承集合、效果链、资源与首次表现的验证方法。
• 修复调试局中，单位移除后取消指令时，玩法追踪可能查询空实体并抛出异常、中断本次逻辑更新的问题。此项需更新服务端框架依赖库。
• 修复摇杆移动可能未遵守 SuppressMovement / DisableMovement 的问题；临时抑制保留持续输入以便解除后恢复，禁用移动会清除输入。此项需更新服务端框架依赖库。

大厅模式与数编游戏模式

• 读取创作者中心大厅模式 key： 新增仅服务端可用的 Game.LobbyModeKey，返回当前游戏局由创作者中心大厅入口传入的后台模式 key。项目可以据此区分不同大厅入口或匹配池的规则；编辑器调试局及未通过大厅入口创建的游戏局返回空字符串。Game.LobbyModeKey 与项目数编配置 Game.GameModeLink 相互独立：前者是平台入口元数据，后者选择项目内的 GameDataGameMode 数据，不能互相替代。详见随进随出模式与开放局。此项需更新服务端框架依赖库。

触发编辑器与可扩展枚举

• 使用更多官方类型的构造函数、方法与属性： 补齐坐标、尺寸、矩形、向量与矩阵，以及日期、集合、JSON 等常用官方类型的部分声明，可在图形化触发器中构造对应值、读取属性并调用相关方法。
• 在图形化编辑器中扩展枚举： 补充枚举扩展指南和配套 AI Skill，说明新建预设值类型并设置“继承”目标的通用流程。“继承”对应 EnumExtension.Extends；需要在数据编辑器中选择新增枚举值时，应保存为触发器 JSON 声明，两端共用的枚举建议定义在公共页（Common）。物品分类是这一机制的使用示例。
• 修复通过 trigger_create_preset 导入扩展枚举时，特性或继承目标无法解析、或目标缺少预设值类型声明，可能仍返回成功并在生成代码时丢失继承关系的问题；现在会返回具体诊断，便于修正声明与引用。此项需更新编辑器。

自定义 Shader 与共享公共头

项目 Shader 可复用编辑器提供的公共头与 varying 定义，也可在无头模式预编译目标平台字节码。配套指南和最小示例帮助作者与 AI 从已有骨架开始编写效果，并按项目验证实际使用的宏组合和设备画面。

• 在无头模式预编译项目 Shader： 无头编辑器支持通过同一套 shader_* MCP 工具管理清单、预览任务并调用独立 ShaderCompile.exe 生成 Windows/Editor DX11、Android ESSL 和 iOS Metal 字节码，无需启动图形编辑器或登录。成功后统一替换项目 Compiled 目录，失败、取消和超时保留旧产物。需更新完整编辑器包、使用 DX11 编译环境并指定安装包中的公共 Shader include 路径；编译不会自动上传或发布。
• 自动使用共享 Shader 公共头： 项目预编译和 PIE 按需编译会优先搜索项目源码目录，再从编辑器当前使用的共享 Shader 包补齐 include 和 varying 定义，无需逐项目复制公共头。共享头的路径和内容变化会更新项目本机缓存标识。需更新编辑器二进制及包含 BLGL 源码的 Shader 资源包；配套指南与 AI Skill 补充独立调用底层编译器时的 include 参数、阶段处理及旧工具边界。
• 从最小示例编写项目效果： 补充项目自定义 Shader 指南和配套 AI Skill，说明 Shader 系统的 Urho3D 来源及当前 SCE/bgfx 接入约定，覆盖阶段入口、顶点输入与 varying、坐标变换、纹理和材质参数绑定、移动端精度及颜色空间处理。提供静态网格主纹理乘色示例，包含 GLSL、varying、Technique、材质、棋盘纹理和四平台初始编译清单，便于 AI 在现有骨架上改写效果；实际运行的宏组合与目标设备画面仍需按项目验证。

商城与星火币支付

以下修复需配套更新客户端与服务端的 GameSystemUI 依赖库。

• 修复官方商城使用项目内付费货币余额判断平台星火币是否充足，可能导致平台钱包余额足够时仍显示买不起、额外提示充值的问题。商品展示与购买引导分别检查项目额度和平台钱包，支付成功后刷新钱包余额。
• 修复平台支付完成后未触发 ShopSystemServer.OnPurchaseSuccess 和 ShopSystemClient.OnPurchaseSuccess，可能导致项目局内状态未刷新、缺少购买结果提示的问题。成功通知按平台订单号去重，通知标记写入遇到临时故障时会有限重试。

编辑器与客户端修复

• 修复连续创建粒子特效时，已结束的拖尾仍参与合批，可能在特效末尾出现巨大条纹或拉伸的问题；同时修复大量粒子合批时的索引溢出及 32 位索引存储问题。此项需更新编辑器或客户端。
• 修复粒子等动态几何复用缓冲区时，GPU 缓冲或顶点布局变化未及时刷新绑定，可能造成绘制异常的问题。此项需更新编辑器或客户端。
• 修复高亮粒子叠加时，HDR 色调映射计算溢出可能产生异常青色、彩色亮斑的问题。此项通过更新 Shader 资源包生效。
• 修复 Windows 编辑器启动时，缺少可用的 WebView2 Runtime、显示安装提示可能触发崩溃的问题。确认提示后会优先启动随包安装器，未附带安装器时打开官方下载页面；安装完成后需重新启动编辑器。安装提示异常会记录到日志。此项需更新编辑器。
• 修复单一 Intel 显示适配器上的 Windows 编辑器启动可能因 WinUI 图形设备初始化失败而退出的问题；此类设备启动 WinUI 时自动使用 WARP，多显卡设备保持系统默认的图形适配器选择。此项需更新编辑器。
• 修复重新打开带裂隙包边的地图后，保存场景可能将包边样式误写为“无”的问题。包边状态改为从实际地形边界读取，调整地图尺寸时也沿用该状态。此项需更新编辑器。
• 修复 Windows 客户端启动时，窗口消息钩子重复接入可能造成递归调用并导致崩溃的问题。此项需更新 Windows 客户端。
• 修复编译项目自定义 Shader 时，varying 文件名不含下划线可能导致崩溃的问题，保留自定义文件命名支持。此项需更新编辑器或客户端。
• 修复 Windows 使用 DirectX 11 渲染时，提交渲染刷新命令可能误用无效绘制状态并导致崩溃的问题。此项需更新 Windows 编辑器或客户端。
• 补充 Windows 渲染中的异常视图映射校验与恢复，降低越界视图编号导致崩溃的风险，并增加诊断日志以便继续排查异常来源。此项需更新 Windows 编辑器或客户端。
• 修复 Spriter 动画资源重载，或在动画播放结束回调中切换动画、移除动画对象时，可能访问失效数据并导致崩溃的问题。此项需更新编辑器或客户端。
• 修复复杂画面绘制时，渲染参数缓冲容量不足可能导致 iOS 客户端崩溃的问题；缓冲不足时会按需增加分页，并保留 GPU 尚在使用的数据。此项需更新 iOS 客户端。
• 修复异步 HTTP 日志回调与退出清理并发时，可能因跨线程释放对象引用而导致客户端崩溃的问题。此项需更新客户端。
• 修复后台定时器更新与取消同时发生时，可能访问正在修改的定时器容器并导致客户端崩溃的问题。此项需更新客户端。
• 修复 Android 客户端启动时，屏幕模式变化早于图形初始化完成可能导致崩溃的问题；初始化尚未完成时会跳过本次输入窗口更新。此项需更新 Android 客户端。
• 修复 Windows 客户端创建连续地形混合材质时，基础材质尚未完成懒加载可能导致崩溃的问题；现在会先确保基础材质可用，缺失时记录诊断并终止本次材质创建。此项需更新 Windows 客户端。
• 修复编辑器调整地图尺寸时，默认瓦片预制体缺失可能导致崩溃的问题；现在会在修改地图状态前校验默认瓦片和预制体。此项需更新编辑器。
• 修复 Windows 编辑器或客户端绑定计算缓冲区时遇到空对象可能导致崩溃的问题；现在会跳过无效缓冲区绑定。此项需更新 Windows 编辑器或客户端。
• 修复复杂光照列表排序时递归分区过深可能导致栈耗尽的问题；排序现在只递归处理较小分区，并循环处理较大分区。此项需更新 Windows 编辑器或客户端。

静态单位、物品与服务端修复

• 将静态单位设为主控单位： Player.MainUnit 支持静态单位，可用于默认镜头跟随；同步补齐服务端的主控绑定、跨场景携带和移除清理。移动指令仍需对应移动能力。此项需更新服务端及框架依赖库。
• 修复未启用 AllowMover 和 Walkable 的物品单位无法跟随持有者切换场景的问题。此项需更新服务端。
• 修复此类静态单位的复活、朝向与俯仰角读取、俯仰角设置、标签与节点标记读取、位置同步、按位置飘字及镜头定位、跟随等接口被单位类型限制的问题，并允许将其作为行走目标。此项需更新服务端。
• 修复三维场景中，移除配置多格足印的单位后，后续范围搜索可能访问已释放单位并导致服务端崩溃的问题。此项需更新服务端。

2026-10-13 ～ 2026-10-20（已发布到线上正式环境）

当前客户端能力版本：8（本期从 7 提升，新增移动端应用生命周期事件）。

本期重点速览

本期更新让项目发布更可控：保存、编译、资源统计、压缩和上传共用一个 WinUI 进度窗口，AI 可通过 MCP 发起发布、等待结果并核对已发布图集；调试编译进度和信息面板的窗口层级更清晰，项目 Shader 预编译改为异步，减少界面线程阻塞。数据编辑器修复了继承配置中集合与嵌套对象写入运行数据的问题。作者可在创作者中心配置对战平台测试模式，并通过二维码邀请测试者加入内测；客户端新增移动端前后台切换与低内存事件，能力版本提升至 8。

客户端应用生命周期事件

• 监听手机前后台切换： 客户端新增 Game.OnApplicationWillEnterBackground、OnApplicationDidEnterBackground、OnApplicationWillEnterForeground 和 OnApplicationDidEnterForeground，用于在手机应用切入后台、完成切入后台、即将回到前台和完成回到前台时执行客户端逻辑。
• 监听低内存通知： 新增 Game.OnApplicationLowMemory。需要触发器事件体系时，也可以订阅 EventApplicationWillEnterBackground、EventApplicationDidEnterBackground、EventApplicationWillEnterForeground、EventApplicationDidEnterForeground 和 EventApplicationLowMemory。
• 兼容旧客户端： 这组事件要求客户端能力版本 8，框架会在初始化阶段完成兼容门禁；旧客户端不会因为加载新版依赖库而启动失败，也不会触发这些事件。

编辑器调试与诊断

调试编译进度、信息面板和 UI 编辑器构建失败信息都围绕同一目标：在编辑器里直接看到当前阶段和失败原因，减少切到其他窗口或翻找日志的次数。

• 在编辑器前方查看编译进度： 调试编译的进度窗口保持在所属场景编辑器前方，切换到其他程序时可被其他程序窗口覆盖。编译期间继续暂时阻挡编辑器窗口操作，结束后恢复；AI 仍可通过 MCP 查询或取消构建。此项需更新编辑器。
• 保持调试信息面板可见： 信息列表增加“总在最前”选项。开启后，调试信息面板会保持在场景编辑器前方，操作 PIE 时无需反复切回消息窗口；关闭信息列表后再次打开会保留本次编辑器会话中的选择。此项需更新编辑器。
• 定位 UI 编辑器启动失败： UI 编辑器创作模式保留实际构建阶段、构建编号、诊断摘要和完整日志位置，菜单提示、调试信息与 MCP 可查询同一次失败。代码生成异常单独保存完整异常日志，方便区分生成问题和客户端编译错误。此项需更新编辑器及配套脚本。

数据编辑器

• 修复继承数编配置时，足印格子等集合及嵌套对象的修改可能未实际写入运行数据的问题，覆盖列表、集合、字典及其嵌套结构。此项需更新编辑器，并重新生成和编译项目数据代码。
• 修复继承配置中，通过基类声明的对象修改派生类专属字段时，字段可能被遗漏的问题。此项需更新编辑器，并重新生成和编译项目数据代码。

项目 Shader 预编译

• 修复项目 Shader 预编译时耗时编译占用界面线程，导致进度不刷新或编辑器暂时无响应的问题。预编译窗口和对应 MCP 改为异步编译；关闭窗口或切换项目时停止后续任务，并保留原有编译产物。此项需更新编辑器。

项目发布进度与大包上传

发布时可更清楚地查看压缩、上传及后台处理所处阶段，并提前获知压缩包超限的原因。后台的大包存储改进需对应服务更新后生效。

• 查看发布进度： 项目发布与协作者资源同步采用 WinUI 进度窗口，保持在所属编辑器前方，切换到其他程序时可被其他程序窗口覆盖；流程结束后恢复编辑器操作。此项需更新编辑器。
• 连续查看完整发布流程： 保存、编译、资源统计、压缩与上传共用同一个进度窗口，阶段切换时持续显示当前状态；上传受理或失败后，在原窗口显示结果并恢复编辑器操作，上传受理时提供创作者中心入口。需要确认依赖资源时，确认后继续同一发布流程，取消则结束发布。此项需更新编辑器及配套脚本。
• 修复项目发布时进度刷新大量积压、窗口可能空白或迟迟不关闭的问题；阶段切换时先刷新进度，后台发布成功后的旧发布目录清理改为异步执行，减少上传结束后的编辑器停顿。此项需更新编辑器及配套脚本。
• 发布结果提示改用 WinUI，保留创作者中心入口；同时减少弹窗创建和调整窗口尺寸时不必要的显示器模式查询，改善上传结束后的窗口响应。此项需更新编辑器及配套脚本。
• 修复发布流程中隐藏进度条残留的窗口关联可能拖慢编辑器鼠标响应、窗口激活和切换的问题。此项需更新编辑器。
• 让 AI 发起项目发布： 新增 project_publish_start、project_publish_status、project_publish_wait，AI 可发布当前打开的项目并跟踪各阶段及后台最终结果，区分上传受理、发布成功和结果未知。未上传的依赖资源会返回具体列表，供处理后重试。此项需更新编辑器及配套脚本。
• 修复 AI 等待发布结果时，单次等待过长可能先触发连接超时的问题。等待工具默认及最长等待均为 20 秒，超时返回原操作编号和当前状态，供继续查询。此项需更新编辑器。
• 让 AI 核对发布后的图集资源： 新增 project_publish_verify_resources 及 status/wait 工具，按成功发布返回的实际平台包身份，在后台核对图集清单、区域 JSON、文件哈希、KTX 纹理元数据和区域边界，等待超时后可继续查询原校验任务。JSON 差异、缺失区域和损坏容器会报告错误；未解码比对像素会明确标记，仍需目标客户端显示验收。此项需更新编辑器、配套脚本及发布服务。
• 区分压缩等待与上传进度： 压缩阶段显示等待状态，上传阶段显示实际已传输量及百分比；压缩耗时不计入上传无进展超时。
• 提前发现上传包超限： 超出单个压缩包 4 GiB 上限时，在上传前提示；服务器拒绝超大上传时，显示明确的大小限制原因。
• 改善大包后台处理： 后台存储项目压缩包与各平台发布包时改用分片传输，减少大包处理的内存占用；遇到临时网络异常时，复用当前上传任务内已完成的分片进行有限重试。同时延长接收上传文件的时限。此项需对应后台服务更新后生效。

创作者中心与项目内测

创作者中心把账号授权、测试模式配置、内测邀请和扫码加入串成更短的操作路径，减少手填项目 ID 与邀请码。相关工具需要单独授权；测试模式不会自动同步正式环境，实际进局仍需平台验收。

• 从账号项目列表连接 AI： 授权页读取已获权限的项目，优先带入项目入口上下文，减少手填项目 ID；授权失败按项目查询、权限校验或票据存储等阶段返回诊断编号，供管理员关联服务日志。连接仍使用可撤销的 15 分钟私有票据。此项需更新配套后台服务。
• 让 AI 配置对战平台测试入口： 新增 author_get_test_modes、author_preflight_test_mode、author_create_test_mode 和 author_edit_test_mode，单独授权后可核对或配置当前项目的测试游戏模式，复用人数、生效范围和敏感词检查，支持版本冲突检测、同请求重试及写后读回。不会自动同步正式环境；实际进局仍需平台验收。连接文档与 AI Skill 同步补齐授权、重试和读回流程。此项需更新作者后台脚本及授权服务。
• 作者一键加入内测： 创作者中心内测邀请码页面新增“加入我的内测”，点击后为当前登录账号开通该项目的内测权限，无需自行输入邀请码。此项需更新作者后台脚本及配套服务。
• 让 AI 把自己加入内测： 新增 author_join_my_test，单独授予 test_invite.join_self 后，可把授权账号加入当前项目已有且启用的内测，无需手动输入邀请码。工具读回确认加入结果，支持重复调用；结果未确认时保留重试语义。成功后在对战平台使用同一账号刷新内测列表。MCP 文档与 AI Skill 同步补齐操作指引；此项需更新作者后台脚本及授权服务，并重新生成包含该权限的票据。
• 展示内测二维码： 邀请码页面新增“显示二维码”，方便向测试者展示或分享；原邀请码继续保留。禁用或删除邀请码后，对应二维码也会失效。此项需更新作者后台脚本及配套服务。
• 手机扫码加入内测： 安卓和 iOS 对战平台的“加入内测”页面新增“扫描二维码”，识别后按原有邀请码规则校验并加入项目内测，继续支持手动输入。取消扫描或拒绝相机权限时不会发起加入。扫码需更新手机客户端及对战平台页面，并配合后台服务更新生效。

Runtime MCP 调试身份

• 确认正在检查哪个游戏局： debug.ping 返回当前游戏局的项目、会话、玩家和运行模式，并单独保留进程启动参数。配套编辑器还会补齐所选 Gameplay 目标的路径和 UUID，避免切换项目或多人目标后误用旧启动参数判断身份。需更新依赖库及配套编辑器；仅更新依赖库时，无法取得的原生路径和路由字段返回未知值。
• 修复玩家没有主控单位时，gameplay.snapshot 无法确定场景并返回 scene_not_found 的问题。现在会回退到玩家当前场景；指定场景不存在时，同时返回可用场景列表，便于 AI 纠正场景编号。此项需更新依赖库。

云数据、场景迁移与验收指引

• 按游戏局规划云数据读写预算： 云数据文档、快速指南、最佳实践与 AI Skill 补充既有服务限额的默认值：正常 1 倍速下，每个游戏局在 60 秒窗口内共享 300 次查询、300 次事务提交及 48 MiB 累计提交量阈值；单次完整响应默认最多 32 MiB 减 100 KiB。同时明确批量查询和事务的计数方式、倍速与暂停对窗口计时的影响、失败请求占额及超限处理，便于为存档、背包、领取等业务预留余量。本次只补充说明，不改变服务限额。完整规则见云数据系统。
• 携带原角色切换场景： 补充场景迁移文档与专项 AI Skill，说明英雄及库存迁移、玩家视图切换与主控绑定的职责，覆盖显式迁移时的执行顺序、往返及失败恢复，并保留框架携带主控的适用说明。
• 核对跨端行为是否完成： 开发流程与预览、行为排查 Skill 补充双端验收要求，结合服务端状态、客户端副本、界面、镜头和实际操控判断结果，并明确记录尚未验收的路径，避免仅凭调用成功或服务端位置正常判定修复完成。

Maker 人形模型与官方动作

Maker 绑骨 MDL 现在按外部骨架处理。首次接入需要先完成骨骼映射和动作重定向，不能只填写动画清单。

• 明确 Maker 模型的动画适配入口： AI 助手应先读取目标模型与官方动作源模型的骨架，建立 boneMap 和 alignmentBones，通过 resource_retarget_animations 生成并验收项目 prefab 与动作；GameDataModel.HumanoidSourceAnimations 仅用于已经完成适配后的资源声明，不能替代首次骨骼映射。同步更新 Maker 模型导入、人形工作流、资源清单排错和 3D 单位 AI Skill，避免把填写动画清单误认为重定向成功。

界面控件与图集

粒子、Spine 和输入框补上了运行时控件已经支持、但数据模板还不能保存的属性；同时补充界面与场景 Spine 的尺寸规则，以及用图集配置让普通控件显示大图区域的方法。不填写这些新字段时，行为与原来一致。

• 配置粒子在控件里的位置和缩放： GameDataControlParticle 新增 ParticleOffset、ParticleAutoScale 和 ParticleReferenceSize。ParticleOffset 用 0 到 1 表示位置，(0, 0) 为左上角，(0.5, 0.5) 为居中。开启自动缩放时，按 ParticleReferenceSize 相对控件实际尺寸计算缩放；关闭后仍使用原来的 ParticleScale。此项需更新客户端。旧版数据编辑器里的粒子预览还需更新编辑器。
• 指定 Spine 皮肤： GameDataControlSpine 新增 Skin，名称必须与 Spine 资源中的皮肤名一致。此项需更新客户端。
• 设置输入框粗体和斜体： GameDataControlInput 新增 Bold 和 Italic，与标签和文字按钮的数据配置一致。此项需更新客户端。旧版数据编辑器里的输入框预览还需更新编辑器。
• 区分界面 Spine 和场景 Spine 的大小： GameGraph 2D 动画文档 与 2D 动画选型 Skill 补充了既有尺寸规则。界面 Spine 按控件宽高等比装入骨架；AnimatedSprite2D 加载时大约 100 个 Spine 单位对应 1 个世界单位，再由节点缩放决定大小。本次只补充说明，不改变运行时行为。
• 让普通控件显示大图中的指定区域： 新增自定义 UI 图集指南，提供 atlas.json 清单与 custom_icons.json 区域配置示例，并更新 UI 和资源选取 AI Skill。AI 可为大图中的图标分配逻辑图片名，再让普通控件通过 Image 引用，无需对应散图或运行时 CPU 裁图。文档同时说明路径前缀、自动打包文件命名与图集缓存刷新方式；这条配置流程已通过 Windows 编辑器 PIE 截图及重开预览验证。本次补充既有能力的使用说明，不改变运行时行为或客户端能力版本。
• 转换外部 UI 图集： 补充 FGUI 透明裁边与九宫格配置说明：保留透明画布，或利用来源偏移还原裁边；完整矩形图片可用 Border 设置四侧保留宽度，无需拆成九块。
• 排查图集黑白边和串色： 文档与 AI Skill 补充留边、边缘扩展和透明像素 RGB 颜色扩散检查，区分透明轮廓污染、Alpha 约定、过滤与发布压缩；颜色扩散须保留原 Alpha，并按子图片隔离处理。示例另通过 Windows 发布包核对及对战平台两个测试模式的实际显示验证；移动端仍需单独验收。

编辑器修复

• 修复场景编辑器“素材”面板在资源列表初始化或显示预设组合时可能触发脚本报错，以及随后点击列表项继续报错的问题。此项通过编辑器脚本热更新生效。
• 修复部分粒子效果在美术资源页可正常预览，但切换至粒子页查看时可能导致编辑器崩溃的问题。此项需更新编辑器。
• 修复编辑器检测 3D 控件悬停时，场景尚未准备好拾取所需的空间结构就可能崩溃的问题。缺少该数据时会跳过这一帧检测。此项需更新编辑器。
• 修复同一场景重新加载后，场景列表整理排序时仍向已释放节点写入排序信息，导致编辑器可能崩溃的问题。重新加载时会先重建场景树，再刷新排序。此项需更新编辑器。

客户端与运行时修复

• 改善控制台输出兼容性： 脚本运行时初始化后，Console.Write / Console.WriteLine 输出统一转入游戏日志，按 Information 级别记录，降低控制台 I/O 异常影响游戏逻辑的风险。此项通过依赖库更新生效，旧客户端无需更新安装包即可受益；项目日志仍建议使用 Game.Logger。
• 修复地图包打开失败，或后台加载贴图与加载地图包同时进行时客户端崩溃的问题。打不开的地图包不再继续登记，后台读取资源包时不再与主线程同时修改包表。此项需更新客户端。
• 修复画布绘制圆形或椭圆时，半径为 0 或负数会反复触发异常的问题。现在会跳过本次绘制，并每 5 秒最多记录一条警告，避免异常刷屏；半径恢复后继续正常绘制。此项通过依赖库更新生效。
• 修复结束游戏局后，渲染纹理释放时残留的绑定引用可能导致客户端或编辑器崩溃的问题。此项需更新客户端或编辑器。
• 修复编辑器在部分窗口或视图布局下，渲染线程整理视图顺序时越界写入并崩溃的问题。异常的视图映射会被忽略，渲染继续按默认顺序进行。此项需更新编辑器及客户端。
• 修复 3D 场景中角色收到摇杆或朝向同步时，如果寻路组件尚未就绪，客户端或编辑器可能崩溃的问题。缺少寻路实例时会跳过本次最近多边形查询。此项需更新客户端及编辑器。
• 修复通过运行时接口切换粒子发射器材质开关时，材质尚未准备好就更新着色器宏，导致客户端可能崩溃的问题。现在会跳过尚未准备好的材质。此项需更新客户端。
• 修复加载 mipmap 表或数据长度异常的 KTX 纹理时可能崩溃的问题。文件头声明的大小与实际内容不一致时直接判定加载失败。此项需更新编辑器及客户端。
• 修复运行时创建纹理并上传图像时，图像数据为空或上传内存分配失败可能导致客户端崩溃的问题。现在会返回失败并记录错误，不再继续提交空数据。此项需更新客户端。
• 修复关闭或重建带独立窗口的界面后，窗口尺寸变化回调仍访问已释放根控件，导致编辑器或客户端可能崩溃的问题。销毁界面根控件前会先解除尺寸回调。此项需更新编辑器及客户端。
• 修复退出捏人会话或切换地图时，已释放资源仍被重复释放，导致编辑器可能崩溃的问题。现在会忽略对已析构对象的无效引用计数操作；开启资源引用追踪时会记录对象指针和调用栈，便于继续定位来源。此项需更新编辑器及客户端。
• 修复 HTTP 服务回收后发起 Lua HTTP 请求或查询支付余额，以及退出游戏局时处理异步 HTTP 日志可能导致客户端崩溃的问题。此项需更新客户端。

移动端修复

• 修复安卓客户端在切入后台、旋转屏幕、退出或系统重建窗口后崩溃的问题。恢复画面时不再使用已经释放的原生窗口；渲染线程查询窗口尺寸或重建画面前，会先确认系统窗口仍然有效，避免把已释放并被其他内存复用的窗口指针当成可用窗口。窗口重新就绪后再重建。此项需更新安卓客户端。
• 修复 iOS 客户端清理过期烘焙阴影贴图缓存时，纹理智能指针在容器搬移过程中可能被重复释放并导致崩溃的问题。此项需更新 iOS 客户端。
• 修复部分 iOS 设备启动游戏时崩溃的问题。初始化画面不再通过可能无效的窗口控制器取视图，改为使用已经创建好的 Metal 视图；窗口尚未就绪时停止初始化，而不是继续使用无效窗口。此项需更新 iOS 客户端。
• 修复安卓和 iOS 上，滚动面板（PanelScrollable）已经滑到边界后如果继续大幅拖动，松手不能回到边界的问题。触摸滑动可以暂时拖出内容范围，松手后现在会回弹；PC 滚轮不能拖出边界，因此不受影响。此项需更新安卓和 iOS 客户端。

2026-10-06 ～ 2026-10-13（已发布到线上正式环境）

当前客户端能力版本：7（本期未提升，没有新增客户端能力条目）。

本期重点速览

安卓客户端修正硬件 sRGB 启用，改善支持设备上的场景颜色显示；独立对战平台新增应用内更新，并保留网页下载入口；游戏模式新增启动资源预加载开关，多关卡项目可选择按需加载；AI 可下载和导出云资源作为创作参考，编辑离散地形的视野遮挡、台阶、裂缝、碰撞与道路，在后台保持 PIE 动画更新并获取新帧截图，同时支持自动关闭编辑器、处理未保存修改和共享消息框；创作者中心 MCP 支持分页分析大日志，减少手动下载、上传附件的步骤；编辑器在后台编译项目，集中显示错误并提供源码和日志链接，AI 可独立生成与编译依赖库，并读取服务端单位状态验证行为；修复 3D 场景的寻路接近、转向与默认战术 AI 攻击问题；记住新建项目目录，修复粒子资源预览与导航文件误删问题；修复资源克隆的生命周期问题，并改进资源加载诊断。

编辑器视口预览与自动化

• 在属性面板即时查看场景变化： 修改氛围和预览镜头属性后，编辑器主动刷新场景画面；异步资源加载或 Shader 编译完成后继续更新显示。鼠标可留在属性面板，快捷键仍按当前编辑上下文处理。
• 在后台完成视觉测试： Runtime MCP 新增 debug.viewport_update，可为指定 PIE 目标临时保持渲染，支持续期、释放和超时回收。PIE 截图默认等待目标视口的新绘制提交，并返回目标和绘制帧信息；隐藏、最小化或无法绘制时提供明确诊断。上述能力需更新编辑器，调用参数以目标工具 schema 为准。

安卓硬件 sRGB 与颜色显示

• 正确启用硬件 sRGB： 修复部分安卓设备具备硬件 sRGB 支持却未正确启用的问题。在设备与贴图格式支持时，自动使用硬件 sRGB 采样，改善颜色贴图的还原及场景颜色一致性。此项需更新 Android 客户端。

安卓对战平台应用内更新

安卓独立对战平台检测到必须更新客户端时，可以直接在应用内下载新版 APK 并进入系统安装流程，减少切换到浏览器的步骤。此项需先安装支持该功能的新版 Android 独立客户端。

• 查看进度并安装更新： 更新页面显示下载进度，下载完成后检查应用包名与版本，再发起覆盖安装；按系统要求申请安装来源权限或由用户确认安装。
• 随时切换到网页下载： 更新页面始终保留可点击的“网页下载”入口，下载、授权或安装遇到问题时可继续通过网页获取安装包，也可在页面重试。
• 保持内嵌包更新行为： 此功能只用于独立对战平台，TapTap 内嵌包保持原有更新方式，不触发此更新页面或额外跳出下载网页。

云资源下载与明文导出

资源目录 MCP 现在可以把官方云资源导出为项目可读取的明文副本。真实的 .effect 和 prefab 样例可以帮助 AI 理解节点、材质、贴图和粒子参数结构，再按项目需求手写或修改资源。

• 下载单个或批量资源： 新增 resource_download 和 resource_download_batch，可按资源目录结果获取完整云资源；批量下载会逐项返回结果，便于定位失败资源。
• 导出明文资源： resource_export 和 resource_export_batch 支持将资源导出到指定项目目录，模型 prefab 和粒子 effect 默认保留所在目录及依赖；官方云资源缓存保持不变。
• 按需自动下载： 导出工具提供 downloadIfMissing，可以把资源准备和导出串成一步。
• 面向 AI 的真实样例： 可先从素材目录选择官方资源，再导出为明文参考，帮助 AI 手写项目自己的 .effect、prefab、材质和贴图引用。配套 MCP 工具速查、使用指南和 AI Skill 已补充完整流程。上述 MCP 入口需更新编辑器。

创作者中心 MCP 大日志分析

AI 可以在项目日志下载授权范围内，直接通过创作者中心 MCP 分析超过 512 KiB 的客户端 ZIP 附件和游戏局脚本日志，无需另外取出连接凭据发起下载请求。新增工具需对应后台服务更新后生效，接入与使用示例见创作者中心远程 MCP 指南。

• 直接读取压缩包中的日志： 新增 author_list_client_log_files 列出客户端 ZIP 内的文件，再用 author_read_log_text 分页读取选定文件的文本；同一文本工具也可直接读取游戏局脚本日志。
• 优先查看报错位置： 支持读取日志末尾、按字面关键词定位和顺序续读，文本每页最多 32 KiB；分页可校验源内容是否变化，避免拼接不同快照。配套 AI Skill 默认采用文本分页分析，遇到旧整包工具的 512 KiB 超限提示时接续使用新工具。
• 分块获取完整附件： 新增 author_read_log_chunk，通过 MCP 获取 ZIP、7Z、DUMP 原始文件或 ZIP 内单个文件的 Base64 分块。ZIP 文本提取支持未加密的 Store/Deflate 条目；7Z 解压和 DUMP 分析仍需 AI 客户端具备相应文件处理工具。
• 扩大游戏局日志读取范围： 游戏局脚本日志总上限从 1 MiB 提升至 16 MiB；客户端原始附件与 ZIP 内单文件解压后的上限均为 16 MiB。已有整包返回工具保留 512 KiB 上限，超过时提示转用分页工具。配套 AI Skill 已同步大日志读取流程。

离散瓦片地形画笔自动化

AI 可通过 MCP 编辑视野遮挡、台阶/斜坡、水域、裂缝、手绘碰撞与道路，并使用预览、撤销重做和显式保存完成可验证的场景修改。新增入口需更新编辑器。

• 补齐场景画笔入口： 新增 terrain_*sight_edit、terrain_*collision_edit、terrain_*crack_edit、terrain_*ramp_edit 和 terrain_*road_edit 的预览/应用工具，并提供视野与手绘碰撞查询、台阶与道路样式目录；水域继续使用已有 terrain_*water_edit。修改纳入场景历史，保存后可重新打开验证。
• 分别编辑台阶与道路： 台阶/斜坡修改地形拓扑，道路画笔处理道路纹理和边界装饰物。原有 terrain_*path_edit 保留为台阶/斜坡入口；道路擦除保留已绘制的地表纹理。修复擦除无裂缝区域时可能误报拓扑失败的问题。
• 明确碰撞与保存范围： 手绘碰撞工具仅查询和编辑手绘层；Surface2D 运行时静态碰撞还包含场景保存时烘焙的地形与装饰物碰撞。配套指南与 AI Skill 补充选格、预览确认、保存重开和验证流程，并补充使用 GameDataEffectLaunchMissile 发射自身、遇静态障碍停止的冲锋配置 Skill。

编辑器关闭自动化

AI 可以通过 MCP 结束当前编辑器进程，并明确处理项目的未保存修改，避免自动化流程停在关闭确认框。

• 按未保存策略关闭编辑器： 新增 editor_close，项目存在未保存修改时可选择 save、discard 或 cancel；项目没有未保存修改时直接关闭。关闭请求会先返回已排队状态，再执行关闭；编辑器退出后 MCP 连接也会结束，调用方应以编辑器进程和 MCP 服务停止确认关闭完成。
• 接管已打开的关闭确认框： 用户已经手动打开“是否需要保存当前内容？”对话框时，editor_close 会复用当前对话框并选择对应操作；其它消息框打开时会返回失败并保留编辑器状态。此项需更新编辑器。
• 读取并处理共享消息框： 新增 editor_dialog_snapshot 与 editor_dialog_choose，AI 可先读取消息内容、用途、窗口 ID 和按钮状态，再对匹配窗口选择可用按钮，继续保存、关闭或更新流程。过期窗口 ID、隐藏或禁用按钮会返回明确诊断；范围为编辑器共享消息框，不包括系统文件选择框与进度窗口。此项需更新编辑器，配套 MCP 文档和调试 Skill 已补充操作流程。

编辑器项目管理

• 新建项目窗口选择或输入的有效保存目录现在会保存到编辑器用户目录，重启编辑器后继续作为默认目录；目录不可用时回退到系统默认路径。此项需更新编辑器。

编辑器资源预览

• 修复从“项目资源”查看含模型模块的粒子特效时，可能因资源路径大小写、分隔符或绝对路径处理异常而报 Lua 错误的问题；同时修正粒子面板刷新时的路径处理。

触发编辑器多行条件

• 逐行组织复杂条件： 条件列表新增“与（多行）”“或（多行）”“非（多行）”，展开后可逐行添加、删除和嵌套子条件，并支持复制粘贴、撤销重做。“与”要求全部子条件成立，“或”要求任意子条件成立，“非”对全部子条件按“与”合并后的结果取反，例如 !(A && B && C)。
• 区分条件行与参数表达式： 多行组只可作为触发器、条件分支、循环或另一多行组中的独立条件行，不能填入参数或动作列表；原有内联“与 / 或 / 非”表达式保留。此项需更新编辑器。配套触发器 MCP Skill 补充图形化多行组与 C# 内联逻辑的使用边界。

编辑器项目编译与错误诊断

调试前的项目 DLL 编译改为后台任务。用户可在编辑器内查看具体错误、打开源码和完整日志；AI 也可读取同一次构建的结构化诊断，修复后再次调试。此项需更新编辑器，手动编译、UI 编辑器创作模式、发布编译和资源统计共用构建流程。

• 保持调试进度可见： 编译进度窗口保持置前，编译期间暂时阻挡编辑器窗口操作，结束后恢复；AI 仍可通过 MCP 查询或取消正在运行的构建。
• 独立生成并编译项目或依赖库： 新增 build_start，保存数据与触发器、生成代码，编译 Server-Debug 和 Client-Debug 并部署 AppBundle 后结束，不启动游戏。返回的 build_id 可用于查询状态、等待、读取诊断和取消，便于 AI 验证依赖库数编代码；运行效果在引用该库的游戏项目中验收。
• 明确依赖库的调试入口： 直接调试依赖库时，在开局前提示使用游戏项目验收、使用 build_start 完成生成编译；已配置测试地图的菜单调试路线继续可用。普通 debug_start 的保存、生成、双端编译与开局步骤已在工具说明和配套文档中明确，debug_start_no_compile 使用已有产物。
• 集中查看编译错误： 错误与警告显示在“信息列表”的“编辑器”页，来源为“编译”。构建失败或超时时，自动显示窗口并切换到该来源，清空搜索条件并恢复全部严重级别可见，避免错误被先前的筛选隐藏。
• 打开源码和完整日志： 具体错误行右侧显示可点击的源码路径及行列，构建阶段消息右侧提供完整日志路径。源码通过系统关联程序打开，行列供定位参考，暂不自动跳到 IDE 对应行；UTF-8 构建日志按项目与任务统一保存到编辑器 logs/build。
• 让 AI 接续修复： AI 可通过 build_status、build_diagnostics、build_wait 和 build_cancel 查询诊断、等待或取消构建，debug_status / debug_wait 同时返回关联构建结果；查询等待超时不会取消正在运行的编译。配套调试指南与 AI Skill 已补充错误定位和重试流程。
• 保留有效的运行产物： 必需配置全部编译通过后才部署 DLL，编译失败保留上次已部署产物，部署失败会尝试恢复上一份产物。

3D 场景寻路与默认战术 AI

• 修复 3D 场景中默认战术 AI 已找到攻击目标，却未按配置转向、可能长时间停留在攻击前摇的问题；转向按单位最终转身速度对应的时间执行，并同步客户端。此项随服务端更新生效。
• 修复 3D 场景中接近单位或坐标的寻路指令、指令查询与停止接近未正确使用 3D 导航的问题，保留目标点的 Z 坐标；同时修正“忽略视野”的判断，并在持续接近期间沿用该选项。此项随服务端更新生效。
• 修复移动与攻击接近指令的范围判定仅考虑平面距离、可能把不同高度的目标提前判为已到达的问题：Volumetric3D 场景按 XYZ 距离判断，Surface2D 场景继续按 XY 距离判断。判定复用已读取的坐标和场景配置，减少高频跨运行时调用。此项通过依赖库更新生效。

服务端单位状态自动化检查

AI 可通过 Runtime MCP 获取当前游戏局的服务端单位状态，用于检查移动、默认战术 AI、指令和生命变化，减少为常规排查添加项目临时诊断代码的步骤。

• 读取真实单位状态： 新增 gameplay.snapshot，按场景、单位和分页读取 XYZ 坐标、生命值、最终移动与转身速度、AI 目标和当前指令，并返回服务端与客户端会话信息，便于核对同一局的证据。请求后使用返回的 request_id 在同一 Runtime 目标查询结果；纯客户端模式不提供服务端状态。此项通过依赖库更新生效。
• 发现可查询的场景： 默认查询主单位所在场景，没有主单位时尝试玩家所在场景；找不到场景时返回可用场景目录。配套行为排查和 3D 单位 Skill 补充目标隔离、范围布置及会话核对流程。

数据样例与公共模板

• 复用官方玩法基础定义： data_sample 的单位、技能、Buff 和物品样例改为继承 GameSparkCore 公共模板，生命值、单位属性和伤害类型统一引用公共声明，减少重复维护。GameSparkCore 新增占位单位、固定单位、被动技能、开关技能和 Buff 模板；数据编辑器 Skill 补充模板发现、继承集合检查与保存生成流程。此项随样例和地图库更新生效。

编辑器调试与导航文件保护

• 修复保存或调试项目时，可能把仍被 3D 场景使用的 map.nav 和 mapnavvoxels 当成 2D 残留删除的问题。普通保存和调试不再删除工程里的导航文件；只有在场景属性里把某个场景从 Volumetric3D 改成 Surface2D，且运行时不会再按 3D 加载该场景时，才清理这一份导航。地图仍按 3D 加载的默认场景会保留导航文件。显式标记为 Surface2D、且运行时不再需要导航的场景，调试和发布上传时会跳过这些文件，但工程内的原文件保留。此项需更新编辑器。

启动资源预加载配置

多关卡或资源较多的项目可以选择按需加载，避免启动时集中加载后续关卡暂时用不到的资源。

• 按游戏模式选择加载方式： 新增“启动时预加载资源”配置 GameDataGameMode.PreloadResourcesOnStartup，默认开启；设为 false 后，资源在场景加载或实际使用时按需加载。
• 保留完整资源下载： 开关不影响资源统计、项目打包和开局前下载；关闭预加载后，首次进入关卡或使用资源时仍可能产生等待。使用新 SDK 配置后需重新生成、编译并发布项目，此项通过依赖库更新生效。

运行时资源与 Shader 诊断

• 修复客户端调用 Technique.Clone()、Pass.Clone()、Mesh.Clone() 或 AnimationResource.Clone() 后，克隆对象可能被提前释放、继续访问时导致崩溃的问题。此项通过依赖库更新生效。
• 减少资源探测噪声： 项目文件缓存探测失败后继续查找共享资源，全部位置都未找到时再报告文件缺失；可选图集、默认界面样式与窗口图标缺失不再作为常规错误或警告记录，Shader 字典内部信息改为调试信息。图集配置损坏、图片最终缺失与 Shader 加载失败仍保留诊断。此项需更新客户端或编辑器。
• 更清楚地定位 Shader 缺失： 缺少 MD5 索引时继续尝试文件名与 UI 缓存；最终未找到字节码的错误补充源码路径、变体、字节码路径、索引状态及资源包名称，便于区分探测失败与实际资源缺失。

场景 2D 动画的射线选取说明

• 明确序列帧与 Spine 的命中范围： GameGraph 2D 动画文档与相关 AI Skill 补充 StaticSprite2D / AnimatedSprite2D 的现有射线检测规则：Octree 常规查询按当前世界 AABB 命中，透明区域及部件间空隙也可能被选中；Triangle / TriangleUv 不提供逐三角形或像素 Alpha 检测。说明命中字段、默认 Any 掩码的用法，以及精确命中需另外配置命中框或物理碰撞形状。本次仅补充文档，不改变运行时行为。

运行时内存与资源释放

• 修复取消 Game.Delay() 等延迟任务后，取消令牌可能继续持有任务及其引用对象的问题；同时修复使用已取消令牌创建任务时，任务可能仍留在更新队列中的问题。
• 修复销毁 GameGraph 父 Node 后，子节点包装对象与组件可能残留的问题；释放框架自行创建的 SceneGraph 时，也会清理其节点树中的包装对象和组件。
• 修复服务端通过 IDisposable.Dispose() 释放 PropertyObject 时，可能遗漏底层同步对象销毁的问题；Destroy() 与 Dispose() 统一清理附加对象、冷却池及事件资源，并避免重复释放。
• 修复对象清理、任务完成或组件释放回调抛出异常时，可能跳过后续资源释放或留下更新对象的问题。上述修复通过依赖库更新生效。

客户端与编辑器基础维护

• 更新网络通信、资源压缩、FBX 模型导入与光照烘焙等基础组件，并统一客户端与编辑器的共享组件版本。
• 修复若干可能导致数值异常、资源读取失败或通信异常的问题，改善跨平台运行稳定性。上述更新需安装对应新版客户端或编辑器。
• 优化客户端与编辑器自身的编译流程，减少重复编译与整体构建耗时，加快版本迭代。

客户端稳定性

• 修复客户端退出时，延迟释放的游戏对象可能访问已销毁渲染器的问题；修复触摸悬停回调重置输入或移除其他触摸点时可能导致崩溃的问题。上述修复需更新客户端或编辑器。
• 修复计算蒙皮在跳过渲染、关闭功能或移除模型后，可能继续访问失效对象的问题；清理遗留帧数据，并检查渲染前模型与批次是否仍有效。此项需更新客户端或编辑器。
• 修复安卓图形初始化失败后仍继续调用图形接口、可能导致崩溃的问题；初始化失败时清理已创建的资源并返回失败。此项需更新 Android 客户端。
• 修复安卓语音模块清理电话监听时，系统服务异常可能导致崩溃的问题；电话监听与广播接收器分别清理，并保留正常来电中断通知。此项需更新 Android 客户端。

任务收集、交付与接入示例

• 识别物品变动来源： 新增 EventItemSlotChange.SourceSlot，保留物品入栏前的来源槽位；新增 EventItemStackChange.SourceCarrier，提供堆叠合并时的来源单位，直接修改堆叠数量时为空。可用于区分新获得物品与同一玩家内部移动或合并，避免重复累计收集进度。此项通过依赖库更新生效。
• 修复收集目标的背包计数与物品入栏更新问题，支持多个背包、物品列表和分类匹配；实时目标在材料减少后更新进度和可提交状态，累计目标避免将背包内移动或合并重复计数。
• 修复收集目标提交时未按 ConsumeOnComplete 扣物的问题；提交前统一检查多个目标的材料需求，材料不足时失败并保留物品。修复堆叠数量增减或合并可能发生的整数溢出问题。
• 修复任务 UI 未优先显示 DisplayName、可接受任务列表未返回已标记链接的问题，并避免重复初始化导致事件被重复处理。上述运行时修复通过依赖库更新生效。
• 修正任务系统文档中的自定义目标通知参数、任务与章节 UI 回调签名、返回类型和双端使用范围；重写服务端任务流程与客户端完整 UI 接口示例，减少按文档接入时的编译错误。
• 补充收集目标计数与扣物规则、奖励关联示例，以及自定义目标更新范围、进度增量与绝对值的区别、操作结果检查和 UI 绑定方式；官方示例检查接取和提交结果，并使用内置初始化。

其他修复

• 修复线上版本编辑器未正确显示真 3D 单位控制器模板的问题。
• 修复 iOS 客户端初始化游戏脚本时，读取时间早于 1970 年的文件元数据可能导致崩溃的问题；无法表示的时间按缺失处理，保留正常文件时间与文件长度。此项随新版 iOS 客户端更新生效。

2026-09-29 ～ 2026-10-06（内网测试中）

当前客户端能力版本：7（本期从 6 提升）。新增 TmxFile2DModernLoading：读取新版 TMX 有限地图与压缩图层数据；项目可通过 ClientEnvironment.Runtime.Supports(...) 判断。技能试验场仅在调试对局启用，相关原生表现能力需要对应新版编辑器。

本期重点速览

本期提供完整 TMX 探索小游戏与二维渲染路径示例，补齐不同客户端的地图格式选择、颜色输出与 UI 排版指引；技能试验场支持在真实调试对局中调整技能并导出草稿；模型资源包可通过 AI 导入、预览并重定向动作，捏人窗口支持 AI 调整体型、换装和染色并另存角色；Buff 倒计时的同步范围可以独立配置；AI 可调整当前场景氛围、启动多人调试并直接切换客户端页签，并通过新版预览工具集中采集完整截图、UI 和日志证据。

GameGraph 客户端附加模型挂载

GameGraph 客户端现在可以把 Prefab-backed 的附加模型挂到角色的主骨骼模型上，适合在运行时组合角色外观、手持物、装备和其他外观部件。附加模型属于表现层模型，不是独立的玩法对象；挂载入口明确放在具体的 AnimatedModelComponent 上，避免一个节点包含多个模型时产生隐式选择。

• 挂载 Prefab-backed 附加模型： 使用 AnimatedModelComponent.AttachAdditionModel(...)，输入 GameCore.ResourceType.Prefab 或已加载的 Prefab；返回 AdditionModelAttachment，可通过 Detach() 解除单次挂载。同一个附加 Prefab 可以创建多个独立挂载。
• 按需裁剪宿主网格： AdditionModelOptions.CullHostMesh 可启用附加模型参与宿主网格裁剪；未启用时仍保留附加模型的骨骼跟随和渲染。
• 明确使用边界： 首版只支持 Prefab-backed 的客户端主骨骼模型和 Prefab-backed 骨骼附加模型；服务端和非 Prefab-backed 模型不提供这组 API。

游戏视觉制作与快速预览

AI 游戏开发流程补充场景、角色、镜头、光照、HUD 与反馈的共同设计和实际画面验收，提供可复用的视觉制作指引与纯客户端预览入口。

• 通过 AI 调整场景氛围： 新增 Editor MCP 工具 terrain_get_atmosphere、terrain_preview_atmosphere_edit 和 terrain_apply_atmosphere_edit，支持查询当前场景氛围及其 .lightgroup 路径，预览并按需修改环境光、雾、环境贴图、反射、后处理和主光源颜色、亮度与方向。一次应用生成一条可撤销、重做的记录，未传入的属性保持原值；修改后需显式保存场景，保存共享 .lightgroup 会影响之后加载它的其他场景。配套氛围指南和场景氛围 MCP Skill说明查询、预览、应用、保存与重载核对流程。此项需更新编辑器。
• 按完整游戏画面制作： 新增 game-visual-production AI Skill 和工业题材 HUD 参考，从游戏起手、GameGraph 和 UI 布局 Skill 接入。检查实际角色和怪物资源、整体与近景构图、多帧移动射击，以及死亡面板和真实重开交互；渲染排查保留可运行基线，逐项替换素材、光源和后处理，减少多项变更同时失效时的定位成本。
• 一次采集客户端预览证据： Start-SceClientOnlyDebug.ps1 -Preview -DeployClientDll 可校验并部署项目客户端 DLL，等待 Runtime MCP 就绪，并在运行时提供启动状态时等待游戏启动、框架加载页退出，再采集截图、UI 快照和本次日志，关闭本次启动的进程。报告记录实际工具版本、项目、运行模式和启动状态；旧运行时无法确认加载页退出时明确保留警告。已有编辑器会话优先复用，服务端玩法仍须正常调试验证。用法见纯客户端调试指南。
• 读取镜头与灯光配置： 新增只读 Runtime MCP 工具 scenegraph.render_snapshot，集中查看主视口、相机、候选光照区域、雾、暗角与灯光参数，并返回遍历限额和部分读取诊断，帮助定位全黑或光照异常。实际选中的光照区域与暗角遮罩绑定尚无法确认时明确标为未知，仍需结合截图核对。预览工具发现该入口后自动保存 render.json；旧运行时不支持时保留正常截图流程。
• 修复 Node.GetComponents() 在原生返回空组件列表时可能抛出空引用异常的问题；没有组件时返回空数组。
• 等待截图写完再读取： Runtime MCP PowerShell 客户端的 -Wait 检查新截图的 PNG 数据块及结束标记，避免文件刚创建时提前接受不完整图片；超时会返回失败阶段。Runtime MCP 的控件 ID 与整数参数兼容带 .0 或指数形式的精确整数，并对非法控件 ID 返回明确错误。

Tiled 地图与二维游戏样例

• 用完整小游戏学习 TMX： code_sample 新增 TmxMapSample 苔湾小镇样例，使用 Maker 生成的地图、图块集与精灵，通过 TileMap2DComponent 渲染，读取对象层中的出生点、阻挡矩形、区域介绍和六枚水晶。包含正交镜头跟随、键盘/摇杆移动、拾取与重置，以及退出资源清理；玩法在客户端本地执行。
• 按客户端能力选择地图格式： 样例启动时检查 TmxFile2DModernLoading，能力版本 7 及以上加载 TMX 1.11 + zlib，未提供该能力时加载 TMX 1.0 + 未压缩 Base64。两份地图共用图块集与图片，图块和玩法对象一致；此分支兼容地图读取格式，其它 API 与渲染配置仍需按目标客户端验证。
• 明确地图与移动输入的坐标： 文档和 AI Skill 区分 TMX 文件的左上原点、Y 向下，与加载后正交地图的左下原点、Y 向上；已加载的对象坐标无需再次翻转。样例把 GameSystemUI 的原始屏幕方向转换为 (X, -Y)，修正 W/S 方向，并说明原始 Direction 与镜头补偿后 WorldDirection 的使用条件。方向转换不包含地图高度偏移，TMX 也不会自行创建相机。
• 直接读取新版 Tiled 地图： TmxFile2D.Load(...) 支持 TMX 1.x 的普通有限地图，包括 1.11，保留 XML、CSV 与未压缩 Base64 图层，并新增 Base64 zlib、gzip、zstd 图层数据解压。压缩对象是图层中的瓦片编号数据，不是图片格式。外部 TSX 的图片按 TSX 所在目录解析，支持相对路径中的 ../。此项需更新客户端或编辑器，最低客户端能力版本为 7。
• 明确格式边界与加载错误： 无限地图、分组图层、动画瓦片、对象模板及文本/点对象尚未支持，会报告具体原因；编码损坏、瓦片数量或解压后长度与图层尺寸不匹配时，会返回加载失败。Load 只加载地图资源，显示地图需赋给节点上的 TileMap2DComponent.TmxFile。完整用法见 TMX 地图指南。

技能试验场

作者可以在自己制作的场景中测试真实单位和技能，边施放边调整表现与时序，再把选定差异交给 AI 落实到源定义。调参默认按所选技能实例隔离、下一次施法生效，方便反复对照和撤销；施法仍由真实调试服务端执行，沿用技能原有的目标、效果、冷却与消耗规则。

• 布置真实单位与技能： 使用 GameDataSkillTestArena 配置场景、出生位置和兜底单位，由 GameDataGameMode.AbilityTestArena / AbilityTestArenas 引用；旧字段仍兼容读取。支持复用已有主控或创建指定单位，从项目和依赖库已注册目录搜索、添加或清空技能、替换单位，并按会话选项单次施放或自动连续施法；退出时按实际对象状态恢复原主控与布置。
• 按下一次施法调整表现： 受支持的动画和阶段表现参数保存在会话覆盖中，保留原共享定义。客户端完成配置准备与版本确认后，下一次施法使用新配置。支持多字段整组修改、撤销、重做和恢复原始配置，项目自定义表现可通过适配接口扩展。
• 保留原公式，固定四段测试： 原始模式使用技能公式；固定模式分别输入前摇、施法、持续施法和后摇的最终目标时长，不再二次归一化。服务端实际采用的四段时间用于客户端动画适配，切回原始模式保留原公式；固定测试目标不会自动把攻速、等级或 Buff 公式改成常量。
• 在三轨时间轴中编排 Sequence： 动画片段按顺序连续拼接，Actor 轨编辑出现时刻与存续区间，事件轨编辑已登记事件的偏移与暂停设置。支持精确输入、增删、复制、片段重排和拖拽，松手一次提交一个撤销事务；源素材裁切与片段占用时长分别编辑，重排片段保持 Actor 和事件的绝对偏移。客户端事件打点不会自动移动服务端伤害判定，时间轴不提供整局暂停、倒放或任意 seek。
• 导出草稿供 AI 采纳： 可将测试差异、原基线、布置上下文和采用资源导出到项目 ui/AppBundle/user_files/skill_test/<name>.json。重新导入会核对项目、定义身份与基线，冲突时返回原因；AI 可按作者确认的差异修改真实源定义，补齐资源统计，再按正常双端编译、上传和重新开局流程核对结果。测试中的清空、添加技能列表默认不回写单位默认技能。配套指南与 AI Skill 说明了这一流程。
• 通过 Runtime MCP 驱动调试： ability_test.open 打开调试面板，ability_test.snapshot 用于读取真实单位、技能实例、目标和版本游标；ability_test.command 返回受理状态与 request ID；ability_test.response 读取真实服务端结果。命令必须使用最新快照中的 session、generation、setup revision 和表现 revision，pending 不代表施法成功。
• 明确进入入口与默认回退： 完成普通调试开局并连接客户端后，在 PIE 顶部调试栏点击 技能调试，面板会自动进入当前模式的默认配置。入口不占用项目游戏画面中的 UI；未配置 GameDataSkillTestArena 时，服务端 AbilityTestService.Enter 使用当前 GameDataGameMode.SceneList 第一个场景、场景中心出生点和当前主控单位作为回退，缺少有效对象时返回 AbilityTestEntryStatus 枚举式原因并记录日志。详细步骤见技能试验场指南和技能试验场 AI Skill。
• 按会话控制施法与默认控件： 面板按“主控与技能、施法、试验会话选项、表现、草稿、观测”分组，技能和单位优先显示显示名；面板单次施放默认使用自身目标，单位/地点目标交给 Runtime MCP。AbilityTestSessionOptions 支持自动连续施法、忽略冷却、不造成伤害，以及默认技能指示器/移动摇杆的条件创建；未配置试验场时两个默认控件选项自动开启，显式配置则由项目适配器读取 SkillTestArenaContext.Options 并在退出时清理。详细语义见技能试验场指南。
• 修正表现节点配置： AttachForwardOnce 现在明确表示捕获父节点和挂点的初始变换后立即解除附着；GameSparkCore 的“劈砍”刀光已启用该设置，粒子表现模板默认开启 Fade。音效没有 Actor 级 Fade 字段，淡入淡出由 GameDataSound.FadeTime 控制。详细语义见 ActorSystem 指南。
• 仅用于真实服务端调试对局： 入口与命令要求 Game.IsDebugTestMode，生产对局拒绝技能试验场操作；纯客户端调试不能替代权威施法验证。工具入口、动画按需准备及相关原生表现能力需更新编辑器，同时使用包含本次更新的依赖库。任务、波次、存档等项目业务需要接入自己的隔离适配，不会因进入试验场自动获得全面保护。

Buff 计时信息同步

PvP 游戏可以向敌方展示 Buff 及其特效，同时保留倒计时信息；是否公开剩余秒数现在可以按每种 Buff 单独配置。

• 独立控制倒计时的可见范围： 新增 GameDataBuff.DurationSyncMode，同步范围同时作用于运行时 Buff.Duration 和 Buff.RemainingTime。提供“不同步”“仅同步给Buff持有者”“继承Buff同步方式”三种选项，默认仅同步给 Buff 所挂单位的所属玩家；未配置该字段的 Buff 也采用此默认值。
• 按需公开计时信息： 选择“继承Buff同步方式”后，计时信息跟随 Buff 的 SyncType；例如视野同步会向视野内玩家公开倒计时。选择“不同步”时，服务端照常计时，客户端不接收计时信息。不接收计时信息的客户端读取 Duration 和 RemainingTime 得到 null，UI 应隐藏倒计时，不能据此判断 Buff 是否永久。
• 修复新附加 Buff 的计时信息可能未按所配置同步范围发送的问题。

项目模型导入与 AI 预览

AI 可以把本机模型资源包导入项目，生成可在美术资源库预览、在地编拖动放置的 prefab，减少手工解析资源引用和适配材质的步骤。

• 静态资源包导入： 新增 resource_import_model_package，支持目录或 ZIP 中的静态 XML prefab、MDL、材质与贴图，解析 UUID 引用、保留可表示的节点变换并适配不透明 PBR 材质。可先预览导入计划，再指定尺寸、向上轴和底面贴地；默认不覆盖已有资源。不支持的格式、材质或组件会返回具体原因。

• 骨骼与动作资源包导入： 同一工具支持带骨骼的 XML/MDL 模型和匹配骨骼的未压缩 UANI 动作，生成骨骼 prefab 与动作集。可以指定动作名称，将待机动作映射为 idle 默认循环预览；仅有绑骨模型时以绑定姿势导入并提示补充动作。导入检查骨骼层级与动作轨道匹配，预览返回动作依赖、时长和轨道数量。支持将 Diff / DiffNormal 源材质近似适配为非金属 PBR，并保留颜色和法线贴图。

• 检查依赖并定位预览： resource_get_preview_info 新增网格与依赖状态，缺失材质、贴图或 technique 时保留部分信息并返回结构化诊断。修复依赖检查失败后可能被本地文件摘要降级误报为成功的问题。可通过 resource_reload 重载资源缓存、刷新项目资源树，通过 resource_open_preview 打开资源库并定位 prefab；实际画面仍需查看，不能只凭网格加载成功判断材质正确。

• 保留中文显示名： 修复导入模型的中文名称可能显示为 Unicode 转义字符的问题，资源库和地编可以按配置的中文名称查找模型。

• 完整导入指引： 配套指南与 AI Skill 覆盖模型包导入、资源库预览、地编放置和保存重开。项目内 res 资源随客户端包封装，无需资源统计；资源统计用于云资源预下载。新 MCP 入口需更新编辑器。

• 优先排查导入模型发白： 材质文档与 GameGraph、Maker 导入 AI Skill 明确先检查颜色贴图的实际 sRGB 设置；常见 sRGB 颜色图若被按线性加载，优先设置为 true，重载贴图与材质，在相同镜头和光照下对照，再排查光源、环境反射和曝光。明确使用线性颜色的源素材，以及法线和混合数据图，仍保持线性加载。

• 按材质适配混合贴图： 文档与 AI Skill 区分 MaterialPBR 默认材质的 R/G 法线、B 粗糙度、A 金属度，与 MaterialPBRVertexColor 的独立法线及 R/G 表面数据布局，避免把普通 RGB 法线直接当混合图或重复相乘粗糙度、金属度。补充同名贴图 XML、金属度开关和运行时核验方法，并说明模型包导入 MCP 已自动适配的范围，以及直接复制或代码引用贴图时需要自行完成的设置。

• 为自定义骨骼模型使用官方动作： 新增 resource_get_skeleton 与 resource_retarget_animations，可读取两套骨架、建立明确映射，并把原始骨骼动作转换到新的项目 prefab 与动作集。根据躯干和左右骨骼的真实参考姿势统一模型空间与单位，生成前检查源参考姿势能否还原目标参考姿势；同空间模型保持原方向。保留动作时长及命中、取消打点，默认不覆盖原资源。配套指南与 AI Skill 覆盖 Maker 绑骨包导入和官方动作重定向；具体握持、手指和脚底效果仍需查看实际动作。此项需更新编辑器。

• 修复重定向中排除根骨骼时，父轨道索引可能越界并导致崩溃的问题；修复最顶层映射骨的位移可能使用未写入的目标变换，导致姿势偏移的问题。

AI 捏人与角色另存

AI 可以在可见的捏人窗口中组合角色，调整体型、服饰、肤色和染色，再另存为当前项目中的模型资源。新工具需更新编辑器，所用体型、部件和材质须已下载。

• 读取实际配置并调整角色： 新增 human_catalog、human_open 和 human_state，查询体型、体态、默认部件、肤色材质及参数范围，新建角色或打开已有捏人 prefab。后续操作使用明确的会话 ID，支持多个捏人窗口；human_set_values 先校验整组参数，再批量调整。
• 同步换装与染色预览： human_set_part 支持部件添加、替换、移除和变换，human_set_skin 应用肤色，human_set_tint 修改材质实际支持的染色通道。调整同步到模型与界面，MCP 染色在另存前仅更新预览，换装刷新保留材质未变的部件上的未保存颜色。
• 生成项目内角色资源： human_save 另存到项目 res 下尚不存在的新目录，生成 model.prefab、材质/贴图、捏人配置与体型默认动画，保存当前可见部件并刷新项目资源树。沿用既有弹性骨骼与物理配置保存流程，不复制原角色自定义动作集；生成失败返回可能已写入的目录，便于检查后换目录重试。human_close 只关闭 MCP 创建的窗口，未保存时须显式丢弃；首版暂不支持 Undo/Redo。

多人调试与 AI 自动化

AI 可以通过 MCP 查询项目玩家配置、启动多人调试，并切换到指定客户端页签继续操作和检查游戏，减少手动打开多人调试窗口与点击页签的步骤。以下新增入口需更新编辑器。

• 指定玩家启动多人调试： 新增 debug_list_players 查询用户玩家槽位、队伍与调试启用状态，debug_start_multiplayer 按所选玩家启动最多 4 个内嵌模拟客户端，支持逐个设置延迟加入秒数，以及通过 skip_compile 使用已有 AppBundle。玩家必须已在项目 PlayerSettings 中启用 LocalTestOpen，队伍沿用项目配置；启动结果可通过 debug_status / debug_wait 查询。
• 直接激活客户端页签： 新增 debug_activate_client，使用 runtime_list_targets 返回的 slot_id 切换可见页签并设置游戏输入焦点，激活结果同样可查询。尚未打开、已经关闭或视口未就绪的客户端会返回失败；后续 Runtime 工具调用仍使用对应的 target_id。debug_stop 的说明明确支持结束当前单人或多人对局，并关闭全部模拟客户端页签。

编辑器调试

• 更清楚地检查运行时控件： UI 编辑器为没有数编来源的控件提供专用只读检查面板，展示当前运行时布局、可见性、透明度、启用状态和来源诊断，并可复制检查详情。有来源但暂时无法解析或读取的控件显示具体原因并支持重试；来源可解析的控件继续使用现有属性编辑流程。此项需更新编辑器。

• UI 编辑器移除默认画布标尺，并下线当前滚轮缩放与中键平移入口，释放画布边缘空间；现有控件选择、边界、拖拽和尺寸调整继续使用原编辑流程。此项需更新编辑器。

• 修复 PIE 顶部“静音”选项对 2.0 游戏中的自定义音效分类不生效的问题；勾选后统一静音，取消勾选或退出 PIE 时恢复声音。静音期间编辑器提示音也会一并关闭。

• 修复远端调试准备过程中，连接断开后进度可能一直停在 99%、后续调试无法重新开始的问题。连接中断或准备超时会结束本次调试并提示重试，同时清理未完成的上传和启动任务；等待服务器开局时显示对应阶段。连接与登录、世界分配、开局等待分别增加 30 秒、60 秒和 5 分钟超时。此项需更新编辑器。

• 修复场景列表更新单个对象排序时，可能访问已失效场景节点并导致崩溃的问题；更新前检查对象注册状态，并记录被跳过的失效节点更新。此项需更新编辑器。

项目上传与发布

• 区分上传受理与发布完成： 上传界面等待服务端确认后再显示上传结果，普通进度通知不会提前触发成功提示。项目上传受理后明确提示后台正在发布，可前往创作者中心查看进度；后台返回的最终发布结果继续记录。
• 更清楚地排查上传失败： 网关超时提示说明服务端处理结果尚未确认，并提供请求编号，避免将项目上传失败笼统显示为依赖库失败。上传日志补充项目、请求编号、阶段耗时、最后进度和后台任务信息，便于定位压缩包校验、文件存储或发布任务入队等步骤；超时后迟到的结果保留记录，避免重复弹窗。
• 修复后台未能建立发布任务时，仍可能报告上传受理成功的问题；压缩包校验失败会记录退出码和失败阶段。

Windows 客户端稳定性

以下修复需更新客户端。

• 修复贴图格式转换过程中，转换缓冲区分配失败时可能崩溃的问题，并补充转换尺寸溢出检查与临时缓冲区清理。
• 修复创建字体贴图时，内存分配失败后可能访问空对象并崩溃的问题。
• 修复启动图形引擎时，初始化对象的内存分配失败后可能崩溃的问题。
• 修复启动读取资源包版本文件时，读取缓冲区分配失败后可能崩溃的问题；读取失败会返回失败状态并记录原因。

Android 客户端稳定性

• 修复语音 SDK 查询网络状态时，Android 系统网络服务异常可能导致崩溃的问题；查询失败时按未知网络状态处理。此项需更新 Android 客户端。
• 修复 Android 客户端打开外部网页时，系统或第三方运行环境报错可能进一步导致崩溃的问题。此项需更新 Android 客户端。

UI 排版与客户端稳定性

• 修复 Label 和 Input 的默认字号可能未同步到实际显示的问题；模板中的显式字号仍优先生效。
• 按目标窗口选择可读字号： UI 指南和 AI Skill 明确说明字号按设计画布缩放，提供桌面字号起点与移动端验收方法；TMX 样例放大 HUD 标题、计分和区域介绍，并保留长文本换行与自动增高。
• 让动态长说明按面板宽度换行： TMX 样例约束 Label 的可用宽度，采用换行、自动高度与 TextTrimming.Clip 边界兜底，让区域介绍变长时面板向下增高。布局指南和 AI Skill 补充 TextWrap 不会自动建立宽度约束、垂直流式容器中的 AutoWidth/横向拉伸条件，以及固定高度与裁剪的影响；排查覆盖短文本变长后再变短，并结合 Runtime MCP 尺寸和截图核对实际布局。约束正确却不更新的情况仍需继续排查实现。
• 修复父控件销毁后，仍存续的子控件更新布局时可能访问失效父布局并导致崩溃的问题。此项需更新客户端或编辑器。

二维渲染与场景稳定性

• 显式配置二维主视图： TMX 像素地图样例使用专用二维 RenderPath，避免沿用宿主的 3D Bloom 和色调映射，并在退出时恢复原视口配置。新增 Renderer.IsEditorDebugViewportActive 判断实际是否使用内嵌调试画布，明确它与纯客户端玩法模式的区别。
• 保持二维素材的颜色输出一致： 样例按 sRGB 采样图片并在线性空间合成；PIE 输出由编辑器 UI 完成最终 Gamma 转换，独立窗口使用显式 rgba16f 高精度缓冲和一次 GammaCorrection 输出，减少中间颜色量化误差。补齐两种 Gamma shader 变体，覆盖编辑器、PC、Android 和 iOS 的配套 shader 资源。
• 复用普通二维游戏的渲染路径： 新增二维渲染指南与专用 AI Skill，附两份 RenderPath XML 和保存/恢复主视口状态的 C# 样例。说明无光照精灵仍会受到全屏后处理影响、BloomHDR 的合成还包含 ACES 色调映射，以及 LightGroup/Zone、sRGB/Gamma 和像素采样各自的作用；给出首次 PIE、先运行 3D 后的 PIE、独立客户端的对照方法。样例面向专用二维精灵主视图，混合 3D 场景与透明画中画按各自合成方式配置。
• 修复启用暗角但未提供有效遮罩时，场景画面可能全黑的问题；没有有效遮罩或强度时跳过暗角合成，清空遮罩路径时同步清除旧纹理。API 文档补充遮罩与强度的合成语义。此项需更新客户端或编辑器。
• 修复通过代码设置尚未挂到场景节点的光照区域属性时，可能访问空节点并崩溃的问题。此项需更新客户端或编辑器。
• 修复手动移除渲染对象后，更新队列可能残留该对象、在对象销毁后继续访问并崩溃的问题；移除时同步清理待更新记录和相关状态。此项需更新客户端或编辑器。
• 修复通过 RenderPath.Clone() 复制渲染路径后，释放脚本包装对象可能提前销毁仍被视口使用的渲染路径并导致崩溃的问题。此项需更新客户端或编辑器。
• 修复 Windows 渲染参数更新遇到空存储或写入长度超过容量时可能崩溃的问题；补充指令类型、数据长度与句柄范围检测，跳过异常更新并记录诊断日志。此项需更新 Windows 客户端或编辑器。

2026-09-22 ～ 2026-09-29（已发布至线上正式环境）

当前客户端能力版本：6（本期从 5 提升）。新增游戏内客户端日志上传请求能力 ClientLogUpload；调用前可用 ClientEnvironment.Runtime.Supports(...) 判断当前客户端是否具备该能力。

创作者中心远程 MCP

作者可以把创作者中心作为独立远程 MCP 服务接入 AI 客户端，不用打开编辑器，也无需安装后台源码，即可让 AI 在授权范围内核对项目配置和排查日志。当前在 alpha 提供试用；其它部署环境需先启用对应后台服务。

• 按项目授予短期权限： 作者登录后为自己的单个项目生成 15 分钟、可撤销的授权。默认只读项目配置，日志正文和内测邀请码需单独授权；票据通过 AI 客户端的私有 Bearer 请求头配置，不放入项目文件或聊天。当前采用手动短期授权，不支持自动登录或 OAuth 刷新。
• 取得真实日志文件： AI 可先列出客户端上传记录或游戏局，再按记录 ID 获取客户端原始附件及游戏局脚本日志；支持实时日志与压缩归档，超过直接返回上限的文件可通过受授权下载接口取得。
• 按需管理内测邀请码： 支持查看邀请码状态和完整代码；只有明确授权并提出创建请求时才创建邀请码，已有代码直接返回。当前不开放模式、大厅配置修改或游戏发布。
• 提供接入指引与 AI Skill： 新增专题 Skill，并提供远程连接、权限选择、日志读取及票据过期处理说明。这项后台能力不要求升级游戏客户端，也不额外提升客户端能力版本。

游戏内上传客户端日志

2.0 项目可在自己的游戏设置或反馈页面放置上传入口，让玩家遇到问题时直接提交本机日志。

• 在自制设置页提供上传日志按钮： 客户端代码可以调用 ClientEnvironment.Diagnostics.TryUploadLogs()，请求将本地客户端日志按当前项目打包上传；沿用现有日志上传流程，无需引入 1.0 游戏设置页面库。请求仅在支持 ClientLogUpload 的客户端可用；返回值表示客户端是否接受请求，不表示网络上传完成，界面不应据此直接显示“上传成功”。此项需更新客户端或编辑器。

UI 编辑器创作模式

UI 编辑器创作模式现在优先保障属性编辑的连续操作，把页面结构作为导航区、全局命令压缩到顶部，并允许用户按自己的工作习惯调整面板空间。

• Inspector-first 双栏布局： 默认将左侧页面结构区控制在约 25%–30%，让右侧属性 Inspector 占据主要宽度和高度；添加控件与更多结构工具位于左侧结构区顶部，页面选择、保存、重载和预览等全局命令保留在紧凑工具栏中。
• 可调整并记忆布局： 左右分隔条以及左侧操作区与结构树之间的分隔条均支持鼠标拖拽，并提供恢复默认布局入口。布局偏好保存在编辑器的 Workbench 设置中，不写入 GameData、页面模板，不产生 dirty、Undo/Redo 或运行时 patch。
• 窄窗口保持可编辑： 窄窗口会在页面结构与属性 Inspector 之间切换面板，优先保证属性字段的可读宽度；调整布局不会改变当前选择、属性草稿、焦点或滚动状态。
• 删除控件与引用分开： 当前项目定义的控件可以选择删除定义与当前引用；如果其它位置仍引用该定义，则只移除当前引用。依赖库控件只能移除当前引用，不能删除依赖库定义；Page 仅允许删除当前项目独立定义的蓝图。MCP 的 uiauthoring_delete_control 对应删除本项目控件，uiauthoring_delete_placement 始终只移除引用。
• 官方控件模板覆盖补齐： UI Workbench 现在为 GameSystemUI 官方控件提供完整的可选模板，包括虚拟化面板、平台适配面板、摇杆和粒子控件；模板显式记录公共布局、交互和控件默认值，同时保留已有的视觉与尺寸配置，减少 Workbench 显示值与生成结果不一致的情况。
• 修复控件定义包含空事件配置时，在 UI 编辑器创作模式中将绝对位置改为相对位置并应用布局，可能因预览重建失败而无法提交属性的问题。

运营邮件与收件箱

GameSystemUI 现已提供运营邮件收件箱，可以在游戏里展示全服和个人邮件、追踪玩家状态并领取资源附件。底层查询同时修正了邮件时间和新玩家范围的处理。

• 直接接入游戏内收件箱： GameSystemUI 提供 MailWindow.Create() 与 MailEntrance.Create(window)，可显示邮件列表、详情、未读红点，支持已读、单封或批量领取及隐藏；服务端自动聚合运营邮件，用 CloudData 保存玩家状态，并将资源发放和领取状态放在同一事务。项目可用 MailSystemClient 自建界面。静默邮件在登录后尝试自动领取、不进入收件箱；不支持玩家互发或游戏脚本主动发信。

• 按当前游戏局环境显示邮件： GameSystemUI 收件箱默认按 Game.RuntimeEnvironment 查询 debug、test 或 formal 邮件，修复正式环境曾使用 production 导致对应运营邮件可能查询为空的问题；仅在项目后台使用特殊环境名时才需显式设置 MailSystemServer.EnvironmentName。

• 按运行时环境查询邮件： OperationMailApi.QueryGlobalOperationMailsAsync 和 QueryUserOperationMailsAsync 新增 GameRuntimeEnvironment 参数重载，可直接传 Game.RuntimeEnvironment，对应后台的 debug、test、formal。原有字符串参数重载仍可使用；Unknown 等无效枚举值会报参数错误。这里不使用部署环境 production。

• 修正邮件生效时机： 查询层把服务端传入的 UTC 或本地时间转换为北京时间后再与运营邮件的生效窗口比较，修复 WASM 服务端使用 UTC+0 时邮件生效后查不到、过期后仍可能被返回的问题。建议传 DateTime.UtcNow；如果此前用 DateTime.Now.AddHours(8) 手动补偿，升级后需去掉这段补偿。返回的 StartTime / EndTime 仍是 UTC，展示北京时间时需要转换。

• 修正全服邮件的新玩家范围： 运营后台勾选“排除新玩家”时，服务端 OperationMailRecord.IncludeNewPlayer 现在正确返回 false，GameSystemUI 收件箱也会排除邮件开始后首次进入游戏的玩家；不勾选时返回 true，邮件可对新玩家显示。API 名称不变；此前若自行对该字段取反，升级后应移除额外取反。个人邮件不受此筛选影响。

2D Spine 动画回调

使用 AnimatedSprite2D 播放 Spine 资源时，项目可以像使用 UI Spine 一样在动画开始、完成循环、结束、打断、轨道销毁和自定义事件处执行游戏逻辑；不需要为了监听事件改用 UI 控件。

• 监听世界空间 Spine 动画： AnimatedSprite2D 新增 OnStart、OnInterrupt、OnEnd、OnComplete、OnDispose 和 OnEvent 回调，回调参数复用 SpineTrackEntry 与 SpineEvent，动画播放、皮肤选择、循环和速度配置保持原有用法。
• 无订阅时不推送事件： 只有 AnimatedSprite2D 至少注册一个回调时才启用原生 Spine listener；移除最后一个回调后立即关闭 listener，未注册回调的动画不会额外产生事件跨 WASM 通信。
• 开放多轨道与骨骼操作： AnimatedSprite2D.GetSpineInstance() 返回与 UI Spine 相同的包装对象，可以使用 AnimationState 控制多轨道和混合、通过 Skeleton 操作骨骼。组件事件与 AnimationState 事件共用一条原生监听链，均无订阅时不推送事件；调用该新方法需要支持它的新版客户端。
• 修复 2D 精灵可见性检查在渲染工作线程中触发 Spine 材质和包围盒更新时，可能因资源状态变化导致崩溃的问题。此项需更新客户端或编辑器。

移动端 UI 图片使用指南

• 避免手机发布后 UI 图片处理异常： 资源指南和 AI Skill 补充了手机发布图片的压缩格式边界：项目 UI 图片在移动端通常转换为压缩纹理，即使路径仍以 .png 结尾，也不应在 Android/iOS 上直接对它调用 Image.Resize。需要不同尺寸时应在发布前预处理素材，或仅调整控件和 Canvas 的显示尺寸；确需识别设备可使用 DeviceInfo.Platform。这次仅完善使用指引，未改变图片压缩或运行时行为。

资源缓存使用说明

• 按资源类型选择刷新方式： GameGraph 文档列出 ResourceCache 常用的资源类型名，并说明 Image、Texture2D 与 GameUI 控件图片缓存的区别。开发中替换同路径普通 UI 散图时使用 GameUI.ImageCache.Invalidate(imagePath)；Spine 动画集及其 atlas 页贴图则按各自的引擎资源类型处理。文档和 AI Skill 均标明适用范围与引用仍存在时的限制；本次没有改变缓存的运行时行为。

项目自定义 Shader 编译与变体清单

项目可以把自定义 GLSL、Technique 和实际使用的 Shader 变体统一纳入编辑器编译流程，并把生成的字节码写回项目 res，避免只在某一次 PIE 中按需编译后遗漏其它平台或宏组合。

• 选择明确的质量和平台组合： 项目 Shader 预编译清单支持 RENDER_QUALITY=0（低）、1（中）、2（高）和 3（最高/自适应），以及 Editor/Windows DX11、Android ESSL、iOS Metal；不把质量 3 误当作质量 1 的起始编号。
• 保留特殊宏的扩展入口： 常用画质、SSAO 和雾选项之外，每条 VS/PS/CS 变体仍可在额外 defines 文本框中填写 CLUSTER、CLUSTER_VS、FOGOFWAR、GAMMA_IN_SHADERING 等实际宏，清单不会把当前内置候选偷偷收窄成固定白名单。
• 通过 Editor MCP 完成闭环： AI 可以使用 shader_list_sources、shader_get_plan、shader_save_plan、shader_validate_technique 和 shader_compile_project 检查源码、Technique、清单和 dry-run 编译计划；确认后再以 apply=true 原子替换项目 res/Shaders/BLGL/Compiled。
• 从日志补齐变体： shader_scan_missing_variants 可以从 Editor/客户端日志提取 Compile Shader、Failed Compile、Shader[...] Defines[...] 和 Could not find resource shaders/blgl/... 记录，帮助区分实际变体与共享 Shader include 缺失；项目资源仍按通常的 res 规则随项目打包，不需要重编官方 shadercacheextra。
• 补充使用边界： 修改 GLSL 或 include 后，如停局重进仍命中旧资源，应先重载项目；当前流程不提供运行中热更新。Technique XML 只负责选择 pass、阶段和 defines，运行时实际加载的路径仍应通过 material.probe 或 scenegraph.materials 验证。

客户端启动日志

• 在崩溃日志中核对客户端版本： 游戏日志启动时记录二进制版本、平台、运行环境、-server / -res_server 参数及实际资源更新路径。Android TapTap 内嵌包的崩溃报告附带游戏日志时，可据此核对星火客户端版本和运行环境；此项需更新客户端或内嵌包。

场景编辑器

• 配置场景导航烘焙尺寸： 3D 场景可在场景属性中启用导航烘焙配置，设置角色半径、高度、最大跨越高度和最大坡度，并恢复默认尺寸。配置保存在 GameDataScene.NavigationBake 中；修改后会提示导航产物需要重新生成，可通过“生成3D场景产物”更新。未配置的已有场景继续沿用原导航参数。该配置描述场景导航网格的最小可通行角色尺寸，不是单个运行时单位的独立代理尺寸。此项需更新编辑器。

地形编辑器

• 删除并复用项目地表纹理槽位： 在离散瓦片地形的“项目自定义地表”中选中纹理后，可以点击“删除选中纹理”。确认后纹理从列表隐藏、原槽位立即释放；下次添加项目纹理会优先复用空槽位，不重排其它地表纹理。删除无法撤销，也不会检查旧地图是否还使用该槽位；再次导入可能让旧地图上的地表显示为新纹理，请先备份项目。此项需更新编辑器资源。
• 通过 MCP 编辑场景灯光： 地形编辑器 MCP 现在可以查询、预览和创建、修改、删除地图中的点光源与聚光灯。支持位置、颜色、亮度、范围、阴影与静态标记，聚光灯还支持朝向和锥角。使用 terrain_query_lights 获取当前场景的灯光 ID，再通过 terrain_preview_light_edit / terrain_apply_light_edit 确认修改；每次有效修改可 Undo/Redo，需显式保存场景才会写入地图。灯光 ID 在场景重新加载后需重新查询；本次不包含 LightGroup 主光源和环境光设置。
• 复制放置对象唯一 ID： 地形编辑器场景树中的单位、物品以及点、线、圆形和矩形区域，现在可以通过右键菜单直接复制唯一 ID，方便在搜索、调试和数据核对时引用对应对象。

响应节点

常用的技能阶段和单位死亡响应现在有官方数编节点，用户可以直接配置响应效果，不必为这些基础事件重复定义自定义响应类型。

• 技能阶段响应： 新增 GameDataResponseAbilityStage，可按技能分类筛选，并在前摇、施法、引导（技能正式生效）和后摇开始时触发响应。
• 单位死亡响应： 新增 GameDataResponseUnitDeath，单位死亡时触发响应，并在响应上下文中提供死亡类型、死亡单位和击杀者信息。

其他修复

• 修复 Windows 客户端或编辑器退出时，尚未结束的 WebSocket 连接任务可能导致崩溃的问题。此项需更新客户端或编辑器。

• 修复编辑器内联机调试无法连接游戏服务器时，游戏画面可能保持黑屏、客户端脚本日志尚未生成且信息列表没有明确提示的问题。现在编辑器信息列表会自动显示连接失败错误、目标地址和排查建议；此项需更新编辑器，不涉及独立客户端进程。

• 修复仅服务端可用的奖励领取次数限制在云数据查询失败时可能继续发放奖励的问题。现在查询失败会拒绝本次领取，不再将查询失败视为尚未领取。

• 修复发放带领取次数限制的奖励时，同步等待云数据写入可能阻塞游戏执行的问题。领取次数改为异步写入；若写入失败，仍会记录警告，已发放的奖励不会自动回滚。

• 修复客户端 Lua HTTP 请求中，部分不支持的请求方式或网络选项设置失败，以及请求回调报错时，可能直接触发客户端进程退出的问题。现在请求配置错误返回给调用方，回调错误会记录具体信息；此项需更新客户端或编辑器，实际崩溃报告仍待新版客户端验证。

• 修复 UI 编辑器创作模式的 Inspector-first 布局回归：恢复页面结构区的“新建 Page”和结构操作入口，窄窗口下结构面板与属性 Inspector 会正确撑满可用区域，空状态提示不再被遮挡或留下无意义的大块空白。

• 支付统计语义收口： 客户端 PaymentClient.GetBalanceInfo() 与 PaymentBalanceInfo.TotalCoin 标记为已废弃；旧调用仍保留兼容路径并记录错误日志，但 TotalCoin 不再被解释为当前项目消耗。需要项目内累计消耗时，改用仅服务端可用的 PaymentServer.QueryCurrentProjectConsumptionAsync(user)，由 Host/ScoreArchive 按当前项目、当前游戏局用户和已结算订单汇总 payment_to_game.gemstone。本次不新增客户端项目消耗 API，也不提升客户端能力版本。

• 修复 UI 编辑器创作模式启动纯客户端预览时误进入旧版 Lua 游戏启动链并输出 base/base/co.lua 初始化错误的问题。现在该模式只启动 UI Authoring 所需的 Wasm GameUI；普通纯客户端调试仍保留原有 Lua 客户端脚本启动流程。

• 修复客户端触发编辑器函数分类错误，导致 as 和部分特殊操作无法在函数分类中找到、比较操作却被错误列入函数分类的问题。现在客户端函数分类与其它环境保持一致；在赋值右值、指定类型参数等有确定目标类型的位置，也能选择 as。选择 as 或泛型返回函数时，会依据目标类型自动确定返回类型，并遵守泛型约束；动态或尚未确定的目标类型不会触发自动推断。

• 修复触发编辑器导入 C# 代码时，把显式强转 (T)value 误转换为安全转换 value as T 的问题。导入后编辑和重新生成代码会保留显式强转语义，包含强转结果继续访问成员的场景。

• 修复离散瓦片地形涂抹斜坡时，部分普通斜坡交汇三角被错误归入悬崖过渡材质，导致场景中出现棕色三角纹理的问题。现在只有符合上悬崖过渡标记组合的三角才使用 Cliff2 材质；已有地形数据无需迁移。此项需更新客户端或编辑器。

• 修复触发编辑器语句选择面板中取消收藏后星标仍保持高亮、再次点击无法重新收藏的问题。星标状态与收藏分类现在会同步更新。

• 修复随机地形或场景重建后，场景树仍保留失效节点并在刷新节点排序时触发编辑器崩溃的问题。现在刷新排序前会重新校验节点仍属于当前场景树注册表，失效节点会被跳过。

• 修复客户端或编辑器退出清理阶段，图片模糊处理使用的辅助渲染路径被错误释放，可能导致崩溃的问题；Android 上可能表现为退出时内存分配器检测到非法释放并终止进程。此项需更新客户端或编辑器。

• 修复 Android 客户端在语音未初始化、初始化失败或重复清理时仍调用语音 SDK 退出接口，可能导致崩溃的问题；退出时同时停止语音轮询并清理音频回调。此项需更新客户端或 Android 内嵌包。

• 修复客户端游戏运行环境初始化失败时，记录原始错误的路径可能再次触发崩溃、掩盖初始化失败原因的问题。此项需更新客户端或编辑器。

• 修复编辑器切换场景时地表纹理风格尚未就绪，选择纹理画刷可能导致崩溃的问题。此项需更新编辑器。

• 修复地编镜头属性面板中“成像参数”控件行定义不足导致文字和输入框重叠的问题。

2026-09-16 ～ 2026-09-22（已发布至外网测试环境）

客户端能力版本

• 当前最新客户端能力版本： 5。
• 本周期是否提升： 是，从 4 提升到 5，新增 RuntimeTerrainTextureEditing，支持按场景保留离散瓦片地表运行时编辑所需数据；RelativeMouseCapture 提供桌面游戏视口的鼠标捕获与相对移动输入。视频控件复用现有客户端视频与纹理接口；离散瓦片地形自定义纹理沿用现有资源格式和 shader overlay，不单独增加能力版本。运行时地表编辑、鼠标捕获与项目视频资源寻址修复需更新对应平台客户端或编辑器。

本期重点速览

新增基础视频控件，可在界面中播放开场、教学、剧情和背景视频，并统一管理异步加载、画面比例和播放器释放。离散瓦片地形现在可以使用项目自带的地表纹理，并与内置及混合风格共同涂抹同一场景。数据编辑器新增首批蓝图 MCP，AI 可以读取画布、管理注释并定位节点，同时通过显式历史状态安全撤销或重做。UI 编辑器创作模式进一步区分属性来源、运行时结果与保存状态，并改进深层结构编辑、危险操作提示和键盘焦点。GameUI 新增项目可选的左上内容对齐默认策略和语义明确的绝对定位、相对偏移 API，新建项目模板默认采用更符合常见预期的布局起点。Urho2D 新增已知材质入口；贴图顶点颜色材质也建立了受光、无光、裁剪和混合四种固定契约，并补齐经典路径的四平台 shader 变体，同时为 PBR 增加明确的混合、裁剪和顶点色入口。Runtime MCP 现在可读取物理角色 MotorProbe 的连续服务端帧，帮助定位体素接缝、台阶和碰撞重建时的偶发着地问题。默认战斗 AI 增加目标保持与攻击间隙靠近，让远程单位在保持原有射程的同时持续追击。

视频播放与界面视频控件

• 在界面中播放项目视频： 新增 GameUI.Control.Primitive.Video 和 GameDataControlVideo，支持异步加载、播放、暂停、跳转、循环、音量、静音与播放速度配置，并提供就绪、结束、失败和状态变化事件。支持 UI.Video(...) 流式构建及 GameSystemUI 视频控件模板。
• 按界面需求适配画面： 支持等比完整显示、等比填满裁剪和拉伸。默认不自动播放，隐藏时暂停；重新显示仅恢复由隐藏策略暂停的播放。控件销毁或对局结束时释放其播放器和纹理资源。模板显式配置颜色与播放默认值，使数据编辑器显示与运行时一致。
• 保留自定义纹理用法： VideoPlayer 新增空播放器创建入口 Create()，可直接开始首次异步加载；视频帧纹理可用于自定义 Canvas 或 3D 材质。新增视频播放指南，说明资源路径、播放控制、数据配置与释放方式。
• 修复项目视频资源加载： 修复按项目相对路径加载视频时可能找不到 res/ 下文件的问题，并补齐包内和混淆视频资源供解码器读取的处理。
• 无音频输出时继续播放画面： 修复无可用音频设备或音频系统未初始化时，视频播放时间可能停滞的问题；无音轨视频同样使用计时时钟推进。
• 直接播放视频内嵌声音： 视频音轨跟随同一播放器进行暂停、跳转、变速和释放，并受视频自身音量及游戏 Master、Effect 音量影响。修复视频音轨已解码但未进入声音输出的问题，以及倍速播放后跳转可能定位到错误音频时间的问题。
• 修复跳转后的旧画面停留： 修复 Windows 视频异步跳转期间可能继续使用旧排队帧，导致声音已切换位置而画面暂时停留的问题。
• 直接运行视频播放示例： code_sample 新增 VideoPlaybackSample，附带同步闪光与短音测试片，可操作播放、暂停、跳转、循环、倍速、音量、静音和资源释放，便于验证目标设备的视频音画表现。
• 完善 iOS 视频音画协同： 由系统播放器统一管理音画时间，并补充前后台恢复与片尾重播处理，减少独立音画时钟带来的不同步风险。此项随 iOS 客户端更新生效。

第一人称鼠标捕获

• 用相对鼠标输入控制视角： 新增仅客户端可用的 GamePointerCapture，桌面游戏可请求鼠标捕获，并通过 RelativeMoved 获取累计相对位移。请求被接受后等待用户点击当前游戏画面；进入捕获的首次点击由宿主消费，不同时作为攻击或普通界面点击。
• 在游戏与菜单之间切换： 打开背包或菜单时调用 ReleaseCapture()，关闭后重新请求捕获。Esc 或失焦会释放实际捕获并等待重新点击，恢复焦点不会自动抓回鼠标；停止游戏或调试时由宿主清理。状态及变化原因可通过 State 和 StateChanged 观察。
• 按客户端能力接入： 需要能力版本 5，使用前检查 ClientRuntimeFeature.RelativeMouseCapture 并处理宿主拒绝请求的情况。移动端触屏继续使用触摸或摇杆。新增鼠标捕获指南及 code_sample 的 PointerCaptureSample，演示视角、菜单、状态与点击计数。

程序化运行时纹理

• 把运行时图片上传为 3D 纹理： 新增仅客户端可用的 Texture2D.CreateFromImage(...)，可将代码生成或修改的 Image 上传为 GPU 纹理。工厂在上传前配置 sRGB 与 mip 层数，上传失败时释放临时纹理并返回 null；过滤和寻址状态可在创建后继续设置。
• 直接创建自定义贴图 PBR 材质： 新增 MaterialPBR(Texture2D, useAlphaChannel) 构造入口，直接绑定自定义 Albedo 并补齐默认金属度/粗糙度纹理。默认 PBR 纹理按实际发布资源路径按需加载，避免首次资源缺失后一直保留空结果。
• 保持发布纹理的跨平台资源流程： 项目中发布的普通纹理继续使用 Texture2D.Load(...)，由 TextureX 容器链路选择各平台打包产物；运行时 Image 使用新工厂，RenderToTexture 继续使用 CreateRenderTarget(...)。新增运行时程序化纹理指南和 RuntimeTextureSample，同时展示 StaticMeshComponent 与 CustomGeometryComponent 绑定棋盘纹理。

P0-C：贴图、顶点色与透明模式材质闭环

程序网格现在有了明确的“贴图 × 顶点颜色”材质契约，可用于方块顶点 AO、烘焙体素亮度、树叶裁剪和玻璃混合，并避免通过修改共享 Technique 或 PBR 行为来碰运气。对应变体已进入 Editor、Windows、Android 和 iOS shadercache overlay，并用真实 Editor 对照两种程序网格路径。

• 按用途选择固定模式： 新增仅客户端可用的 MaterialVertexColor 与 VertexColorMaterialMode。LitOpaque、UnlitOpaque、LitAlphaCutout、UnlitAlphaBlend 分别表达受光/无光和不透明/裁剪/混合，切换 Mode 会整体切换固定 Technique。AlbedoTexture、ColorFactor 与顶点颜色共同决定输出，现有 MaterialPBR 行为保持不变。
• 固定 Alpha 语义： 不透明模式不启用 Alpha 混合；裁剪模式按 Albedo Alpha 决定像素去留，并让深度与阴影使用同一裁剪贴图，顶点 Alpha 不改变裁剪阈值；混合模式将贴图、顶点与材质 Alpha 相乘，使用 Alpha 混合且不写深度。
• 明确 PBR 的混合与裁剪： MaterialPBR 新增 PBRAlphaMode，可明确选择 Opaque、AlphaBlend 或 AlphaCutout。旧 useAlphaChannel: true 继续表示混合；混合读取 Albedo Alpha 且不写深度，裁剪按固定 0.5 阈值统一处理颜色、深度和阴影。
• 在 PBR 中使用体素顶点光照： 新增仅客户端可用的 MaterialPBRVertexColor 与 PBRVertexColorMaterialMode，提供不透明和 Alpha 裁剪两种固定模式。它接收 Albedo、Normal、R=粗糙度/G=金属度贴图，并将完整顶点 RGBA 乘入结果；既有 MaterialPBR 的顶点 RGB 行为保持不变。
• 提供稳定的已知 Technique 名称： KnownTechnique 与 KnownTechniquePath 新增 TexturedVertexColorLitOpaque、TexturedVertexColorUnlitOpaque、TexturedVertexColorLitAlphaCutout、TexturedVertexColorUnlitAlphaBlend。加载对应材质后会恢复为 MaterialVertexColor 及正确的模式。
• 对照两种程序网格路径： code_sample 新增 VoxelMaterialSample，以两组 2×4 矩阵对比 MeshBuilder + StaticMeshComponent 与 CustomGeometryComponent：经典材质组覆盖受光、无光、裁剪和混合，PBR 组覆盖顶点色不透明/裁剪及标准 PBR 混合/裁剪；额外的单面裁剪方块和双面十字植物用于核对剔除方式。样例同时提供材质、纹理通道、pass 与画质切换调试工具；项目发布贴图仍走 Texture2D.Load(...) 与 TextureX，运行时图片只用于生成确定性的测试输入。
• 从运行中的场景读取材质证据： scenegraph.materials 与 material.probe 现在覆盖已加载 SCE 场景、脚本 session 图和 replicated 图，并同时观察 StaticMesh 与 CustomGeometry。结果包含 StaticMesh 的 LOD0 顶点/索引布局、CustomGeometry 材质槽与顶点数、常用纹理元数据，以及实际 pass 的混合、深度、AlphaTest 和 effective defines；瞬态失效会进入有界诊断，不会中断其余结果。
• 覆盖画质与发布平台： Editor、Windows、Android 和 iOS 的 shadercache overlay 已包含经典路径实际观测到的 80 个变体，以及 PBR 路径实际观测到的 24 个变体。真实 Editor 以独立游戏局覆盖 Low、Medium、High、Ultra 与 HDR 开关，StaticMesh / CustomGeometry、PBR 不透明/裁剪、单面方块和双面十字面均正常显示，且无相关缺 shader 日志。Windows game、Android 和 iOS 已完成对应变体的离线编译与包校验，目标设备运行结果仍需分别验收。

物理角色逐帧诊断

• 读取服务端 MotorProbe 帧序列： Runtime MCP 新增 motor.snapshot。用 debug.overlay 打开 MotorProbe 后，可按 Gameplay 和 Unit 读取最近 128 个服务端物理帧，包含着地、位置、速度、胶囊参数，以及选中地面、前向阻挡、低台阶、扫掠和穿透接触，便于复现体素接缝、台阶与碰撞根替换中的偶发问题。支持按 after_physics_frame 增量轮询；切换目标、采样间隔或游戏局会清空旧缓冲。
• 区分权威帧与客户端提示： 已收到的 MotorProbe 样本直接来自服务端。首包到达前，目标缺失或未绑定物理角色只能根据客户端复制状态给出可重试提示，并明确标记为 advisory，不作为服务端最终结论。旧客户端二进制会返回能力不可用，需要更新编辑器或目标平台客户端。

Urho2D 精灵材质

• 通过代码配置精灵材质： 新增仅客户端可用的 KnownTechnique.Urho2D 与 MaterialUrho2D，支持主纹理、材质乘色、混合方式、深度测试和深度写入；KnownColorProperty.Urho2DColor 提供对应颜色参数入口。每个 MaterialUrho2D 拥有独立绘制方案，可单独调整状态。
• 控制与场景的深度关系： 默认使用 Alpha 混合、双面绘制、LessEqual 深度测试且不写深度。可将 DepthTestMode 设为 Always 忽略已有场景深度遮挡，但仍可能被后续绘制的透明对象或 UI 覆盖。
• 明确自定义材质的使用范围： 材质通过 StaticSprite2D.CustomMaterial 接入，纹理和混合方式需自行管理。动画的所有批次会共用同一自定义材质，不自动适配多图集或混合方式不同的动画部件；新增材质使用说明。

数据编辑器与蓝图 MCP

AI 现在可以直接观察和操作数据编辑器中的蓝图画布，不需要通过修改 JSON 猜测当前界面状态。画布注释、节点位置和视口属于编辑显示信息，与游戏运行时读取的 GameData 保持分离；只读查询不会创建布局数据或把项目标记为未保存。

• 查询和整理蓝图画布： 新增 data_blueprint_get_canvas_snapshot、data_blueprint_list_comments、data_blueprint_create_comment、data_blueprint_update_comment 和 data_blueprint_delete_comment，可读取画布结构并管理仅用于编辑说明的注释。快照分别返回显示布局和运行时数据引用，不把完整运行时字段混入布局结果。
• 打开并定位需要检查的内容： 新增 data_blueprint_open、data_blueprint_select_node 和 data_blueprint_zoom_to_fit，支持打开指定蓝图、选中并定位 Entry、注释或引用节点，以及缩放到全部画布内容。打开、选择和缩放只改变编辑器显示状态，不产生 Undo 事务。
• 按明确范围安全撤销： 新增通用 data_get_history、data_undo 和 data_redo。manager 范围对应蓝图文件树，table 范围对应指定蓝图内的节点、字段与画布；MCP 不依赖用户当前焦点。历史提供状态 ID、游标、已应用/可重做状态、稳定操作类型及影响对象，执行时必须携带最新 expected_state_id，状态过期会拒绝操作，避免撤销用户随后产生的新修改。
• 保持一次操作对应一次历史事务： 首次创建画布注释时，布局容器和注释会作为同一条事务处理；自动派生的引用节点不会额外占用用户 Undo 历史。一次撤销即可恢复到写入前状态，重做后继续保留相同事务身份。
• 保持自动引用节点稳定： 修复在项目中查看来自依赖库的蓝图时，已不再对应节点字段的旧自动引用节点可能被反复清理、又从依赖布局恢复，导致节点闪烁、消失或尺寸来回变化的问题。画布现在按数据层级正确记录这类布局清理；普通刷新不会重复发布未变化的节点集合，自动派生布局仍不占用用户 Undo 历史。
• 明确首批范围： 本批工具不包含自动布局、节点迁移和跨节点批处理；这些高影响操作仍由用户在数据编辑器中显式执行。
• 改善自动值字段的手动输入： 修复 Auto<T> 字段切换为手动模式后，数值输入框在窄布局中可能被遮挡的问题；移除数字上下调节按钮，输入框随剩余宽度伸缩，并保留数字校验。模式选项显示为“自动 / 手动”。此项需更新编辑器。

GameUI 布局默认策略

• 让新项目从左上角开始排布普通控件： GameDataGameUI.UseTopLeftContentAlignmentDefaults 可把之后创建控件的 HorizontalContentAlignment / VerticalContentAlignment 默认值从历史 Center/Center 切换为 Left/Top。新版项目模板创建项目自有的 UI 配置并默认开启，用户可在数据编辑器中关闭；旧项目缺少字段时继续保持居中，不会改变已有界面。显式对齐和模板值始终优先，切换配置也不会改写已经创建的控件。
• 明确区分绝对位置与相对偏移： 新增 AbsolutePosition(...) 和 RelativeOffset(...)。原有 Position(...) 保留“只改坐标、不改变 PositionType”的底层语义；代码分析器会提示定位模式不明确的 Position(...) 调用和只设置 Position 的控件初始化器，帮助 AI 与开发者避免把相对偏移误写成父容器坐标。

UI 编辑器创作模式

UI 编辑器创作模式进一步整理属性、结构和持久化信息，让用户在真实界面预览中更容易判断当前编辑的是哪个控件、值来自哪里，以及操作是否已经提交或保存。现有独立预览窗体继续保留，常用编辑流程无需依赖横向滚动或底部状态小字。

• 辨认属性值及其来源： Inspector 优先使用面向用户的字段显示名，并区分本地值、继承值、类型或运行时默认值、显式 null、无法解析的字段、运行时计算值和暂未提供运行时映射的字段。Local、Inherited、Effective、Runtime 各层含义保持独立；可编辑字段会提示提交后是修改现有本地值还是创建本地覆盖。
• 保持当前控件与工作上下文可见： 当前选择、源定义和属性筛选在 Inspector 滚动时保持可见；树节点补充控件类型、源数据及只读状态，同名节点可通过结构路径、源定义和运行时标识进一步辨认。添加、复制、删除、排序或调整父级后，已有深层展开分支与滚动上下文会尽量保留，新节点会展开父链并定位到可见区域。
• 明确命令、预览与保存状态： 顶部命令按结构、布局、历史与文件、危险操作分组，并提供“显示当前预览”与当前预览状态。界面会区分运行时预览、已提交到数据、未保存、正在保存和已保存；重载、删除引用或删除 Page 前会显示目标、影响范围、能否撤销及保存语义，目标在确认期间变化时不会继续执行。
• 完善布局输入与键盘操作： Layout 输入显示像素单位、有限数字范围以及“自动 / 手动”、Relative / Absolute 的关系，并在输入位置提示错误。属性输入补充可访问名称和清晰的键盘焦点环；窄窗口使用纵向工作流，宽窗口保持树与 Inspector 双栏。以上改进需要更新编辑器。
• 补齐虚拟化面板创建： 修复 UI 编辑器创作模式的控件类型列表缺少 VirtualizingPanel，以及从数据定义创建时误返回普通滚动面板的问题。现在可以直接创建虚拟化面板并保留其列表虚拟化配置；此项需更新 WasiCore 运行时产物和编辑器。

场景素材与项目资源

• 修复动作资源路径复制： 修复资源素材库动作页右键菜单中“复制路径到剪贴板”未能写入所选动作资源路径的问题。
• 修复 MCP 放置项目模型的路径前缀： 修复通过场景 MCP 放置或散布项目模型时，可能把资源目录路径中的 res/ 前缀带入场景引用的问题。放置路径与资源 ID 现在按同一引擎相对路径生成；更新编辑器后需重新查询装饰物资源目录获取 ID。对于此前保存的多余前缀，加载和保存时会在确认当前项目中对应文件存在后纠正，并保留真正位于 res/res/ 子目录中的资源引用。
• 从项目目录选择可放置素材： 场景编辑器素材页签的“项目资源”按本地 res 目录展示模型 .prefab 与标准粒子入口 particle.effect，不再依赖线上分类登记，也不把原始 FBX、mdl、贴图和材质等辅助文件混入放置列表。独立资源查看器继续保留全文件浏览。
• 保持场景资源引用可迁移： 修复从项目本地目录拖入素材时，场景可能保存本机绝对路径的问题。拖拽、单资源笔刷与组合笔刷使用项目 res 相对路径；加载和保存时，对当前项目 res 内仍存在的文件补充路径规范化。历史引用随正常场景保存更新，项目外路径和旧机器上的失效路径不自动猜测转换。此项需更新编辑器。
• 沿用素材名称： 项目文件列表和 MCP 资源目录优先使用项目记录中的显示名，其次读取可解析 prefab 携带的名称；缺少名称时，model.prefab、particle.effect 使用所属文件夹名，避免列表和新放置对象都叫统一文件名。名称仅用于展示与搜索，不改变文件名或资源引用；已有场景对象不批量改名。
• 移除不可用的单位自动生成入口： 素材页签移除“自动生成单位”开关及旧创建逻辑。素材仍可作为装饰物放置，单位通过数据编辑器和单位页签创建、配置与放置。
• 完善 AI 资源选择指引： 资源选择 Skill 补充显示名优先级、项目相对路径、本地 FBX 批量导入和场景素材筛选边界，帮助 AI 区分资源名称、浏览路径与实际引用路径。

离散瓦片地形自定义纹理

项目现在可以把准备好的地表纹理资源直接加入离散瓦片地形目录，不再局限于编辑器内置素材。同一场景可以同时使用内置风格、混合风格和项目自定义风格；实现沿用既有客户端资源格式，避免为素材扩展引入新的客户端二进制接口。

• 从颜色图片生成项目地表： 在地表面板选择模板和最终 UV 角度，再通过“添加项目纹理”选择颜色图片。编辑器会优先直接采用同目录或显式指定的 packed _mix；否则自动发现 normal、roughness、metallic 并合成四通道 mix，缺失通道沿用模板。支持 normal G 保持或翻转，多个候选不会静默猜测。旋转默认 90° 以适配默认镜头方向，也可选择 0°、180° 或 270°，不会叠加模板隐藏角度。最终仍创建自包含源 Material、完整目录覆盖、96层纹理数组和九套地形 Material。此项需更新编辑器。
• 在地编中使用和更新项目纹理： 生成后的项目风格会加入“地表风格”列表，可正常涂抹、撤销重做、保存、重载和进入调试运行。首次添加成功后才会显示“生成/更新资源”，用于在手工调整项目 TextureStyle 或源 Material 后重建最终产物；尚未添加时的内置目录不需要生成。切换项目时目录会按当前项目重建，不会保留上一个项目的自定义项。
• 通过 MCP 安全导入和重建： 新增项目地表纹理导入与资源重建的 Preview/Apply 工具，以及异步状态查询和等待入口。导入 Preview 固定颜色图片 SHA256、模板纹理 ID、剩余槽位和地形文档状态；Apply 在写入前重新校验，且不会把内部 Material 路径暴露为用户参数。
• 保持现有场景索引稳定： 自定义风格只允许在现有目录末尾追加，并复用已有 TileSet；已写入场景的风格和纹理槽位不能重排或复用。当前目录最多 16 个风格、每个风格 16 个连续槽位，发布资源固定补齐到 96 个 Material 层。
• 沿用旧客户端资源契约： 本功能不增加客户端能力版本；目标环境需要下载对应平台的96层 shader overlay。自动发现和通道合成只生成既有 packed mix 格式，不改变客户端 shader 输入；当前仍不包含文件热重载、自定义悬崖、道路、装饰物或槽位压缩。
• 提供完整配置说明： 新增离散瓦片地形自定义地表纹理指南和配套 AI Skill，覆盖目录结构、固定槽位、数组顺序、兼容边界、编辑器校验及常见错误。

按场景启用运行时地表编辑

• 为动态地表保留必要数据： GameDataScene 新增 EnableRuntimeTerrainTextureEditing，默认关闭。需要在游戏中改变局部地表纹理或混合权重的场景，可在加载前开启，使用 SceneTerrainController.SetTextureWeights(...) 修改，并在批量写入后统一刷新。
• 从场景属性开启动态地表： 场景编辑器右侧属性面板新增“允许运行时修改地表纹理”开关，直接写入对应场景配置，并提示内存成本和生效时机。选项仅在离散瓦片场景显示，需更新编辑器；保存后重新加载运行时场景或重新进入调试即可生效。
• 按需承担内存成本： 开启后保留纹理权重、地形重建及相关烘焙光照恢复数据；未开启的普通场景继续释放这些缓存。数据随场景实例或显式场景缓存释放，运行中修改配置不会恢复已释放的数据。
• 明确运行边界： 此能力仅影响当前客户端的离散瓦片地表表现，不自动同步其他玩家或写回地图，也不包含高度和拓扑编辑。需要客户端能力版本 5；项目可通过 RuntimeTerrainTextureEditing 判断支持情况。
• 通过完整示例学习动态地表： code_sample 新增 RuntimeTerrainTextureSample，附带独立场景，可操作纹理替换、不同配比的混合、三纹理渐变、柔和圆形笔刷、扩散动画和原貌恢复。示例仅为自身场景开启运行时编辑缓存，并显示采样点写入与回读结果；场景环境文档和 AI Skill 同步补充纹理组映射、完整权重快照、批量刷新与生命周期管理说明。

触发编辑器

• 修复异常捕获代码生成： 修复 try/catch 将异常类型的中文显示名写入代码，生成 catch (异常 e) 等内容并导致编译失败的问题。现在按真实类型名称及命名空间生成异常捕获代码，同时支持自定义异常类型；更新编辑器后重新生成触发器代码即可生效。
• 恢复集合初始化构造器： 修复触发器中使用面向过程调用创建 List<T>、HashSet<T> 和 Dictionary<TKey, TValue> 时集合初始化器不显示的问题。无参集合构造函数现在可以直接编辑初始化项，UiText 中的 {init} 标记也继续生效。
• 保留面向对象方法的完整重载： 修复从控件等派生对象选择继承方法时，同一父类中后遍历到的重载可能被误判为已隐藏的问题；例如控件的无参“销毁”现在会与“销毁（兼容）”正确显示。
• 避免打开项目后触发器选择面板卡住： 修复类型、触发器选择数据与收藏、最近使用记录并行初始化时可能发生异常的问题；初始化过程现在按顺序完成，失败时会及时结束等待并记录具体原因。

AI 系统

• 为不同单位独立配置搜敌范围： GameDataAIThinkTree 新增仅服务端可用的 ScanRange 公式，可按单位、等级或战斗状态计算搜敌距离，不再必须复用攻击范围。该范围同时用于战斗外发现敌人、行为树扫描节点未指定 Range 时的战斗内搜敌，以及 Hunt 模式切换到战术 AI 的交接距离；未配置时保持原有按攻击范围和 WaveAI 扫描上下限计算的行为。
• 让远程单位在攻击间隙主动靠近： GameSparkCore 默认战斗 AI 与战斗思考模板改为优先施放已就绪且射程内的技能，其余时间按距离接近目标。默认靠近到主攻击射程的 70%，超过 77% 时重新起步，距离判定包含双方交互半径；技能射程保持不变。新增 GameDataAINodeValidateCombatMove 节点，可配置距离公式、比例、启停缓冲，或关闭主动靠近。
• 让交战目标短暂离开搜敌圈后仍可追击： 扫描节点新增 RetainTarget 与 RetentionRange，默认树优先保持合法目标，保持距离默认为搜敌距离的 1.5 倍，不扩大新目标的发现范围。目标死亡、不可见、过滤条件不符或越过追击边界时释放；没有移动组件的单位最多保持到搜敌距离。
• 保护攻击动作并按就绪状态决策： 施法节点新增 OnlyWhenReady，可在技能冷却或目标超出射程时转入行为树的其他分支；GameDataAIThinkTree.PreserveAcquiredCasting 可保护自动重施法的前摇及后续施法阶段，并在此期间维持战斗计时。这些选项由默认战斗树启用，既有自定义树保持原有默认行为。
• 按默认标签或自定义公式选择目标： 搜索节点未配置 TargetSorts 时使用树上的 ScanSorts 标签优先级；显式空列表表示不排序，自定义公式则完全接管，可自行读取标签配置决定组合顺序。GameSparkCore 默认战斗树与模板新增可编辑的目标排序公式，显式按标签优先级、再按距离选敌；没有标签优先级时选最近目标，已保持的合法目标不会因出现更优候选而自动切换。
• 修复 AIThinkTree.MoveTo(target, range) 未将指定停止距离传入移动指令的问题，使移动到目标附近的行为按配置距离停止。

其他修复

• 修复界面绘制资源释放或重新加载后，继续使用失效着色器缓存时可能崩溃的问题。此项需更新客户端或编辑器。
• 修复游戏退出后仍存留的界面在查找图片时，可能访问已释放的资源路径数据并崩溃的问题；已缓存图片、绝对路径图片及其他有效图片查找来源仍可使用。此项需更新客户端或编辑器。
• 补充渲染路径切换时的资源生命周期保护，修复视口更换渲染路径后，本帧继续使用旧路径时可能崩溃的问题。此项需更新客户端或编辑器。
• 修复 Canvas 图片回收、重新加载后，部分图片或图标可能批量变白的问题；图片不可用时跳过对应绘制，并保留正常的图片资源回收。此项需更新客户端。仍需支持旧客户端的项目可参考旧客户端图片缓存预算 Skill，按实际设备评估临时规避及内存代价。
• 修复调试时误下载依赖资源的问题： 修复普通调试、纯客户端调试、大厅调试及移动端仿真中，依赖资源可能被下载为客户端或移动端版本，覆盖编辑器所需模板和数据的问题。各调试入口统一按编辑器资源身份和对应 API 版本检查更新，并保留编辑器依赖文件的大小写；纯客户端调试同时继承显式禁用更新的设置。此项需更新编辑器及其更新脚本。
• 修复 iOS 内嵌游戏启动或运行期间，查询已安装游戏大小、卸载游戏或清理日志可能干扰正在使用的网络请求与定时器，进而导致崩溃的问题；相关操作统一检查引擎运行状态，并与引擎启动、退出协调执行。此项随 iOS 客户端更新生效。
• 修复异步网络请求结束时，日志或回调可能在所属脚本模块销毁后继续访问已释放对象，导致客户端崩溃的问题。此项需更新客户端。
• 修复界面控件脱离父级后，后续布局更新或子控件移除可能访问已释放父级，导致客户端崩溃的问题。此项需更新客户端。
• 修复界面更新回调中删除或注销控件时，更新循环可能继续访问失效控件，导致客户端崩溃的问题。此项需更新客户端。
• 防止跨用户云数据事务漏掉操作： 使用 CloudData.ForUsers(...).ForUser(...) 为不同用户配置操作时，如果指定的 userId 未包含在最初声明的用户集合中，现在会立即返回明确的参数错误，避免交易、资产转移等单次提交因漏列用户而静默跳过该用户操作。云数据指南与 AI Skill 同步说明了 ForAllUsers(...) 的同操作批处理、ForUser(...) 的分用户操作，以及 ExecuteAllAsync() 和 ExecuteSingleCommitAsync() 的提交语义。
• 完善跨设备界面适配指引： screen-viewport-resolution Skill 增加部分移动设备 UI 错位的审计流程，明确以 GameDataGameUI 作为设计分辨率的单一配置来源，避免从物理像素重建逻辑视口或反复改写全局设计分辨率，并补充几何与字号同尺度、安全区、事件入口和正常/异常设备对照采集要求。
• 修复部分 Android 横屏界面按竖屏缩放的问题： 当平台方向枚举仍停留在竖屏、但实际渲染 Surface 已是横屏时，ScreenViewport 现在先按 drawable 长短边纠正当前主方向，再计算设计分辨率与设备像素比，避免界面按竖屏基准缩放。WasiCore 托管依赖更新即可获得这层纠正；更新客户端后，如果实际 Surface 在首次转屏后仍与游戏方向不一致，运行时还会有界重试一次，并直接按 Android Display 旋转读取刘海安全区。方向与 Surface 一致的设备及正方形 Surface 保持原行为，不提升客户端能力版本。
• 修复界面控件快速销毁时的渲染崩溃： 控件创建后很快移除或销毁时，渲染缓存不再继续访问已经释放的控件；缓存节点失效后会放弃本帧复用，并在后续帧重新收集界面绘制数据。
• 降低编辑器调试同步大文本时的内存风险： 修复较大文本文件进行差异计算时内存占用过高并可能崩溃的问题；预计工作内存超过安全预算时，编辑器改为直接同步完整文件。
• 修复部分 Android 云手机或模拟器启动游戏脚本时可能崩溃的问题： 当运行环境限制脚本运行所需的系统能力时，客户端会在启动脚本前安全识别并切换到兼容执行方式，避免能力检测本身触发退出；不受限制的设备继续使用原有高性能路径。该修复仅影响 Android ARM64，不改变 Windows、iOS 或服务端的运行方式。
• 修复富文本自定义标签在 Lua 重启后退出时的崩溃： 控件或页面销毁、Lua 状态关闭并重新创建后，旧标签回调不会再访问失效的 Lua 状态；仍有效的回调行为保持不变。
• 修复 CanvasTexture* 系列接口在带布局包装层的画布上误把包装元素当作实际画布，导致设置纹理、填充像素或压缩数据时崩溃。
• 修复 D3D11 状态对象创建失败后将空对象放入缓存，以及缓冲区 Map、临时缓冲创建失败后仍继续访问的问题。
• 修复纹理图片分配失败后继续解引用，以及对局对象晚于 ResourceCache 销毁时重复访问资源缓存的问题。
• 修复 KCP 网络事件队列在跨线程回收节点时可能访问失效节点的问题，改用受互斥保护的事件队列。

2026-09-09 ～ 2026-09-15（已发布至线上正式环境）

客户端能力版本

• 当前最新客户端能力版本： 4。
• 本周期是否提升： 否。本期不新增需要项目主动判断的客户端能力。资源浏览、批量 FBX 导入和数据编辑改进需要更新编辑器；客户端底层稳定性修复随对应平台客户端版本更新生效。

本期重点速览

本期重点完善项目本地资源工作流：复制到项目 res、ui 的文件可以直接浏览，多个 FBX 可以交给 AI 批量导入。数据编辑器统一时间输入并修正跨地区数据解析，物品栏可明确配置销毁时移除或掉落内容物品；同时补充框架选型与 GameGraph 桥接指南，并修复旧客户端兼容、模型切换和资源加载等问题。

项目资源：复制文件即可浏览

从外部工具或 AI 获得素材后，可以直接复制到项目目录，再到美术资源库中查看、预览和复制引用路径。项目资源列表按实际文件组织，减少素材登记与文件管理之间的重复操作。

• 直接浏览项目文件： 美术资源库的“项目资源”默认显示 res、ui 文件目录，支持任意子目录中直接复制的文件，无需先通过导入工具登记或匹配线上素材归属。可刷新目录、复制资源路径并打开文件位置；支持的资源沿用现有预览，FBX 源文件及暂无预览的格式仍可查看文件信息。
• 辨认文件类型并筛选可预览资源： 没有缩略图的文件卡片显示 .xml、.fbx、.material 等扩展名，无扩展名文件显示 FILE。新增默认关闭的“只显示可预览文件”筛选，保留目录树，也保留没有缩略图但支持模型预览的预制件；筛选无结果时会提示切回全部文件。
• 连续浏览不被提示框打断： 选中暂不支持预览的文件时，右侧直接显示文件类型、完整项目相对路径和说明，替代反复弹出的提示框；FBX 源文件会显示转换提示。
• 修复项目图片加载： 修复直接复制到项目 res、ui 的图片因路径处理错误而无法显示缩略图的问题，并为支持的项目图片提供右侧独立预览区域。

通过 AI 批量导入 FBX

需要转换格式的模型和动画，可以由 AI 一次处理多个文件，先检查目标路径，再导入到当前项目，适合批量生成素材后的集中整理。

• 批量转换模型与动画： 新增编辑器 MCP 工具 resource_import_fbx_batch，将多个本机 FBX 转换到当前项目 res 目录。支持模型及其材质、贴图和可导出的内嵌动画，也支持单独导入动画与 Unity3D 导入规格；导入前可预览目标路径，执行后可查看逐文件结果。
• 保留已有资源并处理部分失败： 默认跳过已有目标，可配置遇到错误后继续处理其它文件。取消在文件之间生效；单个大型 FBX 转换期间仍可能占用编辑器线程。当前批量入口面向项目本地，不包含云端批量上传。
• 修正本地导入边界问题： 修复项目位于多层资源目录下时，FBX 产物引用可能生成到错误路径的问题；补充部分产物写入失败检测，并修复加密 FBX 可能让导入流程等待控制台输入的问题。

反馈与问题诊断

• 提交反馈时一并上传应用日志： 用户在 TapTap 容器中提交反馈问题时，系统会同时上传当前应用日志，便于根据反馈内容定位运行问题。

数据编辑器：时间输入与跨地区数据解析

持续时间和重复行为的时间配置采用一致的输入方式，同一份项目数据在不同系统区域设置下也按统一格式读取，减少时间含义和小数解析不一致带来的问题。

• 用时间选择器编辑重复时长： 重复行为的“持续时间”模式改用时间选择器，可编辑小时、分钟、秒和毫秒，并通过确认按钮提交；简体中文界面补齐时间单位与确认按钮文案。
• 统一时间简写含义： 时间输入支持纯数字秒数以及 分:秒、时:分:秒 等格式，例如 00:03 表示 3 秒；时间字段和重复时长共用解析规则，修正简写在不同入口被解释为不同长度的问题。
• 修复不同地区设置下的数据读取： 数值、时间、数据路径索引及代码生成中的相关解析改用固定数据格式，修复更换系统区域设置后，同一份数据可能解析失败或读成错误数值的问题。时间输入仍可按当前地区习惯接收小数，保存为统一格式。

物品栏销毁时的内容处理

单位或物品栏销毁时，可以明确决定内容物品随之移除，还是掉落到携带者最后所在的位置。该策略用于销毁时的清理，适合角色离场、召唤物消失或掉落战利品等场景。

• 默认移除内容物品： GameDataInventory 新增 ContentsDispositionOnDestroy，默认值 InventoryContentsDisposition.Remove 会将内容物品从游戏中移除，适合角色离场、召唤物销毁等常规清理流程。
• 按需掉落到销毁前位置： 将策略设为 InventoryContentsDisposition.DropToGround 后，内容物品会掉落到携带者销毁前的位置；该生命周期策略不受面向玩家主动操作的 AllowDrop 限制。
• 保留销毁后的位姿信息： 单位会在清理物品栏及其它附属对象前保存最后的位置和朝向，修复了销毁携带物品的单位时，掉落流程可能读取到未初始化场景位置并报错的问题。

开发指南与 AI 辅助开发

本次补充面向不同开发经验的阅读入口，以及单位、表现、场景与底层节点的桥接参考，帮助用户和 AI 按具体玩法组合现成系统与引擎能力。

• 从熟悉的经验开始： 新增理解星火：从地图编辑器到游戏引擎，供有暴雪地图编辑器、星火 1.0 或 Unity / Urho 经验的用户迁移知识；零基础用户仍从快速开始和一个可玩的目标起步，无需先学习完整架构。
• 在现有项目中扩展节点与组件能力： 新增单位、表现、场景与 GameGraph 的桥接，集中说明下钻入口、组件查找、单位绑定、客户端与服务端语义，以及状态控制和生命周期归属。
• 让 AI 按玩法需求组合能力： 更新开发与架构 AI 技能，并接入项目 AI 上下文模板。指引要求按功能选型、保留合适的数据和触发器结构，根据用户经验调整解释，并说明影响联网和后续编辑方式的关键假设。
• 复用 Urho 知识编写 GameGraph 代码： 在 GameGraph 总览和相关 AI 技能中补充 GameGraph 与 Urho 的关系说明：GameGraph 将星火所用 Urho 引擎的常用 API 导出并封装为 C# 接口，再补充星火能力与 GameCore 桥接。AI 可据 Urho 知识提出方案，再以当前 SDK 核对可用接口、运行端和星火行为差异。
• 按效果需求选择光束实现方式： 补充 Actor 表现系统与 GameGraph 音频与粒子中的光束指南，说明使用 ActorBeam 跟随目标，以及通过 GameGraph 更新粒子端点的适用场景和对象生命周期。
• 修正单位动画下钻示例： 修正骨骼动画和模型动画文档中通过 unit.GetActor() 转换为 ActorModel 的错误写法；示例改为利用 Unit 自身的动画接口直接访问模型与动画控制器，并说明节点或组件缺失时的处理。

运行时兼容与稳定性修复

本期补齐旧客户端使用新版依赖时的初始化兼容，并修复对象销毁、切换模型和加载不完整资源时的若干异常路径。框架修复随依赖更新提供，客户端底层修复需更新对应平台客户端。

• 修复旧客户端初始化与大厅调用失败： 修复旧客户端使用新版依赖时，初始化 UI、读取运行环境或调用既有大厅开局接口可能因缺少新接口而触发类型加载或方法缺失错误的问题。项目主动调用新客户端 API 时，仍需按该 API 要求判断客户端能力。
• 兼容旧运行时与已编译项目： 补齐客户端热更新依赖对旧 WASI 运行时中 MemoryMarshal 引用的兼容处理，并保留旧程序集使用的 UI 位置初始化设置接口，修复部分组合下的类型加载或方法缺失问题。
• 跳过已经停用的分帧更新对象： 修复分帧更新队列中的对象在同一轮处理期间停用或销毁后，仍可能被继续调用的问题。
• 修复切换模型时的动画回调异常： 修复在动画事件回调中替换模型后，旧动画状态或事件列表仍可能被继续访问并导致崩溃的问题。
• 修复模型、贴图和地图数据加载失败时的异常： 修复资源读取、内存分配或地图数据表加载失败后，仍继续访问无效数据并可能崩溃的问题；同时补充单骨骼模型处理时的顶点与骨骼数据校验。
• 修复退局与重连时的失效引用： 修复游戏局结束后，图片查找仍可能访问已释放的资源查找对象，以及重连回调可能进入已销毁脚本状态的问题。
• 修正多音效并发时的优先级排序： 修复多个音效竞争播放名额时，排序依据随播放进度变化或比较结果不一致的问题，使限额筛选与播放名额恢复使用稳定的排序规则。
• 修复 Android 运行中的若干异常路径： 修复登录回调晚于客户端退出、读取安装包资源时对象缺失、输入设备信息缺失，以及调整画面尺寸时访问失效窗口可能引发异常的问题；修正部分设备初始化时的 OpenGL ES 函数加载路径。上述修复随 Android 客户端更新生效。

2026-09-02 ～ 2026-09-08（已发布至线上正式环境）

本期重点速览

本期围绕“更稳定地运行和排查 2.0 项目”整理了几条主要工作流：2.0 大厅暂时收敛为充值入口，避免旧模块误启动装备局；WASI Mono 的客户端、服务端日志获得独立保存和按需同步；数据编辑器、地编属性面板以及模型导入、资源定位和材质配置等创作能力进一步开放；编辑器依赖包修复工具则把缺包、错包和历史缓存问题收敛到可诊断、可恢复的流程中。上述变化不新增需要项目主动判断的客户端能力，客户端能力版本仍为 4。

客户端能力版本

• 当前最新客户端能力版本： 4。
• 本周期是否提升： 否。本周期的编辑器、运行时日志、数据编辑和稳定性修复不新增需要项目主动判断的客户端能力。

2.0 大厅与充值入口

2.0 项目暂不使用面向 1.0 的商店、装备、任务等大厅模块，避免旧模块在大厅启动或点击时进入装备局并执行普通游戏初始化。充值入口继续保留，用户可以直接在大厅局打开充值页面。

• 暂时仅保留充值模块： 对 api_version >= 2000 的项目，后台“游戏模块配置”只展示并允许配置 payment；旧模块不会因默认配置自动补入，也不能通过新增、编辑、显示/隐藏或删除操作重新启用。
• 阻止旧模块带入装备局： 大厅运行时忽略 2.0 项目的旧模块和签到开关，不再预加载装备局。充值继续通过 open_pay_ui 打开充值页面，不启动装备局。

WASI 运行时兼容

新版 AppBundle 补齐了 .NET 运行时的类型转发契约，避免部分由 .NET 9 SDK 生成的客户端代码在首次加载时因找不到 System.Runtime.InteropServices.MemoryMarshal 而抛出 TypeLoadException。同时，新建项目模板不再拦截常用字符串组合 API，既有项目也可以按需移除对应规则。

• 恢复常用字符串组合 API： 新建项目模板不再禁止 System.String.Join(string, params string[]) 和 System.String.Concat(params string[])。使用新版 AppBundle 的既有项目也可以从 BannedSymbols.txt 中移除对应规则，直接使用这两个 API。

WASI/Mono 运行时日志

WASI Mono 的错误诊断不再依赖启动它的控制台，而是统一从 stderr 采集并与普通脚本日志分开保存。客户端和服务端都可以保留独立诊断文件；只有 PIE 调试且已有其它脚本远程日志时，服务端才会按帧把新增 Mono 日志同步到编辑器，普通线上运行不会建立这条编辑器通知链路。

• 客户端保留独立诊断文件： Mono 的 stderr 写入 logs/client 下的独立日志文件，不再复制到普通脚本日志或编辑器调试信息面板；该文件会随客户端 Themis 日志一起上传。
• 服务端保留独立局日志： Mono 的 stderr 写入服务端游戏局目录中的 mono.log.txt，与脚本日志分开。后台开局日志下载支持 mono 日志通道，用户可以单独下载该文件。
• PIE 按需同步服务端日志： PIE 调试时，只有当前帧已经存在其它脚本远程日志，服务端才会把本帧新增 Mono 日志批量通知编辑器；普通发布运行不会建立这条编辑器通知路径。
• 移除无用调试输出： 删除 Mono 类名查询路径中遗留的 mono_class_from_name 控制台调试打印。

客户端调试与录像

项目调试时，非录像状态下不需要把用于回放 UI 操作的鼠标和键盘事件上传到服务端。现在只有实际录制录像时才保留这类上传，脚本侧键盘事件以及点击后产生的移动、攻击等玩法请求不受影响。

• 减少非录像调试流量： 未开启录像时，客户端不再发送 REPLAY_MOUSE_EVENT 和 REPLAY_KEYBOARD_EVENT；正在录制录像时仍会记录并上传回放事件。
• 修复编辑器内调试的 Spine 资源加载： 修复在编辑器内调试时，AnimationSet2D.Load() 可能跳过当前项目 ui/spine 目录、导致 Spine 素材加载失败的问题；素材位于 ui/spine/hero/hero.skel 时，仍使用 "spine/hero/hero.skel" 加载，配套 atlas 和贴图也会从项目 UI 目录查找。

数据编辑器

数据编辑器现在可以直接预览表现节点引用的模型、音效和粒子资源，并在依赖库不完整时给出可定位的诊断。这样既能在编辑数据时确认实际表现，也能区分“数据为空”和“编辑器模板缺失”两类问题；正常加载路径不会因此增加全量资源扫描。

• 预览表现节点引用的素材： Blazor 数据编辑器支持 GameDataActorModel、GameDataActorSound 和 GameDataActorParticle 的选中预览。音效预览提供播放/停止控制，并在自然播放结束后自动恢复为可播放状态；粒子预览保持无地面、无额外镜头调试信息的干净画面。
• 提示缺少编辑器模板： 当已存在的数据条目无法解析 meta type、类型信息或运行时类型时，编辑器会写入包含条目路径、所属库和类型信息的错误日志，提示重新下载对应依赖的 windows_editor 资源包；编辑器仍会跳过失效条目并继续加载其余数据。
• 补齐 GameSparkCore 表现节点模板默认值： 为各类 GameDataActorXXX 提供可直接复用的模板，并把运行时常用默认值显式写入数据表，避免属性未修改时在数据编辑器中显示为 0、false 而与实际行为不一致。音效表现模板默认 ForceOneShot=true、KillOnFinish=true 并播放一次，空间音效的最大衰减距离为 5000、衰减系数为 4；音乐表现模板默认保持循环播放，创建后由项目主动停止。
• 精简单位节点字段： GameDataUnit 节点不再显示 Properties、VitalProperties、AttackableRadius 和 CollisionRadius，减少单位节点的纵向长度；这些配置仍可在属性面板中正常编辑。

地编对象属性面板

地编对象的属性面板补齐了更多与 1.0 Lua 编辑器一致的常用配置，减少在新旧编辑器之间切换时找不到参数的问题。光源、氛围和装饰物等对象现在可以直接查看并编辑主要显示、光照、雾效、体积光、阴影和距离配置；对象名称、描述及编组信息也能在面板中维护。颜色类参数统一使用颜色选择器，氛围环境贴图和水反射贴图暂时保留资源逻辑路径手填，避免与 UI 图片资源目录混用。

• 补齐光源配置： 支持光源颜色、亮度、范围、圆锥角、静态/阴影开关、光度单位、体积光散射与吸收等常用属性。
• 新增锥形光创建能力： 地编右侧“灯光”创建面板新增“锥形光”入口，可以直接创建具有方向和圆锥照射范围的光源。
• 补齐氛围配置： 支持环境光和雾颜色、主光及天气光参数、深度雾/高度雾、环境贴图强度、全局粗糙度、角色球谐、Bloom、水反射和 Vignette 等属性。
• 补齐装饰物与编组配置： 支持装饰物阴影、相机遮挡、烘焙、描边和显示/阴影距离，以及编组名称和通用变换编辑。
• 让场景尺寸调整一次生效： 修复在地编右侧场景属性面板中，刚输入 X/Y 尺寸后立即点击“立即调整地形尺寸”时，首次点击可能仍使用旧值的问题；按钮现在会先提交当前输入，再调整地形并同步场景数据，同时避免编辑器自身保存场景数据时被识别为外部 JSON 修改并提示重载整个项目。
• 修复线和区域坐标异常： 修复编辑项目时线、矩形区域和圆形区域可能整体移动到原点的问题；切换场景前会先保存当前 native 场景中的区域状态，回到已打开过的场景时重新加载最新区域数据，避免旧坐标快照或失效场景树节点覆盖当前编辑结果。
• 保证装饰物保存一致： 删除或调整装饰物后，普通保存和地形 MCP 保存会等待延迟加载的装饰物完成写入；如果场景装饰物快照写入失败，保存会明确报告失败并保留未保存状态，避免重新打开场景时恢复旧装饰物。

地编与资源创作工作流

本期将几项此前未向普通用户提供的编辑能力正式加入编辑器，用于检查场景性能、控制模型导入规则、追踪项目资源来源和调整材质表现。相关入口面向正常项目编辑流程开放，不要求额外启动参数。

• 查看地形与粒子 LOD： 地形编辑器的辅助信息中可以显示网格 LOD，场景预览也可以固定粒子 LOD，便于对照不同设备档位检查表现。
• 查看场景统计数据： “工具 → 数据统计”现在可直接打开场景统计窗口，辅助定位场景规模和资源使用情况。
• 使用 Unity3D 规格导入模型和动画： 模型与动画导入窗口支持按 Unity3D 的 Y 轴向上、左手坐标系和米制规格转换 FBX；模型与独立动画应保持相同选择。编辑器会记住新导入资源的规格，后续更新模型或重新导入动画时继续使用，避免朝向、骨骼姿势或动作幅度发生变化。该选项只处理 FBX 坐标系与单位，不转换 Unity 材质、Shader、Prefab 或 .meta 数据；完整适用范围见 WasiCore 3D 坐标系统指南。
• 定位项目资源文件： 项目资源属性面板显示项目内资源在当前项目 res 目录中的实际路径，并提供“在资源管理器中打开”；官方缓存资源仍不显示本地缓存路径。
• 调整材质高级表现： 项目材质可配置双面显示、背面接收光照、深度偏移、半透明、透明混合模式、透明深度写入、Shader 宏和运行时染色等属性；不可编辑的材质仍保持只读状态。
• 复制资源逻辑路径： 资源库中的动作、模型、特效、贴图、瓦片、氛围、音效、图标和材质条目均可通过右键菜单将逻辑路径复制到剪贴板，便于填写资源配置或提交给 AI 排查。

编辑器依赖包修复

编辑器依赖包下载不完整或变体错误时，可能表现为项目配置名称不匹配、数据模板或场景列表缺失、触发编辑器没有官方 API、官方系统 UI 控件消失，或者地形编辑器中的镜头和灯光指示器图标缺失。现在可以通过随当前 API 版本编辑器发布的独立工具检查本地版本记录和缓存，并让更新器重新下载指定包，无需手工查找和删除资源目录。

• 安全重置常见依赖包： 新增 WinUI 工具 SCEPackageRepair.exe 和命令行工具 SCEPackageRepair.Cli.exe，支持检查及重置 editor_bcd、global_default、gamesparkcore、gamesystemui、lib_game_options、wasicoresdk。工具只接受 editor-*.spark.xd.com 编辑器渠道，不会把客户端 e.* 目录当作编辑器来源；操作会限制可操作的包和路径、在修改前备份 VERSION.JSON，并在编辑器或更新相关进程仍运行时拒绝写操作；editor_bcd 仅清除版本记录，不删除当前渠道的 res\editor。
• 供用户和 AI 复用的诊断流程： CLI 提供 list、diagnose、sources、remove-sources、reset 和 prune，默认只输出 dry-run 计划，必须显式使用 --apply 才会修改本地文件；WinUI 会单独列出以 e. 开头的异常下载源并提供确认删除入口。工具将操作过程写入 package-repair.log，SDK 文档和 AI Skill 同步补充了错误变体、模板继承链、错误下载源及常见缺包症状的排查方法。

SCE 场景副本

运行时可以从已有 SCE 场景素材创建隔离副本，适用于按玩家、房间或波次拆分地图实例。服务端通过 Scene.CreateCopy(...) 创建副本、加载后切换玩家，并可为副本设置独立默认镜头；客户端收到副本元数据后会建立对应的 Scene，场景加载流程会读取已同步的副本镜头，晚到的元数据可通过 EventSceneReplicated 处理。该能力复用现有属性同步路径，不新增客户端能力版本。

• 区分场景副本与 SceneGraph： 动态 SCE 副本复制已有 native 场景素材，不是凭空创建新的 GameGraph.SceneGraph；独立 SceneGraph 的发布和销毁仍由脚本负责。
• 明确副本内容边界： GameDataScene 中的预放置单位、物品、区域和脚本对象不会随素材副本自动复制，应在副本 OnLoadEnd 后按玩法重新创建。
• 保留副本镜头控制： 客户端不会按副本到模板的关系隐式读取模板默认镜头；副本镜头通过 Scene.DefaultCamera 同步，缺失时才回退工程默认镜头。

其他修复

• 保留未指定的镜头属性： 修复旧版 Lua game.set_camera、WasiCore Camera.SetPosition() / Camera.SetRotation() 以及服务端玩家镜头控制只设置位置或旋转时，可能同时覆盖镜头距离的问题；现在只修改本次明确提供的镜头属性，显式设置镜头距离的行为保持不变。
• 修正 UI 编辑器创作模式的属性标题： 当属性同时提供 DisplayName 与 UiText 时，Inspector 和属性筛选现在优先使用 DisplayName；只有缺失时才按 Label、UiText、字段名回退，避免把包含 {0} 的上下文文案显示成字段标题。触发编辑器继续保留 UiText 的原有语义。
• 更早提示无效投射物配置： 修复投射物效果节点选择“创建投射物”模式但未配置有效投射物单位时执行失败的问题；现在会在执行前明确提示“创建投射物模式需要配置有效的投射物单位数据”。
• 避免空动画状态触发异常遍历： 修复客户端动画状态为空时调用 AnimatedModel.ApplyAnimation() 可能触发无效反向遍历的问题，并补齐相关状态标志的初始化与清理，降低编辑器调试过程中清理动画后继续应用动画时出现访问冲突的风险。
• 修复 Spine 动画名称无效时的客户端稳定性问题： 修复调用 SpineAnimationState.SetAnimation() 或 SpineAnimationState.AddAnimation() 时，传入当前 Spine 资源中不存在的动画名称可能导致客户端崩溃的问题；现在会记录错误并跳过该次播放或排队请求。该修复同时适用于编辑器调试和发布后的客户端运行。
• 避免连续高度场场景创建或保存失败： 修复新建和保存连续高度场场景时可能访问无效场景根节点的问题。
• 避免重复悬崖模型影响烘焙： 修复烘焙包含重复悬崖模型的场景时可能进入异常路径的问题。
• 避免场景树继续使用旧选择： 修复对象移除后场景树仍处理旧选择，导致编辑器访问失效对象的问题。
• 修复粒子预览切换场景异常： 修复粒子预览切换场景时仍使用旧场景对象的问题。
• 修复失效声音资源处理： 修复声音配置包含失效资源时继续使用无效引用的问题。
• 修复角色环境反射贴图保存异常： 修复保存含角色环境反射贴图的场景时可能进入失败路径的问题。
• 修复独立编辑器窗口图形资源初始化失败： 修复独立编辑器窗口图形资源创建失败后继续访问无效资源的问题。
• 修复 Windows 路径场景加载异常： 修复从场景列表打开使用反斜杠路径的场景时，场景名解析可能访问无效字符串并导致编辑器崩溃的问题；现在兼容 Windows \ 与通用 / 路径格式，并加强该加载入口的崩溃信息留存。
• 修复项目资源扫描的并发生命周期问题： 修复客户端在游戏局切换、重连或资源扫描并发进行时，项目资源缓存可能被提前释放并导致崩溃的问题。
• 修复不完整网络消息的解码异常： 修复客户端接收被截断或长度异常的网络字符串、字节数据时，可能先按异常长度分配内存并导致崩溃的问题；现在会在分配前校验消息剩余长度，并按协议解码失败处理。
• 修复 UI 粒子资源不完整时的稳定性问题： 修复 UI 粒子缺少有效材质、渲染技术或透明通道时可能崩溃的问题；同时修正移除像素着色器宏时误写入顶点着色器宏的异常。
• 修复异步纹理上传的源数据生命周期问题： 修复客户端创建纹理时，源图像数据在渲染线程读取前被释放或改写可能导致崩溃的问题；2D、纹理数组、3D 和立方体纹理现在都会为异步上传保留稳定的数据副本。
• 修复 Windows GPU 计时查询初始化失败： 修复部分 Windows 图形设备无法创建 GPU 计时查询时，客户端继续向驱动提交无效查询对象并可能崩溃的问题；查询不可用时会跳过对应计时。

2026-08-25 ～ 2026-09-01（已发布至线上正式环境）

本期重点速览

本期把客户端运行时能力、Editor 自动化和地形创作三条工作流进一步收拢：客户端能力版本提升至 4，项目可以可靠处理主动退局和同尺寸 Surface 重建；外部 AI agent 可以通过 Editor MCP 完成项目、场景和离散瓦片地形的预览、修改、保存、重载与校验；模板、对象销毁和多平台稳定性修复则降低了新项目接入与持续调试的成本。上述能力均保留了旧客户端兼容路径，并明确了 Preview / Early Access 和平台边界。

客户端能力版本

• 当前最新客户端能力版本： 4。
• 本周期是否提升： 是。本周期新增客户端主动退出当前游戏并返回大厅的公开 API，以及可靠接收同尺寸 Surface 重建通知的客户端能力；本周期新增能力统一对应客户端能力版本 4。

客户端游戏局控制

客户端项目现在可以主动结束当前游戏局并返回大厅，不再需要把“退出”实现为服务端踢人或直接断线。调用 LobbyService.QuitCurrentGame() 后，客户端会向 Host 请求主动离局、关闭当前局的重连路径、清理本地游戏实例并切回大厅；服务端仍会记录主动退出状态。旧客户端未提供该可选能力时，API 返回 false。

• 主动退出并回大厅： 新增客户端 API LobbyService.QuitCurrentGame()，适用于玩家点击退出、客户端流程结束等场景；它与 Disconnect() 的断线/重连语义不同，也不等同于服务端 Kick。

客户端屏幕尺寸与 viewport 事件

窗口尺寸变化、屏幕旋转和移动端 Surface 重建可能不会表现为 drawable 宽高变化。现在客户端会在 viewport 状态完成更新后统一通知 GameUI；同尺寸 Surface 重建也会继续经过分辨率事件链路，项目可以在一次回调中读取最新尺寸、方向、设备像素比和安全区信息。该客户端行为与本周期其它新增客户端能力共用能力版本 4，旧客户端仍保留原有尺寸变化兼容路径。

• 统一接收 viewport 状态变化： 新增 ScreenViewport.OnViewportChanged，在尺寸、方向、设备像素比、安全区和裁切偏移更新完成后触发；需要整体刷新布局时应优先订阅该事件，现有 OnSizeChanged 与 OnOrientationChanged 继续保留。
• 补齐同尺寸 Surface 重建通知： Android/iOS Surface 重建但 drawable 尺寸未改变时，客户端仍会广播窗口尺寸事件，避免仅依赖 UI 根节点 E_RESIZED 导致脚本和 WASM 侧漏收通知。
• 旧客户端安全降级： ScreenViewportSurfaceResizeEvents 通过 ClientEnvironment.Runtime.Supports(...) 按客户端能力版本 4 判断增强路径；旧客户端不会调用不存在的客户端能力，仍按原有实际尺寸变化行为运行。
• 补充分辨率变化最佳实践： 新增 ScreenViewport 专用最佳实践文档和 AI Skill，并在 UI 布局 Skill、流式布局指南中补充 OnViewportChanged 的订阅方式、首次主动刷新、安全区处理、幂等更新和旧客户端能力边界，避免只监听单一尺寸或方向事件。

Editor 项目与场景生命周期自动化

外部 AI agent 现在可以通过 Editor MCP 在同一个编辑器进程内准备项目和场景，完成“打开/切换 → 修改 → 保存 → 重载验证 → 清理”的闭环，不再需要用窗口坐标模拟项目管理器操作。生命周期操作统一返回 operation_id，agent 应等待终态并用 editor_get_context 验证项目、场景和 DataManager 的真实就绪状态。

• 通过 MCP 管理项目和场景： 新增 editor_open_project、editor_reload_project、editor_open_scene、editor_reload_scene、editor_create_scene、editor_delete_scene、editor_lifecycle_status 和 editor_lifecycle_wait，覆盖项目切换、项目/场景重载、测试场景创建删除以及异步状态查询。
• 明确 ready 状态与未保存策略： editor_get_context.ready_state 区分 editor_ready、project_loading、project_ready、scene_loading、scene_ready 和 busy；项目切换与重载必须明确选择 save、discard 或 cancel，并在 DataManager/GameDataManager ready 后才算成功。
• 安全完成测试场景闭环： 场景路径限定为项目 scene/ 下的一级目录；删除前必须 Preview，再确认删除，当前场景和 default 场景受保护。新建场景或修改 Terrain 后跨 reload/reopen 保留结果时，除 terrain_save_scene 外还需显式调用 data_save 或 data_save_and_generate 持久化 DataManager 场景索引。
• 补充外部 agent 使用说明： 新增 Editor 项目与场景生命周期 MCP Skill，并在 Editor MCP 接入指南与工具速查中补充调用顺序、错误恢复和验收证据要求。

数据编辑器与地形编辑器联动

在数据编辑器中新建或修改单位、物品后，地形编辑器会立即刷新可创建列表，无需重启编辑器；新条目也可以直接被选择、拖拽和摆放。

• 即时同步单位和物品： DataManager 的数据变更通知现在会同步失效地形编辑器的单位/物品聚合缓存，覆盖新增、删除和修改场景。

数据编辑器资源预览

数据编辑器的预览窗口现在覆盖常用资源节点，编辑数据时可以直接确认模型、粒子和音效引用的实际内容，减少在不同工具之间来回切换的成本。模型沿用 3D 场景预览；粒子会在独立预览场景中加载并播放；音效提供播放和停止控制，切换条目或关闭预览时会自动清理正在播放的资源。

• 预览模型、粒子和音效节点： GameDataModel、GameDataParticle 和 GameDataSound 节点会在 Blazor 数据编辑器的统一预览窗口中显示；音效节点提供播放/停止按钮，粒子节点进入编辑器粒子预览场景，单位和角色模型的原有预览行为保持不变。

离散瓦片地形 MCP 创作工作流

AI agent 现在可以通过完整的 Editor MCP，以“查询选项 → 预览 → 应用 → 撤销/重做 → 保存 → 校验 → 重载”的方式创作离散瓦片地形。地表风格、纹理、TileSet、高度、水域、道路和装饰物都使用语义化选项与结构化诊断，避免依赖内部资源路径；不同 TileSet 可以共存，但跨不同 TileThickness 的非零高度编辑会被安全拒绝。该能力目前为 Preview / Early Access，Runtime terrain.snapshot 对混合 TileSet、完整纹理权重、水域和道路拓扑的观测仍有限。

• 通过 MCP 创作和验收离散瓦片地形： 新增 terrain_* 查询、预览、应用、历史、保存与校验工具，并补充 离散瓦片地形 MCP 创作指南 与 离散瓦片地形 MCP Skill。

随进随出模式与开放局文档

• 补充后台配置、容量模型与槽位清理指南： 新增《随进随出模式与开放局》系统文档及配套 AI Skill，说明创作者中心的模式类型、模式 key、房间最大人数、地图真人玩家槽位之间的关系，并区分大厅自动匹配与通过 OpenGameRef 定向加入的容量判断；《开放局加入系统》文档也同步补充了 LobbyService.QuitCurrentGame()、Player.Disconnect()、Player.Kick(...)、普通断线、放弃重连和未完成连接预约对应的槽位释放时机与排查注意事项。

模板与示例

• 新建项目不再依赖多余的游戏选项库： 官方 map_templates 的所有模板已从 libs.json 中移除 lib_game_options 引用；模板仍保留实际需要的库配置，复制或新建项目时不会再带入这项不再使用的依赖。
• 补充 GameSparkCore 音效数据模板： 新增战斗音效、音乐和界面音效模板，预填对应的音效分类与淡入淡出时间；普通音效默认 0.5 秒、音乐默认 2 秒，VolumeFactor 默认值 1 表示该音效自身的完整增益，实际输出仍会叠加分类音量和距离衰减。
• 避免手写 ScopeData 与用户蓝图重名： code_sample 和 data_sample 中手写的 ScopeData 现在使用 ControlData、UnitData 等明确 alias 指向运行时 GameDataXxx 类型，避免用户在数据编辑器中新建同类蓝图后生成的 GameEntry.ScopeData.GameDataXxx 静态部分类遮蔽类型引用；这只调整模板源码中的引用写法，不改变数据 ID 或生成规则。

对象生命周期与资源清理

对象被场景或宿主级联销毁时，底层通常已经统一接管了实体和单位的非托管资源；如果每个子对象再次按独立对象路径移除场景或释放底层句柄，反而可能造成重复清理。现在普通业务销毁和宿主级联销毁有明确、可扩展的入口，用户自定义派生类也能识别当前销毁来源。

• 区分主动销毁与宿主级联销毁： 普通游戏逻辑使用 Destroy()；宿主（例如整个 Scene）正在卸载时使用 DestroyFromHost()。后者现在是 protected internal，自定义的 DisposableObject、Component 或 Unit 派生类在确认宿主正在销毁时也可以调用。
• 让自定义清理逻辑知道销毁来源： DestroyFromHost() 会在进入清理流程前设置受保护的 hostDisposedValue = true。派生类可以在 DisposeManaged / DisposeUnmanaged 等重写中据此跳过宿主已经完成的非托管清理，或执行只适用于宿主销毁的逻辑；普通 Destroy() 路径不会设置该标记。
• 保留旧程序集兼容： Destroy(bool isHostDispose) 仍保留用于已编译程序集兼容，传入 true 等价于宿主级销毁，但新代码不应直接调用这个布尔重载，更不能把 Destroy(true) 当作活动单位的强制删除方式。

稳定性修复

本期集中修复编辑器初始化、画布文字绘制、粒子池复用、Lua 热重载、FBX 模型导入和 Lite UI 脚本运行中的失败路径，避免底层对象或运行时状态失效后继续被访问；失败时现在会安全返回、刷新运行时引用，或保留可诊断日志与错误信息。

• 修复 Windows 编辑器创建 WebView2 控件失败后仍继续设置 controller bounds 的崩溃风险：现在会检查创建结果和 controller 指针，并在 bounds 设置失败时安全结束初始化。
• 修复 NanoVGCanvas 绘制文字时，异常的字体图集更新区域可能导致上传前读取越界的问题：现在会校验更新区域、行字节数和分配大小，无效更新会被安全跳过。
• 修复池化粒子重新播放时，缓存的发射器可能已随节点内容变化而失效的问题：复用粒子前会重新获取当前节点下仍然有效的发射器，并恢复游戏粒子的运行设置。
• 修复编辑器 Lua 热重载后，“我的地图”等网络请求仍可能使用旧 StateEditor Lua 状态的问题：相关调用现在每次获取当前 Lua 状态，并在重载空窗期安全返回。
• 修复 FBX 导入复制或加载 diffuse / normal 纹理失败后继续使用空 Texture2D 的崩溃风险：现在会记录具体资源路径错误，并继续生成不含失效纹理引用的材质。
• 修复 Lite UI 脚本未注册 LiteTick 时仍调用 Lua 的问题：现在会先检查 Lite VM 和函数是否有效，缺失时跳过本帧调用，避免 Lua 栈状态异常导致访问冲突。
• 修复 Windows 客户端加载 LNI 数据失败时，native 调用链直接触发 Lua 未保护异常并终止进程的问题：LNI 初始化和自定义配置加载现在会把带 traceback 的错误返回给现有数据加载流程，由调用方记录并跳过失效表，不再因单张表加载失败直接 abort。
• 修复 Windows 客户端同步 1.0 技能属性协议时，服务端协议数组包含空条目会被直接解引用的问题：现在会校验普通属性和扩展属性条目，遇到畸形数据时记录索引并安全结束本次同步，避免因单个空条目导致访问冲突。2.0 技能完全由脚本实现，不经过这条 native 技能属性协议，不受此修复范围影响。
• 修复 Windows 客户端在 Lua 调整窗口分辨率时同步重入 Engine::RunFrame() 的问题：窗口尺寸回调仍会处理实际尺寸变化，但不会嵌套执行游戏帧，避免启动或加载阶段的 Lua 包加载状态被重入破坏。
• 修复编辑器承载的 SCE 仿真客户端更新时按统一资源变体误判包类型的问题：API 版本 >=2000 的 SCE 更新会请求 Editor part，但保留各资源自身返回的变体；wineditor 当前使用的 windows_game 包和普通项目资源包不会再被误判为更新错误。
• 修复 Windows 客户端进入游戏并检查项目资源更新时，资源包 I/O 模式切换可能与后台 UI 纹理加载并发，导致访问冲突的问题：现在会等待活动读取结束后再关闭包文件。
• 修复 SCE 仿真客户端销毁独立窗口 UI 根节点后，窗口尺寸变化回调仍访问已释放布局对象的问题：销毁 UI 根节点时会先解除尺寸事件订阅并从 UI 树移除根元素，避免后续调整窗口大小触发访问冲突。
• 修复精简版 Windows 缺少 WebView2 Runtime 时编辑器启动失败且缺少明确引导的问题：启动阶段现在会先验证 Runtime，优先使用随包的 Fixed Version Runtime，没有随包版本时使用系统 Evergreen Runtime；检测失败会提示安装 WebView2。编辑器的普通 BlazorWebView、Composition Controller 和更新进度页统一使用同一 Runtime 配置，并兼容不同 WebView2 SDK 对环境创建 API 的命名差异。
• 修复 Windows 编辑器安装目录或截图目标路径包含中文时，Runtime MCP 截图可能无法写出 PNG 的问题：截图写盘现在按 UTF-8 路径转换为 Windows 宽字符路径，调用 debug.capture_screenshot 时不再要求路径必须是纯 ASCII；打开截图文件失败时也会记录明确错误。
• 修复 iOS 对战平台完成星火币充值后，支付成功回调的前台状态参数可能导致客户端收尾异常的问题：现在会先完成支付结果回调并安全记录参数，同时正确清理充值监听和“充值中”遮罩，避免充值页面及返回后的游戏界面持续无法交互。
• 修复 iOS 对战平台充值成功后充值页余额未及时刷新的问题：Apple IAP 和 TapPay 成功后会延迟并有限次查询最新星火币余额，到账后充值页会自动更新显示。

2026-08-18 ～ 2026-08-25（已发布至线上正式环境）

本期重点速览

本期围绕“新版客户端能力如何安全落地”和“复杂编辑、调试场景如何让 AI 与项目作者更容易掌控”两条主线展开：客户端能力版本由 2 提升到 3，新增支付余额详情查询和三路蒙皮选择；多人 PIE 调试可以先发现目标再路由 Runtime MCP 请求；资源清单、地形氛围、触发编辑器和 GameSparkCore 模板的采用说明也同步收拢。需要注意的是，SimpleSkinning 是多 View 蒙皮共享状态问题的兼容性缓解方案，真正的 View-local 隔离仍在引擎侧持续跟踪。

客户端能力版本与运行时调试

本期新增的客户端能力必须与客户端二进制成批发布，因此统一提升能力契约版本，并由 WasiCore 在调用前判断能力，避免新 SDK 与旧客户端组合时进入不存在的底层接口。

• 客户端能力版本提升至 3： 本期同一批客户端提供 PaymentBalanceInfo（支付余额详情查询）和 SimpleSkinning（AnimatedModelComponent.SimpleSkinning 普通硬件蒙皮开关），两项能力的最低客户端能力版本均为 3。
• 余额查询支持累计值展示： PaymentClient.GetBalanceInfo() 返回当前登录用户的 CurrentBalance 与支付服务回传的 TotalCoin，不接受任意 userId；能力不足或查询失败时返回 null。旧的 PaymentClient.GetCurrentBalance() 保持兼容，仍只返回当前可用余额。
• 三路蒙皮可以按模型选择： SimpleSkinning = true 使用普通硬件骨骼蒙皮；否则在 ComputeShaderSkinning = true 时使用 Compute Shader 蒙皮；两个开关都为 false 时继续使用 CE 默认纹理蒙皮，优先级为 SimpleSkinning > ComputeShaderSkinning > 纹理蒙皮。普通蒙皮仍受设备最大骨骼数限制，WasiCore 会先通过 ClientRuntimeFeature.SimpleSkinning 判断旧客户端能力。
• 画中画和小地图有临时规避路径： 当同一角色需要出现在多个 View 时，可以先使用 SimpleSkinning 绕开共享蒙皮纹理的短期风险；SDK XML、骨骼动画文档和客户端 AI skill 已补充三种路径的选择示例与边界。该开关不等同于 View-local 状态隔离，长期修复仍由 WasiAsync 跟踪。
• 多人 Runtime MCP 先发现、再操作： 新增 runtime_list_targets，返回短生命周期的 target_id、编辑器槽位、玩家 ID、地图和前台状态。AI 助手可按客户端、slot_id 或 player_id 选择目标，再将 target_id 传给 runtime_list_tools 和 runtime_call_tool；多个目标未指定时返回歧义错误，不再静默操作第一个目标。
• 保留单客户端兼容： 只有一个 Runtime 目标时仍可省略 target_id；旧客户端会返回明确的目标路由不可用错误，Gameplay 结束或重建后需要重新发现目标。当前阶段只覆盖同一 Client 进程内的多个 Gameplay，input.* 仍受进程级窗口焦点约束，多个独立客户端进程需要分别配置端口。

资源清单与地形氛围

本期把“编辑器里能找到资源、发布包里也能带上资源”和“修改地形氛围资产、理解运行时效果”两条容易混淆的路径讲清楚，降低发布后缺资源或误改运行时状态的排查成本。

• 属性初值中的资源路径也能被收集： IFile 资源收集分析器继续覆盖 Model、Animation、Material、Prefab、Sound、Texture 等资源类型的变量、字段和属性字面量初值，包括 "path"u8 写法；本期补齐了通过属性初值间接引用资源路径的解析。
• 动态资源路径的边界更明确： 资源清单指南、项目 AI 上下文模板和 3D / 通用开发 Skill 统一说明：测试阶段只下载资源清单引用的内容。运行时动态拼接、未进入 GameDataModel / GameDataAnimation 或 IFile typed literal 的路径，应改成可静态分析的资源字面量，或显式加入 ref 目录清单。
• 氛围资产和运行时控制器分开说明： 地图氛围通常保存在 atmosphere/*.lightgroup 中；该扩展名的内容实际是可读 XML。新增指南和 AI skill 说明如何根据 name.json 定位预设，安全修改 Zone 与主 Light 的环境光、雾、环境贴图、Bloom、主光颜色/亮度、色温和阴影字段，并保留 origin、id、未知属性和资源路径。
• 明确永久修改与临时效果的区别： 直接保存 .lightgroup 是地图资产修改；SceneLightingController / SceneWeatherController 只影响当前客户端运行时。文档同时补充 0～1 RGBA、旋转四元数、深度雾自动计算和色温开关等常见陷阱。

触发编辑器

触发器本期集中改善“代码能否顺利导入”和“作者能否看懂当前编辑上下文”两件事，同时保留结构化触发器不承诺完整 C# 语义的边界。

• 面向过程 UiText 的初始化器按需出现： 过程构造函数默认不再显示对象初始化器；需要时在文本中加入 {init}，初始化器会插入该位置。面向对象调用仍保留原有行为，EnableObjectInitializer=false 仍可彻底关闭某个构造函数的初始化器。
• UTF8 字符串槽位兼容普通字符串表达式： EngineCommon.UTF8String 槽位现在可选择普通字符串立即值、字符串变量和返回普通字符串的函数，生成代码继续依赖 string 到 EngineCommon.UTF8String 的隐式转换；普通 string 槽位不会反向显示 UTF8 字符串立即值。
• 常见 C# cast 可以导入结构化表达式： 代码导入支持 (Type)value、((Type)value) 等写法，并转换为已有类型转换表达式；数字类型显示为“转换为”，引用类型规范化为 value as Type。用户自定义 implicit / explicit operator、模式匹配变量和任意 C# cast 语义仍不在支持范围内，AI 编码规则会优先建议引用类型、UI 控件和事件 sender 使用 as。

GameSparkCore 模板与示例

模板改动的目标是让示例的表现逻辑更容易理解，并让数据编辑器中的默认值与实际运行时行为保持一致；已显式配置的模板字段不会被默认值覆盖。

• 劈砍技能示例按技能阶段生成刀光： 示例改用简单动画配置，通过 StagedSpawns 在 Channel 阶段开始时创建刀光，不再让动画序列承担延迟生成 Actor 的职责；四阶段时长与攻击动画的命中点、取消点和总时长对齐，并继承通用近战攻击模板以复用自动获敌、攻击标记和目标指示器配置。
• 技能和物品模板补齐运行时初值： 显式补齐同步范围、主动技能弧度容差、自动目标获取、施法阶段可打断、可拾取物品初始堆叠和默认堆叠行为等与类型默认值不同的字段，使新建数据时属性面板与实际运行结果一致。

稳定性修复

以下修复覆盖对战匹配、投射物和死亡单位筛选，以及编辑器、Windows、Android 和 iOS 的资源、渲染、脚本与启动生命周期。措辞描述已定位并处理的具体问题，不代表同一操作下所有潜在故障都已覆盖。

• 修复单位切换场景后物品栏中的物品单位仍停留在旧场景的问题：现在单位成功切换场景后，会递归同步其物品栏及嵌套物品栏中的物品单位，避免客户端因物品单位未进入当前场景而出现物品栏内容或属性不同步。
• 修复“随进随出”模式优先加入仍有空位的进行中游戏局，避免后续玩家无法进入首名玩家所在的游戏局。
• 修复投射物沿途碰撞半径与抵达容差使用颠倒的问题：ImpactSearchRadius 用于飞行路径搜索，FinishArriveRadius 仅用于追踪投射物抵达目标时的额外容差。
• 修复死亡单位调用 MoveTo(ScenePoint) 后无法继续被 FilterEntities 找到的问题。
• 修复编辑器清理骨骼插槽实例、切换地图或碰撞层级未挂载、渲染对象正在移除、D3D11 帧缓冲附件失效、空动画轨道采样和单位默认属性表缺失时的崩溃风险。
• Themis 符号与崩溃记录按 数字(api_version) 对齐；编辑器包补充 SCECrashHandler.exe 本地转储兜底，同时保留 Themis 接管路径。
• 修复随机 Landscape 权重纹理上传和场景列表重建时访问失效内存或节点的问题，并修复 Windows AMD 图形环境退出、Android TCP 调试服务关闭、TapTap 启动主题、Android 单位属性同步、EGL 配置与 native window 重建等生命周期问题。
• 修复模型切片动画发布包不播放、异步资源回调在编辑器或 Android 退场期间失效、NanoVG 字体纹理更新越界、触发器损坏 for 节点渲染、血条拖拽失效节点回调和 Lua 重载期间访问旧 Lite VM 等问题。
• 独立 Android 包更新至 3.6.0.3、独立 iOS 包更新至 3.7.0.3；内嵌包继续由 TapTap 提供 Themis，PC 包继续使用现有 Windows 版本。

2026-08-12 ～ 2026-08-18（已发布至线上正式环境）

客户端能力版本

• 当前最新客户端能力版本： 2。
• 本周期是否提升： 是，客户端能力契约从 1 提升到 2。
• 新增能力映射： UIAuthoringRuntimeInitialize → UI 编辑器创作模式运行时初始化；客户端 Scene.EnsureStaticMeshColliders() → 显式加载当前 3D 场景的静态网格碰撞。两项能力都依赖版本 2 客户端二进制；项目主动调用新 API 时，应按目标客户端版本判断是否可用。

本期重点速览

本周期围绕三条主线收口：默认 Loading 进入 GameData 配置体系，项目可以关闭、换肤或复用框架 Loading；触发编辑器补齐重写基类方法、游戏生命周期回调、表达式拖拽和类型推导等高频创作链路；客户端与运行时侧增加能力版本、初始化日志、服务端错误统计和静态碰撞预瞄准，便于在外网测试与正式环境中定位问题并实现更准确的本地表现。商店支付补偿、模型 LOD 指引，以及多项编辑器和客户端稳定性修复也在本期集中发布。

默认 Loading 界面数编配置

框架默认启动 Loading 现在可以通过数据编辑器关闭、换肤或复用。项目无需再为移除默认页、替换背景和品牌图而编写初始化代码；场景切换等临时 Loading 也可以复用同一套数编样式。框架会在当前 GameMode 的游戏设置初始化阶段读取 GameDataGameUI，这组配置只影响客户端启动 UI，不改变平台原生启动图和项目主动创建的页面。

• 一键关闭框架默认启动页： GameDataGameUI 新增 ShowDefaultLoading。设为 false 后，框架不会自动创建启动 Loading；项目代码主动显示的临时 Loading 和平台原生启动图不受影响。
• 通过数编完整自定义当前样式： 新增 GameDataLoadingUI，可配置背景、品牌字标与说明、加载文字、进度条、进度文字、取消按钮、布局、颜色和完成 / 失败后的自动隐藏延迟；GameDataGameUI.DefaultLoadingUI 用于选择当前 GameMode 启动时使用的配置。GameSparkCore 同步提供当前框架样式的默认数据和“Loading界面模板”，项目可以继承后只覆盖需要调整的字段。
• 代码 Loading 复用同一套配置： LoadingUI(GameDataLoadingUI) 可按指定数编数据构造临时 Loading，LoadingUI.Configuration 可读取当前实例使用的配置。无参构造及 CreateSimple(...)、CreateWithProgress(...)、CreateFull(...) 保持兼容；旧项目缺少新字段或未设置 DefaultLoadingUI 时仍使用历史默认样式。
• 文档与 AI 优先推荐数编路线： Loading 页面指南和 ui-layout-api AI Skill 已补充“关闭默认页 → 数编换肤 → 代码动态创建 → 完全自建页面”的选择顺序，并明确默认配置读取时机、GameMode Link 检查方法和场景加载完成边界。

触发编辑器：方法、事件与文件结构

本期触发编辑器的主要目标是减少“必须回到代码里手写”的场景：基类重写、游戏生命周期回调、文件树快捷创建和 UTF8 字面量都可以在图形化界面内完成，并由编辑器生成与当前端侧和 SDK 声明一致的代码。

• 按图形化显示名添加重写方法： 类节点和“新建”菜单新增“添加重载方法”，可从当前类继承链中选择要重写的 virtual / abstract 方法。选择器优先显示触发器里的图形化显示名，同时列出声明类和真实方法签名，便于在显示名与代码名不一致或存在同名重载时准确选择；确认后会自动按基类签名创建 override 方法和空方法体，并过滤静态、私有及当前类已经实现的方法。
• 直接接入游戏生命周期与全局回调： 类配置可开启“接入游戏生命周期与回调”，中央语句区会按初始化阶段、游戏运行和其他回调分组展示当前客户端、服务端或公共环境实际可用的 Game 事件。用户只需在对应事件块内填写动作；编辑器会自动生成 IGameClass、OnRegisterGameClass()、隐藏处理方法及事件订阅。可选事件来自当前 SDK 声明并遵守端侧与隐藏元数据，框架内部注册事件和会改变异常控制语义的 TaskUnhandledException 默认不会作为普通回调开放。
• 事件注册生成与导入保持一致： 单一事件类型的强类型触发器现在生成 Register(sender)，动态或多事件触发器继续生成 AddEvent<T>(sender)；代码导入同时兼容新写法和旧版 AddEvent<T>。历史异常生成代码仍可兼容编译，对应的临时兼容入口不会出现在触发器 API 选择面板中。
• 所有文件树容器统一提供快捷新建： 模块、文件夹、命名空间、类、预设和自定义事件节点右侧均提供 + 入口，并与右键菜单共用同一套合法子成员规则。类内嵌套文件夹会继续按类成员约束创建内容，预设与事件只显示各自允许的成员；只读或导入容器不会提供创建入口。
• 触发器语句树隐藏无效层级： 不可编辑且已无实际用途的“所属场景”不再显示，语句树集中展示事件、局部变量、条件和动作。
• 类型默认值减少重复填写： 类和自定义事件可以配置类型默认值；新建变量、切换变量类型或创建函数调用时，会在适用位置自动复制该默认表达式。局部引用变量在没有显式默认值时还可使用最短构造函数或 null 补齐已有初值位置，但这类普通 fallback 不会自动开启“有初值”；全局变量与函数实参则遵守更保守的初始化规则，避免意外创建共享对象或为参数凭空生成实例。接口不会被当作可直接实例化的默认类型。
• 字符串与数值类型会自动补齐默认值： 局部变量或全局变量切换为字符串时，会立即开启初值并填入 "字符串"；切换为 int、uint、long、float、double 或 decimal 时，会填入保持具体数值类型的 0。创建函数调用时，未配置参数默认值的字符串和数值实参也会使用同样的类型默认值；参数自身配置的默认值仍然优先。
• UTF8 字符串可直接作为立即值： 立即值选择页新增“UTF8字符串”，可在触发器中编辑、保存和重新导入 ReadOnlySpan<byte> 字面量，生成代码形如 "ABC"u8，无需退回代码编辑器手写 UTF8 后缀。

触发编辑器：表达式、类型选择与拖拽

另一组改动集中在表达式编辑的可预期性：清空、撤销、拖拽、类型推导、成员搜索和初始化器都按目标槽位与当前环境重新校验，减少“能放下但生成不合法”或“看起来不能选其实被搜索过滤”的情况。

• 表达式参数可安全清空并撤销： 表达式右键菜单现在明确区分“清除当前参数”和“删除整行”；清除后会保留正确类型的“未填写”占位，Undo / Redo 可以完整恢复这次修改。Switch case 只接受普通枚举项和编译期常量，不再允许变量、函数、GameLink、GameData 或可扩展枚举。
• 用运算符扩展已有值时自动保留原值： 双击已有值打开 TriggerSelect，并把它替换为 +、-、*、/、% 等计算表达式时，如果原值类型可以作为新运算符的左操作数，编辑器会直接把原值填入左侧。例如把立即值 5 替换为乘法表达式时，会得到 5 × 1；类型不兼容的值仍沿用原默认模板和现有过滤规则，不会生成带错误类型的半成品表达式。
• 嵌套表达式拖拽优先命中准确目标： 拖拽表达式时会从光标下最内层的合法目标开始尝试，内层不合法时再回退到父表达式，避免本想替换常量或参数却覆盖整个外层表达式；赋值语句两侧的数组索引器以及条件语句左右表达式也已恢复为可拖拽目标，并按目标类型判断是否允许放置。
• 集合与对象初始化器支持纵向和批量编辑： 折叠状态直接预览 [1, 2, 3]、{键: 值} 等实际内容，并限制预览项数与长度，避免大型初始化器再次横向撑宽语句；展开后 List、HashSet、Dictionary 和对象属性按行编辑并支持拖动重排。新的“批量编辑”侧栏只展示初始化项本身，立即数直接保持为输入框，布尔值与其他表达式继续使用适合其类型的控件；Tab / Shift+Tab 可按键值顺序循环，Enter / Shift+Enter 可在同列上下移动，非法数值会保留焦点并阻止提交，所有修改与重排继续进入全局 Undo / Redo。
• 初始化器元素序号改为 0 开始显示： 批量编辑侧栏和展开编辑行内的序号现在与内部索引一致，不再额外加一；这样更适合按数组、列表和字典的真实下标理解初始化项，避免把第一个元素误认为“第 1 项”。
• 字典初始化与索引访问恢复完整： Map / Dictionary 勾选初值后可以正常添加和编辑键值元素，生成与重新导入代码时会保留条目；字典类型的面向对象成员选择中也会显示 [] 索引访问，不再只能通过方法间接读写元素。
• 接口继承成员可直接选择： 当值的类型是接口时，成员选择器会递归列出父接口提供的属性和方法，并正确替换泛型父接口中的类型参数；多条继承路径产生的相同成员会自动去重。类类型仍沿用自身与父类的成员规则，不会因为实现接口而额外重复显示接口成员。
• 搜索类型后仍可查看该类型的全部合法成员： TriggerSelect“类型”页继续支持同时搜索类型和成员；选中具体类型后，右侧会明确提示成员列表仍受当前搜索词过滤，并可展开查看未匹配文字搜索的“其他可用成员”。展开只取消文字搜索过滤，不会绕过槽位类型、实例或静态上下文、可见性、端侧及当前打开环境等合法性限制；零匹配时也会直接提示仍有多少成员可用，避免把被搜索隐藏误认为该类型没有可选属性或方法。
• 字母名称优先于拼音近似结果： TriggerSelect 与 TypeSelect 搜索会按文字匹配质量稳定排序，直接包含输入字母的类型、属性、方法和枚举项会排在“爱”“坏”等仅由拼音命中的中文结果之前；枚举按“类型名.枚举项”显示时也会单独识别枚举项名称，例如搜索 K 时优先展示“按键.K”。拼音搜索能力和原有类型、环境、可见性过滤保持不变。
• 拖拽虚影完整展示当前表达式： 使用自定义图形化文本的成员访问和函数调用不再只显示末尾文字，拖拽时会展示完整调用者与表达式内容；函数调用、参数以及嵌套运算仍保留各自独立的拖拽粒度，便于确认当前实际选中的元素。
• 悬停与拖拽目标提示更准确： 运算符现在会显示表达式结果类型；拖拽表达式到参数槽位时，提示会优先说明目标槽位需要的类型，而不是继续显示源值类型，避免把“任意”或接口参数误解为只能接受当前具体类型。
• 语句树悬停提示会直接说明操作方式： 可交互元素会按实际行为显示“单击：编辑立即值 / 选择运算符 / 打开类型选择界面”和“双击：打开表达式选择界面”；同时支持单击和双击时，会先列出单击提示。可拖拽的内层表达式会提示“拖拽：复制到可接收此表达式的位置”，使用图形化文本的面向过程表达式还会在返回类型之前显示它在 TriggerSelect 中的面向过程显示名，而不是属性或方法自身的显示名。普通悬停提示与拖拽期间的目标合法性提示相互独立，不会改变或遮挡拖拽反馈。
• 错误类型提示更容易定位原因： 表达式或运算符被推导为错误类型时，悬停提示会显示运算符、左右操作数类型和失败原因；变量初值类型不匹配时，也会同时说明声明类型、初值推导类型和子表达式错误，减少只能看到“错误类型”而需要回到 JSON 或代码排查的情况。
• 表达式填槽与整句重排反馈互不干扰： 将表达式拖向合法参数槽位时，局部变量行等经过区域不再错误显示整行红色非法背景；只有真正移动或重排整句语句时才显示行级落点反馈，视觉提示与最终能否放下保持一致。
• 不同语句区域严格校验可放置内容： 属性访问和普通计算值等纯值不会再因直接拖拽而意外成为独立动作；事件、条件与动作区域会分别校验合法语句，事件语句、动作语句及事件参数不能再通过拖拽跨越作用域。通过动作区选择器添加纯值时自动转换为赋值语句的旧行为保持不变。
• 最外层表达式的拖拽语义更一致： 有合法返回值的语句可以把最外层表达式复制到兼容参数槽位，但不能再用它替换另一条语句的最外层；拖到语句本身时会按光标位置解释为前后插入。赋值语句、无返回值调用和类型未确定的调用仍按原有权限执行整句移动，不能独立成句的值会被明确拒绝。
• 拖拽目标与类型提示保持清晰： 拖拽经过目标语句时不再让整行错误变成半透明，目标槽位类型、类型不匹配原因、合法性高亮与插入位置提示都能保持清晰可见。
• 空值不会再成为非法变量类型： 类型未定义的局部变量接收“空值”时，不再把 null 推断为变量声明类型；已有明确引用类型的变量仍可正常使用空值初值。动作区通过选择器选取纯值时，仍会沿用自动创建局部变量并转换为赋值语句的原有流程，其中空值会使用可用的上下文类型或合法通用类型。
• 列表局部变量会正确创建默认初值： 修正基础类型数据中 List<T> 被误识别为抽象类的问题；新建列表局部变量时会恢复生成合法的 new List<T>() 初值，Dictionary 等已有集合类型行为不受影响。
• 抽象类与接口不再允许创建实例： TriggerSelect 不再展示抽象类和接口的构造函数，旧触发器数据中已经保存的非法构造调用也会给出明确检查错误；抽象类和接口仍可正常作为变量、参数及返回值类型使用。类配置中的对应选项同时明确显示为“抽象类（不可创建实例）”。
• 泛型表达式会按照目标槽位自动补全类型： 在 TriggerSelect 选择或拖拽表达式填入槽位时，编辑器会根据槽位类型推导尚未确定的泛型参数，支持接口继承、多参数、嵌套泛型和部分推导。例如 List<int> 初值选择“新建列表”时会得到 new List<int>()，不会再反向把变量声明污染为 Any；将变量整体改为“任意”时也会保留已有初值。

场景、数编与奖励模板

这些改动面向编辑器内的常用创作路径：场景属性可以从场景树直接进入，镜头预览会跟随属性实时更新；数编类型文档则明确图形化与纯代码两条路线，避免在 AI 或 MCP 自动化中混用两套入口。

• 从场景树直接查看场景属性： 打开场景后，点击左侧场景树中的当前场景名即可在右侧显示场景属性；重复点击已经选中的场景名也会重新切换到场景属性，不再需要点击视口空白区域。
• 从场景树右键重命名场景： 场景名的右键菜单新增“重命名”，修改后会同步更新场景数据、左侧树节点和右侧属性面板；空名称或与其他场景重复的名称会被拒绝。
• 镜头预览会即时反映属性修改： 在右侧属性面板使用“用此镜头预览”后，继续修改镜头位置、旋转、焦点距离、视野角和近远裁剪面时，当前场景视口会同步更新，无需退出并重新进入预览。切换镜头、离开镜头选择、切换编辑器镜头模式或卸载场景时，会自动结束原预览绑定，避免后续编辑错误地影响旧镜头预览。
• 自定义数编类型按创作方式选择正确入口： GameData 专项文档、数据编辑器与触发编辑器 AI Skill 现在统一说明类型、条目和 Link 的边界。需要继续使用图形化数据编辑器时，应先在触发编辑器 Class 的属性面板选择“设置为数编分类”或“设置为数编类型”，依次完成触发定义保存、TriggerGenerated 生成、双端编译和类型发现，再由数据编辑器维护条目并生成 DataGenerated / ScopeData；只有明确采用纯代码开发时，才直接声明 [GameDataCategory] / [GameDataNodeType<T,V>]，并在 OnGameDataInitialization 中用代码注册具体条目。文档同时补充了 T 为根分类、V 为直接父类、生成文件不可手改，以及 AI/MCP 缺少类型 schema 时不得硬写未知 $type 或擅自切换创作路线等边界。
• 直接选择顺序执行或随机选一模板： GameSparkCore 模板库新增“顺序执行效果集合”和“随机选一效果集合”，并补充物品、Buff、技能、效果、顺序集合、随机选一共六种奖励模板。集合模板会显式填写 SetFlags；随机选一模板还会显式设置 MinCount = 1、MaxCount = 1，避免界面上未设置字段的显示状态与运行时默认行为难以对应。
• 奖励集合默认顺序执行全部子奖励： GameDataRewardSet 在未勾选 SetFlags、且未设置 MinCount / MaxCount 时，会按列表顺序执行每个子奖励一次；同时补充无效数量范围、空标志配置和唯一奖励数量不足的校验，避免未设置 MaxCount 时执行失败。

GameGraph 与客户端表现

本期 GameGraph 侧补充了客户端本地表现常见的两个边界：预瞄准需要显式加载静态碰撞，模型 LOD 需要理解运行时使用的稳定尺度。相关文档和 API 说明也同步补齐了易误用的 UI 图片翻转与 Spriter 贴图参数规则。

• 客户端可显式加载场景静态碰撞： Scene.EnsureStaticMeshColliders() 现在同时支持客户端和服务端。客户端调用后会读取当前 Volumetric3D 场景的 PhysicsCollision.dat，在场景中取得或创建 PhysicsWorld 并挂载静态碰撞；重复调用返回 AlreadyLoaded，缺少或损坏产物时分别返回 FileNotFound 或 InvalidData。
• 客户端按需加载后再进行物理查询： 客户端加载由 API 显式触发，不会自动启用单位控制或其他物理模拟逻辑。需要自行进行地形、墙壁和平台等静态场景碰撞查询时，应在预瞄准系统初始化或首次查询前调用该 API；成功后再使用 Raycast、SphereCast 等物理查询。若未先加载静态碰撞，查询可能因场景碰撞信息尚未挂载而穿透墙壁。
• 更容易判断模型何时降级以及应该调整哪一层： 新增模型 LOD 选择与配置文档，说明运行时如何综合相机距离、模型尺寸、相机与模型 LodBias、相机 Zoom 选择 LOD，并整理美术工作台的自动 / 手动屏幕尺寸、节能 / 中 / 高画质偏移和 GameGraph 运行时调节方式。文档同时明确“屏幕尺寸”是用于换算切换距离的编辑参数，不是运行时精确像素占比；项目画质的整数偏移当前只影响静态模型，AnimationLodBias 控制的是骨骼动画更新频率而不是网格 LOD。
• 修复了一个镜头旋转影响模型 LOD 选择的问题： 静态模型和骨骼模型使用旋转后的世界包围盒尺寸参与 LOD 判断时，长条形模型可能仅因朝向变化便切换精度。模型现在使用局部包围盒尺寸结合世界缩放计算稳定尺度；挂在主视角镜头上的枪械等模型，在相机距离、模型缩放和 LodBias 不变时，不会再仅因镜头旋转从 LOD0 切换到 LOD1。实际距离、缩放或 LodBias 变化时仍按原有规则切换。
• 避免对滚动面板误用 FlipX / FlipY： ImageFlipX、ImageFlipY 及 .Flip()、.FlipX()、.FlipY() 的 XML 文档和 AI 使用指引现在明确说明：PanelScrollable 的底层滚动控件不支持图片翻转；对滚动面板调用扩展方法时会记录警告。需要翻转图片时请使用普通 GameUI.Control.Primitive.Panel，并注意便捷构建器 UI.Panel() 当前返回的是关闭滚动的 PanelScrollable，不能替代普通 Panel。
• Spriter 动画贴图颜色与原图保持一致： 修复 GameGraph AnimationSet2D 加载 Spriter / SCML 普通 PNG 时绕过同名纹理参数 XML，导致配置的 sRGB 解码、过滤和寻址方式不生效的问题。项目可在贴图同目录添加同名 .xml，并使用 <srgb enable="true" /> 处理因色彩空间不一致而出现的发白；多张序列帧的参数一致时仍会合并图集，参数缺失或不一致时会分别加载并记录警告。Spine 图集原本已经支持同名纹理参数 XML。

运行时日志、脚本生命周期与线上排查

运行时侧的改动重点是让初始化失败、线上脚本错误和跨平台加载问题更容易定位，同时修复若干脚本状态与游戏局生命周期中的具体稳定性问题。

• WASM 游戏初始化失败时保留关键诊断： 游戏初始化现在会在运行时日志中记录初始化入口、游戏类注册、数编初始化和 GameMode 校验等阶段；检测到 GameMode 数据缺失并准备退出时，会记录具体空值状态并立即刷新 native 日志。这样即使 WASI 以退出码结束 SCE_game_init_export，仍可从客户端日志判断失败发生在哪个初始化阶段。
• 客户端初始化日志标明二进制版本与运行环境： 每次客户端游戏局开始初始化时，WasiCore 会在运行时日志中记录客户端二进制版本、能力版本，以及当前项目运行环境（Debug / Test / Formal）。二进制版本与 Themis 崩溃报告中的客户端自定义版本号使用同一来源，便于将普通运行日志与崩溃记录对应起来；不支持环境读取的旧客户端会安全记录为 Unknown，不会因此启动失败。
• 线上 PC 客户端脚本日志可直接查看： 线上环境的 2.0 / WASM 客户端运行日志不再使用 TNND 混淆格式，logs/client 中新生成的日志可以直接按 UTF-8 文本打开，便于玩家回传和开发者现场排查；历史客户端已经生成的混淆日志不受影响。
• 后台可以查看 2.0 服务端错误统计： 服务端脚本通过 Game.Logger.LogError / LogCritical 输出的错误，以及 WASM 运行期间捕获的脚本异常，现在会汇总到开发者后台「Lua 报错统计」的服务端报错栏目；相同错误会按错误内容统计数量，便于定位线上服务端脚本问题。原有服务端脚本日志仍会保留，可结合完整日志查看错误上下文。
• 修复了一个 iOS 内嵌包启动 WASM 失败的问题： iOS 运行时与 AOT cwasm 生成流程现在统一将 Wasmtime 线性内存的初始虚拟地址空间预留从 4 GiB 降至 2 GiB，降低宿主应用地址空间紧张时出现 mmap failed to reserve 0x104000000 bytes、导致游戏脚本无法实例化的风险。2 GiB 只是初始预留而非内存硬上限；需要继续增长时，线性内存仍可移动并通过 memory.grow 扩展。该调整仅影响 iOS，不改变其他平台的 WASM 加载方式。
• 修复了一个普通游戏局退出时重复释放资源的问题： 客户端结束进程或销毁游戏引擎时，游戏局已经进入析构后仍可能被 Wasmtime / GameUI 清理流程重新查询并临时持有，导致同一游戏局及其资源被重复释放。游戏局现在会在最终析构前先从运行时查询容器中摘除；仅供编辑器 PIE 使用的 UI 图片缓存清理也会先检查编辑器运行环境，普通 Windows、Android 和 iOS 游戏局不再进入该专属路径。
• 修复了一个 Lua 重载期间访问失效 Lite VM 的问题： 脚本状态重载时，Tick、事件队列和 VM 上下文清理不同步可能导致旧回调继续访问已释放或正在替换的 Lite VM；重载期间会暂时阻断相关 Tick，完成清理后再恢复执行。
• 降低粒子池复用期间访问失效发射器的风险： 粒子回收入池时保存发射器缓存对应的内存统计和淘汰标记；从池中复用或因内存限制淘汰时直接使用快照，不再反复遍历长期缓存的发射器裸指针，降低特效创建期间发生访问冲突的风险。

商店支付可靠性

正常情况下，GameSystemUI 商店仍在同一原子事务中完成商品发放和星火币扣除。本周期进一步补齐了扣费事务出现名称冲突等异常后的恢复路径，降低“星火币已扣除但商品未到账”的风险。

• 扣费后自动尝试退化发货： 框架在确认订单尚未结算后，会尝试不重复扣除星火币的发货事务；正式发货、退化发货和补偿共用订单结算幂等标记，避免同一订单重复处理。
• 退化发货失败后返还项目付费货币： GameSystemUI 会根据商品 Cost.Resource 的 CloudDataKey，按本次实际扣除的 notification.Gemstone 在独立事务中返还项目内付费货币；用户购买前已有的余额不会被重复返还。
• 补偿结果可审计： GameSystemUI 将补偿订单独立记录到 shop_payment_compensations，并通过 PaymentServer.OnPaymentCompensated 通知项目刷新余额或更新界面。
• 自定义支付需要主动接入： 直接使用 PaymentClient + PaymentServer 的项目必须自行注册 PaymentCompensationHandler，根据自己的商品配置决定返还哪种项目货币；补偿 Handler 和补偿审计记录不会由底层支付 API 自动推断或生成。

编辑器稳定性与崩溃诊断

以下条目集中修复编辑器启动、渲染、资源加载、PIE 退场和资源导入路径中的具体稳定性问题。修复项描述的是已经定位并处理的故障原因，不代表同一操作下所有潜在崩溃原因都已被覆盖。

• 旧版 Intel Iris Xe 驱动会在启动前得到更新提示： 启动器会在编辑器本体启动前通过独立显卡探针检查当前首选 DXGI 适配器；若 Intel Iris Xe 仍使用 27.x 或更早版本驱动，会提示该驱动在 D3D11 像素着色器创建路径存在已知崩溃风险，建议更新驱动，或在配有独立显卡时将 SCE.exe 设置为高性能。检测与提示不会阻断本次启动，并且只检查首选且已经通过硬件图形自检的适配器，避免因机器安装了但未实际使用旧核显而误报。
• 修复了一个界面顶点缓冲资源耗尽后访问空缓冲的问题： 编辑器长时间运行、反复加载或更新资源后，临时顶点缓冲申请失败时底层仍可能继续访问空缓冲对象。分配失败现在会安全终止本次缓冲提交，帧间缓冲合并或缩容失败时也会保留原缓冲，降低 UI 渲染触发原生崩溃的风险。
• 修复了一个 D3D11 临时顶点缓冲创建失败后的空资源提交问题： Windows 渲染线程在临时顶点缓冲底层资源为空时，会跳过无效的更新与提交并记录创建参数，避免把空资源传给显卡驱动的 Map 调用；正常创建成功的动态和临时顶点缓冲上传流程保持不变。
• 修复了一个停止 3D 导航调试时访问失效导航上下文的问题： 显示导航网格或体素调试信息后结束 PIE 时，导航数据已经销毁但调试节点仍继续接收渲染更新，可能访问失效导航上下文。结束游戏局时会先移除导航调试节点，残留更新也会安全跳过。
• 修复了一个资源目录变化期间后台加载访问失效路径的问题： 编辑器切换项目、重载资源路径或退出 UI 编辑器创作模式时，后台线程仍在加载 UI 图片及其纹理参数文件，与资源目录清空或重建并发后可能访问失效路径并导致原生崩溃。资源路径规范化现在会与目录及地图资源缓存更新同步；同一保护也覆盖正式客户端的进程内切局和脚本重载，不改变地图资源优先级、后台加载行为或旧游戏局资源回收流程。
• 降低浏览大贴图预制体资源时的内存峰值： 编辑器不再在创建贴图编辑对象时立即复制每张贴图的完整文件数据，而是在实际编辑或保存时按需读取，降低浏览包含大量贴图或超大贴图的预制体目录时的瞬时内存占用；读取失败时也不会留下不完整的缓存状态，后续重新打开或保存贴图仍可正常重试。
• 隔离 C# 事件回调中的未处理异常： 编辑器原生事件调用 C# 处理器时，会在跨语言回调边界捕获未处理的托管异常，避免异常穿回 C++ 并终止进程；事件数据也会在异常路径中可靠释放。捕获到的异常会记录事件名、异常类型、消息和托管调用堆栈，并注册到 Themis 自定义日志上传，便于后续从崩溃报告继续定位具体 C# 故障。
• Themis 自定义 C# 日志可以完整保留到崩溃回调： 修复 Themis 初始化时过早清空 Exception / WinUIException 日志路径的问题。编辑器启动阶段产生的 C# 初始化异常日志现在会继续保留，原生崩溃发生时可随自定义日志上传，便于关联启动异常与后续崩溃。
• 修复了一个批量删除场景树对象时的索引越界问题： 同时选中父子节点或多个层级对象后执行删除时，场景树选择状态与节点集合更新相互重入，可能触发索引越界异常。删除前会先清理界面选择，并合并父子节点的重复删除范围，场景对象与树节点现在可以稳定移除。
• 修复了一个更新页关闭后继续处理下载进度回调的问题： 编辑器启动完成、更新页关闭或应用退出时，页面已经从窗口移除但界面绑定仍继续监听进度数据，可能在后续下载回调中触发 WinUI 异常。更新页现在会先停止界面绑定，再以幂等方式清理 WebView2 初始化、事件和窗口资源。
• 修复了一个脚本重载后刷新 UI 资源访问失效查找器的问题： 编辑器 Lua 状态重载后，地图资源缓存仍可能使用已经释放的资源路径查找器，导致重命名 UI 视口或刷新关联图片时发生访问冲突。编辑器现在会在旧查找器释放前解除绑定，并在新查找器创建后重新绑定。该调整仅作用于编辑器脚本状态，不改变正式客户端游戏局的资源查找流程。
• 修复了一个反复进入 PIE 或重建动态界面后的旧控件引用问题： 旧版节点画布等编辑器界面删除、重建控件后，界面即时构建状态仍可能复用同 ID 旧控件引用，随后在刷新子控件时发生原生崩溃。控件引用现在会随对象销毁自动失效，复用界面节点前也会校验当前控件仍是同一对象。
• 修复了一个退出 PIE 后刷新 UI 资源使用临时游戏局路径的问题： PIE 会避免把长期存在的编辑器地图资源缓存绑定到临时游戏局的资源路径查找器；结束游戏局后，重命名 UI 视口或刷新图片缓存会跳过已释放路径。正式 SCEGame 的 GamePlay_Game 仍按原流程绑定和清理自己的地图资源缓存，普通游戏局的创建、重连与退出生命周期不变。
• 修复了一个删除骨骼绑点时访问失效引用的问题： 项目资源中的骨骼模型删除绑点时，模型切换或节点移除后残留的失效绑点引用可能被再次访问，导致编辑器发生原生崩溃。绑点删除、查询和显示流程现在会跳过并清理已经失效的引用。
• 修复了一个导入蒙皮信息不完整 FBX 时访问空数据的问题： FBX 包含蒙皮数据但缺少有效骨骼簇时，编辑器仍按骨骼模型访问空数据并可能触发原生崩溃。导入器现在会检查全部蒙皮数据、过滤无效骨骼簇，并在完全缺失时按静态模型继续导入并记录警告。
• 修复了多个 Windows 编辑器长时间运行后的稳定性问题： 地图编辑器恢复缓存场景时会重新绑定当前场景和地形、灯光等依赖，避免旧场景释放后继续被灯光组刷新路径访问；C# 资源选择桥接会在每次调用时重新获取当前 Lua 状态，降低脚本重载后访问失效 Lua VM 的风险；D3D11 纹理更新会跳过空资源、越界区域和过期层级更新，避免资源导入或同步期间把无效更新提交给显卡驱动；Blazor WebView 窗口关闭清理中的异常会被记录并隔离，降低编辑器退出阶段被托管清理异常终止进程的风险。
• 取消关闭编辑器时会保留主界面： 从 Windows 任务栏右键关闭地形编辑器并在保存确认中选择“取消”后，顶部菜单栏不会再被提前清空。编辑器主窗口现在会先完成可取消的关闭确认，再释放窗口内容；其他需要阻止关闭的 WinUI 编辑器窗口也可以复用同一关闭请求入口。
• 修复了一个触发编辑器地图加载期间的延迟引用竞态： 固定选择数据初始化和其他类型解析路径同时处理延迟引用时，可能出现未观察任务异常；并发首次解析现在只会完成一次目标绑定。

2026-08-05 ～ 2026-08-11（已发布至线上正式环境）

客户端能力版本

• 当前最新客户端能力版本： 1。
• 本周期是否提升： 是，客户端能力契约从基础值 0 提升到 1。
• 新增能力映射： HostDisconnectedEvent → Game.OnServerDisconnected / EventServerDisconnected；SceneGraphReplicationEvents → SceneGraph.OnRegistered / OnUnregistered 等服务端发布图注册能力。两项能力都要求版本 1，CapabilityVersion == 0 的旧客户端仍按不支持处理。
• 如何判断兼容边界： CapabilityVersion 主要用于展示和诊断；需要项目主动调用的新客户端能力应优先使用 ClientEnvironment.Runtime.Supports(...) 判断。客户端更新多数不是强制更新，只有平台明确完成强制更新后，不高于该保证基线的能力才可以视为目标环境必定存在。兼容判断与维护规则见客户端二进制兼容与能力版本。

本期重点速览

本周期重点扩展了 GameGraph 的 Urho 兼容 API，让不依赖 Unit / 技能系统的场景图与物理玩法更容易同时覆盖客户端和服务端；编辑器侧补齐了 UI 布局属性往返、地形作者投影检查与导入预览，以及数据、触发器和场景树中的常用创作操作；客户端能力版本提升到 1，项目可安全监听断线和服务端发布图事件；GameUI 也新增 UI.Page() 统一完整页面的根容器写法。与此同时，本周期集中修复了代码生成、场景克隆、物理查询、几何与渲染边界、单位模型切换和移动端启动等稳定性问题。

重点：GameGraph Urho 兼容 API 扩展

不依赖 Unit / 技能系统的 2D、3D 玩法和底层表现逻辑，现在可以更直接地使用 GameGraph 组织场景图、组件与物理逻辑。扩展沿用 Urho 开发者熟悉的 SceneGraph → Node → Component 心智模型，但保留星火的高层 GameCore 路线、资源格式和端侧边界，并不是对原生 Urho 全部 API 与底层子系统的一对一复制。

• 双端场景图与物理能力更完整： Node、SceneGraph、组件层级与变换、Serializable / Variant、常用数学几何、3D Physics 和 2D Physics 补齐了更多查询、复制、属性和碰撞能力，适合服务端权威 SceneGraph 与客户端表现共享代码结构。
• 客户端可以接收服务端发布图： 服务端通过 SceneGraph.Publish(player) 显式发布的独立脚本图，可以在客户端通过 SceneGraph.OnRegistered / OnUnregistered 观察注册与注销，并通过 GetRegisteredSceneGraphs() 获取已经到达的发布图；这些入口不代表当前 SCE 场景的切换或卸载。
• 客户端表现 API 覆盖扩大： 材质、模型、动画、Octree、Billboard、Decal、Text3D、Terrain、纹理和渲染相关能力得到补充；Text3D 是场景中的可渲染文字，不是 GameUI 控件。资源内容、GPU 对象和实际渲染操作仍以 api/client / api/server 声明的端侧范围为准。
• 从 GameCore 对象进入底层控制： Unit.GetNode()、Scene.GetSceneGraph()，以及 Actor 的 GetText3D()、GetSoundSource()、GetAnimatedModel()、GetAnimationController() 等扩展方法，可以在保留高层生命周期和业务语义的同时进入 GameGraph 精细控制。
• 引擎属性与业务属性各自负责不同状态： Node、SceneGraph 和组件的 Serializable / Variant API 用于引擎对象属性、场景保存与克隆、原生网络属性；Unit 属性、PropertyObject 与 PropertyHostComponent 仍是游戏业务状态、变更监听和框架同步的推荐入口。
• 音频能力按端侧拆分： SoundSourceComponent、SoundSource3DComponent 和 SoundListenerComponent 的部分状态与控制可以双端使用；SoundResource、按资源播放、AudioManager 和实际声音输出仍为客户端能力。
• 粒子与骨骼动画遵循星火资源管线： API 保留 Urho 式的资源、组件、动画状态、层级、权重和骨骼遮罩用法，但资源格式、运行时 Builder、表现管线和角色动画能力应以星火 SDK 声明及专题文档为准。
• 配套文档与 AI Skill 同步更新： GameGraphOverview.md、粒子 / 音频 / 骨骼动画专题，以及 client-scenegraph-game、wasicore-game-architecture Skill 已补充 Urho 兼容心智、星火差异和端侧边界。

客户端断线处理

客户端项目现在可以在已经建立的游戏服务端连接断开时及时清理本地状态、关闭临时界面或提示玩家重新连接。该能力仅属于客户端运行时，不改变服务端连接处理逻辑。

• 监听已经建立的连接断开： 新增仅客户端可用的 Game.OnServerDisconnected 事件；使用触发器事件体系时也可以订阅 EventServerDisconnected。两者表示同一次 Host 连接断开，不用于描述尚未连接成功的尝试，也不应重复执行同一份清理逻辑。
• 旧客户端由框架完成初始化门禁： 框架只在客户端初始化注册底层断线事件时检查能力版本；不支持该能力的旧客户端不会注册事件，也不会因为加载新依赖库而启动失败。项目可以直接订阅公开断线事件，无需再自行比较 BinaryVersion 或 CapabilityVersion。

GameUI 页面根容器

完整页面过去常用 Panel 直接 AddToRoot() 后再手动铺满视口，容易把页面根布局与页面内部布局混在一起。本周期新增专门的页面根容器，将菜单页、整屏 HUD 和全屏遮罩的根节点语义统一下来。

• 完整页面优先使用 UI.Page()： 新增 Page / UI.Page() 作为 viewport 级页面根容器，挂到 UI 根节点后会保持占满视口的页面语义，适合菜单页、整屏 HUD、全屏遮罩和代码创建的完整界面。
• 普通控件仍可独立挂载： 非 Page 控件依然可以通过 AddToVisualRoot() 添加到 UI 根节点，原有挂载方式保持兼容；但对于完整页面、菜单或整屏 HUD，不再推荐直接把普通 Panel 作为页面根，最佳实践是使用 UI.Page()。
• 页面内部继续使用普通布局容器： Panel、VStack、HStack 和滚动容器仍负责页面内部布局；需要占满页面剩余区域时，将它们放入 Page 后再调用 FillParent()。需要“宽度铺满、高度可滚动”时，应让 Page 包含滚动容器，而不是让页面根本身承担滚动语义。
• 示例与迁移指南统一采用新写法： FluentUILayoutGuide、03-UI-SYSTEM、ui-layout-api、migrate-1to2 及多份 map_templates 示例已改用 Page 作为完整页面根容器。Canvas 的整屏绘制路径不变，仍使用 canvas.FullScreen()。

UI 编辑器创作模式

UI 编辑器创作模式继续扩展有来源控件的布局编辑范围。项目可以在真实 PIE 中预览布局变化，再把结果写回 DataManager 源数据；原生投影失败时会回滚数据，避免预览状态和项目配置不一致。

• 编辑外边距和水平 / 垂直对齐： Workbench 新增 Layout.Margin、HorizontalAlignment 和 VerticalAlignment 编辑，可将变化投影到同一来源定义的实时控件实例，并纳入 DataManager 的撤销、重做和保存链路。当前只开放可解析来源且已有明确布局数据的控件，不会为缺失或异常的可空字段静默创建新值。
• 对齐值可以稳定生成和往返： 对齐设置现在以 Left、Center、Right、Top、Bottom、Stretch 等枚举名保存，不再因写入数字序号而被代码生成器注释掉；重新加载、撤销和重做后仍能保持类型明确的对齐配置。

地形作者投影与自动化

在地形作者投影的保存与回写基础上，编辑器 MCP 现在可以先检查场景、产物和冲突状态，再决定是否进入外部修改或导入流程。检查与预览工具均为只读，不会保存地图、改写投影或触发导入。

• 列出并检查项目地形场景： 新增 terrain_list_scenes、terrain_get_scene_summary、terrain_get_artifact_status 和 terrain_validate_scene，可查看场景显示名、SpaceModel、当前打开状态、投影文件、manifest、源 map.acmap 与哈希一致性，并严格校验 PNG 图层和装饰物 JSON。
• 导入前预览冲突和变化范围： 新增 terrain_preview_projection_import，用于当前打开场景。工具会先区分 projection 已修改、源地图已修改、双方均修改或场景仍有未保存改动等状态；满足安全条件时，再返回变化图层、地形值变化数量和装饰物变化估算，不会直接应用修改。

场景编辑器

• 镜头重命名和删除直接维护场景数据： 场景树会显示数编中的镜头名称，重命名会写回对应 DataManager 条目；删除只对当前场景可删除的私有镜头开放，并增加确认提示和“至少保留一个镜头”的保护，继承或模板来源的镜头不会被误删。
• 修改场景名不再误报外部文件变化： 在地形编辑器右侧属性面板修改场景名并保存时，不再偶发弹出要求重载整个地图的提示。

触发编辑器

GameSparkCore 和 GameSystemUI 的更多公开能力现在可以直接在触发器中选择，减少 API 已经存在、但节点列表不可见或引用无法选择的情况。

• 更多常用系统能力可直接用于触发器： 扩充 GameSparkCore / GameSystemUI 在触发编辑器中的可用内容，覆盖单位、技能与 Buff、物品背包、AI、移动输入、卡牌、对话、聊天和商城 UI 等常用系统；例如可以使用 GetChild(...) / GetChildren(...) 查询 UI 控件子节点，也能直接选择更多单位操作、技能摇杆、移动控制与商城交互方法。AI、技能、角色、伤害类型、飘字、状态条和物品品质等常用默认数编资源也可以作为引用选择。
• 导出声明顺序在保存后保持稳定： 触发 API 的额外 UI 元数据现在会保存并恢复 Order，加载后按声明顺序重新排列文件树，避免地图库声明经过 sidecar 保存或重新导出后退回文件扫描顺序。
• 新建项目模板不再出现未知定义： 修复新建 game_entry 项目后，客户端“游戏开始时初始化”触发器中的移动控件和技能摇杆调用可能显示为“工具函数·未知定义”的问题；模板现在可以正确识别并编辑这两个调用。

数据编辑器

GameSystemUI 的常用业务配置会更完整地显示在数编蓝图节点中，项目可以直接搭建和检查商店、技能摇杆、移动控制、Buff、卡牌、背包、对话与聊天配置。

• 更多属性可在节点卡片中查看和填写： GameDataShop、GameDataShopCategory、GameDataShopItem、GameDataPeriodShopItem、GameDataLobbyResource 等节点现在会显示商店名称、图标、分类、商品、购买消耗、奖励、限购、有效期、周期领取和货币类型等字段；技能摇杆、移动控制、Buff、卡牌、背包、对话与聊天相关字段也同步补齐。
• 在文件树中直接新建数据： 可创建文件的分类和文件夹节点现在会显示快捷新建按钮，不必先打开右键菜单即可创建对应数编条目。
• 撤销和重做会正确更新未保存状态： 保存后再撤销到更早版本时，DataManager 会重新标记存在未保存修改；重做到已保存版本时会清除该状态，避免误以为修改已经保存或反复提示保存未变化的内容。移动数据表等跨文件操作也遵循同一版本判断。
• 泛型隐式值可以正确生成代码： 对支持隐式转换的泛型字段，例如数值包装类型，数据生成器现在会解析具体类型参数并生成有效赋值，不再把本可用的配置注释为无法生成。

客户端下载入口

星火对战平台官网现在直接提供当前客户端的版本化下载地址，避免固定中间页或浏览器缓存继续返回旧版本；iOS 入口也已恢复为可用的 App Store 下载按钮。

• PC 与 Android 使用版本化直链： 本周期将 spark.taptap.cn 首页更新为 PC 版 260804 和 Android 版 76 的直接下载地址，并在按钮文案中显示版本号。
• iOS 入口恢复下载： 首页按钮现在打开星火对战平台的 App Store 页面，不再显示“iOS 版敬请期待”。
• 首页更新更及时： 首页 HTML 增加 no-cache / must-revalidate 响应头，降低浏览器长期缓存旧下载链接的概率。

稳定性与兼容性修复

• 编辑器原生崩溃诊断链路恢复： Windows 下载版编辑器重新接入 Themis 原生崩溃上报；未处理的原生异常会上传 MiniDump，SCE / SCEEngine 符号也会随对应版本同步，使后台能够解析函数名和源码位置，降低本地转储写入失败后无有效堆栈可查的问题。
• 脚本异常日志恢复完整： 修复游戏脚本运行状态重新初始化后，后续 WASM 异常可能无法写入运行日志的问题，便于继续定位脚本调用和接口绑定错误。
• 场景克隆不再因特殊节点崩溃： 修复通过 Node.Clone() 克隆包含特殊节点类型的层级时可能崩溃的问题；克隆结果会继续保留名称、标签、变换和自定义变量等基础节点属性。
• Shader 源码按实际长度读取： 修复预处理 Shader 缓存缺少结束标记时可能继续越界读取的问题，异常缓存不再引发非法访问。
• 无效 2D 碰撞体输入会安全跳过： 创建链形或多边形碰撞体时，链形少于 2 个点、多边形少于 3 个点将不再继续创建；补齐有效顶点后仍可正常使用。
• CustomGeometry 拒绝无效几何索引： 空几何、当前索引失效，或传入索引等于几何数量时，不再发生越界访问；相关顶点属性写入以及 BeginGeometry / DefineGeometry 调用会安全失败。
• 空绘制批次会被安全跳过： 空文本、空描边等没有有效顶点的矢量绘制不再继续提交，避免潜在渲染异常或崩溃。
• 物理查询无命中统一返回空数组： PhysicsWorld2D.QueryAABB、2D / 3D RaycastAll，以及 3D OverlapSphere、OverlapBox、GetCollidingBodies 不再把空结果错误解码为 null 并抛出 NullReferenceException；单结果 Raycast 的无命中语义保持不变。
• 单位模型切换正确识别完整哈希： 修复部分 GameDataModel ID 的 32 位确定性哈希最低字节为 0x00（例如 0x87742C00）时模型未能切换的问题。该修复随客户端版本发布；尚未更新客户端的玩家仍遇到问题时，项目可以临时修改受影响的模型数据 ID（例如在末尾追加字符）并重新构建发布，同时确认新哈希最低字节不再为 0x00。
• 移动端启动稳定性提升： 修复 Android / iOS 客户端在部分机型上启动游戏局时可能发生崩溃的问题。
• 行距配置说明更准确： 修正 GameDataControlLabel.LineSpacingRatio 的属性说明：0 表示使用字体默认行高，0.5 表示 1.5 倍默认行高，1.0 表示 2 倍默认行高，避免将 1.0 误解为默认行距。

2026-07-29 ～ 2026-08-04（已发布至线上正式环境）

本期重点速览

本周期重点是扩展可复用表现、渲染和迁移工具链：GameGraph 补齐透明背景画中画与保留渲染到纹理透明度的渲染链路；GameUI 在停止 PIE 时会自动清理项目 ui/ 普通图片缓存，并新增同一 PIE 内替换散图后的手动失效 API，方便代码和自动化连续验证图片修改；1.0→2.0 项目迁移 Skill 系统梳理数据映射、表现资源和验收边界；编辑器与数编工作流则补齐地形作者投影、Blazor 注释画布、触发器生成诊断和 2.0 JSON 保存边界。

编辑器体验

• 主界面聚焦星火 2.0 常用功能： 移除编辑器主工具栏和“模块”菜单中的“预制功能库”入口。该功能展示的是星火 1.0 预制依赖库内容，不属于 2.0 项目的工作流，主界面不再提供相应入口。
• 性能监测框不再显示过时的 1.0 统计： 编辑器内调试的性能监测框移除“Buff 数量”和“服务端 GC 次数”。星火 2.0 的 Buff 已由 WasiCore 层实现，不再使用旧 C++ Buff；原“服务端 GC 次数”统计的也不是服务端 Lua VM 的完整 GC 轮次，而是旧 Lua 单位 userdata 触发回收 C++ LightUnit 的次数，两项数据在 2.0 项目中均不再具有诊断意义。Ping、FPS、服务器负载、Jank 等其余性能指标保持不变。
• 技能动画可自动进入模型烘焙清单： 资源统计现在会尝试沿 GameDataUnit.Model / Abilities → GameDataAbility.Animation → GameDataAnimation 动画素材展开引用，把单位模型与其技能动画合并写入 ref/model_animation.json，不再只依赖 GameDataModel.HumanoidSourceAnimations。该能力属于编译期静态分析，helper、工厂、运行时条件或动态集合等复杂写法仍可能无法覆盖；关键动画可以继续显式加入 HumanoidSourceAnimations 作为保险，也可以手动维护 model_animation.json 后在编辑器中只执行“工具 → 资源统计和动画重定向 → 生成”。再次统计资源会覆盖手工清单。

SCE 地形作者投影

SCE 地图保存现在会同时维护一份稳定、可往返的地形作者投影，方便外部工具或自动化流程处理高度、地表、边界、瓦片样式和静态装饰；客户端仍以 scene/<scene>/map.acmap 为运行时来源，不会把编辑器投影误当成新的客户端地图格式。

• 保存时自动导出作者投影： 编辑器会在 editor/terrain/scenes/<scene>/ 生成 manifest.json、height.png、surface.png、edge_h.png、edge_v.png、style.png 和 decorations.json。清单记录地图尺寸、层级、编码、样式调色板以及源 map.acmap 的哈希，便于外部工具安全判断输入是否仍匹配。
• 外部修改可回写地图： 重新打开地图时，如果 map.acmap 哈希未变化而投影内容发生变化，编辑器会校验投影清单并把高度、地表标记、边界标记、瓦片样式和静态装饰回写到 SCE 地图，再刷新脏地形并标记地图待保存；非 SCE 地图不走这条路径。

UI 编辑器创作模式

在前一阶段的控件选择、层级查看和 MCP 定位基础上，UI 编辑器创作模式已经形成有来源控件的早期编辑闭环：先在真实 PIE 中预览原生投影，再提交 DataManager 源数据，投影失败会回滚源数据，避免只改预览而丢失项目配置。运行时动态控件、未解析来源和复杂交互仍保持只读或需要普通客户端验收。

• 编辑控件透明度、位置和尺寸： 选中有来源的 GameUI 控件后，可以在 Workbench 调整 Opacity、Layout.Position.Left/Top 与 Layout.Width/Height；位置和尺寸也支持在 PIE 画布中拖动 / 缩放，修改会同步到实时实例和 DataManager。
• 撤销、重做和保存保持同一条数据链路： UI Authoring 现在支持编辑变更的 Undo/Redo、保存与重载，PIE / overlay 焦点和快捷键会把撤销、重做、保存操作路由到创作会话，避免误操作游戏或编辑器其他面板。

GameUI 图片开发调试

GameUI 会缓存已经加载的图片。停止 PIE 时，编辑器现在会自动失效当前项目 ui/ 下的普通图片资源，下一局可重新加载；如果要在同一轮 PIE 内覆盖同路径图片并立即继续验证，则可以由项目代码主动失效单张图片缓存。

• 同一 PIE 内手动刷新替换后的 UI 图片： 新增仅客户端可用的 GameUI.ImageCache.Invalidate(imagePath)。开发者或自动化工具覆盖项目 ui/ 下的同路径普通散图后，可以传入控件或 Canvas 使用的逻辑路径，让当前 GameUI 视图在下次使用时重新加载图片。该接口主要保证普通文件散图，不是图集、打包图片、Spine、字体、GameGraph 或所有原生缓存的通用重置 API；RT: 运行时纹理继续使用 RuntimeTexture.Unregister(...)。完整用法见 项目资源路径指南。

触发编辑器

• “任意”值可以直接参与表达式计算： “任意”类型的局部变量和字典取值现在可以直接用于加减乘除、取余、乘方和比较等表达式，编辑器也允许将它们放入相应的计算槽位。例如，读取 dict["x"] 后可以通过 dict["x"] + 5 继续计算，并将结果用于后续语句。运行时实际值仍需支持对应运算；dict["x"] += 5 一类复合赋值不在本次调整范围内。
• 代码生成问题可在编辑器内定位： 触发器生成后如果存在诊断，状态栏会显示问题数量，下方问题面板列出可复制的诊断，并支持点击跳回对应源节点；生成代码仍保留 #error 定位信息，便于修复后重新生成。没有问题时面板会自动清空。
• 嵌套表达式和语句拖拽更容易操作： 嵌套表达式会按层级高亮并支持点击选中、括号范围反馈和整组拖拽；条件表达式拖入动作列表时会按需要转换为可执行语句并支持 Undo，语句排序和拖入空动作列表的有效落点也扩大到整行和列表末尾。
• 变量显示设置和局部变量保存更可靠： 单独修改“作为全局变量显示”会正确标记并保存，局部变量默认值与声明跳转也不再触发错误的选择语句弹窗。

数据编辑器

Blazor 版节点画布现在可以把注释作为真正的可持久化画布节点使用，帮助项目把复杂数编结构按区域组织，而不必退回到截图或手写布局信息。

• 创建和维护注释节点： 支持从画布菜单新建注释、双击编辑文字、调整大小、复制 / 粘贴和删除；注释会保存到 DataManager JSON，并纳入撤销 / 重做。
• 用注释组织节点和自动排版： 节点可以拖入或移出注释，移动注释时会带着其层级内节点一起移动；自动排版可针对注释内部内容计算位置并同步调整注释边界。向量字段同时改为自适应宽度并隐藏数字微调箭头，减少窄面板中的挤压和溢出。

2.0 数据保存边界

2.0 项目的单位和区域数据现在由 DataManager JSON 负责持久化。编辑器保存地图时不再从旧版单位 / 区域 Lua 序列化场景数据，也不再生成或覆盖 unit_save.lua 与相关 .sceneconfig，避免旧 Lua 链路覆盖现有 2.0 场景兼容文件；1.0 旧项目的迁移仍按迁移指南执行。

GameGraph 透明画中画准备

• 新增 EngineRes/RenderPaths/GameOverlay.xml，供直接附加的 Viewport 叠加角色或其他局部场景使用；该路径只清理深度、保留已有颜色，并移除 Bloom 等全屏后处理。
• 新增 RenderTargetFormat 与 Texture2D.CreateRenderTarget(..., format) / ResizeRenderTarget(..., format)，Rgba8、Rgba16F 和 Rgba32F 可用于保留 RenderToTexture 的 alpha 通道。旧的 highDynamicRange 重载保持兼容。
• 新增透明画中画指南与 AI Skill，并提供 RenderPath、KnownTechniquePath 对应 Technique、默认 Material 和光照预设的可读 XML 参考副本；code_sample 的 RendererViewportSample 增加普通与透明 PIP 并排对照。
• 材质 API 正式区分 Technique XML 与真正的 shader：项目代码使用 Technique、KnownTechnique、KnownTechniquePath、Material.Technique 和 SetPass*；未来的 shader source、stage、variant 与运行时编译能力使用独立命名空间。
• 本次不修改 Bloom shader 或 shadercache；需要透明 Bloom 的 alpha resolve 仍待 shader 编译资源恢复后单独处理。

自动挂载模型表现

装备、携带物、Buff 或单位自带的额外模型现在有统一的对外配置说明，帮助项目把手持物、背饰、披风、头饰和整套外观接入单位或物品的表现生命周期。

• 按数据配置自动显示和清理： 使用 GameDataActorAdditionModel 定义附加模型，再通过单位或物品槽位的 ActorArray 配置；物品换槽、失效或丢弃时由框架自动维护对应表现，不需要额外编写客户端常驻创建/销毁逻辑。
• 明确模型资源制作要求： 附加模型应使用目标宿主的原始骨架，在 Bind Pose 下定位并蒙皮到与宿主一致的骨骼；骨骼名称、坐标轴、单位和初始变换必须匹配，并导出带 Skin 和骨骼的 FBX。该功能不是只给普通静态模型设置局部偏移。
• 明确挂接字段边界： 这条自动挂载模型表现路径通常只需要填写 Model；无需填写 Socket，填写也不会改变结果，位置和骨骼跟随由美术资源决定。CullHostMesh 可用于整套外观、外套或披风覆盖宿主主体时减少重叠显示。
• 补充 SDK 文档与 AI Skill： 新增 自动挂载模型表现 和对应 AI Skill，并在 Actor、物品系统文档中补充入口与公开字段说明。

1.0 → 2.0 项目迁移 Skill

迁移指南现在把“数据映射、运行逻辑和客户端表现”分开验收，并补充旧项目资源与发布链路的迁移边界，帮助 AI 助手避免只完成代码翻译却遗漏实际入口、表现资源或发布依赖。

• 补齐迁移台账与表现验收： migrate-1to2 Skill 新增可达性、生命周期、重复触发、客户端可见性、资源依赖闭包和按功能类型选择证据的质量门槛，并区分 source-mapped、compiled、runtime-smoke-passed 与 accepted。
• 明确旧项目资源复制边界： 迁移时应按相对路径合并复制 1.0 工程的 res/，并一并迁移 ui/image/、ui/spine/ / ui/Spine/ 及其配套资源；复制后通过 Client-Resource 检查 ref/objref.txt，同时记录同名资源冲突和目标环境的云端资源可用性。
• 修正场景与 UI 迁移口径： 1.0 默认不涉及 Volumetric3D，不要求生成 3D 场景派生产物；2.0 UI Authoring 已进入工具链但仍属早期能力，复杂交互继续要求普通客户端运行时验收。

其他修复

• 修复停止 PIE 时按地图打包目录而非项目根目录清理 UI 图片资源、导致部分项目第二次调试时 Canvas 图形正常但中央图片缺失的问题。现在会按当前项目的真实 ui/ 路径失效普通图片缓存，并继续兼容地图目录下的 ui/ 资源。
• 2.0 单位状态条不再强制依赖旧血条绑点： API 版本不低于 2000 时，客户端会优先使用模型的 socket_status_bar 定位单位血条和状态条，并继续兼容旧模型的 socket_blood_bar；两个绑点都不存在时会以单位根节点为默认位置，不再因此跳过状态条创建。1.0 项目保持原有行为，没有绑点时不创建状态条。需要显式调整高度或屏幕偏移时，仍可通过模型数据的 CustomStatusBarPosition 覆盖默认定位策略。
• 补充碰撞事件初始化时序说明： PhysicsSystem 文档、直接 GameGraph 与服务端权威物理 AI Skill 现在明确提醒：OnCollisionBegin / OnCollisionBegin2D 只表示接触开始，不会回放订阅前已经发生的初始接触。创建动态碰撞节点时应先注册事件，再让刚体和碰撞形状进入活动物理模拟；如果需要处理初始重叠，应在订阅后额外执行 overlap 查询。
• 修复单位初始状态配置 UnitState.IgnoreSelector 后，客户端可能将其错误识别为隐藏模型、导致单位不可见的问题。现在该状态只会让单位忽略选择器，单位模型仍正常显示。
• 修复 GameSystemUI 默认技能摇杆组在本地玩家主控单位切换后没有及时重绑、以及单位后续附加技能没有自动重刷按钮的问题。现在 UseMainUnit 模式会跟随主控单位变化重新绑定，并在当前绑定单位上监听技能附加 / 移除事件，客户端已经复制到的技能会及时出现在技能按钮上。
• 修复仅服务端通过 GameGraph 创建原生 2D 物理组件时组件工厂未注册的问题。SceneGraph.CreateComponent<PhysicsWorld2D>() 不再返回 null，RigidBody2D、2D 碰撞形状和约束等同属 Urho2D 的组件也可以在服务端正常创建。
• 无效 UI 设计分辨率不再导致客户端假死： ScreenViewport.SetDesignResolution(...) 现在会拒绝非有限值和小于 1 的宽高；客户端遇到窗口尺寸暂时为 0 的情况时也会保留有效缩放，避免 DevicePixelRatio 变成 0 或无限值并传入底层全局缩放。
• 修复客户端在异步分块加载期间切换场景或清理地图缓存时，可能因继续向已卸载场景添加节点或组件而触发 Windows 原生崩溃的问题。现在单帧加载会稳定持有正在处理的场景与构建器，场景缓存遍历使用稳定快照；如果节点事件回调切换或清理了当前世界，则停止旧场景的后续分块加载与导航处理。
• 修复 Android 客户端在异步地形分块加载与切换场景 / 清理地图缓存交错时，可能因地形顶点颜色数据提前释放而触发 SIGSEGV 原生崩溃的问题。现在会先等待地形异步任务结束，再释放场景构建数据，避免对战过程中退场或切图访问失效的地形数据。
• 修复 Windows 客户端在极少数瞬态顶点缓冲资源创建失败或生命周期异常时，D3D11 上传空资源可能导致崩溃的问题。现在会跳过无效上传，并补充资源创建、销毁与提交诊断信息，便于进一步定位设备异常或资源时序问题。
• 修复 Windows 客户端在 D3D12 分辨率或窗口状态变化期间，交换链重建失败后继续访问无效 back buffer、导致 RendererContextD3D12::postReset() 原生崩溃的问题。现在会检查 ResizeBuffers / GetBuffer 结果；设备丢失时跳过当前帧，其他重建失败会记录分辨率、格式和 reset flags，并等待下一帧重试。
• 修复 Windows 客户端启动时默认渲染路径 EngineRes/RenderPaths/Forward.xml 缺失、解析失败或未及时挂载时，渲染器继续解引用空资源并触发 0xC0000005 原生崩溃的问题。现在会在 RenderPath 和渲染器初始化边界检查资源与根节点，并输出明确的加载失败日志。

2026-07-22 ～ 2026-07-28（已发布至线上正式环境）

本期重点速览

本周期集中扩展客户端表现层、项目设置和服务端收口能力：项目代码现在可以通过 SCE 场景控制器安全调整地形、天气、光照和雾效，也可以用 ClientSettings 接管画质、音频和本地偏好，并通过 ClientEnvironment 访问打开链接、剪贴板、本地化、网络、电量和诊断等客户端环境能力；Widget 血条 / 飘字、3D SceneGraph 中的 2D 动画、激励视频广告和项目自定义托管程序集加载都有了成体系的能力、文档和 AI Skill；服务端新增同用户切局清理窗口，音频发布资源统计与数据编辑器节点画布也更贴近实际项目工作流。本期同时修复了一批编辑器、Windows 客户端、GameUI、UI 创作模式和粒子生命周期崩溃问题。

SCE 场景内置节点、地形、天气与光照运行时控制

这次补齐的是项目代码访问 SCE 场景内置节点的统一入口，覆盖地形、天气、光照和雾效等固定场景结构。普通 SceneGraph 不保证存在 __SCE_TERRAIN__、LightGroup、Weather、PointLights、DirectionalLight 等固定命名节点，因此高层 API 放在 Scene 扩展方法上；只有由 SCE 场景加载流程创建的 Scene 才应使用这些控制器。

• 通过场景获取内置节点和控制器： 新增 Scene.GetBuiltinNode(...) / Scene.GetBuiltinNodes(...) 以及 TryGetTerrainNode()、TryGetWeatherNode()、TryGetLightingNode() 等便捷入口；控制器侧提供 Scene.TryGetTerrainController()、Scene.TryGetWeatherController() 与 Scene.TryGetLightingController()。这些 API 基于 SCE 场景内置节点工作，找不到对应节点时返回 null 或 false，适合在地图加载完成后安全探测。
• 运行时读取和编辑地形表现与权重： SceneTerrainController 可从当前 SCE 场景进入地形运行时能力，读取地形材质、替换材质贴图槽，读取/设置普通 tile 地表 TerrainTextureWeights，查询主导贴图标签，刷新 dirty terrain，并操作 Landscape patch blend、Landscape weight map 像素和矩形涂刷权重。材质替换和地形权重操作用于当前运行时地形状态，不等同于编辑器地形资产保存流程，也不会自动同步为服务端权威玩法数据。
• 运行时调整天气、雾效和战争迷雾： SceneWeatherController 可读取/设置 TerrainData 天气效果、地形雾色、cloud shadow、Zone 雾效参数，以及创建和调整当前客户端战争迷雾；配套参数快照使用 SceneZoneFogSettings、SceneFogOfWarSettings 与 SceneEnvironmentMapSize。相关操作均为仅客户端运行时视觉修改，不同步服务器，也不会写回地图资源。
• 运行时调整光照、环境和 LightGroup 预设： SceneLightingController 可读取/写入主光源、点光源、Zone 雾效、环境贴图强度、角色 SH、Bloom、Vignette 等运行时参数，配套参数快照使用 SceneLightSettings、SceneZoneFogSettings 与 SceneZoneEnvironmentSettings，并支持直接加载或渐变切换 LightGroup/*.xml 预设。
• 查看文档和 AI Skill： SCE 场景内置节点、地形、天气与光照运行时控制 和 sce-scene-environment AI Skill 说明 Scene 与普通 SceneGraph 的边界、仅客户端/不持久化语义、常见代码示例和验证流程。

客户端游戏设置 API

WasiCore 客户端新增游戏设置 API，项目可以用它读取和修改画质、音频与本地偏好，也可以在此基础上编写自己的设置界面。

• 图形设置： 新增属性式 ClientSettings.Graphics，支持读取和设置画质预设、渲染分辨率、场景质量、粒子质量、动态光、HDR、抗锯齿、角色遮挡描边和帧率上限。MaxFrameRate 支持任意正整数；需要取消显式上限时使用 ClearMaxFrameRate() 或把属性设为 null，不要求项目代码记忆底层特殊值。
• 音频设置： 新增属性式 ClientSettings.Audio，可通过 ClientSettings.Audio.Music.Volume / .Enabled、ClientSettings.Audio.Voice.Enabled 或 ClientSettings.Audio[AudioChannel.Effects] 按音乐、音效、语音播放和麦克风通道控制音量与开关，音量统一使用 0 ～ 100。
• 项目本地偏好： 新增 ClientSettings.Preferences，用于保存轻量的项目自定义本地偏好，例如伤害数字开关、镜头灵敏度或 HUD 布局选择。偏好可以按当前游戏隔离，也可以显式保存为设备级偏好；不应用于云存档、付费状态、背包进度或服务端权威数据。
• 查看文档和 AI Skill： 客户端设置系统 和 client-settings AI Skill 说明仅客户端边界、平台设置面板关系、无变更事件的 UI 读取模式，以及图形 / 音频 / 自定义偏好的推荐用法。

客户端环境能力 API

WasiCore 客户端新增 ClientEnvironment API，项目可以用现代 C# 风格的门面访问当前玩家本地客户端的环境能力。这些信息只描述本地客户端，不同步服务器，也不应作为玩法权威数据。

• 打开允许的外部链接： 新增 ClientEnvironment.TryOpenUrl(Uri) 与 TryOpenUrl(string)。QQ 群加群页应使用 QQ 群分享生成的完整邀请链接，例如 https://qm.qq.com/q/xxxx；其中 xxxx 是 QQ 生成的分享码，不是群号本身。默认 URL 白名单非常有限，主要覆盖常见 QQ 群加群链接；游戏官网、问卷、活动页、客服页、社区页和其他应用链接都需要先申请或配置项目 URL 白名单，否则调用会返回 false 或由客户端提示无法跳转。
• 剪贴板与本地化： 新增 ClientEnvironment.Clipboard.Text / Clear()，可读写短文本；ClientEnvironment.Localization 使用 .NET CultureInfo 暴露 DefaultCulture、SystemCulture 和可写的 CurrentCulture，用于读取系统语言和切换客户端本地化语言。CultureInfo.Name 常见形式为 zh-CN、en-US，项目比较时应按大小写不敏感处理。
• 网络、电量和诊断快照： 新增 ClientEnvironment.Network、ClientEnvironment.Power 和只读 ClientEnvironment.Diagnostics.Current，可读取 Wi-Fi 状态、电池电量 / 充电状态 / 健康状态、FPS、ping、内存、draw call、流量和卡顿计数等信息。电池百分比和剩余时间等平台可能无法提供的值使用可空类型表示。
• 查看文档和 AI Skill： 客户端环境能力 和 client-environment AI Skill 说明 #if CLIENT 边界、URL 白名单和 QQ 群链接写法、CultureInfo 使用模式、只读诊断用途和常见验证流程。

Widget、单位血条与飘字

这次把单位血条和飘字从旧的固定 JSON 配置路线整理为 WasiCore 数据与运行时 handle 模型。项目可以继续通过数编配置单位血条和飘字模板，也可以在客户端代码里取得具体 Widget 并临时修改文字、图片、颜色、显隐和进度条；对于不依附单位的轻量提示，还新增了主动创建和销毁的无主血条能力。Widget 仍定位为轻量绘制组件，不替代 GameUI 控件系统或 Canvas 自由绘制路线。

• 用数据表配置血条和飘字组件： 新增独立 GameDataWidget 数据类型及 GameDataWidgetText、GameDataWidgetImage、GameDataWidgetBar、GameDataWidgetRuler 等节点类型；GameDataStatusBar.Widgets 与 GameDataFloatingText.Widgets 使用 Widget 链接组织模板，运行时代码按链接查找组件，避免依赖不稳定的名称或模板内序号。
• 直接修改运行中的 Widget： 单位当前血条可通过 unit.StatusBar 取得，FloatingText 和 StatusBarCustom 也提供一致的 GetWidget(...)、GetWidgetText(...)、GetWidgetImage(...)、GetWidgetBar(...) 与 WidgetCount / GetWidgetByIndex(...)。文本、图片、进度条 handle 分别支持 SetText(...)、SetImage(...)、SetPercentage(...)、SetSkinIndex(...)，通用 Widget 支持 SetVisible(...) 和 SetColor(...)。
• 在血条重建后重新接管 Widget： 单位血条新增 StatusBar.OnInitialized 与 StatusBar.OnDestroyed 生命周期事件。项目可以在初始化回调里重新获取文字、图片或进度条 handle，避免模板切换、关系变化或 native 实例重建后继续使用旧 handle；订阅 OnInitialized 时如果血条已存在会立即回调，未订阅时客户端不会启用 native 生命周期转发。
• 创建无主轻量表现： GameDataStatusBar.CreateStatusBarCustom(Vector3) 可在世界坐标创建独立血条，CreateStatusBarCustom(Vector2) 可在屏幕坐标创建独立血条；返回的 StatusBarCustom 支持移动位置和 Destroy()。这适合采集进度、场景标记、临时屏幕提示等轻量表现，创建者负责销毁，不会自动绑定某个单位生命周期。
• 飘字支持屏幕坐标和运行时组件访问： GameDataFloatingText.CreateFloatingText(...) 支持世界坐标、屏幕坐标和绑定单位三种创建方式，返回 FloatingText handle 后可以继续修改其中的 Widget。伤害、治疗、金币、经验等飘字仍可使用模板动画和叠加规则，代码只在需要定制显示内容时介入。
• 拆清文本显示字段： GameDataWidgetText.Font 现在只表示普通字体文件路径；图片字/数字图集前缀改用 ImageFontPrefix；前后缀字段改为 TextPrefix / TextSuffix。整数相关语义也区分为 DisplayValueAsInteger（只控制显示）和 ReadValueAsInteger（按整数载荷读取属性值），等级等整数语义字段应使用后者。
• 统一单位展示扩展字段： 新增 PropertyUnit.StatusBarDisplayName 与 PropertyUnit.StatusBarDisplayImage，用于绑定“显示在血条上的名字”和“显示在血条上的图片”。这让血条展示内容可以独立于单位真实名称、模型或其他业务字段，适合昵称、称号、头像和特殊标记等场景。
• 查看文档和 AI Skill： Widget、血条与飘字系统 和 widget-system AI Skill 说明 Widget 与 GameUI / Canvas 的边界、Widget 数据配置、属性绑定、运行时 handle 生命周期、资源路径和常见排查方式。

GameGraph 2D 动画与 3D 场景中的 Spine

这次补齐的是把 2D 动画当作 3D 场景对象使用的路线。项目不需要先把 Spine 渲染成贴图再贴到模型上；当 2D 角色、特效或序列帧需要参与透视相机、远近缩放、深度遮挡，并与 3D 几何同屏时，可以直接在客户端 SceneGraph 中创建 AnimatedSprite2D。UI 层的 Spine 控件和 Canvas 绘制路线仍适合纯 UI 展示或全屏 Canvas 游戏。

• 在 3D SceneGraph 中播放序列帧和 Spine： AnimatedSprite2D 与 AnimationSet2D 支持加载 Spriter / SCML 序列帧动画，以及 Spine .skel / .json + .atlas 资源；项目本地资源优先按 UI 资源惯例放置，Spriter/序列帧放 ui/image/...，Spine 放 ui/spine/...，代码使用 AnimationSet2D.Load("image/...scml") / AnimationSet2D.Load("spine/...skel") 并保留扩展名。旧项目的当前项目 res/... 路径继续作为 fallback 兼容。Skin / SetSkin(...) 提供 Spine skin 语义入口，Entity 继续用于 Spriter entity 并保持兼容。
• 按 3D 世界变换参与相机和深度关系： StaticSprite2D / AnimatedSprite2D 位于节点世界变换中，不是自动朝向镜头的 billboard；透视相机会产生近大远小效果，也可以和 3D 几何形成前后遮挡关系。Layer / OrderInLayer 继续用于 2D 排序；Renderer2D 由 2D Drawable 渲染路径按需使用，普通项目通常不需要手动管理。
• 明确光照和调色边界： 默认 Urho2D 材质不受 3D LightComponent、Zone 环境光或阴影影响。要让 Spine 或 Spriter 更贴合当前 LightGroup，可通过继承自 StaticSprite2D 的 Color / Alpha 做手动乘色、压暗或淡入淡出；真正受光的 2D 角色需要项目自定义 shader 和额外资源设计。
• 查看文档、AI Skill 和完整示例： GameGraph 2D 动画组件 覆盖 3D 场景中的 Spriter / Spine 用法，资源路径指南 区分 UI Spine.Resource 与 GameGraph AnimationSet2D.Load(...) 的路径规则；2D 动画与序列帧选型 AI Skill 会在 UI、Canvas 和 3D 场景动画之间做路线分流；map_templates/code_sample 新增 AnimatedSprite2DSample，同时演示 Spriter 金币和 SpineBoy 放入一个 3D 盒子场景。

广告系统 API

这次新增服务端激励视频广告入口，面向观看广告后领取奖励、复活、刷新次数和双倍收益等玩法。项目代码不需要自己维护广告验证频道，也不要让客户端自证广告完成；服务端调用统一 API 后等待平台结果，只在结果达到奖励条件时发放奖励。

• 通过服务端请求激励视频广告： 新增 GameCore.AdvertisingSystem.Ads.ShowRewardedVideoAsync(player, timeout?)，返回 RewardedVideoAdResult。项目应在服务端 await 结果，并以 RewardedVideoAdResult.IsCompleted 作为是否发放奖励的判断；RewardedVideoAdStatus 可区分 Completed、RequestFailed、Timeout 和 Canceled。
• 按平台处理完成语义： Android 客户端成功发起播放后，服务端等待 TapADN 验证回调，验证匹配后才返回 Completed；iOS 按内嵌平台 SDK 的本地结果处理，SDK 成功发起播放后返回 Completed，明确失败时返回 RequestFailed。项目代码通常不需要为 Android / iOS 分别写发奖逻辑，统一检查 IsCompleted 即可。
• 明确测试环境边界： 当前真实广告播放链路仅可在线上正式环境测试；外网测试环境、Windows 编辑器、本地调试和其他缺少平台广告能力的环境不能作为广告播放成功验证环境。项目可以先接入服务端 API 和发奖逻辑，但真实广告验收需放到线上 Android / iOS 客户端。
• 明确调试和通道边界： 调试模式不会提前拦截广告请求；如果底层广告能力明确失败且 Game.IsDebugTestMode 为真，会额外写入 warning 日志并返回 RequestFailed。广告验证通道由框架和 Host 层单独处理，不应使用通用 ServerChannel 自行拼接或监听广告回调。
• 查看文档和 API 注释： 广告系统 说明服务端调用示例、结果状态、平台语义、调试模式行为和常见错误；公开 API 也补齐 XML 注释，方便在 API 参考和 IDE 提示中理解广告结果。

资源清单与 AI 音频约束

这次把音频随包资源的收集边界写得更明确：运行时播放配置可以继续动态组织，但需要发布进包的音效和音乐必须能被 Client-Resource 静态看到。这样可以避免 TapTap 内嵌客户端等正式包环境中，编辑器调试能播、发布包却缺少 sound/... 文件的情况。

• 轻量音频 helper 可被识别： Client-Resource 使用的 IFile 分析器现在可以识别传给轻量 helper 的字面量资源路径，前提是该参数在 helper 方法体里直接转发到 IFile / Sound 字段或属性，例如最终写入 GameDataSound.Asset。这不会扩展为扫描任意字符串、配置表、数组循环或运行时拼接路径，动态候选资源仍应使用静态资源表或显式清单。
• AI 生成音效代码有明确护栏： 资源路径指南、发布资源缺失排查指南、项目上下文模板和 wasicore-dev AI Skill 已补充约束：不要只在启动或运行时代码里临时 new GameDataSound / new GameDataActorSound 批量注册音效；需要随包发布的音频应进入静态 GameDataSound.Asset / GameDataActorSound 数据、Sound / IFile 字段或显式资源清单，并在新增后检查 ref/objref.txt。

项目自定义托管程序集加载

WasiCore 现在新增项目自定义托管程序集加载能力。项目可以把拆分出的业务库或项目自有第三方托管 DLL 按普通 .NET 依赖方式随 GameEntry.dll 一起部署，适合把大型玩法拆成多个业务库，或复用已经适配当前运行环境的项目自有托管库。

• 新增 GameEntry.dll 同级 DLL 加载层级： 服务端项目自有 DLL 放在 AppBundle/managed/，客户端项目自有 DLL 放在 ui/AppBundle/managed/，与对应端的 GameEntry.dll 同级。推荐通过 src/GameEntry.csproj 的 ProjectReference、PackageReference 或明确来源的 Reference 管理依赖，再使用编辑器正常编译、调试和发布流程部署。
• 按来源区分 SDK、依赖库和项目程序集： 项目自有 DLL 应使用项目自己的唯一名称，避开 SDK 自带程序集名称和项目依赖库 ID。若某个 DLL 名称对应项目依赖库 ID，该 DLL 由对应依赖库提供；SDK 与运行时组件由当前编辑器、SDK 和依赖库版本统一提供。
• 补齐调试排查和 AI Skill： 新增 自定义托管程序集 指南，说明服务端 / 客户端部署位置、命名规则、debug_start_no_compile 手动复制方式和常见排查；wasicore-dev 与 debug-tools AI Skill 已同步提醒 AI 在不编译调试时复制项目自有输出 DLL，并在用户自定义 DLL 已放入但没有生效时优先检查是否与 SDK 自带程序集或项目依赖库 ID 重名。

数据编辑器节点画布

这一组更新继续补齐 Blazor 版数据编辑器的节点化操作体验，让表现节点和服务端公式字段都能在同一套数编工作流里维护，减少回退到旧版编辑器或手写 JSON 的需要。

• 节点支持挂载表现节点： Blazor 版数据编辑器节点画布现在支持在节点尾部挂载表现节点，可新建表现节点、引用公共表现节点，并支持拖入 / 拖出、换父节点和删除等基础操作，进一步还原 1.0 数据编辑器的节点化操作体验。
• 服务端公式字段可正常配置： 修复数据编辑器无法配置服务端公式字段的问题。现在按字段所在端侧识别可配置类型，服务端专用的公式字段可以正常显示和编辑。
• 查看 AI 操作指南： 数据编辑器 MCP 与结构化数编操作可参考 SCE 数据编辑器 Skill 和 数编 MCP 工作流。

同用户游戏局切换清理

同一用户在同一游戏内切换到另一个游戏局时，旧局和新局都可能接触同一份用户云数据。项目如果只依赖普通退出事件，或旧局仍按周期保存所有玩家状态，容易出现玩家已经在新局继续游戏，但旧局稍后把旧快照写回 CloudData 并覆盖新局进度的风险。本期新增一个仅服务端可用的短时清理入口，让旧局在用户切换前尽力提交最后的用户级状态，并停止继续代表该用户写旧局快照；同时保持它只是清理机会，不承担匹配、邀请或进房裁决职责。

• 注册旧局用户级清理处理器： 新增 GameCore.GameSystem.UserSessionHandoff.RegisterCleanup(...)、UserSessionHandoffContext、UserSessionHandoffOptions 与 UserSessionHandoffReport。项目可以在服务端注册短小、幂等的异步处理器，用于提交 CloudData、释放用户级临时资源或写入离线快照；多个处理器支持按 Order 排序，并可设置单处理器 Timeout。
• 按 UserId 清理而不是依赖玩家槽位： UserSessionHandoffContext.UserId 始终可用，Player 则可能为 null。这让旧局即使已经找不到本局玩家对象，也可以继续按平台用户标识完成云数据收尾，避免把本局 Player.Id 或玩家槽位误当作持久用户标识。
• 明确切换等待、超时和诊断边界： 清理窗口发生在用户正式完成新游戏局连入之前，新局玩家连入事件不会先于旧局清理完成触发；框架会捕获单个处理器异常并继续后续处理器，整次请求受 UserSessionHandoff.DefaultRequestTimeout 限制，该值默认 3500 毫秒，也是当前允许设置的最大值，项目代码可以按需要调小。清理完成或等待超时后平台继续后续连入流程，因此这个超时不应被用作排队、审核或阻止进房机制；CleanupCompleted 提供日志和指标观察入口。关键玩家资产仍应在正常玩法流程中及时提交，切局清理只是额外收口窗口。
• 查看文档、AI Skill 和 API 注释： 同用户游戏局切换清理 和 user-session-handoff AI Skill 说明同用户切局、CloudData 保存、Player 可空、幂等处理、ServerChannel / 开放局 / 常驻局边界；复杂项目也可以配合 ServerChannel 和常驻协调局核算用户在多个游戏局间的实际状态。公开 XML 注释也已按对外 API 视角补齐。

其他修复

• 修正 WasiCoreSDK 文档和 AI 上下文中关于 Physics2D / Box2D 运行端的旧描述。Physics2D 与 3D Physics 均已支持客户端和服务端；服务端可以作为 Box2D 权威模拟端，客户端仍负责 Canvas / GameUI / 渲染表现，服务端结果需要通过 replicated Node / SceneGraph 或业务消息同步给客户端。
• 修复编辑器内“帮助 / 文档”、项目管理器使用手册和欢迎引导在线手册仍打开旧 1.0 文档站的问题。现在这些入口统一打开 https://doc-sce.taptap.cn/，避免从编辑器跳转到过期文档。
• 修复编辑器尚未打开地图时，自动更新流程、编辑器首页或 AI 工具执行 MCP 健康检查可能导致编辑器闪退的问题。现在未加载地图时也能安全完成健康检查。
• 修复 Windows 编辑器切换到较旧 API 版本后，可能无法打开项目并提示 lib_game_options 等官方库配置异常的问题。现在编辑器会正确获取当前 API 版本所需的编辑器资源，已存在的客户端资源不会再阻止编辑器资源更新。
• 修复 Windows 编辑器切换或更新星火 2.0 官方库时，若系统未启用长路径支持，可能因 GameSystemUI 等资源包内超过 260 字符的文件路径解压失败而反复更新中断的问题。编辑器启动后会在资源更新前检查当前长路径支持状态；未启用时会明确提示风险，并可协助开启 LongPathsEnabled，完成后重新启动编辑器即可继续更新。
• 修复客户端属性动画在同一帧销毁对象或控件，或替换、移除同名动画时，可能导致 TapTap 内嵌客户端崩溃的问题。GameUI 控件过渡、SCE 场景对象属性动画和项目资源中的 ValueAnimation 在这些情况下会更加稳定。
• 修复 Windows 客户端断线后多次重连失败并返回启动页时可能崩溃的问题。玩家在网络超时、重连失败或退回启动页时不再因此闪退。
• 修复 Windows 客户端窗口尺寸或分辨率变化后，立即退出游戏局、切换地图或清理 UI 单位场景时可能崩溃的问题。现在这些操作与窗口变化连续发生时会更加稳定。
• 修复 Android 客户端在分块异步加载资源期间退出游戏时，场景销毁仍可能提交待处理资源任务、访问已关闭的后台资源加载器并触发原生崩溃的问题。现在退出阶段会跳过已进入销毁流程的资源提交任务，并让后台加载器的摘除与并发提交安全串行化。
• 修复 Windows 客户端退出进程时，字体纹理可能在渲染系统关闭后才释放、导致 0xC0000005 原生崩溃的问题。现在字体相关资源会在 Graphics 关闭前完成释放，退出流程更加稳定。
• 修复 Windows 客户端或编辑器内调试中，CanvasAnimated 绘制回调、启动页切换、背包 / 快捷栏等 GameUI 同帧创建或移除控件时，UI 渲染遍历可能崩溃的问题。现在渲染收集会在遍历期间安全处理 UI 树变化，这类界面切换和运行时 UI 更新更稳定。
• 修复 UI 编辑器创作模式结束 PIE 会话时，Local runtime 可能没有完整触发 WASM / Lua 游戏结束清理，导致 GameUI 视图以及 Canvas / CanvasAnimated 底层绘制资源在编辑器不关闭的情况下持续占用的问题。现在停止创作会话会按正常游戏结束链路释放运行时 UI 资源，并在 WASM 状态销毁时兜底移除对应视图，反复进入和退出创作模式更稳定。
• 修复 Windows 客户端后台加载字体等资源时，UI / AnimationSet2D 路径搜索按需刷新资源目录与异步加载并发，可能在字体参数加载过程中崩溃的问题。现在资源目录更新、地图资源缓存访问和自定义缓存替换受到同步保护；@lib/...、image/...、spine/...、icon/... 等 UI 资源路径的搜索能力保持不变。
• 修复 Windows 客户端播放拖尾、Billboard 或层级飞行曲线粒子特效时，在资源重载、连续创建、同帧清理或玩法状态切换期间可能崩溃的问题。现在已加强粒子模块与渲染资源的生命周期管理，并补齐旧版或不完整拖尾资源的默认曲线兼容；相关特效在连续触发和资源更新期间会更加稳定。

2026-07-14 ～ 2026-07-21（已发布至线上正式环境）

本期重点速览

本周期把项目发布、编辑器工作流和 AI 辅助开发继续向稳定默认路径收口：服务端可以主动结束游戏局，部署环境 / 运行时环境可以被项目代码明确区分，ServerChannel 会按运行环境隔离消息；Blazor 版数据编辑器现在已经是默认数据编辑器，旧 WinUI 版降为临时备用入口；AI 助手获得完整编辑器 MCP 调用脚本、美术资源库 MCP、UI 编辑器创作模式 MCP 和更可靠的运行时自动检查；QuickStart 和发布流程文档也重新对齐编辑器新建项目、模板复制备用路线与 TapTap App 星火 2.0 内嵌客户端已上线的现状；对外文档网站正式上线，集中承载快速开始、官方示例画廊、系统手册、API 参考与更新日志，API 参考也新增结构化 JSON 数据源；GameGraph、GameUI、Canvas、云数据和地形 / 调试体验还有一批面向项目稳定性的修复与文档补强。

服务端生命周期、环境判定与跨服隔离

这组更新把“官方部署通道”和“项目运行阶段”拆成两个可编程状态，项目不再需要用频道名、配置文件或约定字符串来推断自己处在哪个环境。服务端生命周期也补齐主动结束入口，适合对局完成、房间关闭，以及常驻游戏局完成项目级任务后主动退出。

• 通过代码结束当前游戏局： 新增仅服务端可用的 Game.RequestSessionEnd()，调用后会向 Host 发起当前游戏局的结束请求，并进入正常的 GameOver 与回收流程。它只负责发起请求，不会同步触发 Game.OnGameEnd；实际收到引擎结束通知后才会触发该事件，OnGameEnd 继续用于最终资源清理。
• 判断官方部署通道： 新增 Game.DeploymentEnvironment 与 GameDeploymentEnvironment，用于判断当前 Host 所在的部署环境：master 为部署通道保留值，不作为项目发布、测试或迁移目标；alpha 为外网公开测试环境；production 为线上生产环境。同时提供 Game.IsMasterDeploymentEnvironment、Game.IsAlphaDeploymentEnvironment、Game.IsProductionDeploymentEnvironment 便捷判断。
• 判断游戏局运行阶段： 新增 Game.RuntimeEnvironment 与 GameRuntimeEnvironment，用于判断当前游戏局的运行时环境：debug 为调试环境，test 为项目内测环境，formal 为项目正式环境。同时提供 Game.IsDebugRuntimeEnvironment、Game.IsTestRuntimeEnvironment、Game.IsFormalRuntimeEnvironment 便捷判断。
• 组合判断完整环境： 部署环境与运行时环境是正交轴，可以表达完整 3 x 3 组合。运行标签沿用现有云数据隔离链路：空标签仍按 formal 处理；服务端逻辑可以直接按当前环境值编写分支，Unknown 不代表一个可发布、可运营的环境，客户端代码读到该值时应按保守兜底状态处理。
• 跨游戏局消息自动按环境隔离： ServerChannel 现在会按当前游戏局的运行环境隔离消息。现有 ServerChannelMessage.Publish(...)、Subscribe(...)、用户专属频道等用法保持不变，项目代码不需要手动在频道名里拼接环境标识；公告、跨游戏局同步、组队邀请、私聊通知等依赖 ServerChannel 的服务端通信会与云数据的 test / formal 环境边界保持一致。
• 补齐环境与迁移指南： 新增 docs/guides/DeploymentAndRuntimeEnvironments.md 与 game-environments AI Skill，统一说明 alpha / production、debug / test / formal、项目内测与正式上线的关系。文档明确 test 是用户项目自己的内测环境，不是编辑器 alpha 外网公开测试环境；production + formal 表示游戏经过平台审核并正式上架 TapTap 渠道后，玩家可以在 TapTap App 和星火对战平台上公开找到并游玩。
• 明确测试与正式数据边界： 环境指南补充迁移与运营预期：部署环境和运行时环境按完整组合隔离，尤其是 test 和 formal 云数据相互独立。
• 固定每周发布节奏入口： 项目内 docs/sdk/CHANGELOG.md 现在作为排期入口被明确记录。用户可以在其中查看最新发布到外网测试环境的更新日志，按发布周期判断目标能力所在批次；外网和线上通常都是每周更新，同批外网更新通常在两周后的周二抵达线上，因此线上每周拿到的一般是外网约两周前的那批能力。
• 说明线上修复和资源迁移预期： 文档补充线上问题修复和资源迁移预期：官方依赖库和服务端问题通常可以热修；客户端问题往往需要等待客户端版本覆盖，完整覆盖可能需要两到三周。云端资源适合多项目共享和跨游戏下载缓存复用，但用户上传的自定义云端资源在外网和线上互相独立；大量自定义云端资源迁移到线上时建议提前找官方人员协助同步。项目内资源则随项目发布，更适合需要跨环境自洽的私有资源。

数据编辑器与编辑器工作流

Blazor 版数据编辑器现在已经是默认数据编辑器，项目日常数编维护、节点画布和 AI/MCP 工作流都应优先按 Blazor 版本理解。旧 WinUI 版本现在降级到工具栏菜单里的备用入口，只作为 Blazor 版本出现问题时的临时替代品保留，并会随着 Blazor 版本稳定后逐步退役。

• 节点画布更适合直接维护常用配置： Blazor 数据编辑器节点卡片继续补齐字段展示能力，支持通过 ShowFullPathOnNode 把嵌套字段按面包屑显示，并为 GameSystemUI 商店、背包、移动控件、对话、卡牌、Buff 栏等常用配置补充节点卡片展示标记。弹窗和菜单打开时也会阻断画布、文件树和顶栏快捷键，避免在配置对话框中误触复制、删除、保存等全局操作。
• 保存和生成不再打断当前地图： 数据编辑器保存、data_save / data_save_and_generate、UI 编辑器创作模式保存等链路会精确跳过本轮由 DataManager 写入的 editor/data 文件和 editor/trigger/generate_record.json，不再把自己的保存 / 生成结果误判为外部文件改动，也减少 AI 自动保存生成后弹出“是否重载整个地图”的干扰。

AI 辅助调试与编辑器 MCP

AI 助手的默认调试路径更贴近真实编辑器工程：能通过完整编辑器 MCP 时优先在编辑器内启动、观察和验证；只有纯客户端确实更合适时才独立拉起客户端，并且要自己负责进程生命周期。

• 优先使用编辑器内调试： 收紧纯客户端本地验证指引：目标项目已在编辑器中打开且编辑器 MCP / 调试命令可用时，优先使用编辑器内调试；只有明确要求纯客户端、需要验证仅客户端行为、测试本地未发布 AppBundle，或编辑器 MCP 不可用时，才独立启动纯客户端，减少重复调试窗口。
• 自动管理 AI 启动的纯客户端进程： AI 助手现在必须跟踪本轮自行启动的纯客户端进程：代码改动需要重启时先结束旧实例，验证成功、失败或工具异常后均默认回收；同时禁止按进程名批量结束用户或编辑器拥有的 SCE 进程。
• 按指定窗口尺寸验证客户端界面： 纯客户端调试 Skill 与用户指南补充 -width=<pixels> / -height=<pixels> 启动参数说明。AI 助手在验证响应式 UI、竖屏布局、移动端 Canvas 表现或截图对比时，可以用 Start-SceClientOnlyDebug.ps1 -ExtraArgs 启动指定客户区尺寸的窗口，例如 390 x 844 手机比例或 1080 x 1920 竖屏设计分辨率。
• AI 可直接读取官方模板： 官方 map_templates 更新包改为非加密发布。AI 助手可以直接读取空项目、数据示例和代码示例等内置模板内容，基于模板查看代码和用例时，不再需要用户先在地图编辑器中新建对应模板项目来提供文件上下文。
• 统一解析 Runtime MCP 工具列表： Runtime MCP 对外文档补充编辑器 MCP 桥接返回结构说明：runtime_list_tools / debug.list_tools 的工具列表在 result.tools 下，直接 TCP 兜底连接则直接返回 payload；AI 助手可统一用 parsed.result ?? parsed 解包，避免把顶层桥接响应误判为空工具列表。
• 提供完整编辑器 MCP 调用脚本： SDK 新增完整编辑器 MCP HTTP 调用脚本：项目生成的 ai/tools/Invoke-SceEditorMcp.ps1 会解析 src/WasiCoreSDK.props 并调用版本化 tools/editor-mcp 实现，支持 -HealthOnly、-Context、-ListTools、-Tool、-RequestJsonPath 与 -Smoke UiauthoringP0 / -Smoke RuntimeMcp。该脚本会执行 MCP initialize / notifications/initialized，保留 JSON-RPC 与 result.isError 结构化错误，并默认拒绝把 TriggerMcpHost 当作完整编辑器 MCP 使用。
• 运行时自动检查减少误报： -Smoke RuntimeMcp 现在会在 debug_start / debug_start_no_compile 后等待 debug_wait 终态，并对调试客户端刚启动时短暂的 runtime_state_unavailable、client_runtime_timeout 或 client_runtime_unavailable 做有限重试；自动检查会从 ui.snapshot 的真实根节点坐标取点，不再因运行时尚未完成 Wasmtime 初始化或坐标兜底而误报失败。

SDK 入门文档与发布流程

新用户第一次接触星火 2.0 时，最容易踩坑的是把 SDK 仓库当成游戏工程起点，或者沿用旧文档里已经过时的 TapTap 容器状态。SDK 文档现在把“从零创建项目”和“项目跑起来后的调试、内测、上架流程”拆成两个入口，减少 AI 助手和开发者在错误目录、错误模板来源或旧发布状态上浪费时间。

• 快速开始回到编辑器新建项目： docs/guides/QuickStart.md 已重写为新用户入口，明确首选通过星火 2.0 编辑器的新建项目菜单创建工程；首次打开项目会刷新 src/WasiCoreSDK.props、AGENTS.md / CLAUDE.md、docs/sdk/、docs/api/、docs/schemas/、docs/examples-index.md 和 ai/tools/。文档不再指导用户 clone 或构建 SDK 仓库本身，也不再把本机 .NET SDK 描述为所有新手必备；只有手写代码并想在 IDE、终端或 AI 工具中自行 dotnet build 时才需要安装。
• AI 复制模板只作为备用路线： QuickStart 补充 AI 从当前编辑器随包 map_templates 复制 game_entry、data_sample、code_sample 或专项模板的边界：复制后需要更新 project/map_settings.json 中的项目标识，但不要手工固定 src/WasiCoreSDK.props 的 SDK 缓存路径；复制完成后仍应让编辑器打开项目一次，刷新 SDK 路径和 AI 上下文。
• 按需求查找官方示例： 新增 docs/guides/ExamplesGallery.md 官方示例画廊，把 code_sample 与 data_sample 按“我想做 X”整理到同一个入口。开发者和 AI 助手可以从玩法、同步、GameGraph、UI、云数据、触发器等需求反向定位示例目录，再进入对应 GameMode、客户端 / 服务端代码或 README 阅读实现。
• 发布流程对齐 TapTap App 现状： docs/guides/Editor2PublishAndAiWorkflow.md 改名并重组为“项目跑起来之后”的发布、调试与 AI/MCP 开发流程，移除旧的新项目上手重复步骤，并明确 TapTap App 的星火 2.0 内嵌客户端已经上线；需要 TapTap 审核和正式上架的项目不再等待额外容器能力，而是按当前创作者中心和 TapTap 发布流程完成审核、素材配置、合规检查、版本发布与实机验证。文档也补充“调试（不编译）”的边界：只有已经自行编译并把最新 GameEntry.dll 部署到服务端 AppBundle/managed/ 与客户端 ui/AppBundle/managed/ 时才应使用该入口。
• 文档索引按新职责排序： SDK 根 README、docs/README.md、docs/ai/README.md、docs/guides/toc.yml、AGENTS.md 和 CLAUDE.md 已同步更新入口说明：QuickStart 负责第一次创建、编译和运行；发布流程文档负责 AI/MCP 开发闭环、调试路线和内测 / 上架检查。

对外文档网站

此前 SDK 文档主要随编辑器和项目内副本分发，读者需要先拿到项目或定位本地 SDK 才能查完整资料。现在文档网站提供稳定公开入口，适合新用户上手、团队共享链接和 AI 辅助开发前快速确认当前对外说明；项目内副本继续用于跟随具体编辑器版本的本地检索。

• 访问统一入口： 星火 2.0 开发文档上线至 doc-sce.taptap.cn，集中提供快速开始、系统手册、最佳实践、AI 辅助开发、API 参考和更新日志等入口。
• 复用同一份发布说明： 站点内容由 WasiCoreSDK docs/ 构建同步，docs/CHANGELOG.md 会作为网站“更新日志”页面显示，确保网站和 SDK 随包说明使用同一份对外内容。
• API 参考获得结构化数据源： SDK 发布包现在随 api/client/api-model.json、api/server/api-model.json 和 api/shared/api-model.json 提供结构化 API 模型；文档站和工具链可以直接读取类、成员、注释、平台侧等结构化信息，不再只依赖 .cs 声明文件或 XML 文档做二次解析。
• 保留项目内本地副本： 项目内 docs/sdk/ 仍作为随编辑器版本落地的本地副本，适合 AI 助手在具体项目中离线检索，并跟随当前 SDK 缓存版本使用。

美术资源库 MCP

AI 现在可以直接通过编辑器 MCP 获取美术资源信息，在编辑器首页或尚未打开项目时也能查询公共资源和云素材；项目打开后再扩展到当前项目与依赖库资源。这样可以减少靠静态索引猜素材路径，或要求用户先手动打开地图、翻找资源面板的情况。

• 按编辑器上下文选择资源来源： sce-resource-picker AI Skill 已接入 resource_catalog_* 工作流：连接到完整编辑器 MCP 时优先调用 editor_get_context、resource_catalog_list_categories、resource_catalog_search 和 resource_catalog_get_detail，根据 projectOpen、availableSources 与 warnings 判断当前可用来源；MCP 不可用或目标来源不可用时再回退到 docs/resources/*.json 静态索引。
• 无项目时也能查公共和云素材： 无项目状态下，resource_catalog_search source=local / source=cloud 可用于选择编辑器公共资源和云素材；source=project 会返回空结果与明确提示信息，而不是作为工具错误处理。项目打开后，source=project 会扫描项目 res/、ui/ 以及依赖库资源。
• 按项目根和资源类型过滤素材： resource_catalog_search 补充 rootKind 项目资源过滤和图片、图标、音效、动画、粒子、UI 等资源类型。AI 助手可以用 source=project, rootKind=currentMap 只列出当前项目自身的本地资源，需要依赖库资源时再放宽范围。
• 读取素材结构化预览信息： 新增 resource_get_preview_info，AI 助手可以读取模型包围盒、顶点 / 面数、材质 / 贴图摘要，图片尺寸与格式、音频时长与采样信息、动画长度、粒子配置和 UI 文件元数据等结构化预览信息，用于判断素材是否适合当前需求。项目代码使用资源路径引用所选素材。
• 云素材查询慢时优先返回已有结果： 美术资源库 MCP 对 cloud 查询增加耗时预算和提示信息；source=any 即使云素材库较慢，也会优先返回已经拿到的本地 / 项目结果。同时，非法 tools/call 参数会返回结构化 invalid_params，不再触发编辑器 FirstChanceException 诊断弹窗。

项目架构路线指引

AI 选择模板、写代码和推荐素材前，需要先判断项目更接近哪条玩法实现路线。SDK 现在把这些选择标准写进文档和 AI Skill，避免把“2D / 3D”当作唯一分类，也让同一项目中混用 SCE 场景、GameGraph 和 Canvas/GameUI 时有稳定的解释口径。

• 按玩法路线选择项目架构： 新增 wasicore-game-architecture AI Skill 与 docs/guides/GameArchitectureRoutes.md，把起手路线明确拆成 SCE 场景 + Unit/技能系统、直接 GameGraph SceneGraph、Canvas/GameUI 绘制三类，并说明这些路线可以在同一项目中混用。
• 澄清 2.5D 与 3D 场景语义： 文档统一澄清 GameDataScene.SpaceModel：Surface2D 是 2.5D 单层地表寻路和碰撞语义，场景仍然可以有 Z 坐标和 3D 渲染；Volumetric3D 只在同一 XY 需要多层可走面、3D 导航或物理角色 motor 等真 3D 空间语义时使用，并需要生成 3D 场景产物。
• 把架构术语接入文档和 AI Skill： SDK 入口文档、项目生成的 AGENTS.md / CLAUDE.md / project-context.mdc、以及 wasicore-game-scaffold、3d-unit-game、canvas-2d-game、client-scenegraph-game、server-authoritative-3d-physics 等 skill 已接入这套术语。3d-unit-game 和 canvas-2d-game 保留历史目录名，但说明其分别代表 SCE Unit/技能系统路线与 Canvas/CanvasAnimated 绘制路线，不再作为严格的游戏维度分类。

UI 编辑器创作模式（初期能力）

“UI 编辑器创作模式”是 UI 编辑器的早期创作架构；uiauthoring_* 是这组 MCP 工具的固定前缀。这部分能力仍处在初期开发阶段，本期先开放控件选择、状态查看和 AI 辅助定位，后续属性编辑、拖拽、保存、模板等更完整的 UI 编辑能力会继续迭代。

• 在控件选择模式查看控件属性： 用户现在可以在 UI 编辑器的控件选择模式中查看当前 GameUI 控件的层级和基础属性，用于理解运行中界面由哪些控件组成，以及选中控件来自代码、数编还是运行时动态创建。
• AI 进入真实 UI 编辑器链路： AI 助手可以通过 uiauthoring_* MCP 工具进入同一套真实 UI 编辑器链路：启动、查询、等待和清理真实 UI 编辑器创作会话，读取当前 GameUI 层级，定位带来源信息的控件和运行时动态控件，并按结构化选择器选中目标。
• 启动和清理 UI 编辑器创作会话： 新增 uiauthoring_start / uiauthoring_status / uiauthoring_wait / uiauthoring_stop，用于启动、查询、等待和清理真实 UI 编辑器创作会话；工具返回真实会话阶段，而不是只证明按钮或事件已派发。
• 读取控件层级与 Workbench 状态： 新增 uiauthoring_get_state，返回原生会话 / 控件层级与 Workbench 宿主快照的组合状态。Workbench 关闭时仍可读取原生会话，Workbench 部分会明确报告窗口、宿主或快照不可用。
• 选择控件并切换编辑 / 交互模式： 新增 uiauthoring_select、uiauthoring_set_mode、uiauthoring_refresh、uiauthoring_open_workbench 和 uiauthoring_close_workbench。AI 可以按当次生成的控件句柄、唯一 source_entry_id 或来源定义选择器选择实时控件，在编辑 / 交互模式间切换并检查输入门控，通过真实 UIAuthoringWindow 打开或关闭 Workbench。

GameGraph 与 SDK API 表面

GameGraph 本期重点是让服务端同步 SceneGraph 逻辑复用更接近客户端的节点查询和变换 API，同时补齐 SDK 声明中嵌套类型的可读性。

• 服务端补齐节点层级和变换 API： 补齐服务端 GameGraph Node API 与客户端的能力对齐：Node.Name 现在可在服务端读写，服务端也可以读取 Parent / Children、按名称查找或移除子节点，并使用 LookAt、Translate、Rotate、SetWorldTransform、LocalToWorld、WorldToLocal、Clone、RemoveAllChildren 和 LoadXML 等节点层级与变换工具。GetComponentInChildren<T> 在服务端会递归遍历子节点，CollisionShape.WorldBoundingBox 也可在服务端读取，方便服务端权威物理和同步 SceneGraph 逻辑复用同一套节点查询代码。
• 单位与节点同步 API 回到服务端： UnitNodeBinding.SyncToUnit(...) 与 SyncUnitFromNode(...) 现在只在服务端 API 中公开；客户端旧空实现本来不会同步单位位置，相关单位同步逻辑应由服务端执行。
• SDK 声明展示嵌套类型成员： SDK 随包提供的 api/client 与 api/server 声明列表现在会展示更多公开嵌套类型。Node.Children 返回的 Node.NodeList 已在客户端和服务端 API 声明中完整展示，包括 Count、索引访问、GetEnumerator()、Add(...) 和 Remove(...)；CollisionChain2D.Vertices 与 CollisionPolygon2D.Vertices 返回的 VertexArray 也会展示顶点数量、索引读写、Resize(...) 和 SetAll(...)。这项更新只补全文档化的 API 表面，不改变运行时行为或兼容性。

GameUI、Canvas 与加载页

这一组更新主要面向客户端 UI 的“可解释、可调优”：Canvas 移动端性能有了专门指南，Loading 页归到 GameUI 文档入口；相关运行时 UI 修复集中放在本期“修复”小节。

• 降低移动端 Canvas 绘制压力： 新增移动端 Canvas 性能调优 AI Skill，面向 Canvas / CanvasAnimated 在手机上更新帧耗时高、整帧耗时高、发热或 framebuffer/底层绘制缓冲压力大的场景。文档说明如何通过 Canvas.Resolution 降低底层绘制分辨率，同时继续让控件按原布局铺满显示区域。
• 提供 Canvas 移动端调优写法： Canvas 性能指引给出项目侧推荐写法：先通过 Canvas 上的轻量帧诊断 overlay 观察 FPS、delta 和绘制耗时，确认是真实帧率 / 绘制耗时问题，而不是动画时间计算错误；再通过 DeviceInfo.Platform / Platform 收窄到 Android、iOS 或编辑器移动模拟环境，避免误伤桌面体验；最后关闭 AutoUpdateResolutionOnResize、保留 CanvasCoordinateMode.DesignResolution、在 OnSizeChanged 中按像素预算设置 Resolution，并在绘制阶段用 Scale(quality, quality) 复用原有逻辑坐标。文档同时提醒不要按手机物理分辨率推断 GPU 持续性能，文字和细线较多的 Canvas 应提高质量预算或改用普通 GameUI 控件。
• 补齐 Loading 页面文档入口： SDK 新增 docs/systems/LoadingUIScreen.md，明确项目内 Loading 页面属于客户端 GameUI，而不是原生 App splash screen；文档覆盖 LoadingUI / GameEntryLoadingSystem.ShowLoading(...) 快速接入、自定义全屏遮罩、StandardUIType.Loading.ExpectedZIndex 层级、GameDataGameUI 配置和等待场景加载完成的写法。
• AI 按新 Loading 指南处理加载页： UI_LEARNING_PATH.md、文档总索引和 ui-layout-api AI Skill 已接入 Loading 页指南。AI 助手在处理自定义 Loading 页面、启动遮罩或场景切换进度时会优先读取该入口，避免继续引用 SDK 外部的旧 Loading 文档。

GameSystemUI 商店与支付

商店系统继续补齐“用内置窗口快速接入”和“项目自定义 UI 接管部分流程”两条路线。默认窗口仍适合大多数项目快速落地，自定义领取或支付链路时也有更清晰的文档入口。

• 自定义周期商品领取界面： GameSystemUI 周期商品领取 UI 可以按项目需要替换。客户端新增 ShopSystemClient.OnPeriodClaimAvailable 可领取事件；PeriodClaimDialog.AutoShowEnabled 可关闭默认领取弹窗；ShopWindow.AutoShowPeriodClaimResult 可按窗口关闭默认领取成功 / 失败结果弹窗。两个 UI 开关默认开启，现有项目行为保持不变。
• 补齐商店与支付接入指南： SDK 新增 shop-payment AI Skill，并在商店与支付系统文档中说明 ShopWindow + ShopSystemClient、仅复用 ShopSystemClient 的自定义 UI、以及直接使用底层 PaymentClient / PaymentServer 的选型边界。文档同时提醒平台充值星火币需要配置创作者中心大厅保留链路，以及自定义支付流程中 productId 不会自动反查数编商品配置。

云数据扫描与诊断

云数据这次补齐了大列表分批读取、失败诊断和限额处理指引；框架计时器相关修复集中放在本期“修复”小节。

• 分批扫描大列表云数据： 云数据 ListItem 新增游标分批扫描 API：服务端可通过 CloudData.ScanUserListItemsAsync(...) / ScanPlayerListItemsAsync(...) 按 ItemUUID 倒序分批读取同一用户、同一 key 下的大列表，并用 ListItemScanBatch.NextBeforeItemUuid 继续下一批。该能力面向“分次不漏读完整列表”的后台整理、迁移、审计和缓存恢复场景；正常扫描不会重复返回已读列表项，但不是强一致数据库快照，扫描期间新增的列表项通常留到下一轮完整扫描，删除或移动列表项会影响后续批次。QueryUserListItemsAsync(..., maxCount) 仍适合读取最新若干条或确认很小的列表。
• 云数据失败自动输出诊断日志： 云数据查询和事务失败时，框架现在会自动输出兜底警告日志，包含操作名、结果码、请求 ID 和用户数 / key 数 / 操作数等摘要。项目不再必须在每个调用点手写日志才能定位未初始化、参数缺失、发送失败、超时、解析失败或服务端返回错误等问题；成功查询和成功事务不会被默认刷屏，日志也不会输出具体云数据值或 Blob 内容。
• 云数据限额有明确处理方式： CloudData 文档和 AI Skill 补充服务限额处理指引：明确 TooManyReadOperations、TooManyWriteOperations 和 MessageSizeTooLarge 应通过批量查询、合并事务、限制列表返回数量、缩小或拆分 payload 来处理，避免在短时间内原样重试导致持续失败。

日志诊断与输出控制

项目侧日志现在可以先在 WasiCore 托管层完成级别过滤，再进入底层运行时日志通道。这样调试时可以临时打开更多细节，正式或高频场景下也能把无关日志挡在格式化和 WASM 边界之前，减少字符串构造、跨端调用和日志刷屏成本。

• 按最低级别过滤 Game.Logger 日志： 新增 Game.MinimumLogLevel 与 Game.SetMinimumLogLevel(...)，可将通过 Game.Logger 发出的 C# 日志限制到 Warning、Error 或 None 等级别。被过滤的日志不会执行 formatter，也不会继续进入客户端 / 服务端运行时日志通道；默认值保持 Trace，兼容现有项目输出。
• 补齐双端日志守门行为： 客户端与服务端运行时日志在写入前都会检查 IsEnabled(...)，并正确忽略 LogLevel.None。客户端已有的内部禁用级别设置会实际影响写出路径，不再只影响查询结果。
• 降低流式文本输出穿越边界的风险： 框架内部的 LoggerTextWriter 适配器改为按行缓冲，遇到换行或 Flush 时才写出一条日志，避免将 TextWriter.Write(...) 的片段式输出拆成多次 WASM 日志调用。常规项目代码仍推荐直接使用 Game.Logger.LogInformation(...) 等参数化日志 API，而不是依赖 Console.WriteLine。
• 明确当前边界： 这次过滤面向 WasiCore C# 侧 Game.Logger，不改变 C++ 原生日志、服务端日志采样、客户端原生日志总开关，或绕过 Game.Logger 直接写入运行时日志通道的行为。

修复

• 修复编辑器内调试中央游戏视图偶发无法接收键盘输入的问题。调试过程中即使焦点曾切到侧边面板或其他编辑器控件，重新点击游戏视图后也能继续使用 WASD、快捷键和 GameUI 输入框输入，不再需要重启编辑器恢复。
• 修复地形编辑器右侧属性面板修改尺寸后，立即点击“立即调整地形”可能仍按旧尺寸执行的问题。现在按钮会先提交当前输入值，并在调整成功后立即保存场景属性；例如输入 16 x 16 会按 16 格乘 16 格调整地形，不再沿用调整前的尺寸。
• 修复场景列表删除场景后没有同步清理对应 GameDataScene 数编表、MapGameMode.SceneList 和 DefaultScene 引用的问题。删除尚未生成 3D 场景产物的 Volumetric3D 场景后，保存项目时不再继续校验已删除场景，也不会反复提示 3D 场景产物校验失败。
• 修复删除场景后首次保存仍可能弹出“以下文件在外部发生改动”提示的问题。EntryInfo.json 和 Metadata.json 这类数编缓存 / 元数据文件会被文件监控永久忽略；删除场景保存时由编辑器自动写入的 MapGameMode.json 和场景数编表也会按本次保存精确跳过监控，不再误判为外部改动要求重载地图。
• 修复通过 Node.Dispose() 或 Node.RemoveChild(...) 销毁 / 移除 GameGraph 场景节点子树后，旧的递归节点快照仍可能持有已失效 native 节点句柄的问题。项目在遍历 GetChildren(recursive: true) 时删除匹配节点后，后续旧 Node 包装对象再读取 Name、父子关系或其他节点属性会安全返回默认结果，不再因为访问已释放的节点导致客户端或编辑器内调试崩溃。
• 修复客户端 Terrain.GetMaterials() 获取地形材质时可能尝试直接构造抽象 Material 类型的问题。现在地形材质和静态模型材质读取都会通过统一的材质类型分发器返回 MaterialPBR、MaterialFlatLambert、MaterialWater 或 MaterialCustom 包装，避免首次访问地形材质列表时因材质包装失败导致异常。
• 修复 Progress 控件 ProgressionMode 枚举与实际填充方向不一致的问题：RightToLeft 不再与 LeftToRight 表现相同，TopToBottom / BottomToTop 也会按名称语义填充，顺时针与逆时针行为保持不变。使用了这些枚举的地图需要重新编译才能正常运作，否则会保持旧有错误行为。
• 修复使用 RuntimeTexture.Register(...) 或 .Image(texture, name) 将 RenderTarget / Texture2D 显示到普通 GameUI 控件后，关闭编辑器内调试窗口可能导致编辑器崩溃的问题。游戏结束清理运行时纹理时不再触发已失效资源搜索，使用战斗画中画、预览相机等运行时纹理 UI 的项目可以正常退出调试。
• 修复 Game.Delay 等通过 IThinker 每帧驱动的等待 / 计时逻辑在 tick 中完成或停止时，可能把已结束对象长期留在内部 dirty thinker 队列的问题。高频创建短延迟任务的项目不再因为这些过期记录被持续持有和每帧重复扫描而出现内存增长、帧率逐步下降或手机发热加重；同一修复也覆盖其他在 tick 阶段切换 DoesThink 的框架对象。
• 修复 GameUI 图片资源路径显式写出库名前缀时，如果路径中混用 / 与 \ 可能解析失败的问题。项目代码、数编或 AI 生成内容里出现混合分隔符时，图片查找会先统一子路径分隔符，减少跨平台路径写法导致的资源丢失。
• 修复客户端结束游戏和编辑器关闭嵌入式 Blazor 窗口时的两个清理竞态：WASM 游戏状态会先于 Lua teardown 结束，避免 GameUI / RuntimeTexture 等资源在错误顺序下访问已清理对象；Blazor WebView 初始化完成时如果窗口已关闭，会安全退出初始化流程，不再继续访问空的 WebView2 实例。

2026-07-06 ～ 2026-07-13（已发布至线上正式环境）

本期重点速览

本周期的四项重点是：作者可以将自己创建并由项目代码识别的服务端游戏局设为常驻，在玩家全部离线后继续承担跨游戏局协调和权威云数据处理；服务端现在可以只加载编辑器预烘焙的碰撞产物，无需上传或加载原始模型资源，也无需在运行时处理模型几何，即可支持动态复杂模型碰撞；Runtime MCP 补齐鼠标、键盘和文本输入自动化，AI 助手可以真正操作并验证运行中的游戏；GameUI Label 支持轻量富文本和局部链接，一个文本控件即可承载混排样式与可点击交互。服务端同时新增玩家文本敏感词过滤入口，并明确跨服消息传输不会自动审核载荷；场景加载状态、数据编辑器、触发器、序列帧、商店和 SDK 文档也有一批改进与修复。

重点：作者可控的常驻游戏局

普通游戏局会在玩家全部离线或达到自然运行时限后结束，但项目级协调与权威云数据处理有时需要独立于单局玩家生命周期继续运行。作者现在可以通过服务端 API 把自己选定的游戏局设为常驻，使其在无人在线时继续执行逻辑，同时仍保留显式终止和平台安全保护。

• 服务端新增 Game.SetSessionResident(bool) 与 Game.IsSessionResident。申请会返回 SessionResidenceResult，可区分成功、项目数量已达上限、服务暂不可用和当前游戏局状态不允许切换；项目应只在成功后启动长期业务。
• 同一项目最多同时有三个常驻游戏局。作者可以先创建用于长期服务的房间，再由服务端根据创建者 UserId、房间参数或其他项目条件识别该房间并申请常驻；一般玩家创建的对局不需要执行这段逻辑。
• 常驻局会跳过游戏局自然运行时限和全员离线回收，但显式结束、管理员终止、平台安全保护与服务器关闭仍然有效。重要状态仍应持久化，并支持游戏局意外结束后的恢复。
• SDK 新增常驻游戏局系统文档与 AI Skill，覆盖 API 调用、结果处理、跨游戏局协调、CloudData 持久化和生命周期边界。

重点：无需上传模型资源的服务端预烘焙碰撞

客户端可以直接读取模型几何数据并在运行时生成复杂碰撞，但服务器若采用同一路线，就必须上传和加载原始模型资源，并承担几何解析、碰撞生成和资源常驻带来的计算、存储与内存压力。服务端预烘焙模型碰撞的核心价值，是把这部分工作提前放到编辑器侧完成：发布时只向服务器提供专用碰撞产物，不上传原始模型、材质或纹理；运行时直接加载烘焙结果，仍可支持动态建造房屋、运行时楼梯、可受力装饰物等“运行时才生成、且复杂几何难以用基本形状表达”的权威碰撞需求。

• 项目可在 GameDataModel.CollisionBake 中选择 StaticTriangleMesh、ConvexHull 或 CompoundConvex。静态三角网格要求 Mass = 0；单凸包和复合凸包可用正质量创建动态刚体；MaxHullVertices 可在 4 至 4096 之间控制凸包复杂度。复合模式会按 Prefab 中每个独立 StaticModel 部件生成凸包并保留本地变换，但不会自动分解单个凹网格。
• 资源统计会生成 ref/model_collision.json，编辑器据此输出 block/model_collision/<HashCodeLocal>.bin 与同名 .roles.dat。发布到服务器的是这些专用碰撞产物，而不是原始模型、材质或纹理；服务端因此不需要在运行时解析模型几何或生成复杂碰撞，也不需要让表现资源长期占用服务端内存。脚本可通过仅服务端可用的 PrebakedModelCollision.ApplyPrebakedCollision(...) 加载碰撞，并获得明确的结果枚举。
• 动态凸包的本地 RigidBody / CollisionShape 会直接附着到目标同步 Node。客户端只需在同一 Node 下挂本地 Prefab，视觉模型即可跟随服务端权威物理变换，碰撞资产与表现资源保持分层。
• 这套机制用于“运行时生成的复杂模型碰撞”。地形编辑器中的静态内容仍使用场景烘焙，角色继续使用胶囊控制器；盒、球、胶囊、圆柱已经足以表达的普通对象仍应优先使用基础形状。
• SDK 新增对应系统文档与 AI Skill，覆盖形状选型、CollisionBake 配置、Client-Resource 清单、编辑器烘焙、服务端结果处理、发布目录和双端表现分层，并明确其与 server-authoritative-3d-physics、3d-unit-game、sce-resource-picker、sce-preview-verify 的分工。

重点：Runtime MCP 输入自动化

Runtime MCP 从“读取运行状态和调用调试接口”扩展为完整的有状态输入自动化。AI 助手现在可以观察游戏 UI，再模拟鼠标、键盘和文本输入完成实际操作，用于验证按钮、拖拽、滚轮、快捷键、输入框和连续按键等交互，而不再局限于截图或直接调用业务接口。

• ui.click 可按坐标、控件 ID 或 Label link ID 点击；input.pointer 可分别发送移动、按下、抬起和滚轮事件，因而支持拖拽等连续手势；input.key 支持持续按键和带修饰键的原子组合键；input.text 可向焦点控件输入 Unicode 文本；input.reset 可在自动化中断后释放仍被持有的按键与指针状态。
• 所有指针工具统一使用 ui.snapshot / ui.get_rect 返回的游戏 UI 像素坐标。即使编辑器内嵌 GameView 或纯客户端窗口没有物理输入焦点，AI 助手仍可操作游戏 UI；Label 富文本链接的命中区域也使用同一坐标系。
• Runtime MCP 客户端链路同步收敛：修复单参数 JSON 请求在 PowerShell 严格模式下可能于联网前失败的问题；地图内辅助脚本自动使用 WasiCoreSDK 的版本化共享客户端，不再各自保存易漂移的协议副本；编辑器 MCP 与命令行兜底连接会标明失败阶段，截图调用也会等待文件实际生成。现有 debug.*、ui.*、material.* 工具名和业务参数保持兼容。

重点：Label 富文本与局部链接

Label 现在既能做轻量文本混排，也能在一段文字中声明局部可点击区域，适合任务说明、规则提示、聊天内容、帮助文本和协议链接等不值得拆成多个控件的界面。

• Text 支持 <b>、<i>、<u>、<color value="#RRGGBB">、<br/> 和 <link id="...">，并允许链接与样式嵌套。
• 客户端可通过 Label.OnLinkClicked 接收 LinkClickedEventArgs.LinkId 和指针按钮信息，再按 LinkId 路由到具体行为。只有 <link> 范围会响应链接事件，点击同一 Label 中的普通文字不会误触发。
• Runtime MCP 可通过 Label link ID 或富文本链接的实际命中区域点击链接，因此 AI 助手可以从 UI 快照定位链接并验证交互闭环。
• SDK 新增 Label 富文本与链接指南及 AI Skill，覆盖标签语法、样式嵌套、事件路由、控件选型和客户端验证流程。

场景生命周期与 GameUI

• 客户端场景启动状态现在有明确的公开语义：GameStart 只表示游戏脚本生命周期已开始，不保证地图已经加载完成。Game.LocalScene 与 Player.Scene 继续保持非空；当原生运行时尚未关联到当前 SceneList 中的场景时，会返回名为 Engine Fallback Scene、IsEngineFallback = true 的后备场景。它可供音效等不依赖地图数据的 Actor 使用，但不代表地形、导航、场景碰撞、预放置对象或底层 SCE SceneGraph 已可用。同标识的 SceneList 场景注册后，后备实例会原地转为正式配置场景，已有 Actor 引用无需替换。
• 客户端 Scene 新增 LoadState 与 Loaded，可区分 NotLoaded、Loading、Loaded 和 Failed。客户端日志会记录场景加载开始、成功和失败；加载失败不会再触发成功语义的 OnLoadEnd / EventSceneLoadEnd。依赖地图的初始化应检查状态并等待目标场景的 OnLoadEnd，不要把 GameStart 或固定延迟当作加载完成信号。
• Sprites 序列帧控件补齐单图 sprite sheet 与文件夹序列两种模式的配置能力和播放表现。普通单图 sprite sheet 现在可以通过 SpriteSheet(...) 或 FrameCount、RowFrameCount / FramesPerRow、SpriteSize / FrameSize 明确声明单帧尺寸、总帧数和每行帧数；也可通过 StartFrame、EndFrame、FramePerSecond、IntervalMillisecond、Play()、Stop() 控制播放范围和状态。文件夹序列会按子图列表播放，并支持用 FrameCount 限制最多播放的子图数量。GameDataControlSprites 同步支持这些配置。未完整配置帧参数、资源为空或传入异常参数时，控件会以更稳定的方式处理，避免简单 UI 序列帧因为资源或配置问题导致播放异常。
• GameSystemUI 商店新增 ShopWindow.Create(...) 高层创建入口，可一次绑定商店配置、购买回调和返回按钮行为，减少首次接入官方商店窗口时遗漏购买请求或关闭逻辑的情况；购买回调中仍由项目调用 ShopSystemClient.Purchase(...) 发起购买。
• GameSystemUI 周期商品领取 UI 现在可以按项目需要替换：客户端新增 ShopSystemClient.OnPeriodClaimAvailable 可领取事件；PeriodClaimDialog.AutoShowEnabled 可关闭默认领取弹窗；ShopWindow.AutoShowPeriodClaimResult 可按窗口关闭默认领取成功/失败结果弹窗。两个 UI 开关默认开启，现有项目行为保持不变。

数据编辑器体验

• 数据编辑器补齐一批常用配置的节点直接展示，覆盖单位技能、冷却与充能、消耗、施法时间、AI、场景、相机和动画等字段。常用配置现在可以直接在节点上查看和修改，减少频繁切换属性面板。
• Blazor 版数据编辑器节点画布补齐空白区右键新建、复制 / 粘贴、公共节点、快捷方式和 Lnk 删除等操作；跨表 Link 目标会自动投影为公共 Lnk，模型预览、创建 / 配置对话框和字段菜单交互也进一步与 WinUI 版行为对齐。
• 数据编辑器 MCP 新增 data_save_and_generate 收口工具。AI 助手修改数编后可以一次完成保存、项目校验、src/DataGenerated 生成和文件变更摘要回传；完整编辑器已加载项目但 DataManager 面板未打开时会自动加载当前项目，没有加载项目时会明确返回 no_project_loaded，不再要求用户为了生成代码手动打开数据编辑器。
• 触发器生成记录 editor/trigger/generate_record.json 被视为编辑器内部派生文件。它在数据 / 触发器生成链中更新时不再触发“外部文件发生改动，是否重载整个地图”的提示，避免 AI 自动保存生成后打断当前编辑器会话。

触发器体验

• global_default 补齐近期公开 API 的触发器 UI 元数据，覆盖 3D 单位移动与场景导航、ActorScope、运营邮件、云数据事务、材质和调试工具等能力；平台枚举中的 Android、Windows、iOS、macOS、tvOS 等名称也已修正，触发器中不再显示错误或歧义翻译。
• Trigger MCP 新增只读引用诊断，可按资源树路径或 Declaration ID 查看节点的正向、反向和失效引用，并区分目标不存在、当前环境不可见等基础原因；删除工具新增显式 ignoreIfMissing 安全幂等模式、精确环境与父路径校验、外部引用保护，以及 outcome、changed、safeToRetry、persistence 等结构化结果，AI 自动化可以在删除前检查引用，并在生成状态不明确时停止重试而不是重复破坏现场。
• 修复触发器引用已删除或签名已变更的 API 定义时，保存地图可能直接导致编辑器崩溃的问题。现在保存失败会保留编辑器进程并显示具体错误；battle_grounds_template 中过期的 ActorParticle 构造引用也已更新。
• 修复触发编辑器偶尔为普通事件触发器生成错误的泛型事件注册调用，导致生成代码无法编译的问题。已有异常生成代码现在可以兼容编译，临时兼容入口不会出现在触发器 API 选择面板中。

玩家文本敏感词过滤

聊天、私聊、昵称、公会名、房间名、留言等玩家文本现在可以在服务端统一过滤，再进入广播、持久化或跨服转发流程，避免各项目分别寻找底层接口或只在可绕过的客户端做检查。

• 新增仅服务端可用的 Game.FilterSensitiveWords(string)，返回 SensitiveWordFilterResult。WasFiltered 表示本次是否发生替换，FilteredText 提供可继续发送或保存的过滤结果；未命中不是错误状态。
• DualEndEvent、TypedMessage、ProtoCustomMessage 和 ServerChannel 都只负责传输，不会自动过滤玩家文本。项目应在服务端校验身份、权限、频率和长度后显式过滤，并只广播、保存或转发 FilteredText。
• ServerChannel 是不同服务端实例之间的发布/订阅消息传输机制，其中 channel 是消息主题或路由标识，不是玩家聊天房间。即使主题名包含 chat，复杂 JSON 或字节载荷也不会被传输层检查；使用它开发跨服聊天时，应在来源服务器过滤，必要时由接收端在展示前再次过滤。
• SDK 新增敏感词过滤系统文档与 AI Skill，并修订 ServerChannel、DualEndEvent、API 参考和项目 AI 编码规则。文档同时明确：敏感词过滤只是玩家文本合规流程的一环，项目仍需自行处理禁言、频率限制、举报和审计策略。

其他 SDK 能力与文档

• GameGraph 新增客户端鼠标光标控制 API：可通过 GameGraph.InputSystem.GameCursor 隐藏 / 显示鼠标、临时隐藏鼠标、切换内置 CursorShape、按光标名切换形状，并可用项目图片资源定义自定义光标形状。该能力仅在客户端侧可用，适合纯客户端交互、编辑器内预览、拖拽工具、准星/技能指示器等需要控制系统光标表现的场景。
• 3D 单位移动文档进一步明确：KinematicCharacterMotor 是 KCC ghost object，不是 Kinematic RigidBody，当前没有角色质量或内建推力；若项目需要临时推动动态刚体，可在 Binding Node 下使用严格限制碰撞过滤、尺寸和跟随位移的 server-local PushProxy 子节点。
• 配套新增 GameUI 序列帧选型文档与 AI Skill，明确 Sprites 适合加载动画、按钮光效、头像框等普通 UI 序列帧，AnimatedImageSource + CanvasAnimated 适合 2D 角色、命名动画、图层、命中框和游戏循环绘制对象；同步在 Canvas 与 AnimatedImage 文档中补充交叉引用，减少两套序列帧方案混用。
• Canvas 2D 游戏 AI Skill 与 Canvas 绘制系统文档补充 NanoVG 封装说明和 API 对照表，明确 WasiCore Canvas 是对底层 NanoVG 绘制能力的 C# 封装；AI 助手可以借用 NanoVG / SVG / HTML5 Canvas 的图形概念理解路径、填充、描边、变换栈、裁剪和文本绘制，但生成代码时仍必须使用 WasiCore Canvas API，避免误写 nvg* 或 ctx.* 调用。
• 3D 单位游戏文档与 AI Skill 补充官方状态栏说明：明确 Hero 系列血条左侧区域是等级槽，单位未配置有效 Level / Leveling 时会显示黑色块；不需要等级显示时应改用 Normal 系列血条，需要显示等级时应同时配置 GSC.GameDataUnitLeveling.HeroLevelingSample 和初始等级。文档同步列出 GameSparkCore 中单位与英雄血条系列的准确 GSC.GameDataStatusBar.* 名称。

其他修复

• 修复后台对 2.0 Blob 类型云变量执行回滚后，再次查询可能返回 500 的问题。标准云变量和列表型云变量现在都能正确恢复回滚前的数据，并兼容 1.0 与 2.0 项目已有云变量。
• 修复随进随出玩家槽位被新用户复用时，旧用户的异步名称查询回调可能覆盖新用户名称并取消新用户查询订阅的问题。现在名称回调只会更新 UserId 一致的当前用户，并从实际发起查询的用户对象上取消订阅，避免槽位换人后的用户信息串位。
• 修复服务端 GameGraph.NodeSystem.Node 可以按名称创建、却无法读取节点名称的问题。Node.Name 现在在服务端公开只读 getter，客户端仍保持可读写。
• 修复 Sprites 文件夹序列在使用普通 image/... 路径时，无法直接播放项目 ui/image/... 下散文件序列帧的问题。现在把按顺序命名的图片放入同一文件夹后，可直接通过 Image("image/xxx") 作为 UI 序列帧播放，不需要额外资源索引配置或显式库路径。
• 修复 GameSystemUI 物品栏 / 装备栏在使用 DisallowItemWithFailedRequirement 等本地限制规则时，服务端同步过来的物品槽位变更可能被客户端本地规则误拦截的问题。现在物品槽位同步会按服务端权威结果更新，不会因为物品暂时处于无槽位状态或源物品栏禁止丢弃而导致可视物品丢失、无法装备物品不显示等异常。
• 修复 GameSystemUI 背包拖拽、一键穿戴和卸下错误使用普通拾取规则校验交换的问题。相关操作现在统一按物品交换语义校验，并允许一键穿戴直接替换已占用的装备槽，合法交换不会再被客户端提前阻止。
• 修复 GameSystemUI 商店购买异常流程：批量购买会使用更安全的奖励数量计算，并拒绝包含非正数奖励数量的无效配置，避免整数溢出或错误配置导致发奖、订单记录和结果展示异常；限购查询失败时不再按“已购 0 次”继续购买，云数据事务失败也会区分并发资源不足、达到限购和普通事务失败，客户端与触发器可以获得更准确的购买结果。
• 修复项目发布前资源收集（Client-Resource）在编辑器或内置 .NET SDK 安装路径包含空格时可能失败的问题。资源收集现在会直接启动 PowerShell 并正确保留 dotnet.exe、项目文件和日志文件路径，避免路径被截断成类似 C:/TapTap/PC 后导致发布失败。

2026-06-22 ～ 2026-07-06（已发布至线上正式环境）

框架与表现系统

• Actor 系统新增服务端创建 / 声明客户端表现的能力。服务端现在可以在已有 IActorScope 上调用 PlayTransient(...)，请求当前可见客户端播放一次性 Actor 表现；这类瞬时表现不做 late join replay，生命周期由 actor 的 transient 配置或调用时显式 Duration 决定，非 transient actor 也可通过显式 Duration 强制按 transient 生命周期创建。对于需要长期存在、重新可见后仍要恢复的表现，ActorScopePersist 现在可通过 scope.SetActorSlot(...) 在服务端声明普通持久表现，客户端按 slot 声明本地创建 Actor，slot 版本由框架自动推进，不需要用户手动刷新。所有这类可同步表现都从属于某个 ActorScope，客户端看不到作用域时也不会收到对应声明，适合命中火花、临时提示、持续光环、挂点特效、服务端创建的场景提示等服务端权威触发的表现需求。同时新增 ActorScopeNodeBinding 高级入口，用于在 ActorScope 下创建 / 绑定真实 replicated Node，并在该 Node 上承载 Actor slot 声明；普通持久表现优先使用 scope.SetActorSlot(...)，只有需要 Node SyncVar、GameGraph 组件或真实 replicated Node 可见性 / 生命周期语义时才使用它。
• 3D 单位移动控制器形成第一版对外闭环：GameDataUnit.MovementController 可声明单位的移动控制器数据，UnitMovementController 会在 Volumetric3D 场景中管理 VolumetricNavigation 与 PhysicalCharacter 模式切换；物理角色模式底层使用 GameGraph KinematicCharacterMotor 胶囊 motor，并通过 UnitNodeBinding(NodeDriven) 将 node transform 写回 Unit。服务端可通过 ActivateUnitPhysicalCharacterMovement(...)、ReturnUnitToSceneNavigation()、TryJumpUnit(...) 和额外空中跳属性控制角色移动，客户端可通过同步的 UnitMovementSignal 驱动表现。Locomotion 动画新增 GameDataUnitLocomotionAnimationProfile，覆盖 idle / move / jump start / air rise / air fall / land 等状态。本次同步新增“真3D单位控制器模板”，包含 Volumetric3D 场景产物、3D 寻路 / 物理角色切换、跳跃、额外空中跳跃、移动速度测试 UI、调试 overlay 和 locomotion 示例，方便从模板直接验证整套链路。Rigidbody 与 Scripted 单位移动模式仍为保留项，不作为本轮公开能力。需要注意的是，技能系统中的搜索效果、投射物效果等历史玩法能力原本按 2.5D 单层地表语义设计，目前尚未针对 Volumetric3D 多层地表做完整优化；在真 3D 场景中使用时建议先按项目需求验证高度层、遮挡和命中表现，后续会围绕多层地表的技能搜索与投射物链路做专项优化。
• GameGraph UnitNodeBinding 在 SCE 场景中已随绑定 Unit 的视野可见性同步：Unit 离开某客户端视野时，对应的 replicated 绑定 Node 会从该客户端移除并停止后续 transform/delta；Unit 重新进入视野时会重新完整同步当前 Node 状态。该行为覆盖 UnitDriven、NodeDriven 和 Manual 绑定，适用于 hitbox、hurtbox、fire point、raycast target 和自定义 proxy；未绑定 Unit 的 replicated Node 仍按所属 SCE Scene 级别同步。此项不需要用户改代码，也不引入新的公开 API。
• 执行上下文语义做了一次设计对齐：主动技能通过 Order 施放并创建效果树时，OrderAbilityActive 现在会把正在施放的技能作为 IExecutionContext.Ability 暴露出来。因此 GameDataEffectCustomAction.Func、效果公式和子效果里读取 context.Shared.Ability / context.Ability 时，可以直接拿到触发本次主动技能效果的技能实例；context.Shared.Order 仍保留本次施放指令实例，用于读取指令目标、阶段、施法过程状态等 Order 语义。非技能指令的 IExecutionContext.Ability 仍为空；需要兼容旧写法的项目可以继续从 context.Shared.Order 判断具体指令类型。

编辑器与触发器体验

• 项目管理器的“我的项目”列表会对非当前 API 版本项目显示版本标记：API <= 13 的 1.0 项目使用更醒目的不兼容提示色，API >= 2000 但与当前编辑器 API 不一致的 2.0 项目使用警告提示色；与当前编辑器 API 一致的项目保持原列表样式，减少误用 2.0 编辑器打开不匹配项目的风险。
• 菜单中新增测试用 Blazor 版本数据编辑器入口，可通过 工具 -> 数据编辑器（Blazor） 打开。当前主入口 模块 -> 数据编辑器 仍然是 WinUI 版本数据编辑器，Blazor 版本暂时不会取代它；后续会在功能和稳定性补齐后再逐步切换。如果使用 WinUI 版本数据编辑器时遇到崩溃问题，可以先从该菜单入口打开 Blazor 版本进行实验性编辑。
• 地形编辑器右侧属性面板补齐场景级编辑能力：未选中对象时可直接修改场景名、场景尺寸、地形包边、SpaceModel、Vision 和是否渲染地形环境。场景名会写入 GameDataScene.Name，与左侧场景列表显示保持一致；尺寸面板按地编格数显示，输入范围为 1～128，保存到 GameDataScene.Size 时自动换算为世界单位（每格 256）。需要同步改变实际地形资产大小时，可点击“立即调整地形尺寸”按钮。
• 地形编辑器属性面板新增氛围和可放置形状编辑：选中“氛围”可调整环境光、雾色、主光颜色和亮度；选中区域 / 点 / 线等可放置形状可编辑标识、分组、触发引用标记，以及圆形半径或矩形尺寸，并会随地图保存写入 GameDataScene.PlacedSceneShapes。
• 3D 空间模型场景的属性面板新增“生成3D场景产物”入口，与菜单和左侧场景列表中的生成入口一致。修改 3D 地形、静态阻挡或导航相关内容后，可在场景属性面板中直接重新生成 3D 场景产物。
• 触发器继续补齐常用节点的可发现性与语句文案，覆盖玩家昵称 / 队伍 / 关系判断、单位技能 / 等级 / 经验读取、场景点距离 / 2D 距离 / 寻路路径点、单位自定义属性、事件触发器创建 / 注册 / 注销 / 销毁，以及 System.Convert 常用数值与字符串转换节点；这些节点现在更容易在触发器面板中直接搜索、插入并读懂生成语句。
• GameCore 触发器节点文案继续整理，玩家、单位、物品、物品栏、命令、表现、协议、计时器等常用对象的显示名、说明和 UiText 更贴近日常玩法编辑语境，减少机器翻译式描述和占位符显示异常。
• GameUI 基础控件触发器节点继续收敛和补强，面板、标签、输入框、文本按钮、控件层级、布局位置、背景、字号、文本和颜色等常用 UI 操作更容易直接搜索和插入，语句文案也更贴近界面搭建语境。
• 触发器新增“游戏-即将关闭时”事件，可在游戏关闭前注册收尾逻辑；GameSparkCore 同时补充普通回调式触发器创建节点，适合只需要执行无参回调的简单事件订阅。
• GameSystemUI 触发器新增一键创建并启用默认移动控件、默认技能摇杆的客户端节点，可直接绑定指定单位并加入界面，降低通过触发器搭建移动 / 技能操作 UI 的接入成本。

商城与界面体验

• GameSystemUI 商店平台支付链路补齐商品配置校验、星火币实付金额校验、限购扣减、订单记录和购买统计，平台支付购买普通商品或周期商品后会同步刷新资源余额、商品状态、可领取提示与限购剩余次数。
• 商店商品列表和详情面板的限购显示会随购买、资源余额和商品状态同步刷新，并在刷新当前分类时保留已选商品与详情弹窗，减少购买后界面跳回空状态或显示负数剩余次数的问题。

模板与示例

• game_entry 默认模板补充游戏开始时初始化逻辑，会为玩家主控单位创建并启用默认移动控件与默认技能摇杆；模板数据也默认接入当前游戏模式的显示规则与经验规则。
• 新增“真3D单位控制器模板”，用于验证和展示 Volumetric3D 场景下的单位移动控制器能力。模板包含 3D 场景产物、UnitMovementController 的 3D 寻路 / 物理角色模式切换、跳跃、额外空中跳跃、移动速度测试 UI、调试 overlay，以及 locomotion 跑跳落地状态机示例，可作为接入真 3D 单位控制器时的参考工程。
• battle_grounds_template 经验 UI 修正为读取当前等级内经验和下一级所需经验计算进度，角色升级或获得经验后经验条和百分比会正确刷新，不再长期停留在 0%。

修复

• 修复 GameSystemUI PC 键盘移动控件在按住 Shift / Ctrl / Alt 等额外修饰键时，WASD 按下或释放状态可能丢失的问题。KeyboardAccelerator 新增 AllowExtraModifiers 支持按下事件允许额外修饰键，释放事件会按主键归还状态；KeyboardAcceleratorEventArgs 同步透出 IsRepeat，便于区分长按重复触发。
• 修复 GameSystemUI 商店周期商品购买 / 续费后有效期、可领取状态和活跃周期商品列表可能未正确生效的问题；平台支付购买周期商品时也会走同一套周期状态写入与同步逻辑。
• 修复 GameSystemUI 移动摇杆在本地玩家尚未就绪时初始化可能因注册主控单位变化事件而失败的问题。
• 修复 GameSparkCore 表现创建辅助函数的位置与作用域问题：按场景点创建 Actor 时会设置实际位置和 GroundZ，按物品创建 Actor 时会优先挂到携带者作用域，物品没有有效单位作用域时会安全返回。
• 修复地形编辑器中新建 3D 空间模型场景后，直接刷“视野遮挡”可能导致编辑器崩溃的问题；该工具在 3D 场景下仍按 2D 柱状格子语义记录阻挡，用于普通 / 精确视野计算。
• 修复服务端 EventPlayerUserAbandonReconnect 事件错误实现为 ITriggerEvent<EventPlayerUserConnected>，导致 Trigger<EventPlayerUserAbandonReconnect> 无法订阅放弃重连事件的问题。
• 编辑器项目文件变更监控收窄为 2.0 项目实际会影响读图状态的 editor/、scene/、project/ 路径。调试或构建过程中写入项目根目录的 Client-Debug.log、Server-Debug.log 等日志，以及 src/、ui/、AppBundle/ 等运行/构建产物，不再反复提示“外部发生改动，是否重载地图”。
• 修复当场景为普通视野，在客户端缺没有显示普通视野迷雾的问题。现在场景级视野配置会正确影响客户端的迷雾显示：Normal 恢复按单位视野和阵营计算普通迷雾，Open 仍保持全开视野，Precise 仍走精确视野的 sight mask 特殊渲染路径。

SDK 与文档

• 优化模型动画系统文档，补充 AnimationLogicLayer 与 Priority 的底层层级关系、Priority 的有效范围（0～31）、默认 idle / move 状态机的优先级，以及手动动画如何与默认移动动画或自定义 UnitLocomotionAnimation 配置配合。
• 新增 docs/guides/3DSceneSetup.md，专门说明 3D 项目/场景创建、3D 模板、Surface2D / Volumetric3D 选择、地形编辑器属性面板、手动生成 3D 体素/导航/碰撞产物、以及 3D 场景下 VolumetricNavigation 与 PhysicalCharacter 的选型边界；同步更新 README、guides 目录、SceneSystem、地形属性文档和 3d-unit-game AI Skill 的入口。
• 新增 docs/systems/UnitMovementControllerSystem.md，集中说明 3D 场景 SpaceModel、3D 场景产物、GameDataUnit.MovementController、PhysicalCharacter、KinematicCharacterMotor、跳跃/空中跳、UnitMovementSignal 与 locomotion 状态机；同步更新文档总索引、systems 目录和 3d-unit-game AI Skill。
• 新增 docs/systems/ServerActorPresentationSystem.md 作为“服务端创建表现”的专题文档，集中说明 PlayTransient(...)、ActorScopePersist + scope.SetActorSlot(...)、双端 GameDataActor 前置条件，以及高级 ActorScopeNodeBinding 的适用边界；ActorSystem.md 改为保留基础概念并跳转到该专题，降低样例分散造成的误用。
• AI 上下文生成支持项目自定义说明：项目根目录可新增 AGENTS.project.md，编辑器打开项目或运行 tools/setup-ai-context.ps1 时会把其内容合入生成的 AGENTS.md、CLAUDE.md 和 .cursor/rules/project-context.mdc。生成器不会创建、覆盖或删除 AGENTS.project.md，用户无需再直接编辑会被刷新的生成文件；wasicore-dev AI Skill 同步补充了使用规则和敏感信息提醒。
• 新增 GameSystemUI 对话、卡牌和 CmdResult 面板文档：对话文档覆盖 ConversationPanel、BubbleUI、ConversationUI.Register 和打字机效果；卡牌文档明确 CardSystemUI 只是客户端 UI / 拖拽层，玩法规则与服务端校验由项目实现；CmdResult 文档说明 CmdResultManager.ShowCmdResult 的使用边界和服务端失败结果回传方式。聊天系统仍存在昵称、私聊格式、敏感词、消息验证和跨局转发等未完成项，暂不作为 SDK 推荐公开入口。
• 新增 GameSystemUI 背包控件文档，沉淀 DefaultInventoryUI、InventoryUIEntrance、QuickBarUI、PickButton 的推荐接入方式、数据前置条件、模板定制和常见问题，并明确低层格子/列表类暂不作为第一层公开入口。
• 新增 OperationMail 运营邮件查询文档与 AI Skill，说明服务端如何查询运营后台全服邮件和个人邮件、如何与 CloudData 配合保存已读 / 已领取 / 红点状态，并明确该能力不是玩家互发邮件，也不包含官方收件箱 UI；官方邮件 UI 完成后会再补充高层 inbox / redpoint / 领取流程文档。
• 云数据 key 访问语义对齐远端数据库行为：远端数据库保存和比较 key 时本身按大小写不敏感语义处理，因此 WasiCore 包装层的按 key 取值便利方法与批量查询返回字典也调整为大小写不敏感匹配。对外文档和 CloudData AI Skill 同步明确：不要依赖 Gold / gold 表示不同数据，项目内仍建议统一使用小写 ASCII 与下划线 key。
• 云数据批量事务补充跨用户单次提交能力与文档：BatchTransactionBuilder.ExecuteSingleCommitAsync 可将多个用户各自通过 builder 添加的操作合并为一次 commit，适合玩家交易等需要整体成功或整体回滚的场景；文档同时补充了通过 CloudDataApi.ExecuteTransactionAsync 手动构造 TransactionOperation 列表并一次提交的低层用法。
• 云数据 ListItem 补齐 typed payload 便利 API：新增 PrepareUtf8ListItem / PrepareDoubleListItem、批量准备方法、UpdateListItemUtf8 / UpdateListItemDouble，以及 TransactionOperation.ListItemAddUtf8 / ListItemAddDouble 等底层工厂。ListItem 仍使用 CloudDataValueType.ListItem，内部通过 CloudDataListItemValueType 标记 raw / UTF-8 / Double；查询结果 IListItemRecord 新增 ValueType、Utf8Value、DoubleValue 和 TryGet... 便捷读取。手动构造 TransactionOperation 列表时，可通过 ListItemReference.ToListItemAddOperation() 把 PrepareListItem 生成的引用转成添加操作，无需直接暴露或手写列表项 UUID。
• GameGraph 材质系统补充对外纯色材质入口：新增 MaterialFlatLambert / KnownTechnique.FlatLambert / KnownTechnique.FlatLambertAlpha，用于程序生成 Mesh、调试几何体和无贴图纯色对象；同步补充 MaterialWater 的 SingleLayerWater 路径说明。当前不再对外推荐 MaterialUnlit / NoTextureUnlit*，真正无光照 Unlit 等外部 shadercache 覆盖后再作为独立入口补充。
• Runtime MCP 新增并文档化 GameGraph 材质排查工具：scenegraph.materials 可列出当前客户端 SceneGraph 中的 StaticMeshComponent 材质，material.probe 可按节点名、节点 ID 或材质槽返回单个材质快照。返回内容包含 technique path、base/alpha/depth/singlelayerwater pass 命中、关键材质参数、Stencil、RenderOrder、Cull/Fill 状态，便于配合 RenderDoc 排查 3D 物体不可见问题。
• 新增 gamegraph-materials AI Skill，整理 GameGraph 材质选型、RenderPath/pass 排查、Runtime MCP probe 用法和本地 technique 试验流程；运行时 Mesh 粒子示例改用 Editor/Techniques/Lambert/ParticleLambert.xml 作为推荐 technique。
• 补充纯客户端 SceneGraph 小游戏开发文档与 AI Skill：沉淀单人 3D 小游戏 / 材质 probe / 本地物理原型开发中的 GameMode 接线、SceneGraph 渲染链、RigidBody 驱动、GameSystemUI 输入事件模式、PBR witness 和 Runtime MCP 验证闭环；code_sample 新增 BlackHoleSample 作为客户端本地 SceneGraph 玩法样例。
• GameSystemUI 移动控件补充“输入事件模式”：MoveControlBase 现在可通过 UseMainUnit = false 关闭主控单位自动绑定，并在没有绑定 Unit 时继续通过 OnMoveInput 派发跨平台移动输入；新增 MoveInputEventArgs / MoveInputState 以及 GetMoveControl、TryGetMoveControl、SetUseMainUnit、BindMoveUnit 等扩展方法，方便从 GSUI.GameDataControl.MoveControl 的平台自适应根控件中取得实际键盘 / 摇杆控件。该模式面向纯 GameGraph / SceneGraph、相机、载具、光标等没有 MainUnit 概念的自定义控制目标；常规单位游戏仍可继续使用默认的 MainUnit 自动移动模式。同步新增 docs/systems/GameSystemUIMoveControl.md，并在 3d-unit-game AI Skill / reference 中补充 MainUnit 模式、指定单位模式和只读取输入事件模式的示例。
• 数据编辑器 AI 上下文补强了 Metadata.json、EntryInfo.json、src/DataGenerated/** 等派生文件边界，明确这些文件由编辑器 / MCP / 生成链从源数据刷新，不应作为手工维护入口，降低 AI 助手直接修改生成元数据的概率。
• 数据编辑器生成的 ScopeData.cs 会为公共 GameLink 字段补充 XML <see cref="..."/> 注释，IDE 中可直接跳转到对应 GameData 初始化代码的 Root() 工厂方法，方便从公共 Link 追踪到具体数据来源。
• 双端事件与 TypedMessage 文档补充 JSON 序列化边界：跨端 payload 应使用公开 get; set; 属性，框架默认 GameJsonSerializerOptions 未开启 IncludeFields，普通字段不会参与序列化。同步更新 wasicore-dev、3d-unit-game AI Skill 和项目 AI 编码规则模板，避免 AI 或用户用字段传递双端事件数据后对端只收到默认值。
• 面向已经拥有 TapTap Maker 限定测试资格的开发者，新增 AI 资产生成接入指引。完成本机配置后，可以让 AI 助手协助调用 TapTap Maker 生成图标、精灵、贴图、3D 模型、视频或背景音乐，并把生成结果按 WasiCore 项目的资源路径导入游戏工程。3D 模型流程也补充了导入说明：Maker 输出会包含原始模型文件和 MDL 资源包，资源包中已展开 .mdl、.prefab、材质和贴图；接入 WasiCore 项目时无需再手动从 GLB/FBX 转成 MDL，但仍需要按项目资源库流程接入整套模型资源。

2026-06-13 ～ 2026-06-22（已发布至线上正式环境）

编辑器与调试体验

• 编辑器已支持多人调试，因此移除了项目配置窗口中 1.0 时期遗留的“调试玩家虚拟 ID”配置项。调试模式下用户 ID 会按连入的调试玩家槽位数量从 100 开始递增分配，不再需要手工配置单个 user_ids[1]。
• GameSparkCore 与 global_default 补强了触发器里的字符串处理体验：新增可直接接收可变参数的“拼接字符串”节点，并补充对象转字符串、字符串转整数 / 浮点 / 双精度等常用转换节点的展示与弹出式表达方式，减少手写绕路逻辑。
• GameSparkCore 统一了 Timer 相关触发器节点的“等待 / 延迟”表述：等待一次、等待重复 N 次、等待循环 和 等待到下一帧 等节点的名称、说明与语句文案现在更一致，触发器里阅读和搜索定时逻辑时更直观。
• global_default 继续补齐触发器事件参数显示名，覆盖 GameUI.TriggerEvent 输入事件、对话事件，以及常见的技能、Buff、服务器频道等事件属性；在触发器里读取这些事件参数时，不再只看到难理解的原始字段名。
• global_default 已同步导出最新 WasiCoreSDK 触发器 API 声明，覆盖 DebugRenderer、多 Viewport / RenderToTexture、运行时 Particle Builder、场景视野、Node SyncVar、PropertyHostComponent 和 UnitNodeBinding 等近期新增能力；这些 API 现在可以在触发器选择面板中直接搜索和插入。
• 触发器选择面板优化了搜索后的标签列刷新：标签会跟随当前搜索结果更新并显示匹配数量，面向对象展开列在搜索切换后也会重新按当前模型刷新，减少旧分类或旧展开结果残留造成的误选。

商城与界面体验

• GameSystemUI 商店系统继续优化竖屏适配：商品详情区、数量选择器、商品列表卡片和交易记录弹窗改为更稳定的响应式布局，竖屏下的信息密度、点击区域和交易记录阅读体验都有所提升。

3D / 物理与 SCE 场景单位系统融合进展

• SceneGraph 层已经具备完整的 3D 与物理联机支持；与此同时，这些能力与 SCE 场景、单位系统的融合仍在稳步推进。本阶段已支持在编辑器中新建场景时选择空间模型（2.5D / 3D），已创建的场景也可以在数据编辑器中切换空间模型。
• 在 3D 空间模型下，单位已经可以在 SCE 场景中进行多层地表寻路；物理系统也已经可以识别 SCE 地表高度，并能正确托住掉落的物理对象等常见场景。
• 目前 3D 场景在修改地形后，需要手动重新生成对应的体素与导航网格：可通过菜单“场景 -> 生成3d场景资产”，或在地形编辑器左侧场景列表树中右键点击场景名并选择“生成3d场景资产”。生成完成后，如果在地形编辑器中看到半透明导航网格，即表示生成成功。
• 远端调试同步已补充 3D 静态阻挡产物 .blockhf 的二进制整文件发送，带静态阻挡单位的 3D 场景在调试启动时不再容易因为缺少 block 几何文件而与本地保存结果不一致。
• 当前单位移动控制器仍以 2.5D / 3D 寻路控制器为主，暂不包含物理模式控制器。物理移动控制器会在后续版本逐步补齐；现阶段如需自定义物理移动行为，可以通过 UnitNodeBinding 将单位与 GameGraph Node 关联后自行实现。

SDK 与文档

• 服务端 Player 新增连接管理 API：Kick(reason, clientMessage = null) 会按踢人流程发送客户端提示、清理平台注册信息并记录踢人原因；Disconnect() 会按主动离开流程断开连接。需要强制移出玩家时优先使用 Kick，普通退出 / 主动离开流程使用 Disconnect。
• GameGraph 运行时 Particle Builder 补充 Mesh 发射器材质 / Technique 覆盖和 Ribbon 行为、渲染、细分配置；code_sample 的 RuntimeParticleBuilderSample 增加动态拖尾和模型粒子展示。
• 补充 GameUI 自定义字体文档与 AI Skill：明确 Label.Font / Input.Font / TextButton.Font 使用字体 family 而不是 .ttf 文件路径，项目私有字体需要放在 res/font/... 并手写加入 ref/fontref.txt；未来可扩展类似资源收集工具的字体 ref 自动收集能力。
• 云数据新增两种值类型：SetUtf8Blob（可编辑的长 UTF-8 字符串，不受 SetData(string) 的 255 字符限制）与 SetDoubleBlob（双精度浮点云变量，补齐小数云变量能力——此前 2.0 数值仅支持 64 位整数）。读取分别用查询结果的 Utf8BlobData / DoubleBlobData 便捷视图。开发者后台「云变量查询」可直接查看并编辑这两类；普通二进制 blob 仍为只读（避免手工编辑损坏开发者自定义格式）。
• 云数据补充服务可用性判断 API：服务端可通过 CloudData.IsReady / CloudDataApi.IsReady 判断云数据服务是否已初始化，也可 await CloudData.WaitUntilReadyAsync() 等待服务可用；同时修复 SDK API 生成器遗漏静态属性 static 修饰符的问题，生成声明现在能正确展示 Game.IsUserCloudDataServiceInitialized 等静态属性。
• CloudData 文档和 AI Skill 补强启动时序说明：首轮云存档加载应同时等待 CloudData ready 与玩家 UserId ready，明确区分 ServiceNotInitialized、FailedToSend 与业务失败，并强调客户端 UI 通过服务端快照刷新，不直接访问云数据。

修复

• 修复 2.0 项目自定义字体在实机客户端和纯客户端调试中可能回退到默认字体的问题：编辑器保存时不再覆盖用户维护的 ref/fontref.txt，项目 res/ 下通过 ref/fontref.txt 声明的私有字体现在能在这些运行环境中正常生效。
• 修复地形编辑器在切换、预加载或保存多个场景时，区域 / 点可能从当前场景串写到其他场景视图或场景数据中的问题。
• 修复启动页竖版购买弹窗在商品图片为空时仍保留大块图片占位的问题，避免无图商品的标题、描述和购买信息被空白区域挤压。
• GameSystemUI 商店在编辑器调试模式下不再轮询星火币余额，也不会打开充值或平台支付入口；调试环境中点击相关付费入口会给出明确限制提示，避免反复输出余额查询告警或误导为真实支付可用。
• GameUI 的 .Border(...) 已恢复为独立 Border 控件包装模式，修复 native border 在父控件缩放或拉伸子控件时边框表现不符合预期的问题。Control.BorderThickness / Control.BorderBrush 以及 GameDataControl 中对应字段已从 SDK 高层 API 移除；需要边框时请使用 .Border(...) 或 UI.Bordered(...)。
• 修复编辑器结束远端调试时服务端日志可能未及时落盘的问题，AI 助手和开发者现在能更及时读取 logs/server 下的服务器日志。
• 修复 trigger-editor-mcp Skill 中 trigger_create_trigger 的误导性示例和说明：明确 Conditions 是正向通过条件、Statements 只放动作语句，触发器最终 return true; 由生成器自动补，避免 AI 把成功/失败 return 写入动作区导致后续日志等语句不可达。
• 修复触发器文件树在类节点上下文仍能新建模块级变量 / 触发器的问题；类上下文现在只保留构造函数、方法、属性、文件夹等合法成员创建项，新建类时也会默认补一个无参构造函数以贴近旧版 WinUI 行为。
• 编辑器已兼容 GameDataModel.Asset = { "Path": "res/path.prefab" } 这种结构化素材配置，避免 AI 助手按字段结构生成数据时导致预览或地形单位面板读取失败；但标准写法仍推荐直接使用字符串素材路径（如 "Asset": "res/path.prefab"）。

2026-06-08 ～ 2026-06-12（已发布至线上正式环境）

重点更新

🔗 新增 PropertyHostComponent 混合同步机制：位置走 Node、数据走属性组件（连续运动联机推荐范式）

为连续运动的联机游戏（小鸟 / 跑酷 / 弹球 / 竞速等）提供推荐同步形态：位置交给 replicated Node 的 transform（客户端原生平滑、零外插），游戏数据交给挂在该 node 上的同步属性组件。解决了以往用 PropertyObject 同步连续位置时、客户端必须手写 smoothing / 线性外插的痛点。

• 新增 PropertyHostComponent 属性宿主组件 + [PropertyHostFacet] / [PropertySyncType] 代码生成：在枚举上声明即生成强类型同步属性组件；服务端 node.AddPropertyHost<T>(player, syncType) 一行挂载并读写，客户端 node.OnPropertyHostReady<T>(...) / node.TryGetPropertyHost<T>(out ...) 取用（容忍组件晚于 node 到达）
• per-property 可见性 / 反作弊：属性可逐条设 SyncType.Self / Ally / All，且收件人 = 实体所在 SceneGraph 订阅集 ∩ 属性范围——可实现「看得到对面在动、却看不到对面背包」
• 新增客户端便利 SceneGraph.ObserveReplicatedNodes(onAdded, onRemoved)：一行跟踪当前及之后所有发布图里出现 / 消失的 replicated node，免去重复的 OnRegistered / OnNodeReplicated / 回灌样板，返回 IDisposable 解订阅
• Canvas 文本流式扩展（FontSize / TextAlign / LineHeight 等）改为可空友好（标注 NotNullIfNotNull）：在持有可空 Canvas?（如每帧渲染回调）时链式调用不再误报可空告警，行为向后兼容
• code_sample 新增 HybridFlappyBird（混合同步联机 FlappyBird 完整范例：node 位置 + PropertyHostComponent + CanvasAnimated 渲染 + IThinker 服务端模拟）与 PropertyHostPrivacy（per-property Self 反作弊演示）；保留 PropertyHostSample 作最简首读
• 新增对外文档：参考 docs/systems/PropertyHostComponentSystem.md（含 PropertyObject vs Node+PropertyHostComponent 选型对比）、老用户指南 docs/veteran-user-guide/05-MULTIPLAYER-SYNC.md、AI Skill docs/ai/skills/multiplayer-hybrid-sync/

⚠️ 旧 2D 联机模板（Simple2DMultiplayerGame 体系）弃用

Simple2DMultiplayerGame / RealtimeActionGameTemplate / TurnBasedGameTemplate 模板基类标记弃用（仅文档注释，不影响现有项目编译）。被弃用的是这套重模板基类，不是 PropertyObject——PropertyObject 作为离散 / 回合制状态的同步原语仍然推荐。

• 连续运动联机改用 node + PropertyHostComponent（见上）；离散 / 回合制直接用 PropertyObject
• 旧 code_sample/FlappyBirdMultiplayer 样例保留作迁移对照并标记弃用，指向 HybridFlappyBird
• docs/Simple2DMultiplayer/ 加弃用横幅指向新范式

🧱 GameGraph 双端物理能力补齐

GameGraph 进一步补齐服务端权威物理与客户端表现的双端闭环。现在可以在服务端运行 2D/3D 物理模拟、订阅 Node 级碰撞 / trigger 事件，并通过 replicated SceneGraph / Node / transform 将权威结果同步到客户端。

• 2D 物理支持服务端运行：PhysicsWorld2D、RigidBody2D、CollisionShape2D、Box / Circle / Edge / Chain / Polygon 形状、2D raycast result 和 11 种 Constraint2D 已同步到服务端 API
• 2D 碰撞事件双端可用：Node.OnCollisionBegin2D、OnCollisionEnd2D、OnCollisionPreSolve2D 可在服务端和客户端订阅；PreSolve 支持控制本次接触是否生效
• 3D 碰撞 / trigger 事件双端可用：Node.OnCollisionBegin、OnCollisionStay、OnCollisionEnd 可在服务端和客户端订阅；CollisionContact.IsTrigger 可用于区分 trigger 与普通碰撞
• 3D 约束与载具双端可用：Constraint 支持 Point / Hinge / Slider / ConeTwist，RaycastVehicle 支持服务端权威载具模拟，客户端可继续通过同步 transform 做表现
• replicated transform 平滑参数已开放：SceneGraph.TransformSmoothingConstant、TransformSnapThreshold 与 ConfigureTransformSmoothing(...) 可用于调节客户端接收服务端同步结果时的视觉平滑
• 典型 2D 用法现在可以采用“服务端 2D 物理模拟 -> SceneGraph 同步到客户端 -> 客户端 Canvas / GameUI 绘制映射内容”的模式
• GameGraph-only 层面已覆盖服务端建图、运行物理、接收 Node 级物理事件、查询、约束 / 载具控制和客户端 transform 同步；若需要把碰撞事件归属到 Unit / 技能 / 机关，仍建议结合 UnitNodeBinding 与业务层规则设计

✨ GameGraph 运行时 Particle Builder

新增客户端运行时粒子构造 API。现在可以不预制 .effect 文件，直接用 C# builder 创建 sprite / mesh / beam / ribbon 发射器，并配置位置、速度、加速度、生命周期尺寸、旋转、颜色、材质、SubUV、Beam 噪声 / 收束 / 平铺等常用模块。

• ParticleSystem.CreateRuntime() 创建运行时粒子系统，AddSpriteEmitter()、AddMeshEmitter(...)、AddBeamEmitter(...)、AddRibbonEmitter() 追加发射器
• 新增高层 builder：Timing、Spawn、Lifetime、Location、Velocity、Acceleration、Size、Rotation、Color、Material、SubUV、Mesh、Beam、Ribbon
• ExportEffect(...) 可在 Debug 模式下把运行时构造结果保存为 .effect，默认写入当前项目 res/RuntimeParticles；非 Debug 模式返回 ParticleEffectExportResult.NotDebugMode
• 公开 SDK API 声明已补充简短 XML summary，AI 助手可直接从 api/client/GameGraph_ResourceSystem.cs 理解各 builder 模块的用途
• code_sample 新增 / 完善 RuntimeParticleBuilderSample，展示运行时构造艺术化能量门、火花喷泉和一次性爆发粒子，并带 SceneGraph 镜头、UI 切换、Replay 和 Debug 导出

🔄 新增「1.0 → 2.0 项目迁移」AI Skill

新增面向 AI 助手的 1.0(ts2lua) → 2.0(C#/WasiCore) 项目迁移早期 Skill，与本周期「阻止 2.0 编辑器自动提升 1.0 项目、改为引导通过 AI 助手迁移项目内容」的改动配套使用。

• 新增 docs/ai/skills/migrate-1to2/（SKILL.md 流程层 + reference.md 详细层），已登记到 docs/ai/toc.yml 与 AI 文档索引
• 覆盖确定性迁移工作流、1.0→2.0 目录 / 类型名 / 概念映射表、1.0 工件解读（.ini 数编配置、trigger_module_main*.ts、trigger_validator*.ts、lua_declare.d.ts、场景资产），以及「必须手补 / 2.0 暂不支持」清单
• 明确当前能力边界：这是迁移 Skill 的早期版本，目前更适合作为迁移步骤、映射线索和人工校验清单使用，自动转换能力还比较弱；复杂逻辑仍需人工补齐和复核，后续会逐步补充映射规则、示例和可自动化的迁移能力

📘 「3D 单位游戏」AI Skill 补充：自动索敌投射物 / 瞬发消耗 / 模型阴影

基于实际项目排查，强化 docs/ai/skills/3d-unit-game/ 对几类常见误区的覆盖——这些机制引擎本就支持，旧文档未点透时容易被手写代码绕开：

• 新增「方向性自动索敌投射物（玩家开火 / 朝敌人射击）」：Vector + AlwaysAcquireTarget + 无目标施放即可实现"范围内有敌人朝最近敌人射、没敌人朝当前朝向射"；明确投射物方向取自技能 ExecutionTarget、与单位朝向无关——无需手动 SetFacing、监听 Order 阶段或客户端自算朝向。
• 新增「瞬发技能的弹药与资源消耗」：瞬发技能（Transient）不经过 Cast 阶段，消耗 / 门槛应放进效果树（首节点 Validators 做门槛、GameDataEffectCustomAction.Func 做消耗），不要挂在 Order 阶段事件上。
• 补充模型阴影行为：GameDataModel.ShadowSetting 默认不投阴影（需 opt-in），而 PrimitiveShape 默认带阴影——避免"主角(模型)没影子、子弹/敌人(形状)有影子"的不一致。
• SKILL.md 错误速查新增对应条目，并扩充该 Skill 的 description 触发词（投射物 / 射击 / 塔防 / 开火 / 自动瞄准 / 弹药）。

GameSystemUI 商店支付与余额显示补齐

GameSystemUI 商店系统补齐平台支付直发货订单记录，并优化商店顶部资源栏对星火币余额的展示。玩家通过平台支付购买商品后，订单历史现在能保留平台订单号、实付星火币和奖励明细，便于后续查询与对账。

• 平台支付直发货商品会写入商店订单历史，记录 IsPlatformPayment、PlatformOrderId 与 PlatformPaidAmount
• 平台支付订单会写入去重标记，避免同一平台订单重复补录
• 商店资源栏新增星火币余额显示，并在商店打开期间定时刷新；查询失败时保留上一次成功余额并输出告警
• 商店资源栏布局调整，普通资源、星火币余额、充值入口和交易记录按钮的排列更稳定

文档

• 纯客户端调试启动 Skill 补充 -width / -height 窗口尺寸参数说明，并提示可通过 Start-SceClientOnlyDebug.ps1 -ExtraArgs 传入。

编辑器与触发器体验

• GameSparkCore 常用触发节点的 Description 与 UiText 已统一，覆盖技能、Buff、单位、玩家、场景点、计时器、AI、物品、任务和云数据等节点，触发器搜索、语句阅读和 AI 辅助理解更一致。
• global_default 补齐技能、Buff、实体、物品、玩家、区域、场景、单位、GameUI 指针等内置事件参数显示名，触发器中读取事件参数时不再出现空白或难理解的原始字段名。
• 触发器菜单新增“打开项目文件夹”，可从代码生成目录快速回到项目根目录；模块启动器新增日志目录入口，便于排查 standalone/触发器加载问题。

修复

• 修复 Blazor 版信息列表在多人调试客户端日志中按玩家槽位过滤不准确的问题。客户端日志现在会直接携带当前客户端的玩家槽位，WASM 与 Lua 客户端日志都会写入同一套槽位元数据，避免不同玩家消息被归到玩家 0 或混入其它槽位筛选结果。
• 修复 game_entry 默认模板中的 TestTriggers 示例仍判断框架内置 GameCore.ScopeData.GameMode.Default 的问题。模板默认测试模式实际为项目数据中的 ScopeData.GameDataGameMode.MapGameMode，此前会导致新建项目的 Hello World 示例触发器不注册；现在示例逻辑已与 GlobalConfig.TestGameMode 保持一致。
• 修复 2.0 实验版本编辑器打开 1.0 项目时可能自动提升项目 API 版本的问题。现在这类项目结构跨度较大的打开操作会被阻止，并提示通过 AI 助手迁移项目内容，或在误用 2.0 编辑器时切换回 1.0 标准版本。
• 修复投射物朝向配置在底层表现中的不一致问题。
• 修复 GameDataUnit.Particle 粒子在频繁创建和复用时可能沿用上一次本地变换的问题，避免单位朝向正确但粒子视觉方向或偏移异常。
• 修复方向性粒子在多个实例同时播放时可能因渲染合批导致朝向互相干扰的问题。
• 修复部分粒子特效在材质配置异常时可能导致游戏直接中断的问题。现在单个异常粒子会在加载阶段被安全跳过并输出错误日志，不再因坏资源导致整体运行失败。
• 修复了特定情况下 Beam 粒子渲染可能出现的崩溃问题。
• 修复 global_default 缺失 System.TimeSpan.FromMilliseconds(long) 触发器声明的问题。
• 修复 global_default 触发器 UI 文案在保存或重新导出后可能丢失的问题，内置 API 的显示名、参数名、语句文本和分类配置会稳定保留。
• 修复触发器代码生成在属性 / 索引器访问、事件订阅、params 参数类型转换和缺失参数场景下可能生成错误 C# 或报错不清晰的问题；手动“生成代码”会强制刷新输出。
• 修复自定义事件属性 / 参数在文件树和语句树中的创建、显示与选择问题：右键节点会先同步选中，创建后会自动展开并选中新节点，自定义事件参数不再被错误映射成构造器参数显示。
• 修复触发事件或语句节点在可删除但不可拖拽时右键菜单缺少“删除”项的问题。
• 修复「触发器回旋镖游戏模版」中的法球发射伤害目标位置、双端事件参数反序列化和整数 TimeSpan 调用兼容问题。
• 修复开发者后台「云变量查询」无法显示 Blob 类型云数据的问题：2.0 项目上传后，后台此前只能看到数字（BigInt）类型的云变量，Blob 类型显示为空，现已可正常查看（目前显示二进制值，更多显示方式之后可以扩展）。
• 修复开发者后台无法查看 2.0 游戏局服务端脚本日志的问题。
• 修复开发者后台「游戏局日志 / 开局记录」中每个游戏局重复显示两份的问题。

2026-06-01 ～ 2026-06-05（已发布至线上正式环境）

重点更新

🧰 GameGraph DebugRenderer（客户端新增）

GameGraph 新增客户端调试绘制组件 DebugRenderer，用于在运行时直接绘制调试线框和辅助几何，方便排查碰撞、寻路、技能范围、骨骼挂点、raycast 命中、服务端同步对象可视化等问题。

• 新增 GameGraph.NodeSystem.Component.Graphics.DebugRenderer，通常挂在 SceneGraph 根节点使用
• 使用前需要对应视口开启 Viewport.DrawDebug = true
• 支持绘制线段、三角形、四边形、包围盒、视锥、球体、胶囊体、圆/弧线/椭圆、圆柱、圆锥、三角网格、任意多面体和骨骼
• 支持 AddStaticModelNormals(...) / RemoveStaticModelNormals(...) / ClearStaticModelNormals() 持续显示和清理静态模型法线
• 普通调试几何会在帧末清空；需要持续显示时应每帧重新提交
• 该组件为客户端渲染调试能力，只能在 #if CLIENT 代码中使用；不要在服务端逻辑中依赖它

🖼️ GameGraph 多 Viewport 与 RenderToTexture（客户端新增）

GameGraph 客户端渲染能力补齐多视口与渲染到纹理流程，适合画中画、监控屏、小地图预览、独立场景预览和材质贴图式的 3D 面板。

• Renderer.SetViewport(...) 支持附加 viewport，并可配合 Viewport.SetRect(...) 做画中画或分屏布局
• 新增 Renderer.GetOccupiedViewportIndices() 与 Renderer.GetNextFreeViewportIndex(...)，用于避开已占用的 viewport 编号
• 新增 Texture2D.CreateRenderTarget(...)、Texture2D.RenderSurface 与 RenderSurface.SetViewport(...)，可将独立 SceneGraph + Camera + Viewport 渲染到纹理
• 新增 GameUI 运行时纹理闭环：RTT 纹理可通过 RuntimeTexture.Register(...) / 控件 .Image(texture, name) 显示到普通 UI 控件，也可通过 Canvas.DrawTexture(...) 直接绘制到 Canvas
• 附加 viewport 和 RenderToTexture viewport 均可独立调用 Viewport.SetRenderPath(...)，推荐初始化时设置一次，例如使用 EngineRes/RenderPaths/CEMapSSAO.xml
• 编辑器内嵌调试模式下，直接调用 Renderer.SetViewport(...) 时会输出一次性提示：该模式的 viewport / render-target 配置与实机或独立客户端不同，手动 viewport 编号和 SetRect 坐标不一定代表最终运行效果，并提示使用非内嵌模式调试游戏的编辑器启动参数。主 GameGraph 视口仍推荐使用 Renderer.SetupMainViewport(...)

🌐 GameGraph Node SyncVar（新增）

新增 replicated Node 的轻量同步变量能力。服务端可以在 replicated Node 上写入小型状态或元数据，客户端随节点同步后读取这些值，用于发布图、服务端权威物理对象、机关状态、调试对象等场景。

• 服务端新增 Node.SetSyncVar(...)，支持写入 int、bool、float、string、Vector2、Vector3、Quaternion
• 客户端和服务端新增 TryGetSyncVar(...)、HasSyncVar(...)、GetSyncVarType(...)
• 客户端 SDK 不暴露 SetSyncVar(...)；如果客户端需要改变同步状态，应请求服务端处理，由服务端校验后写入
• string key 适合普通业务代码使用，内部按 Urho StringHash 规则转为 hash；uint key 适合生成代码、常量或已缓存 hash 的热路径
• SyncVar 只适合节点级轻量元数据或小型状态，不替代 Entity / Unit / Player 属性系统，也不适合复杂对象、大字符串或高频大 payload
• 当前不暴露删除 / 清空变量语义；需要清除状态时优先写入新的状态值，或通过节点生命周期重建

🎯 UnitNodeBinding metadata 自动识别

UnitNodeBinding 已接入 Node SyncVar metadata。服务端绑定 Unit 与 GameGraph Node 时会写入 unitId、sceneId、role、key，客户端收到 replicated Node 后可自动恢复本地查询绑定，用于 hitbox、hurtbox、发射点、raycast 目标等反查。

• 服务端 Unit.GetNode() / EnsureNodeBinding(...) 创建的 replicated Node 会携带 Unit 绑定元数据
• 新增 Unit 与 Node 的查询代理 API，包括 BindNode(...)、EnsureNodeBinding(...)、GetNode(role, key)、GetNodeBinding(...)、GetNodeBindings(...)、UnbindNode(...)、Node.GetBoundUnit() 与 PhysicsRaycastResult.GetBoundUnit()
• 支持按 role + key 为同一个 Unit 绑定多个 Node，内置用途包含 Root、Hitbox、Hurtbox、FirePoint、RaycastTarget、QueryProxy 与 Custom
• 客户端 replicated Node 到达时会读取 metadata 并建立本地查询绑定；Node 早于 Unit 到达时会等待 Unit 出现后补绑
• 客户端自动恢复的绑定只用于查询/反查，不会反向改写 replicated Node transform
• Scene 新增 GetEntity(int entityId) / GetUnit(int unitId)，用于按同步 ID 快速查询当前场景中的实体或单位

Vital 当前值 Clamp 可配置

GameDataVital 新增 ClampCurrent 配置，用于控制该类 Vital 的 Current 是否在结算时自动限制到 0 ～ Max。

• 默认值为 true，现有生命值、法力值等常规 Vital 行为保持不变
• 设置为 false 后，该 Vital 的 Current 可以低于 0 或高于 Max，适合超量护盾、过载能量、怒气溢出、蓄力池等玩法资源
• Vital 消耗系统中“加资源不能超过 Max”的检查会同步尊重该配置；关闭 ClampCurrent 的 Vital 可以通过负消耗恢复到超过 Max

👁️ 场景视野与扇形视野（WasiCore 新增）

WasiCore 新增场景级视野配置和单位视野能力对象，用于配置战争迷雾、视野全开、精确视野和扇形视野。

• GameDataScene.Vision 按 scene 生效，支持 SceneVisionMode.Normal（正常视野）、Open（视野全开）和 Precise（精确视野）
• 精确视野支持 VisionObserverPolicy.AllOwnedUnits、Explicit、MainControlledUnit 三种观察者策略；Explicit 可只让显式启用的少量单位参与计算
• GameDataUnit.Vision 是可选默认配置；配置存在时单位创建后会懒创建 UnitVision 并应用观察者开关和圆形/扇形形状
• 视野距离仍以单位默认属性 GSC.GameDataUnitProperty.Sight 为权威来源；UnitVisionConfig 不配置第二套距离，运行时 unit.Vision.Range 读写的也是 Sight
• 精确视野下可通过 UnitVisionShape.Cone、CentralAngle、InnerRadius 和方向来源配置扇形视野；无扇形配置时保持圆形精确视野
• 客户端新增现成可用的单单位本地视野遮罩渲染，通过 Player.LocalVisionFocus 选择焦点；SceneVisionConfig.UseMainUnitAsLocalVisionFocus 可自动使用本地玩家主控单位作为遮罩焦点
• 内置本地视野遮罩同一客户端同一时间只支持一个焦点单位；服务端精确/扇形视野的观察者数量不受此限制，多单位客户端视野表现可用 Canvas 或 GameGraph 绘制 API 自行绘制
• 文档补充精确视野性能建议：优先用 Explicit 控制观察者数量；敌方怪物不需要遵守迷雾/墙体/扇形时，可通过自定义 AI/技能过滤减少敌方精确视野观察者数量

🧩 GameSparkCore 触发器与默认资源补充

GameSparkCore 补齐了一批面向触发器和模板游戏的便捷封装，减少创建单位、物品、技能和读取常用状态时的样板逻辑。

• 新增默认物品分类预设 DefaultItemCategory，内置主手、副手、武器、盾牌、防具部位、药水、材料、任务等常用分类
• 新增服务端触发器节点 CreateUnitByLink(...)、CreateItemByLink(...)、CreateAbilityForUnit(...)，支持直接通过 IGameLink 创建单位、物品和为单位添加技能，并在无效链接或空目标时给出保护性返回
• 新增计算类触发器节点 RandomFloat(...) 与 IncludedAngle(...)，用于区间随机浮点数和两个角度的较小夹角
• Unit / Item 常用节点补齐默认值和触发器 UI 表达，包括技能、Buff、物品栏、订单、等级、经验、属性、AIThinkTree / WaveAI、拾取判断和物品给予等常见操作
• 用户云数据查询、任务接受 / 交付 / 对话通知、玩家主控单位设置等节点补充默认参数，触发器中可直接落地常见流程

🧭 触发器 UI 数据与默认值整理

global_default 同步整理新版触发器元数据，重点改善触发器面板中的显示名、描述、默认参数和可发现性。

• 补齐事件参数翻译、事件属性显示名和默认值，减少触发器节点中空白或难理解的字段
• 为时间、数学、布尔、弹窗、场景入口、单位 / 实体、表现调用等常用参数补充默认值和默认调用者
• 系统整理单位、技能、物品、玩家、游戏等分组的触发器 UI 数据，包含显示名、描述、提示、Label、排序和默认值
• 暴露区域创建配置，并补充圆形、锥形、矩形、线段等形状搜索 / 效果搜索相关 UI 数据
• 隐藏部分由 GameSparkCore 内部实现的底层创建函数，引导在触发器中使用更稳定的封装节点

修复

• 修复服务端寻路查询返回路点丢失场景归属的问题：调用 ScenePoint.PathWayPointsTo(...) 或 PathDistance(...) 时，返回的路点未携带其所在场景，会产生无意义的 “Scene created with hash 0” 报错日志，返回路点的 Scene 归属也不正确。现在每个返回路点都会正确归属到发起查询的场景，相关报错不再出现。（寻路结果的坐标本身一直是正确的，本次仅修复场景归属与误报日志。）

SDK 与文档

• API 声明已同步：服务端包含 SetSyncVar(...) 与读取 API，客户端仅包含读取 API
• API 声明已同步：客户端与服务端 Scene 均包含 GetEntity(...) / GetUnit(...)
• API 声明已同步：客户端与服务端 GameDataVital 均包含 ClampCurrent
• API 声明已同步：客户端与服务端包含 SceneVisionConfig、UnitVisionConfig、UnitVision，客户端包含 Player.LocalVisionFocus
• API 声明已同步：客户端 GameGraph.NodeSystem.Component.Graphics 包含 DebugRenderer
• GameGraphOverview.md、ServerGameGraphSceneGraphReplication.md、PhysicsSystem.md 已补充 Node SyncVar 的使用场景、端侧边界和示例
• GameGraphOverview.md 已补充 DebugRenderer 使用方式、帧生命周期和常用调试绘制 API
• GameGraphOverview.md 已补充多 viewport、RenderToTexture、SetRect 坐标基准和编辑器内嵌调试注意事项
• 新增 SceneVisionSystem.md，并在 wasicore-dev AI skill 中补充场景视野速记
• server-authoritative-3d-physics 与 wasicore-dev AI skill 已补充 SyncVar 速记，避免继续把 replicated Node 只理解为 transform 同步
• wasicore-dev AI skill 已补充多 viewport / RenderToTexture 速记，便于 AI 生成 GameGraph 渲染样例时避开硬编码 viewport 编号和编辑器内嵌调试误判
• GameGraphAudioParticle.md 已补充运行时构造粒子的示例、模块覆盖表、Debug 导出说明和端侧边界；新增 runtime-particle-builder AI skill，方便 AI 助手在“代码生成粒子/程序化特效/不用预制 .effect”场景下直接采用正确流程
• map_templates 的 code_sample 新增 RendererViewportSample，演示主视口接管、多 viewport、SetRect、RenderPath 对照和 RenderToTexture
• map_templates 的 code_sample 新增 SceneVisionSample，演示 GameDataScene.Vision、UnitVisionConfig、显式观察者策略、扇形视野和平台自适应移动控制
• code_sample 示例索引已补充多视口 / RenderToTexture 与场景视野示例入口，方便从需求直接定位示例目录
• 触发器 MCP 文档补充：普通触发器逻辑应通过 trigger_* MCP 修改，不应直接手写 editor/trigger/**/*.json
• game_entry 模板已引用 GameGraph；game_entry、data_sample、battle_grounds_template 等模板新增 BuildAndCopy.bat，可直接构建并复制客户端 / 服务端 Debug 产物
• 模板 BannedSymbols.txt 新增对当前 WASM BCL 风险调用 String.Join(params string[]) 与 String.Concat(string[]) 的禁用提示，降低客户端运行期 TypeLoadException 风险
• SCE Editor MCP DebugTools 新增 debug_stop，自动化调试结束后可请求编辑器关闭当前内嵌调试游戏

---

2026-05-20 ～ 2026-06-01（已发布至线上正式环境）

重点更新

🌐 服务端 GameGraph 场景同步（新增）

新增「服务端 GameGraph 场景发布与同步」能力。现在可以在服务端组装 GameGraph 场景并发布，引擎会按玩家维度将场景同步到对应客户端，客户端可订阅场景同步的变更事件。

• 新增 SceneGraph 发布 API 与显式的同步复制模式配置
• 脚本创建的 SceneGraph 支持按玩家 Publish(player) / Unpublish(player)，一个客户端可同时订阅多个服务端发布的 SceneGraph；SCE 默认场景仍沿用每客户端一个同步会话
• 服务端场景在「无角色物理」模式下运行，按 SceneGraph id 路由引擎更新
• 客户端连接后再启动场景同步，避免提前同步带来的问题
• 客户端新增 SceneGraph.OnRegistered / OnUnregistered、GetRegisteredSceneGraphs()，以及按 SceneGraph 开启的 OnNodeReplicated / OnNodeUnreplicated 事件，便于观察发布图和节点生命周期
• SceneGraph / Node / Component 新增 IsReplicated 判定，服务端和客户端都可用于调试同步状态
• SceneGraph 新增同步变换平滑配置：TransformSmoothingConstant、TransformSnapThreshold 与 ConfigureTransformSmoothing(...)
• published_scenegraph_sync_smoke 已验证单客户端生命周期、双客户端多图订阅 / 隔离、断线清理、客户端本地网格可视化与主视口绑定 / 恢复，以及服务端权威 3D 物理变换同步闭环
• SDK 文档同步更新 GameGraph 双端化状态，移除“GameGraph/3D 物理仅客户端”的旧限制说明，并新增服务端 SceneGraph 发布语义文档

🔌 三端共享引擎接口

客户端、编辑器、服务端现在共享同一套 Urho3D 原生接口绑定，脚本侧（WASM）可在三端一致地调用引擎能力，显著减少端差异。

🎨 原生 GUI 边框（新增）

编辑器支持原生 GUI 边框编辑，GameUI 改用原生边框属性，边框渲染与编辑体验更统一。

---

新功能与 API

• GameGraph 渲染 / 视口控制：新增 Viewport.SetRenderPath、Renderer.GetMainViewport 与可选辅助类 SceneGraphMainViewportController。独立 SceneGraph 可以只作为同步数据源使用；若要直接渲染为 3D 画面，需要客户端配置 Camera/Viewport。底层主视口入口仍是 Renderer.SetupMainViewport，辅助类只用于临时接管主视口时管理保存、绑定、注销切换和恢复。

  Renderer.SetupMainViewport(scene, camera);
  Renderer.GetMainViewport()?.SetRenderPath(
      "EngineRes/RenderPaths/CEMapSSAO.xml"u8);

• GameGraph transform 平滑：SceneGraph 可配置 replicated Node transform 的客户端视觉平滑常量与 snap 阈值。该能力控制客户端向最新网络目标的收敛表现，不改变服务端权威物理结果，也不会作为网络状态自动同步。
• 日志 flush：新增 Game.FlushLogs()。用于测试与诊断时强制落盘当前运行时日志；服务端在编辑器调试链路下会同时触发本地保存的远端服务端日志 flush，便于在流程结束后立即查看 logs/server。该能力需要 SDK 与客户端/服务端运行时二进制同时更新到包含 IViewGame.FlushLogs 的版本；兼容旧运行时时可作为可选诊断能力。
• 自动施法移动策略：AI 新增 auto-cast movement policy。决定移动时是否进行自动施法。
• 地编可放置对象坐标输入框：场景中可放置对象现在可以手动输入坐标和朝向

---

优化改进

AI / WaveAI 战斗行为

• 追击（Hunt）模式全面重做距离判定：交战阈值统一换算为「中心距」并与攻击 / 扫描范围对齐（engagementRange = max(MinimalApproachRange, ClampedAttackRange)）。
• 远程单位不再强行贴脸；近战 + 大扫描范围单位不再在中途呆站等待下一次 tick；支援 / 采集等无攻击技能单位也能正确受益。
• MinimalApproachRange 配置现在被正确尊重（此前被写死的移动参数和精度修正系数架空）。
• 行为树扫到敌人、FocusTarget 锁定时均会正确刷新 CombatDelay，明确战斗内 / 外扫描范围相互独立。

Spine 动画

• 支持 Spine 3.8 skel 资源。注：仅支持 3.8 skel 格式而非 3.8 json 格式。4.1 和 4.2 版本资源两种格式都支持。
• 优化动画事件监听器，降低运行期开销。

编辑器体验

• 改进「创建条目」类型选择器的加载与展开交互。
• API 版本通道切换 UI 优化：新装编辑器默认使用标准 API 通道，并在所选通道内自动保持最新 API 版本。
• 修复多开编辑器与 MCP 功能的冲突。

诊断

• 新增托管 minidump 与全局异常处理，便于崩溃诊断。
• 新增脚本侧显式日志 flush 能力，减少自动化测试与远端服务端调试时等待日志刷盘的成本。

---

问题修复

稳定性 / 崩溃

• 修复地形检视器崩溃。
• 修复数据编辑器窗口在关闭时导致的一系列崩溃问题。
• 修复 WinUI 首次异常重入问题。
• 修复关闭 Spine 调试页签崩溃、Spine 空事件回调崩溃。
• 修复瞬发连续施法（instant recast）导致的栈溢出。
• 修复 iOS 上 HTTP Lua testAlive 崩溃。

触发编辑器

• 修复部分类相关问题、get 函数被替换、函数参数默认值、变量错误检查、元组类型、函数类型右键等多处缺陷。

其他

• 修复数据编辑器新建条目显示继承模板名而非实际输入名。
• 修复资源库首次导入模型染色会闪退的问题。
• 修复配置 ini section 更新。

---

SDK 与文档

• 新增官方捏人资源索引，增加更多图标资源（供 AI 助手 / SDK 工具使用）。
• 新增 behavior-troubleshoot 运行期行为排查能力。
• 新增 server-authoritative-3d-physics AI skill，沉淀服务端权威 3D 物理与 GameGraph 发布图的推荐分层。
• 同步更新 SDK 产物：SceneGraph 同步、自动施法、Spine、GUI 边框等。
• 修正官方 UI 库中自定义数编表的资源字段类型：相关字段现在使用对应资源类型而非字符串，数据编辑器中填写这些节点时会显示正确的资源选择控件。
• 补充 Spine 3.8 兼容性说明。