【Scratch×AI 系列 02】Target 与素材引用舞台/精灵为什么会消失摘要Scratch 里“舞台/精灵”的本体就是 targetname 缺失会导致 target 直接不加载costumes/sounds 不是“随便写个路径”它们决定了 Scratch 去哪里找素材文件我把素材管理拆成两段仓库里用可读路径assets/…打包时再转换为md5.ext彻底解决“导入后不显示”本文用最少字段讲清 target 结构并给一份“写 target 时不容易翻车”的字段清单系列导航01先搞懂 SB3为什么 AI 生成的 project.json 常常“导不进 Scratch”02Target 与素材引用本文03Blocks 结构与 inputs/fieldsAI 最容易写错的地方04进阶与踩坑清单从“能导入”到“能稳定跑”规范参考Scratch3_SB3_配置文件规范.md1. Target 是什么它为什么这么关键在 SB3 里舞台和精灵没有本质区别它们都是targets数组中的一个元素。换句话说target 一个可运行的角色实体舞台或精灵变量、列表、广播、脚本 blocks、造型 costumes、声音 sounds全都挂在 target 上其中有一个坑非常致命name 缺失。在我整理规范时反复验证过一个现象如果targets[].name缺失Scratch 会直接不加载这个 target结果看起来像“精灵消失了”其实是压根没进项目。因此name是真正意义上的“强必填”。2. Stage舞台与 Sprite精灵的基础字段每个 target 至少要区分它是不是舞台舞台isStage: truename: Stage精灵isStage: falsename为精灵名称一个“够稳”的 target 通用字段清单不是最少但最不容易翻车isStagenamevariables/lists/broadcastsblockscommentscurrentCostumecostumes强烈建议至少 1 个soundslayerOrdervolume精灵sprite还常见visible、x、y、size、directiondraggablerotationStyle舞台stage还常见tempovideoState、videoTransparency用到视频相关扩展时更重要详细字段说明见规范文件的 Target 章节Scratch3_SB3_配置文件规范.md3. costumes 与 sounds决定“显示/播放”的核心引用3.1 costumes舞台背景/精灵造型costumes是数组每项通常包含nameassetIdmd5extdataFormat例如svg、pngrotationCenterX/rotationCenterY在标准 SB3 里md5ext应该是类似15a4306fd588bde3d45723fefdcf200e.svg而不是assets/sprite/sprite1/plane.svg因为 Scratch 导入 .sb3 时是在 ZIP 根目录找素材文件。3.2 sounds声音sounds同理关键字段assetIdmd5extdataFormat例如wav、mp3rate、sampleCount建议保留声音最常见的坑不是“字段写错”而是引用的md5ext指向的文件在压缩包里根本不存在或者扩展名/格式 Scratch 不支持4. 我是怎么解决“仓库可读路径 vs SB3 md5ext”的矛盾的如果你直接写标准 SB3那你会遇到一个现实问题素材必须重命名成 md5 文件名但在仓库里这种文件基本不可读、不可维护、不可协作。我的解法是分层4.1 生成阶段用可读路径保证可维护在生成 project.json 时例如执行 plan先允许写assets/backdrops/bg1.svgassets/sprite/sprite1/plane.svg这样你能在 Git 仓库里看清楚“这个造型到底是哪个文件”在需求/计划里直接引用同一份路径减少沟通成本4.2 打包阶段统一转换为 SB3 规范 md5ext在打包 skill 中扫描 project.json 的costumes[].md5ext/sounds[].md5ext对assets/...这种引用读取真实文件内容计算 MD5复制到 build 根目录并重命名成md5.ext回写 project.json 的assetId/md5ext再把 build 根目录压缩为 zip改名为.sb3这一段流程可以参考.trae/skills/xw-scratch-build/SKILL.md.trae/skills/xw-scratch-build/build_plan.ps15. 写 target 的“稳妥模板”不追求最少追求不翻车下面是一段“结构示意”为阅读做了删减你可以用它做 mental model{targets:[{isStage:true,name:Stage,variables:{},lists:{},broadcasts:{},blocks:{},comments:{},currentCostume:0,costumes:[{name:bg1,assetId:15a4306fd588bde3d45723fefdcf200e,md5ext:15a4306fd588bde3d45723fefdcf200e.svg,dataFormat:svg,rotationCenterX:240,rotationCenterY:180}],sounds:[],layerOrder:0,volume:100,tempo:60}],monitors:[],extensions:[],meta:{semver:3.0.0,vm:0.2.0-...,agent:...}}注意示例里用的是标准 SB3 的 md5ext。如果你采用“先可读路径、后打包转换”的策略那么生成阶段的md5ext可以先写assets/...但最终打包出来的build/project.json必须变回 md5ext。6. 小结target 这层不稳后面 blocks 写得再对也白搭很多人以为 Scratch 不能导入是“blocks 写错了”。但实际上target 不加载name 缺失/结构断裂会让你看起来像“精灵消失”costumes 引用对不上会让你看起来像“造型面板空白”下一篇我们进入最容易出事故的地带blocks 的图结构、next/parent、以及 inputs/fields 的编码。这也是 AI 最爱“看起来像对其实全错”的地方。