Godot 制作预览校验：材料够不够、结果对不对，别等点下去才知道

制作系统通常看起来很直接：选择配方，检查材料，点击制作，获得道具。但真正进入项目后，会出现批量制作、随机词条、成功率、替代材料、活动折扣、背包容量、服务器确认和 UI 预览。玩家最讨厌的是点下制作后才发现材料不够，或者预览显示的结果和实际得到的不一致。

Godot 客户端需要把制作预览和提交分开。预览阶段给玩家一个可信的 CraftQuote：需要什么材料、会消耗多少、可能得到什么、背包是否够、成功率或保底如何；提交阶段带 quote_id 或配方版本给服务器确认。

项目里的真实问题

一个装备打造系统中，客户端按本地配置显示需要 10 个铁矿，服务器活动期间实际只要 8 个。玩家点制作前看到材料不足，无法点击；另一次配置反过来，客户端显示够材料，服务器扣除失败。还有随机词条装备，预览只显示基础装备，玩家以为一定得到固定属性。

制作系统的核心问题是预览可信度。客户端可以做本地快速预览，但涉及消耗和结果时，最终应使用服务器或权威配置生成的 quote。UI 必须告诉玩家哪些结果确定，哪些结果随机。

设计目标

• 预览可信：材料、消耗、结果和限制来自同一份配方快照。
• 失败前置：材料不足、背包满、配方锁定尽量在点击前展示。
• 提交可对账：制作结果由服务器返回驱动，不由客户端猜测。
• 批量安全：批量制作时材料、容量和部分失败有明确处理。

这些目标不是为了堆抽象，而是为了让 Godot 客户端在内容量增加、平台差异变多、团队协作变复杂之后仍然可维护。原型阶段直接在节点脚本里写判断很快，但进入发版节奏后，系统需要能解释当前状态、能处理失败、能被 QA 复现，也能被后续同事接手。

推荐架构

flowchart TD
    A["制作意图/配方选择"] --> B["CraftPreviewService"]
    B --> C["配方快照"]
    B --> D["材料校验"]
    B --> E["结果预览"]
    B --> F["提交确认"]
    C --> G["状态快照"]
    D --> G
    E --> G
    F --> G
    G --> H["表现层/日志/回滚"]

图里的模块可以按项目规模合并。小团队可以先用一个 Autoload 管理核心状态，大团队再拆成 Resource 配置、运行时服务、调试面板和 UI ViewModel。真正重要的是调用方向：业务脚本提交意图，系统层做决策，表现层只消费快照。这样功能不会随着页面和场景数量增长而失控。

关键实现细节

CraftQuote 包含 recipe_id、recipe_version、quantity、required_items、optional_items、currency_cost、result_preview、random_pool、success_rate、inventory_check、expires_at。UI 展示 quote，而不是自己读多个配置表拼结果。
本地预览可以快速响应，但当配方涉及活动折扣、服务器库存、限时成功率时，应请求权威 quote。本地 quote 和服务器 quote 都要带 source，UI 调试模式能看出来。
批量制作要逐项或整批定义。若材料只够制作 7 次，玩家输入 10 次时，UI 应提示最多 7 次；若背包容量只够 5 件，结果也要提前提示。随机结果批量展示可以用范围和概率，而不是假装确定。
提交制作后进入 pending。按钮禁用，材料暂不从本地永久扣除，只显示“预计消耗”。服务器成功返回 grants 和 consumed 后，再更新背包并展示结果。

失败处理和恢复路径

服务器返回 recipe_changed 时，刷新 quote 并要求玩家重新确认。不要按新配方自动制作。
背包满时，提示缺少容量或引导整理，不要吞掉制作结果。若服务器支持临时邮箱，也要清楚展示。
请求超时后，查询制作订单或刷新背包。不能简单重试，以免重复消耗。

数据契约和协作接口

RecipeProvider 提供配方版本和本地预览；CraftPreviewService 负责合并玩家状态和权威 quote。
InventoryService 提供材料和容量快照，制作 UI 不直接改背包。
RewardPresenter 使用服务器 grants 展示结果，特别是随机词条和暴击产出。

GDScript 接口草图

class_name CraftPreviewService
extends Node

signal snapshot_changed(snapshot: Dictionary)
signal warning_raised(code: String, detail: Dictionary)

var _snapshot := {}
var _active_version := 0

func submit(intent: Dictionary) -> void:
    _active_version += 1
    var version := _active_version
    _snapshot = {"phase": "pending", "intent": intent, "system": "godot-crafting-preview-validation-2026"}
    emit_signal("snapshot_changed", _snapshot)
    _resolve(intent, func(result: Dictionary):
        if version != _active_version:
            return
        if result.get("warning", "") != "":
            emit_signal("warning_raised", result.warning, result)
        _snapshot = result
        emit_signal("snapshot_changed", _snapshot)
    )

func current_snapshot() -> Dictionary:
    return _snapshot.duplicate(true)

这段代码只表达接口形状。实际项目里，intent 应该换成明确的 Resource 或 typed Dictionary，_resolve 内部也要处理超时、取消、错误码和日志。保留版本号，是为了避免旧异步结果覆盖新状态。Godot 项目里 UI 快速切换、资源晚返回、网络重试都很常见，没有版本保护会出现非常隐蔽的回退问题。

分阶段落地

第一阶段实现本地配方预览、材料不足和背包容量提示。
第二阶段接入权威 quote、recipe_version 和 pending 状态。
第三阶段支持批量制作、随机结果展示和订单查询。

自动化验证和人工验收

活动折扣改变材料消耗时，预览刷新并和服务器一致。
材料不足、背包满、配方未解锁分别有不同提示。
批量制作数量超过材料或容量时，UI 给出最大可制作数。
提交超时后不会重复扣材料。

观测指标

• Quote 获取成功率和过期率。
• 制作失败原因分布。
• 批量制作被限制次数。
• 预览和实际结果不一致次数。

指标不必一次性全部上报。开发包可以显示完整调试面板，内测包采样关键计数，正式包只保留错误码和聚合趋势。关键是让一次异常能落到具体阶段、具体配置和具体玩家路径，而不是停留在“好像偶尔不对”的口头描述。

上线前检查清单

• UI 展示 CraftQuote，不散读配置。
• quote 带 recipe_version 和 expires_at。
• 随机结果明确标注概率或范围。
• 制作成功以服务器 grants 和 consumed 为准。
• 超时后查询订单或刷新背包。

检查清单不是为了增加流程负担，而是把隐性经验写下来。能自动化的尽量交给脚本，不能自动化的也要明确谁在什么阶段确认。每次事故复盘后补一条检查项，系统会随着项目经验逐渐变厚。

案例复盘

一次活动打造事故中，服务器配方减免材料，但客户端本地表没更新，玩家明明够材料却不能制作。接入权威 quote 后，活动期间 CraftQuote 返回减免后的 required_items，UI 立即更新。配置不一致不再直接阻断玩家。

灰度验收脚本

灰度验收可以准备固定配方、随机配方、活动折扣配方和批量配方。分别测试材料不足、背包满、配方变更、提交超时。验收报告要能对账：预览消耗、服务器消耗和背包最终状态。

维护策略

制作系统上线后，新增配方必须补预览样本。样本包含材料、结果、随机池、限制和活动修正。没有样本的配方不要直接上灰度，否则预览和实际结果很难校验。

工程补充

制作预览还要处理替代材料。某些配方允许任意同类矿石、任意品质布料或活动代币替代。UI 必须明确显示当前会消耗哪一种材料，并允许玩家切换偏好。自动选择材料时，应优先消耗低稀有度或即将过期材料，但这个策略必须写清楚，不能让玩家觉得系统偷偷用了珍贵材料。

这个系统落地后，配置版本要进入日志和问题反馈。无论是停顿规则、地表定义、高亮样式、配方表、成就定义还是占位策略，只要配置能影响玩家体验，就应该有版本号。线上反馈如果只知道“高亮不对”或“脚步声错了”，但不知道玩家用的是哪版配置，排查会非常慢。

调试面板也要尽早准备。开发包里至少能看到当前输入意图、系统决策、最终快照、失败原因和配置来源。对于表现类系统，最好能在画面上叠加当前 id：surface_id、highlight source、recipe_id、achievement_id、boss_phase。QA 截图带上这些信息，开发就能少猜很多。

协作与内容接入

这类系统大多需要内容同学持续接入。新增地表、新增配方、新增成就、新增 Boss 阶段、新增高亮样式，都不应该只改一个资源路径。每种新增内容都要有最小样本和验收步骤。样本可以很小，但必须能触发主要路径和失败路径。

建议把接入说明写成三段：需要填哪些字段，常见错误是什么，如何在调试模式验证。文档不必冗长，但要足够具体。例如“新增配方必须提供 recipe_version、result_preview、server_quote_policy”，比“记得配置完整”有用得多。

边界和降级

降级策略要提前写清楚。HitStop 异常时可以跳过停顿但保留伤害；脚步 Surface 缺失时用默认脚步；高亮样式缺失时用低强度默认描边；制作 quote 失败时禁用制作按钮；成就平台同步失败时保留本地 pending；截图隐私处理失败时阻断公开分享。不同系统的降级不一样，不能统一成“出错请重试”。

降级也要进入指标。fallback 次数长期偏高，说明内容或配置质量有问题。运行时兜底是保护玩家路径，不是让错误长期存在。每周看一次 fallback 排行，比发版前临时大扫除更有效。

小团队接入版本

小团队可以先用本地 CraftQuote，不接服务器 quote，但仍然让 UI 只消费 quote。这样未来切到服务器权威时，页面不用重写。

交付边界

交付标准是玩家点击制作前知道自己会消耗什么、可能得到什么、为什么不能制作；点击后结果和服务器一致。制作系统的信任来自预览和结果对得上。

结语

制作预览不是装饰，它是玩家决定是否消耗资源的依据。Godot 客户端把配方、材料、结果和提交状态收口到 CraftQuote 后，制作流程才会清楚、可信、可对账。