Minecraft redstone music

<!-- The YAML block above is OPTIONAL metadata for Claude Code's skill loader (name + trigger phrases). Other agents/platforms can ignore it — there is no loader to satisfy; just read the body below (or README.md) and run scripts/build_machine.py. -->

Minecraft Redstone Music (Family A — RedPiano)

⚡ 匀速跑道 = 正式默认 (uniform pacing, agent 必读)

默认 = --form straight + pace=uniform + grid=auto。脉冲前沿与跟拍相机 全程恒速(匀速素材),休止占格不压缩;multilane/swave/custom 同样匀速, multilane 是核心用户的核心形态。旧的变速打包保留为 --pace compressed (占地最小的兼容选项,不再是默认)。

对 agent 的硬指令:

1. 用户没有明确指定形态时,默认 --form straight;pace/grid 都不用传: schema 默认 uniform + grid=auto——按节奏最适配,自动选歌自己坐得上的最大 网格(零合并 + ≥95% 在网,取 4/3/2 中最大),选不动就落回 grid=1(对 compressed 零音频损失)。速度是网格的结果,不追求恒定值;--grid 1..4 强制指定会牺牲节奏精度(量化),要向用户说明这笔交换。
2. dry-run 报告里把 pacing/cells/forceload 三行原样念给用户, 超 soft cap 时给四个选项:--grid 2/4(量化换更短)、换 swave 折叠、 --force-cap 硬装、--pace compressed(最后手段)。
3. 已知边界:手动 grid=2/4 的量化可能把两个旋律音挤进 min_cut 间隔, 构建期会洪亮报错(cut_delay floor >= gap)——这时改 --grid 1 或 auto, 不是 bug。grid=auto 因零合并门槛天然避开此坑。
4. 进游戏实测后,把结果(TPS/断音/相机是否匀速)记回 docs/history/DEVLOG.md。

实现位置:generators/swave.py 与 generators/multilane.py 的 §2 时间轴、 params_schema.py(pace/grid 字段)、build_machine.py(--pace/--grid 旗标)、 redpiano_core.py(auto_grid 节奏适配)。发声路径与上游完全一致:真音符盒 + 红石方块点火,数据包全程零 playsound(旋律截断的 stopsound 除外)。

两条腿:先判断走哪条路 (READ FIRST)

This skill is a skill, not a one-size tool — it plays a MIDI as redstone/note-block music on any Minecraft Java version by choosing between two legs:

• 🟢 快速路径 (fast path) — MC 1.21..1.21.10. Fully automated: 11 prebuilt jars in the repo + a version table that self-syncs pack_format/folders/sign dialect. This path is high-quality and self-contained — just follow the numbered steps below. Don't rebuild or route around it.
• 🔨 工匠路径 (craftsman path) — every other version (≤1.20.6, ancient releases, etc.). There's no prebuilt jar and no version-table row, so you plan/build/verify a single delivery by hand. The skill hands you the domain knowledge, tactics, and verification method: read docs/VERSION_TACTICS.md — it maps every version generation to a machine form, timing strategy, sound strategy, and a verify checklist, all anchored to the Codex compatibility report. (Bedrock is out — see VERSION_TACTICS §2.E.)

How to pick: if the user's MC version is 1.21.x (x ≤ 10) → fast path, the steps below. Any other version → open docs/VERSION_TACTICS.md and work from there. Everything from here to the end of the numbered steps is the fast path; the craftsman path lives in that doc.

---

这是什么?(给小白看的 30 秒说明)

• 它能干嘛:你给它一个 MIDI 音乐文件(.mid),它就在你的 Minecraft 世界里 搭一台机器,用真正的音符盒 / 红石音乐把这首歌弹出来。
• 你需要什么:Minecraft Java 版 + Fabric 加载器 + RedPiano 模组 + qzpno 资源包 (Java 21 也要)。这些不用你自己折腾——agent 会帮你装好/编好。
• 最简单的玩法:把你的 .mid 文件 + 你的 Minecraft 存档文件夹 交给 agent, 选「默认预设(推荐)」,然后照着它打印出来的几步游戏内命令做一遍就行。
• 本质上:这其实是一个 agent 驱动的自动化工具。绝大部分活儿都是 agent 在干—— 你只要回答一两个问题、在游戏里敲几条命令、按一下播放按钮,就能听到歌。

想自己设计走线 / 形状 / 粒子?可以,但那是进阶可选项(见下面第一问的「自定义」)。 不想折腾就选默认预设,照样能听到完整的歌。

老版本 MC 也能玩(1.16 / 1.12 之类):只是不能像 1.21 那样全自动——agent 会读 docs/VERSION_TACTICS.md,按你的版本手工搭一台能响的机器,并如实告诉你这个版本能做到 什么、音色/精度差在哪(见上面「工匠路径」)。不会因为版本老就直接拒绝你。

---

Convert a MIDI file into a playable Minecraft RedPiano runtime bundle: datapack + enabled qzpno_mv resourcepack + installed RedPiano/Fabric API mods. The datapack is only the machine logic; sound requires the resourcepack to be present in the Minecraft profile's resourcepacks/ folder and selected in options.txt / Options -> Resource Packs.

怎么使用 / 安装 (how to use / install this skill)

• 推荐:整仓 clone 后在仓库目录里直接用. Clone/download the whole repo (not just this minecraft-redstone-music/ folder), cd into it, and let the agent run the scripts directly — no registration step needed. This works with any agent/platform (Claude Code, Trae, Codex, a human shell, ...).
• 若要注册成 Claude Code skill,必须保留仓库目录结构. The YAML frontmatter at the top of this file lets Claude Code's skill loader discover and trigger this skill by name. But the scripts under scripts/ resolve sibling paths like ../binaries/ (prebuilt jars) relative to the repo root — so registering the skill only works if minecraft-redstone-music/ stays inside the full repo tree. Do not copy just this folder out on its own; it will build datapacks but silently lose access to the prebuilt binaries described in BINARIES.md. The sampled, attributed resourcepack ships at assets/qzpno_mv.zip; keep the complete skill folder so the default build can find it.
• 交付链只支持 Windows. The generated installer is DEPLOY_TO_GAME.bat — a Windows batch file. This skill's install path assumes a Windows machine running Minecraft Java Edition. On a non-Windows native host, skip the .bat and either use --install-now (native, non-sandboxed hosts only) or copy dist/ into the profile by hand; there is no .sh/.command equivalent shipped today.

用户端流程 (onboarding — 任何 agent / 平台按此驱动用户)

To fulfill a "make Minecraft redstone music from this MIDI" request, collect the inputs below, then run the build command in step 4.

语言跟随用户 (language follows the user). Talk to the user in whatever language they used — questions, progress updates, error explanations, and the final delivery summary should all follow their language, not default to English or Chinese. Code, commands, and file paths stay as-is regardless of language.

⚠ 交付准则 — AGENT MUST READ before reporting success (the #1 failure mode)

You are almost certainly running in a filesystem SANDBOX (Trae SOLO / similar). In it, writing to C:\Minecraft\... is silently redirected to a private mirror (%APPDATA%\Roaming\TRAE SOLO CN\VMCache\...) that the real, natively-running game never reads. So if you copy the datapack/resourcepack/mod into the profile and "verify" them, everything looks fine but the game is unchanged and /function <ns>:setup says Unknown function. This — not a build error — is why past runs "succeeded" yet nothing played. Full explanation: docs/RUNTIME_SANDBOX.md. The rules:

1. Build with scripts/prepare_all.py. It writes the datapack + qzpno_mv.zip + mod/Fabric API jars into the workspace dist/ (the ONE place a sandbox can write reliably) and emits dist/DEPLOY_TO_GAME.bat with the real paths + a token baked in. Do not deploy into C:\Minecraft\... yourself, and do not hand-roll a deploy.ps1/deploy.bat — prepare_all.py owns pathing, encoding, and options.txt.
2. The last step is the USER's, not yours. Tell the user to double-click dist\DEPLOY_TO_GAME.bat in Windows Explorer (a native process, outside the sandbox — that is what actually reaches the game). Never run the .bat yourself (subprocess / Start-Process): if you run it, it inherits the sandbox and installs into the mirror.
3. The receipt is the ONLY proof. The song is in-game only after dist\DEPLOY_RECEIPT.txt exists. Check it with python scripts/deploy_bundle.py --verify <dist> (✓ INSTALLED exit 0 / ✗ exit 1). Until it's ✓, report "built — NOT in game yet; the user must double-click DEPLOY_TO_GAME.bat". Never say "installed / you can hear it now" without the receipt.
4. On a genuinely native host only (a real terminal, not a sandbox) you may add --install-now to install inline and skip the .bat. Never use it inside a sandbox.
5. 工匠路径下诚实降级 (honest downgrade on the craftsman path). Off the green band you may end up delivering vanilla-timbre note blocks, tick20 timing, a Carpet dependency, or a hand-ported jar — all legitimate. When you do, say plainly what changed: which timbre (16 vanilla instruments vs 103 RedPiano samples), what timing precision (tick20 = 4× coarser than tick80), and how much is now manual. Never dress a craftsman delivery up as the automated fast path, and never claim RedPiano audio when you actually shipped vanilla tones. An honest "here's what this version can do and what it costs" beats a false "fully supported." (Details per generation: docs/VERSION_TACTICS.md.)

Do not hand-roll a datapack on the fast path. A valid green-band Family A deliverable is generated by scripts/prepare_all.py / scripts/build_machine.py and contains a physical note-block machine (setup, play, many setblock commands, and a console). The judgment call is whether you shipped a real note-block machine, not which script produced it: a pack of tick_*.mcfunction files that only calls playsound minecraft:block.note_block.* is a vanilla background scheduler pretending to be a machine — it plays through no physical note block, so on the fast path rebuild it through the scripts. (The craftsman path may legitimately hand-emit a setblock list or command-block chain for an old version — still a physical machine, still valid; VERSION_TACTICS §2.D. What's never valid is a silent playsound scheduler passed off as a redstone machine.)

Sound needs version-matched binaries — both are bundled and selected automatically. The datapack auto-adapts the commands/format, but the SOUND needs a mod jar + qzpno_mv.zip that match the MC version; a mismatch makes the note blocks fall back to vanilla tones (faint harp + booming basedrum). The mod jar is self-service: run python scripts/fetch_binaries.py --mc-version <ver> — it reads the shipped binaries/binaries_manifest.json, resolves the version's jar from the local binaries/ folder (sha256-verified; local hit = instant), and prints a VERDICT (listened in-game vs only bytecode-checked). The jar is per-version: fabric.mod.json pins a "minecraft" range and Fabric refuses to load a jar whose range doesn't cover the running game — fetch_binaries selects the right one (redpiano-1.0.0-mc<ver>.jar). The sampled resourcepack ships at assets/qzpno_mv.zip. Its root CREDITS.txt attributes Salamander Grand Piano v3 / Alexander Holm under CC BY 3.0; drums are VCSL CC0 and bass/lead/pad are synthesized. With no resourcepack flags, prepare_all.py selects this asset and automatically rewrites pack.mcmeta for the target version. Use --prebuilt-rp or --samples-root only when the user deliberately wants other sounds. Then feed the jar to prepare_all.py via --prebuilt-mod-jar (+ --fabric-api-jar). If the target version has no jar in the manifest, fetch_binaries says so and points you to recompile (mod_build.py --write + Gradle) — a stripped sandbox usually can't build the jar, so prefer a version the manifest already carries. See BINARIES.md.

NEVER hand-write or fake fabric-api / fabric-loader stubs to force the jar to compile. The Gradle build MUST resolve the real fabric-api from maven.fabricmc.net. If you can't reach that maven (no network, blocked sandbox), the mod build is BLOCKED — report it as blocked and stop; do not hand-roll placeholder classes, empty interfaces, or a stub jar to get a green build. A fake dependency + a fake toolchain is a silent failure the manifest can't catch (it looks built but the mixin was compiled against nothing and plays no sound — this really happened). Prefer --prebuilt-mod-jar <redpiano.jar> when you can't build honestly. When a jar IS produced, sanity-check it before install with mod_build.py --check-jar (confirms the real fabric-api was resolved, not a stub) as a pre-deploy gate.

If fetch_binaries.py resolves a jar for the target, DO NOT compile the mod at all. A version-matched jar ships in ../binaries/ for every version in the manifest — 11 jars, covering 1.21..1.21.10 (see binaries_manifest.json). Currently none of the 11 are confirmed by an in-game listen — all are bytecode-checked only (mod_build.py --check-jar clean, not yet heard). 1.21.8 had previously been confirmed, but it was just rebuilt with a new global mute check and its listened flag was honestly reset to false pending a fresh listen after a full restart — see BINARIES.md's "Honesty: currently zero jars are listened-confirmed" note before claiming sound works. Inside the sandbox you do not need and must not run Gradle — run fetch_binaries --mc-version <ver> and pass its jar as --prebuilt-mod-jar. Only when the manifest has no jar for the target (i.e. outside 1.21..1.21.10) should you recompile, and even then a stripped sandbox usually can't — building the mod in one is exactly what tempts the fatal fabric-api-stub shortcut above.

Never claim it "works" before an in-game listen. A recompiled mixin can compile yet be silent or mis-pitched. After the receipt exists, hand off the in-game steps (step 4) and ask the user to confirm they actually hear it. Simplest reliable target = 1.21.8 / 1.21.7.

前置门槛 (Pre-flight) — confirm these TWO before step 0 (a "no" here means stop or warn):

• (a) Java 版, 不是基岩版 (Bedrock). This whole pipeline is Java Edition only — it relies on datapacks, /function, /tick rate, and a Fabric mod, none of which exist on Bedrock (Windows 10/11 "Minecraft" app, phones, consoles, Realms-Bedrock). If the user is on Bedrock, say so plainly and stop — there is no Bedrock path here. Confirm they run the Java launcher (Modrinth / official Java launcher / Prism, .minecraft/profile folder).
• (b) 目标世界已开作弊 / 有 OP. /reload, /tick rate 80, and /function <ns>:setup all require cheats enabled (single-player) or OP (server/LAN). If the save was created without cheats, the quick fix is: pause → 对局域网开放 (Open to LAN) → 允许作弊: 开 (Allow Cheats: ON) → click Start; commands work until you quit the world. Confirm this now, or the in-game steps in step 4 will silently fail with "无权限/Unknown or incomplete command."

0. 默认预设 还是 自定义? — the default is 默认预设(推荐): you pick a good form and build; the user only provides the MIDI + save folder. Use it unless the user signals they want to shape the build. The escape hatch is 自定义: the user designs in the visual HTML tools that ship here and exports JSON —

   • designer/layout_designer.html — 走线 / 形状 / 尺寸 / 折叠 / 起点 (routing/shape).
   • designer/particle_editor.html — 粒子 / 烟花 / 命令方块关键帧 (particles).

   Most users don't know these designers exist, so mention both by name early rather than burying them in step 5 — that's how the user discovers the option. You don't need a rigid two-round quiz; read what the user wants and only ask when it's genuinely ambiguous.

   中文用户术语对照(必须遵守):面向中文用户呈现形态选项时,一律用下表的中文名+一句话 解释(括号带英文参数名),不要甩 inplace/swave 裸词让用户猜;命令行参数值照旧用英文。

   参数值	对中文用户说	一句话解释
   straight	直线型	默认:一条匀速跑道跑到底,拍素材首选,占地最长
   swave	S形折线型	脉冲沿 S 形巡游、灯流好看;直线太长时的折叠方案
   inplace	原地紧凑型	占地小、不随歌曲变长,只想听不想拍时的省心选
   custom	自定义路线	用户自己在设计器里画走线
   multilane	多轨并行型	每个声部一条并行轨道,列对齐壮观;核心形态,同样匀速

   另:根 README 的「开场怎么说」小节提供了 5 条可复制的开场提示词,用户很可能照着它开场—— 提示词里已给出的信息(版本/存档路径/意图)不要再重复问。

1. 收集输入 — ask for these things:

   • MIDI 文件 path (.mid). 拿到 MIDI 先跑质量预检, before choosing a form: python scripts/midi_report.py --midi <mid> [--form <form>]. It prints a build-time preflight — duration, instrument-family distribution, estimated dropped notes, estimated footprint, and a one-line verdict. Show that verdict to the user and let it inform the form choice (step 2): e.g. a long/dense MIDI on swave/straight may report a large footprint → suggest inplace.
   • 用户只有 MP3/音频,没有 MIDI 怎么办 — agent 可以代跑转换,不用把用户打回去自己找 MIDI:

     python scripts/audio_to_midi.py --audio 歌.mp3 [--out 歌.mid] [--engine auto|basic-pitch|piano] [--min-note-ms 60]
     # 依赖: pip install -r requirements-audio.txt   (默认引擎 basic-pitch, Apache 2.0, CPU 可跑)
     # 可选钢琴专用引擎: pip install piano_transcription_inference  (质量更好但拖 torch, 钢琴独奏曲用)
     # mp3 解码可能需要 ffmpeg (winget install ffmpeg), wav/flac 不需要
     

     (没有现成的 mp3→midi 独立 skill 可嵌,本功能是包装两个开源项目代跑,不是自研转录:默认引擎 Spotify basic-pitch(Apache 2.0),可选钢琴专用引擎 ByteDance piano_transcription_inference。)

     ⚠ 强制诚实提示(必须放在显著位置,转换前告知用户,不能静默转完直接建机器): 音频转录出来的 MIDI 质量必然低于原生 MIDI——和声粘连、幽灵音、时值破碎是转录算法的 常态,不是 bug。纯钢琴独奏曲效果最好;人声/多乐器混音效果最差,经常惨不忍睹。 转完必须先跑上面那条 midi_report.py 预检再决定要不要照常建机器——预检显示掉音多/ 音符破碎,就该老实劝用户去找原生 MIDI(爱给网、musescore.com 等站点搜同名曲目)而不是 硬着头皮拿一份烂转录去建。agent 行为准则:转换前要向用户说明这个质量落差,不要拿到 mp3 就默默转完直接进入建机器流程。

   • 存档路径 — the world's datapacks/ folder, for deployment. If it looks like <profile>/saves/<world>/datapacks, infer <profile> from it.
   • Minecraft profile root (or confirm the inferred one). The resourcepack must land in <profile>/resourcepacks/qzpno_mv.zip; a datapack path alone is not enough. Using PCL2 / HMCL with per-version isolation (版本隔离/独立)? --profile-dir must point to that specific version's own folder — typically .minecraft/versions/<你的版本>/ — not the shared .minecraft root. Full guidance: QUICKSTART.md §"--profile-dir".
   • Resourcepack source — default to bundled; override only on purpose:
     1. Default: pass no resourcepack flag. prepare_all.py finds assets/qzpno_mv.zip, checks it, and derives the correct version automatically.
     2. --prebuilt-rp <zip> / --samples-root <dir>: use a replacement pack or the user's own five-instrument sample library.
     3. --skip-resourcepack — build the datapack/mod runtime without staging any resourcepack. 诚实后果(取决于装没装模组): 装了 RedPiano 模组时 → 彻底静音 (模组的 mixin 会取消原版音符盒声音、改播 qzpno: 自定义事件，没有资源包=那个事件没有 任何 .ogg 支撑=无声);不装模组时 → 原版 16 种音符盒音色。它绝不会"自己退回原版 音色当降级"。只有当匹配的 qzpno_mv.zip 已经装好并启用在目标 profile 时才用本开关。 换音色/自备包的正规做法见本文档下方 「音色与资源包」。
   • Mod status: inspect <profile>/mods/, but do not stop there. Default behavior is to build/install RedPiano and install/reuse/download the matching Fabric API automatically; only the final Minecraft restart and listen test remain user actions.
   • MC 版本号 — default & verified = 1.21.8. The automated band is 1.21..1.21.10 (tier "green"): one --mc-version flag self-syncs pack_format, folders, the pack.mcmeta shape (single ≤1.21.8 / min-max ≥1.21.9), and the sign-NBT dialect (SNBT ≥1.21.5). Outside this band, switch to the craftsman path — don't treat it as a dead end. Below 1.20.3 loses /tick rate (so tick80 needs Carpet or a tick20 downgrade), 1.20.3–1.20.6 adapts the data but the mod wants a one-line Java port, and older versions step down through the primitives — all of this is mapped, per generation, in docs/VERSION_TACTICS.md. The build scripts still raise off the green band (they only auto-build green), and their error text now points here too; that's a signal to open VERSION_TACTICS and build by hand, not to stop.

   If the user uploads an MP3 / audio instead of MIDI: agent 现在可以代跑 scripts/audio_to_midi.py 把音频转成 MIDI,再走上面「用户只有 MP3/音频,没有 MIDI 怎么办」 的流程,然后照常进入下面这套正常构建步骤。但这条转录路径不是 Family B——转录出的 MIDI 质量必然低于原生 MIDI(见该小节的强制诚实提示),真正「音色和原曲一模一样」的还原只有 slice 形态(Family B)能做到,它活在外部 mc-noteblock-demo 仓库,本技能不构建它。

2. 选播放形态 — pick a form. Default = inplace 原地调色板: functionally complete and the user confirmed a build as "特别好", but it has been tested in-game fewer times than swave — reach for it unless there's a reason not to. Escape hatch: if the user wants the "playhead travels the line" animation, offer swave S 型曲折直线 (--form swave) — this form has been tested in-game multiple times and confirmed working; custom routing/particles go through the HTMLs in step 5. Confirm the form when it's ambiguous, but you don't need a mandatory extra round-trip when the user already told you what they want (or said "just use the default"). The midi_report.py verdict (step 1) can steer this — a long/dense MIDI on swave reports a large footprint, nudging toward inplace.

   时长经验值: swave/multilane 的占地随歌曲时长增长,长歌容易撞上 360 区块的 forceload 软上限(超限需 --force-cap 才能强建,不是保证不断音)。经验值:swave 约 ≤6 分钟、multilane 约 ≤4 分钟 以内通常安全;更长的歌优先选 inplace—— 它是原地调色板,占地基本恒定,不随时长增长。拿不准就先跑 midi_report.py 看估算占地。

3. 备好 mod + 音效包 for the chosen version (any of 1.21..1.21.10) — start with fetch_binaries.py:

   • The RedPiano mod jar + qzpno_mv resourcepack are runtime assets, not optional extras. prepare_all.py stages them into the workspace dist/ (the native .bat then installs them — see step 4). It does not copy into <profile> from a sandbox.
   • the jar is one command — python scripts/fetch_binaries.py --mc-version <ver> reads binaries/binaries_manifest.json and resolves the version's jar from the local binaries/ folder (sha256-verified; local hit is instant). It also verifies the bundled resourcepack asset. Its VERDICT tells you whether that jar was listened in-game or only check-jar clean (so you know to listen once). If the manifest has no jar for the version, it says so and points you to build one.
   • resourcepack — use bundled assets/qzpno_mv.zip; do not ask the user to locate one. prepare_all.py automatically derives the target rp_format. If the asset is missing or its hash is wrong, search the repository and target profile for another qzpno_mv.zip; only after that fails should you rebuild from sample folders or ask the user for a replacement.
   • mod — pass fetch_binaries's jar as --prebuilt-mod-jar. A stripped sandbox usually cannot run Gradle/JDK, so prefer the resolved jar. Only when the manifest lacks the version do you retarget (number-only within 1.21.x: mod_build.py --write + a Gradle build on a native host, then fetch_binaries --gen-manifest to register it). The mixin binds to internal NoteBlock bytecode, so a recompiled jar still needs one in-game listen. (Below 1.21 the mod needs a Java source-port — see docs/MOD_ARCHITECTURE.md.)

4. 生成 + 交付 — one end-to-end command; it builds into dist/ and emits the native installer (it does not and should not write into C:\Minecraft from a sandbox): python scripts/prepare_all.py --midi <mid> --ns <ns> --origin X Z Y --mc-version <ver> --form swave --world-dir <profile>/saves/<world>/datapacks --profile-dir <profile> [--prebuilt-mod-jar <redpiano.jar>] [--fabric-api-jar <fabric-api.jar>] --dist dist. --world-dir/--profile-dir are the real game paths — they get baked into the generated .bat, not written to now. Pass the prebuilt mod jar from binaries/; omit all resourcepack flags to use the bundled sampled pack. Do not add --skip-* flags unless the user explicitly asks for a partial artifact.

   ⚠ --origin order is X Z Y, NOT X Y Z. The in-game F3 debug screen shows coordinates as X Y Z — copying them in that order swaps height and Z and puts the machine somewhere wrong (often underground or in the wrong spot). Read X, Z, Y off F3 in that order when typing the flag. Full site-picking guidance: QUICKSTART.md §1a/§2. 新手不必纠结坐标:走默认预设时直接用 --origin 0 0 100 就行——进游戏后机器会出现在 世界水平坐标 (0, 0)、高度 100 附近(开阔地多半没问题,若那里有地形挡着就往上调高度)。 或者告诉 agent 你现在站在哪(报一下 F3 上的 X/Z/Y),由 agent 帮你换算成 --origin 的 X Z Y 顺序——不需要自己心算坐标转换。 ⚠ --ns must be a name you haven't used before in this world's datapacks/ folder — an existing datapack directory with the same namespace gets overwritten wholesale. 多歌共存: 同一个世界里可以建多首歌(各自不同的 --ns),本版本起每首歌的 forceload/开关都按自己的 --ns 隔离,不会互相踩掉对方的建筑或播放状态——但同时只应该 播放一首(两首同时播会混音,而且都要人站在附近才不断音)。旧版本生成的歌(在这次 forceload 隔离修复之前建的)仍然可能和新歌互相干扰;与新歌共存前,建议先对旧机器跑 /function <旧ns>:cleanup 拆除重建,而不是让新旧数据包一起留在 datapacks/ 里。 If prepare_all.py exits nonzero, fix the missing dependency or report blocked — do not summarize it as complete.

   ▸ 版本参数化黄金路径 (version-parameterized golden path). For ANY supported version, the four steps are the same — only <ver> changes:

   1. Ask the user their MC version (<ver>, e.g. 1.21.7 / 1.21.8 / 1.21.9).
   2. python scripts/fetch_binaries.py --mc-version <ver> — resolves the jar from the local binaries/ folder and verifies bundled assets/qzpno_mv.zip. No manifest jar for <ver>? it tells you to build one (or pick a version that has one).
   3. prepare_all.py as below, with --prebuilt-mod-jar pointing at the fetch output and no resourcepack flag. It selects the bundled pack and converts its metadata automatically. Fabric API version note: binaries/ only bundles the 1.21.7 Fabric API jar in-repo; for any other <ver>, leave --fabric-api-jar unset (default auto) so prepare_all.py downloads the matching build from Modrinth automatically — this needs network. Offline on a non-1.21.7 version? you must supply your own matching --fabric-api-jar <jar> ahead of time; there is no bundled fallback for it. Optionally gate the mod jar first with mod_build.py --mc-version <ver> --check-jar <jar>.

   ▸ 打包分发场景 — concrete example (Fabric 1.21.7, offline, prebuilt jar). The golden path above, instantiated for the common handoff: a repo-snapshot with a sibling binaries/ folder and a user on Fabric 1.21.7. Run it from the minecraft-redstone-music/ directory, so ../binaries/… resolves. Every path here is real — --world-dir and --profile-dir must be the user's actual game paths (ask them first); the two shown are only placeholders. The jar + Fabric API come from binaries/; the resourcepack comes from bundled assets/qzpno_mv.zip. With these assets, no Modrinth / network is needed:

   bash 语法（行尾 \ 续行）；PowerShell 用户请用 Git Bash 运行，或把整条命令改写成不带 \ 的单行。

   python scripts/prepare_all.py \
       --midi <mid> \
       --form swave \
       --ns  mysong \
       --origin 0 0 255 \
       --mc-version 1.21.7 \
       --world-dir  "<profile>/saves/<world>/datapacks" \
       --profile-dir "<profile>" \
       --prebuilt-mod-jar ../binaries/redpiano-1.0.0-mc1.21.7.jar \
       --fabric-api-jar   ../binaries/fabric-api-0.129.0+1.21.7.jar \
       --dist dist
   

   Notes: the mod jar is the mc1.21.7 one (the mc1.21.8 jar declares ~1.21.8 and Fabric would reject it on a 1.21.7 game); the bundled base rp-64 qzpno_mv.zip serves both 1.21.7/1.21.8. If the supplied jar is still named …-mc1.21.7-UNVERIFIED.jar, use that filename verbatim (the -UNVERIFIED just means "listen once to confirm"); optionally gate it first with python scripts/mod_build.py --mc-version 1.21.7 --check-jar ../binaries/redpiano-1.0.0-mc1.21.7.jar (exit 0 = bytecode-clean, safe to install). For a 1.21.8 game, swap --mc-version 1.21.8 and the mod jar to ../binaries/redpiano-1.0.0-mc1.21.8.jar, and drop the --fabric-api-jar line entirely — binaries/ only ships the 1.21.7 Fabric API jar (fabric-api-0.129.0+1.21.7.jar), which does not match a 1.21.8 game; omitting the flag lets prepare_all.py auto-download the matching build from Modrinth instead (needs network — offline on 1.21.8, supply your own matching jar). Every flag above is real on the current prepare_all.py — confirm any variant with python scripts/prepare_all.py --help.

   Then deliver the one manual step and stop claiming more than the receipt proves:

   • Tell the user (point at the exact path): 「双击 dist\DEPLOY_TO_GAME.bat（在 Windows 资源管理器里，不要让 AI 代跑）就能装进游戏」. That native double-click copies the datapack/resourcepack/mods into the real profile, enables qzpno_mv, and writes dist\DEPLOY_RECEIPT.txt.
   • Verify before you claim success: python scripts/deploy_bundle.py --verify dist. Only ✓ INSTALLED means the song is really in the game. No receipt → say "built, NOT in game yet — user must double-click DEPLOY_TO_GAME.bat". See docs/RUNTIME_SANDBOX.md.
   • After the receipt exists, the in-game steps (the .bat also prints these), in order:
     1. full restart Minecraft if the mod jar changed (a jar swap needs restart, not /reload).
     2. /reload — register the datapack functions.
     3. /tick rate 80 — ⚠ 用户必须自己手动敲这一条. Without it playback is ~4× too slow and melody-cut timing is off. The machine does NOT self-set it.

        ⚠ /tick rate 80 speeds up the ENTIRE world — crops, mob spawning/AI, redstone, everything, not just the music machine. Be cautious on a multiplayer/shared world. Remember to /tick rate 20 back when done listening. ⚠ Tick rate does NOT persist across sessions. Quitting/rejoining the world or restarting the game silently resets it back to 20 — the user must retype /tick rate 80 every session, even if they set it correctly last time. ⚠ Server overload can defeat tick rate even when it IS set. A big machine (hundreds of forceload chunks) plus a heavy world (Distant Horizons, Terralith-style terrain gen mid-generation) can push the server past what it can simulate; watch the log for Can't keep up! Running N ticks behind (seen as high as ~8914 ticks in testing) — when that appears, real TPS has already collapsed regardless of the /tick rate 80 setting, and playback sounds slow/dragging/choppy. Mitigate with a smaller-footprint form (inplace), disabling Distant Horizons or lowering render distance, waiting for nearby chunks to finish generating before playing, or not running multiple machines at once. 若用户报"第二次播放变慢了":先问是否重进过世界/重启过游戏(tick rate 重置是最常见 原因),再看服务器日志有没有 Can't keep up!(服务器过载是第二常见原因),排除这两条之后 再怀疑是构建/生成器本身的问题。

     4. 确认资源包 — the .bat already enabled qzpno_mv in options.txt; the user just confirms it's on the right (selected) side in Options → Resource Packs.
     5. /function <ns>:setup — build the physical machine + console at the origin.
     6. 非超平坦世界(Terralith 等地形生成 mod)先按控制台的 [preload] — 把玩家切成旁观者、 沿机器路径每 128 格 tp 一次,但走的是验证式等待:每段都等下一段区块真正加载完成 (loaded 判定通过)才推进,不是固定时间间隔硬等;头顶有一条蓝色 bossbar 显示"第几段/ 共几段"进度,地形生成越慢等得越久是正常现象。跑完自动传回控制台、置 READY 并提示完成; 超平坦世界可跳过。
     7. press the [play] sign/button. ⚠ [play] 现在带 preload 门禁 — 沿线远端区块没 加载完时会拒绝启动并提示先按 [preload],这是有意为之,不是 bug。⚠ [play](连同 setup/prosetup)现在会自动临时改 5 个高负载 gamerule(性能模式/perfmode: randomTickSpeed→0、关生物生成/火/天气/昼夜)给 tick80 播放减负,[stop]/播放结束/ 拆机时会自动精确恢复;若游戏是闪退/强杀等异常方式退出、没来得及恢复,重进后手动敲 /function <ns>:perfoff 即可恢复。

        中途想停/重播? 按控制台的 [stop]——它现在会物理挖断行进中的中继器(4 游戏刻 后自动补回),所以停下后可以立刻重按 [play] 干净重播,不用等整首歌播完;手速极快 连续按时看到"机器复位中,约1秒后再按"提示属正常复位锁(ARM lock),稍等即可,不是 bug。

     8. (展示用,可选) 控制台后方有一个 [音色展台] 按钮,按下会 tp 到一座实体展台逐格试听 真实发声路径——⚠ 别右键展台里的音符盒,会改音高毁掉展品,只用侧面石按钮试听。
     9. (录制/跟拍,可选) 控制台最左有一个 [跟拍] 按钮(swave/straight/custom/multilane 形态):按下把 玩家骑上一个隐形盔甲架相机,再按 [play] 后相机沿两轨正中(单轨=沿路径)与脉冲前沿 逐游戏刻锁定前进——不是匀速,是按生成期算好的"到达时刻表"变速跟随,tick rate 缩放和 服务器卡顿都自动同相,不会漂。骑乘期间鼠标可自由转头(适合手持录屏或 Flashback); 重按 [play] 重播时相机自动弹回起点。退出:按 [stop](会 tp 回控制台自动下架)或 /function <ns>:camoff。为什么不用飞行跟/tp 玩家:脉冲速度本就不恒定(中继器 1..4 档 延迟 + 0 延迟 U 弯),人工飞必漂出模拟距离,tp 玩家又触发区块重发断音——骑乘实体走的是 客户端载具插值,每刻一小步即丝滑,这是二者的结合点。相机位置不合适(横向偏/太高/太贴脸)? 在 layout_designer 起点区调「跟拍相机 高/退/横移」或 params 里给 cam_height/cam_back/ cam_dz(默认自动取轨带中线)。

   ⚠ 「完全没声」先跑一键体检 doctor.py, 再看这三项. The fastest triage is python scripts/doctor.py --dist dist --profile-dir <profile> --world-dir <world>/datapacks --mc-version <ver> --ns <ns> — it prints a numbered ✓/✗ checklist (receipt present? qzpno_mv enabled with the matching pack_format? mod + fabric-api in mods/? datapack in the world? tick-rate reminder) with a fix line under every ✗ and a final VERDICT; all-green = exit 0. Then, in order: ①dist\DEPLOY_RECEIPT.txt 在不在(不在=根本没部署,让用户 双击 .bat);② qzpno_mv 是否在 Options → Resource Packs 右侧「已选用」(其 pack_format 必须匹配 MC 版本:1.21.8/1.21.7 = 64,不匹配 MC 会静默禁用 → 全静音);③ 有没有手动敲 /tick rate 80。 Bare scripts/build_machine.py is datapack-only; for a playable result use prepare_all.py (it stages the resourcepack + mod and emits the native installer). 给 agent 的两条常见排查(非"没声"类):

   • 用户问**"怎么卡在预加载/[preload] 半天不动"** → 这是地形生成慢,属正常现象(§4 步骤 6: 现在是验证式等待,不是固定间隔硬等),让用户看头顶蓝色 bossbar 的进度,不要当成卡死去 重启;地形生成 mod(Terralith 等)越重的世界越慢。
   • 用户报**"gamerule 被改了 / 生物不刷了 / 庄稼不长了"** → 这是性能模式(perfmode)的临时改动 没被自动恢复,通常因为闪退/强杀游戏,没走到 [stop]/播放结束/拆机这几个自动恢复点,不是 bug 也不需要重新生成机器——让用户在游戏里手动敲 /function <ns>:perfoff 即可恢复。

5. 自定义需求 → 两个 HTML(用法都是:浏览器里手动填 → 直接复制或导出 JSON 交给 agent):

   • designer/layout_designer.html — 自定义走线方式(形态 / 尺寸 / 折叠 / 起点)。 导出 layout params JSON → 传给 build_machine.py --params. params JSON 可选加一个 protection 字段(straight/swave/custom/multilane 支持,inplace 不支持)开一层 可选保护壳,产物会多出 <ns>:prosetup(代替 setup,先分段建壳再建机器)和 <ns>:unprotect(只拆壳);字段与用法见 QUICKSTART.md §7「区块保护」。

     ⚠ agent 若要替用户把 protection.clear_interior 设为 true,必须先在聊天里向用户 明确确认——它会真的清空保护壳包围盒内的地形/水/岩浆,且不可逆,不能替用户默认打开。

   • designer/particle_editor.html — 自定义关键帧 + 命令方块位置(粒子 / 烟花 / 任意命令, 同步音乐时间与世界坐标)。导出 particle_keyframes JSON → build_particles.py(见 docs/PARTICLES.md).

Forms & pipeline (details live in references)

Five forms share one MIDI→resolve→layout→melody-cut→emit pipeline. Pick by footprint/effect; the full capability table, per-form verified status, and the 6-stage pipeline are in the authoritative reference — don't re-derive them here:

• straight — long constant-speed runway; THE DEFAULT (uniform pacing, filming-grade 匀速 front). Longest footprint of the line forms.
• swave — marching-pulse S-wave with the "playhead travels the line" effect; tested in-game multiple times and confirmed working. The fold-down option when a straight runway is too long; uniform pacing applies here too (行内匀速, U 弯瞬移).
• inplace — in-place palette, tiny footprint, user-verified "特别好"; the upstream default, for listening-only sessions (no pulse, nothing to film).
• custom / multilane — drawn waypoint route / one lane per voice. All v1, geometry-confirmed. multilane fully supports uniform pacing (all lanes + signal tracks share the one constant-speed skeleton) — it is the core users' core form; test it first. custom/multilane designer --params JSON as before.

→ Capability matrix + pipeline + known constraints: docs/FEATURE_MATRIX.md (authoritative single source of truth; supersedes DEVLOG). Multi-instrument uses the 103-block assets/redpiano_map_multi.json; melody-cut is event-level; unconsumed designer fields hard-fail (docs/CONTRACT.md §2). Craftsman-path form choices per version: docs/VERSION_TACTICS.md.

Install prerequisites (fast-path #1-silence checklist)

The low-level machine generator produces a datapack, but the playable deliverable is the datapack plus active runtime assets. For normal requests, prepare_all.py owns these steps by default; this section is a checklist, not a reason to stop and hand work back.

1. Fabric Loader + Fabric API + Java 21 for the target Minecraft version (verified default 1.21.8; supported auto band 1.21..1.21.10). Install Fabric Loader first via the official installer: https://fabricmc.net/use/installer/. The script auto-detects JDK 21/Gradle for RedPiano builds and downloads/reuses Fabric API when possible; missing toolchain/network means not ready, not success.
2. RedPiano mod jar in <profile>/mods/ (then restart Minecraft — a jar swap needs a full restart, not /reload). The easy path is fetch_binaries.py --mc-version <ver> → pass its jar as --prebuilt-mod-jar. prepare_all.py can also build one via Gradle when the manifest lacks the version and a JDK 21 is present. RedPiano is server-side logic (docs/MOD_ARCHITECTURE.md §0/§6.4 — it gates on ServerLevel/ServerPlayer); for singleplayer just install it like any client mod (the integrated server runs on your machine). For a dedicated multiplayer server, install RedPiano on the server; it is shipped with environment: "*" so a client copy is harmless but not load-bearing.
3. qzpno_mv resourcepack placed in resourcepacks/ and manually enabled by the user in Options → Resource Packs (moved to the right/selected side). prepare_all.py copies the zip and tries to select it in options.txt, but the user MUST still confirm the pack is on the selected side in-game — forgetting this is the #1 cause of total silence. If its pack_format does not match the MC version, MC silently disables it → total silence. The pack_format is version-specific (e.g. 64 for 1.21.8); a base qzpno_mv.zip is rp 64, and for any other version scripts/build_resourcepack.py --from-zip derives a matching pack from it (rp_format + shape from the version table, no re-encoding needed). The base zip ships at assets/qzpno_mv.zip; its CREDITS.txt carries the required Salamander Grand Piano / Alexander Holm / CC BY 3.0 attribution. fetch_binaries.py verifies this asset.
4. tick80 is required for playback timing. The user must manually type /tick rate 80 in-game before pressing [play] — the machine does NOT self-set it (auto-set via a command block was tested and does not work). Without it, playback runs ~4× too slow and melody-cut timing is off. Make this a required in-game step, not just a diagnostic. ⚠ It also does not persist across sessions — quitting/rejoining or restarting resets it to 20, so this is a per-session step, not a one-time setup. If a session that already had tick80 set starts sounding slow again, also check the server log for Can't keep up! Running N ticks behind (server overload can defeat tick80 even when it's set) — see step 4's in-game-order notes above for the full triage.

Bundled runtime assets. Prebuilt RedPiano jars ship in the repository's binaries/ folder; the attributed qzpno_mv.zip, 103-block map, and demo MIDI ship in this skill's assets/. Keep the complete repository structure when distributing the skill.

音色与资源包(换音色 · 默认加载保障)

一句话详版在 BINARIES.md;QUICKSTART.md 顶部有小白版。这里回答三件最常被担心的事。

① 默认链路一定会启用资源包吗?会,没有"试一下失败就退回原版"的静默降级。 默认走 prepare_all.py:它把 qzpno_mv.zip 塞进 dist/,生成的 DEPLOY_TO_GAME.bat 在你双击安装时 会主动把 file/qzpno_mv.zip 写进 options.txt 的 resourcePacks 数组(并从 incompatibleResourcePacks 移除),即"强制选用"。它不会"尝试加载、发现不行就悄悄用原版顶替"—— 要么装好并选用,要么在 .bat/doctor.py 里明确报错告诉你哪一步没成。唯一需要你手动确认的 是进游戏后在 选项 → 资源包 里看一眼 qzpno_mv 在右侧"已选用"(这一步谁也替不了)。

⚠ 装的时候先完全退出 Minecraft:options.txt 会在游戏退出时被内存里的旧设置覆盖,游戏开着 双击安装器 = 启用被冲掉、进游戏发现没生效。安装器和 README_部署说明.txt 现在都会检测并警告。

② 音色不兼容/资源包缺失会怎样?——装了模组就是"彻底静音",不是退回原版。 这是必须诚实交代 的一点:RedPiano 模组的 mixin 取消了原版音符盒声音,改播 qzpno:<id> 自定义音效事件。所以——

• 装了模组 + 资源包格式不符(MC 静默禁用)或缺失 → 那些 qzpno: 事件没有 .ogg 支撑 → 完全没声(不是原版 harp/bass 音色);
• 只有不装模组时,音符盒才响原版 16 音色;
• 想验证到底响没响:doctor.py 全绿时会给你一条 /playsound qzpno:pno_c4_mf master @s,进游戏 敲,听到钢琴=资源包生效,报 Unknown sound event 或没声=包没启用/格式不符。

③ 想换音色怎么办?两条正规路径,都不会"锁死一个包"。

• 换采样重打包(想要不同真实音色/自己的采样): python scripts/build_resourcepack.py --mc-version <ver> --samples-root <你的采样目录> --out my.zip, 再把 my.zip 作为 --prebuilt-rp 传给 prepare_all.py。采样目录结构=每个乐器一个 samples_<inst>/ 文件夹 + 一个 samples_manifest_<inst>.json(见 BINARIES.md「Sampled resourcepack」)。没有采样又想先听响:python scripts/make_demo_samples.py 合成一套开放 demo 音源。
• 自备打好的 .zip(--prebuilt-rp <zip>): 你的 zip 必须满足两个契约,否则会被拒或部分静音:
  1. pack_format 要对上目标版本(1.21/1.21.1=34、1.21.4=46、1.21.5=55、1.21.6=63、 1.21.7/1.21.8=64、1.21.9/1.21.10=69 且用 min_format/max_format 形状)。不符会被 prepare_all.py 硬拒并教你用 build_resourcepack.py --from-zip <你的zip> --mc-version <ver> 换版本重打包(只改 pack.mcmeta,不用重编码,一个 zip 派生任意 1.21.x)。
  2. 要覆盖全部 103 个 qzpno: 音效事件(与 assets/redpiano_map_multi.json 对齐)。缺哪些, prepare_all.py 会 [warn] 列出(缺的那些音符盒在游戏里静音,不退回原版),但不阻断安装。

④ 世界升级到新 MC 版本后要重建吗?——只需重跑资源包,机器本体不用重建。 旧 qzpno_mv.zip 在新版本会因 pack_format 不符被 MC 自动禁用(→静音)。修法:build_resourcepack.py --from-zip <旧 qzpno_mv.zip> --mc-version <新版本> 派生一个新版包,重新装/选用即可;datapack 机器结构本身在 1.21.x 内不用重建(命令/格式由 --mc-version 自适应,重建机器只在需要换 MIDI/形态时才做)。

Scope

Family A only — RedPiano mod, real note blocks (re-performed notes). The Family B audio sample-slice pipeline (method=slice — chopping the original recording into per-tick ogg slices for MP3-faithful timbre) lives in an external repo (mc-noteblock-demo) and is out of scope; the generators hard-fail on method=slice. This is a technique boundary, not a version one — don't confuse it with the craftsman path's honest vanilla-timbre downgrade (§ delivery rule 5), which is a legitimate in-scope Family A fallback on old versions.

Next step

• Fast path (1.21.x): QUICKSTART.md for the end-to-end build-and-play checklist + "no sound?" triage; docs/CONTRACT.md for the build-script interface spec; docs/FEATURE_MATRIX.md for capabilities.
• Craftsman path (any other version): docs/VERSION_TACTICS.md — the per-generation domain-knowledge + tactics + verify map.