TiXL SkillQuest 关卡引导反馈机制全解：Tip/Warning 提示的触发、抑制与褪入规则

TiXL SkillQuest 关卡引导反馈机制全解Tip/Warning 提示的触发、抑制与褪入规则【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3TiXL 内置的 SkillQuest 技能关卡系统会在关卡进行中提供轻量、分层的引导蓝色Tip图标指向下一个值得调整的参数黄色Warning图标标记你改过但不属于解法的参数。本篇技术指南以仓库中的手动测试集 .tests-manual/skill-quest-feedback.md 为骨架逐条还原 11 个验证步骤的可复现操作与预期结果并深入到 LevelFeedback.cs、SkillQuestParameterHint.cs、TourInteraction.cs 等源码讲清提示如何分类、何时被抑制、如何褪入、如何换手帮助开发者在改动编辑器 UI 后对 SkillQuest 反馈做系统性回归验证。SkillQuest 反馈机制与测试集背景SkillQuest 是 TiXL 编辑器中的关卡化学习系统用户在 Home 屏的Skill Map中选择主题如 Gradients进入对应关卡编辑器会切换到最小化布局隐藏主菜单加载该关卡的符号工程并播放引导 tour。其核心运行逻辑位于 SkillTraining.csStartActiveLevel()负责载入关卡工程、切换到SkillQuest布局、隐藏全部 UI 元素、把输出窗口固定到关卡根实例PostUpdate()在每帧求值后调用LevelFeedback.Rebuild()重新分析用户编辑与解法快照的差异。这套引导反馈完全基于关卡符号上定义的 Snapshot快照LevelFeedback.TryCreate()从VariationHandling.GetOrLoadVariations(compositionRoot.Symbol.Id)读取关卡的变化池找出唯一的非预设快照作为解法。快照缺失或数量多于一个时会通过Log.Warning输出诊断信息并选择第一条。因此运行本文档的前提是Skills 层级上至少定义了一个快照默认关卡都满足且 TiXL 处于已打开、允许离开运行状态的环境中。本文档属于仓库.tests-manual/目录下的手动测试集。按照 .tests-manual/README.md 的约定每个测试集是单个 Markdown 文件frontmatter 中的id如skill-quest-feedback与文件名一致added-in-version: 4.2标记其随 4.2 版本引入scope: skill-quest、tags: [user, essential]分别标注功能域与筛选标签essential表示功能主路径。每个步骤以## Step:开头用**Action:**描述测试者操作、**Expected:**列出可观测结果——这套格式设计为将来可被编辑器内的 runner 解析驱动。前置条件与运行入口执行本测试集前确认以下条件TiXL 已打开且当前没有加载项目或加载的是可以放心离开的项目Skills 层级上至少存在一个快照默认关卡自带从 Home 屏打开Skill Map选择Gradients主题并启动第一关等待 tour 出现。由于关卡屏幕会隐藏主菜单测试的第一步先通过快捷键唤出辅助窗口方便后续逐步核对。步骤 1关卡进行中切换手动测试运行器操作从 Home 屏打开 [ui:SkillMap|Skill Map]选择Gradients主题并启动第一关。tour 出现后按下CtrlShiftAltT。预期结果即使主菜单已隐藏Manual Test Runner 窗口仍会浮现在关卡之上再次按下CtrlShiftAltT会隐藏它CtrlShiftAltL以同样的方式显示/隐藏 Console Log 窗口。这一步验证的是SkillQuest 关卡在SwitchToMinimalLayout()见 SkillTraining.cs中切换到最小布局、并调用UiConfig.HideAllUiElements()隐藏主菜单后调试类窗口依然可以通过全局快捷键拉起保证测试者在关卡内也能观察日志与运行状态。这也为后文观察褪入时序、核对提示切换提供了窗口基础。步骤 2Tour 阅读期间抑制提示操作逐个点击 tour 的引导点但在第一个信息型引导点停下该点的小圆点标签为弱化色而非橙色。不点击Continue等待至少 15 秒。预期结果参数行、图中任意 operator 徽标、[ui:ParameterWindow|Parameter Window] 任意位置都不会出现黄色 Warning 或蓝色 Tip 图标输出画面仍正常渲染tour 本身不受影响。这一行为在源码中有明确对应TourInteraction.IsTourBlockingHints(SymbolUi)见 TourInteraction.cs会在当前 tour 点样式为Info或InfoFor时返回 true——即信息型引导点正在占用用户注意力时反馈提示被整体抑制而 Call-to-Action、Conclusion、Tip 型引导点因为期待用户动手操作不会阻断提示。LevelFeedback.UpdateGlobalEligibility()每帧读取该状态一旦处于阻断期就把_hintsEligibleSince重置为当前时间从而让提示何时开始褪入的计时始终从 tour 放行之后重新起算。步骤 3Tour 结束后提示褪入操作继续点击剩余 tour 点直到 tour 到达最后的 now you try 步骤或完全结束。随后不触碰任何参数保持等待。预期结果约 5 秒后第一批 SkillQuest 图标开始褪入一个蓝色 Tip 图标出现在建议尝试的参数上一个黄色 Warning 图标出现在每一个当前值与解法不一致的参数上再过约 5 秒图标达到完全强度图中 operator 上对应的徽标与参数行图标同步褪入。源码中的HintDelaySeconds 5.0与HintFadeInSeconds 5.0见 LevelFeedback.cs正是这两个时间常数的出处。ComputeAlpha()对每个可见提示维护独立的_hintSeenSince时间戳先从提示出现起等待 5 秒此间 alpha 为 0再用 5 秒线性褪入到 1。GetOpHintAlpha()则对 operator 徽标取触发该徽标的所有 key 的最大 alpha实现参数行图标与图形徽标同步淡入。步骤 4同一时刻只显示一个 Tip操作在 Parameter Window 与图内徽标中扫描蓝色 Tip 图标。预期结果整个关卡范围内恰好只有一个蓝色 Tip 图标——位于单个参数行上若该参数所属的 operator 在图中可见则其徽标上也只有一个 Tip其余建议参数不携带任何图标。这是聚焦提示focused tip策略的体现。LevelFeedback.UpdateFocusedTip()在每帧重建时从所有Required当前为默认值但属于解法与Warm已偏离默认且属于解法但值还不正确参数中按ComputeRelevancy()的评分只挑出一个作为当前 Tip评分规则中 bool 参数得 1000 分、枚举得 500 分、数值/向量为 0 分同层级内更靠后更接近可见输出的子节点与参数优先且优先选Warm接近正确的参数而非未触碰的Required。而SkillQuestParameterHint.TryGetVisible()对非聚焦 Tip 直接返回 falseTryGetOpStatus()也只允许聚焦参数所属的 operator 挂上 Tip 徽标保证图中始终只有一条前进方向的提示。步骤 5回退后 Warning 提示清除操作任选一个当前显示黄色 Warning 图标的参数先确认图标可见然后改变它的值切换 bool、拖动滑杆均可再点击该参数的名称按钮将其回退到默认值。预期结果Warning 图标立即从参数行消失图中 operator 的徽标同步更新如果这是该 operator 唯一被标记的参数黄色徽标一并清除接下来 10 秒内不会重新出现黄色图标——参数已回到默认值。源码中的参数状态判定非常关键Rebuild()使用值相等性而非IsDefault标记来归类见 LevelFeedback.cs——把 bool 拨回默认值或把数值重新输入默认值后IsDefault仍为 false但值已与默认一致此时应归为Required/Untouched而非Forbidden。AreEqual()优先使用ValueUtils.CompareFunctions注册的比较函数未注册类型才回退到字符串比较。回退动作通过参数名按钮触发对应源码中参数行名称按钮上的 revert 槽位SkillQuest 图标恰好绘制在同一个槽位见 SkillQuestParameterHint.cs。步骤 6拖拽期间 Tip 保持粘性操作找到聚焦 Tip 参数带蓝色图标与进度环的那个拖动其值扫过快照目标值——即一路拖过正确值、拖到另一侧期间不松开鼠标。预期结果蓝色 Tip 图标与进度环全程保持可见即使值短暂经过或停在正确值进度弧在接近目标值时朝满弧增长扫过目标后收缩颜色在接近目标时从深色向白色偏移。两个源码细节支撑此行为。其一TryGetVisible()中有一条专门分支见 SkillQuestParameterHint.cs当ImGui.IsAnyItemActive()为真正在拖拽任何控件且当前 key 是聚焦 Tip 时即使它已命中正确值仍强制返回 Tip 提示避免可视化在拖拽途中弹出又弹回。其二UpdateFocusedTip()同样在拖拽期间ImGui.IsAnyItemActive()保持当前聚焦选择不变。进度弧本身由DrawProximityArc()绘制GetTipProximity()返回的接近度经ApplyGainAndBias(0.2f, 0.2f)柔和化后映射为弧的填充比例弧色从前景色向更亮色混合形成越接近越亮的视觉效果。步骤 7松开鼠标后 Tip 换手到下一个参数操作保持聚焦 Tip 参数被选中将其拖到精确的正确值并松开鼠标。预期结果蓝色 Tip 图标立即从已正确的参数上消失紧接着蓝色 Tip 图标出现在另一个建议参数上复选框、下拉框或数值取决于哪一个是最值得尝试的下一步新 Tip 用约 5 秒淡入而不是瞬间达到完全强度。这正是聚焦策略与褪入机制的协同结果松开鼠标后ImGui.IsAnyItemActive()变为 falseUpdateFocusedTip()重新按相关度评分挑选下一个 Warm/Required 参数作为新聚焦点新 key 没有_hintSeenSince时间戳在UpdateHintTimestamps()中被登记随后ComputeAlpha()从零开始走完 5 秒延迟 5 秒淡入的完整窗口因此表现为换手后重新褪入而非瞬切。步骤 8Bool/枚举型 Tip 不显示进度弧操作继续解题直到聚焦 Tip 落到复选框或下拉框参数上这类参数在关卡中很常见悬停该图标。预期结果蓝色 Tip 图标正常显示但周围没有进度环——复选框/下拉框非对即错没有逐渐接近的中间态可画悬停 tooltip 以彩色提示行开头Try tweaking this parameter…或Youre close — keep tweaking…。源码中SupportsProximityArc()明确把枚举类型排除在进度弧之外ComputeProximity()对不支持的离散类型返回-1f哨兵值DrawProximityArc()见到负值直接跳过环与填充见 LevelFeedback.cs 与 SkillQuestParameterHint.cs。tooltip 的彩色首行由DrawTooltipPrefix()输出以 Tip 蓝或 Warning 黄渲染提示文案再接 4px 垂直间距随后才是常规的描述与 Click to reset to default 说明。步骤 9Gradient 参数保持静默操作在包含Gradient输入的关卡默认 Gradients 关卡全部包含中检查渐变参数行。预期结果即使编辑过渐变渐变参数行上也永远不出现 Tip 或 Warning 图标仅因渐变与解法不同的 operator不会因此获得 SkillQuest 徽标。这是Rebuild()中的显式过滤源码在遍历输入槽时遇到input.Value.ValueType typeof(Gradient)直接continue跳过见 LevelFeedback.cs注释说明了原因——Gradient 这类结构化引用类型没有可靠的相等性比较若走ToString()回退比较会产生肉眼相同但判定不同的幻影不匹配因此在实现基于采样的比较之前一律不参与反馈。步骤 10悬停 tooltip 展示提示文案操作悬停一个带 SkillQuest 图标的参数名称聚焦蓝色 Tip 或任意黄色 Warning等待 tooltip 出现。预期结果tooltip 第一行是 SkillQuest 提示消息颜色与图标一致Tip 为蓝、Warning 为黄其后是常规的描述与 Click to reset to default 说明非当前 Tip 的其他建议参数不显示提示消息只有普通描述。提示文案映射在SkillQuestParameterHint.TryGet()中定义Required参数给出 Try tweaking this parameter…Warm给出 Youre close — keep tweaking…Forbidden给出 This parameter isnt part of the solution. Revert it.颜色分别对应UiColors.StatusActivated与UiColors.StatusWarningCorrect及其他状态不产生任何提示。而参数行上的图标只在该参数是聚焦 Tip或该参数是 Forbidden时绘制这与步骤 4 的单 Tip规则一致。状态机与徽标聚合的源码视角将所有步骤串联起来看整套反馈可以归纳为一条每帧执行的数据流SkillTraining.PostUpdate()在求值后调用LevelFeedback.Rebuild()Rebuild()遍历关卡的 snapshot 可用子节点及其输入槽跳过EnabledForSnapshotsfalse的节点、不可混合的类型与 Gradient用值相等性把每个参数归类为Untouched / Required / Correct / Warm / Forbidden之一见 LevelFeedback.cs 的枚举定义与分类逻辑UpdateFocusedTip()按相关度评分选出唯一聚焦 TipUpdateHintTimestamps()维护每个可见提示的褪入计时SkillQuestParameterHint.TryGetVisible()/DrawIcon()/DrawTooltipPrefix()完成图标、进度弧与 tooltip 首行的渲染TryGetOpStatus()把该 operator 存在 Forbidden 参数聚合成黄色 Warning 徽标、把该 operator 拥有聚焦 Tip 参数聚合成蓝色 Tip 徽标消息文案区分单个/多个参数This parameter is not part of the solution. Revert it. 或 {n} parameters are not part of the solution. Revert them.。关卡通关由名为_PlayModeProgress的浮点变量驱动PostUpdate()中当求值进度达到 1.0 且状态稳定后SkillTraining会记录Completed结果、更新主题进度并弹出SkillProgressionPopup。此外Rebuild()还内置了MaybeLogTransition()诊断把当前R/W/C/F四个计数压成指纹仅在变化时输出一行[LevelFeedback]日志——测试者在步骤 5、7 之后可通过CtrlShiftAltL打开的 Console Log 核对这些计数变化作为肉眼观测之外的第二重证据。总结skill-quest-feedback.md这份测试集用 11 个可执行步骤覆盖了 SkillQuest 引导反馈的关键契约提示的唤起tour 结束后延迟 5 秒褪入、再 5 秒到位、单 Tip 策略、Warning 回退即清、拖拽粘性、换手重淡入、离散参数无进度弧、Gradient 静默与 tooltip 着色。配合 LevelFeedback.cs、SkillQuestParameterHint.cs、TourInteraction.cs 三处源码任何改动若触及参数反馈、tour 交互或徽标渲染都可以按本测试集逐条回归确保引导提示在正确的时间出现、在正确的时刻移动、在正确的时机清除。若需为 SkillQuest 新增关卡或调整反馈行为也建议遵循 .tests-manual/README.md 的约定同步维护本测试集。【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考