ツール・DSL・配置の普遍トラップ集

このスキルは、過去の成功・失敗知見（knowledges/ 配下）から抽出した、環境・ツール・DSLに起因する再現性のあるトラップ集です。回路設計・テストコード記述の前に必ず読み、これらのトラップで5回の試行上限を枯渇させないようにしてください。

「フレームワーク/DSLの誤用で試行回数を消費する」のは最も無駄な失敗パターンです。 本質的な回路デバッグに試行を全振りできるよう、以下のトラップを事前に排除してください。

---

1. place-blocks のフェーズ配列（list渡し）の取り扱い

トラップ

mc-cli place-blocks にJSONのフェーズ配列（[PlaceRequest, PlaceRequest]）を渡す場合、JSON配列として正しく渡していないと、Invalid JSON 等のエラーで試行を消費する。

正しい使い方

• --blocks 引数には単一 PlaceRequest オブジェクト、または PlaceRequest の配列をJSON文字列として渡す。
• フェーズ配列を使う場合、各フェーズが順番にAPIへ送信され、フェーズ間に自動的に1tickの待機が入る。
• JSONファイル（@file.json）を使う場合も、トップレベルが単一オブジェクトまたは配列であることを確認する。
• 配列の各要素は PlaceRequest 形式（blocks, attaches, connects, fills 等を持つオブジェクト）であること。

// OK: フェーズ配列
[
  { "blocks": [...] },
  { "attaches": [...] }
]

// NG: トップレベルが配列ではない、または要素がPlaceRequest形式でない
{ "blocks": [...] }, { "attaches": [...] }

---

2. 動的状態（power/powered/lit）は明示しない

トラップ

place-blocks の blocks や attaches の state に powered, lit, power 等の 動的状態 を明示的に書き込むと、Minecraft 側のブロック更新ループが阻害され、リピーターがOFFのままロックされたり、ランプが点灯しなかったりする異常動作を引き起こす。

正しい使い方

• state には 静的なプロパティのみ を指定する（facing, delay, mode, face 等）。
• powered, lit, power, extended, enabled 等の動的状態は 絶対に書き込まない。
• レバー/ボタンの ON/OFF は interact-block で操作する（次項参照）。

// OK: 静的プロパティのみ
{ "x": 10, "y": 64, "z": 10, "block": "minecraft:repeater", "state": { "delay": "2" } }

// NG: 動的状態を明示
{ "x": 10, "y": 64, "z": 10, "block": "minecraft:repeater", "state": { "delay": "2", "powered": "true" } }
{ "x": 10, "y": 64, "z": 10, "block": "minecraft:redstone_lamp", "state": { "lit": "true" } }

重要: これは正規のプレイでは不可能な操作であり、本サーバー環境でも異常動作を引き起こすことが確認されています。過去の成功知見で一時的に有効に見えたケースもありますが、再現性がなく推奨されません。絶対に実施しないでください。

---

3. BUD-lock 回避のためフェーズ分離（デバイス→ソース）

トラップ

レッドストーンソースブロック（レバー、RSブロック、トーチ等）を、レッドストーンデバイス（リピーター、コンパレーター等）と 同じTickで配置 すると、ブロック更新がスキップされ、リピーターがOFFのままロックされる（BUD-lock）。

正しい使い方

• 配置順序を フェーズ配列 で分離する:
  • フェーズ1: デバイス（リピーター、コンパレーター、トーチ、ダスト）
  • フェーズ2: ソース（レバー、ボタン、RSブロック）
• フェーズ間には自動的に1tickの待機が入るため、デバイスの初期化が完了してからソースが配置される。

[
  {
    "blocks": [{ "x": 10, "y": 64, "z": 10, "block": "minecraft:stone" }],
    "connects": [{ "src": [10,64,10], "dst": [12,64,10], "component": "minecraft:repeater" }]
  },
  {
    "attaches": [{ "component": "minecraft:lever", "pos": [10,65,10], "base": [10,64,10] }]
  }
]

---

4. レバー/ボタンの attaches は土台フェーズの後に

トラップ

レバーやボタンを土台ブロックと 同じフェーズ で配置すると、土台がまだ存在しない空中に attaches が置かれ minecraft:air のままになってレバーが設置されない。空中にレバーが浮く想定で設計しても、attaches は土台ブロックの存在を前提とするため、土台が未配置だと失敗する。

正しい使い方

• 土台ブロックはフェーズ1、レバー/ボタンの attaches はフェーズ2以降に分離する。
• attaches の base 座標が、前のフェーズで配置された土台ブロックの座標と一致することを確認する。

---

5. interact-block の同期ズレ対策

トラップ

mc-cli interact-block でレバー/ボタンを操作した直後に get-blocks やテストで状態を観測すると、Minecraft側のブロック更新が完了しておらず、古い状態を観測してしまう（同期ズレ）。これで「操作が効いていない」と誤診し、無駄な修正試行を消費する。

正しい使い方

• interact-block の後は 必ず --delay を指定するか、別途 wait を挟む。
• リピーター遅延が絡む場合は delay × 1tick + 余裕 の待機を入れる。
• ボタンの場合はパルス時間（石系: 10tick / 木系: 15tick）以上待つ。

# OK: 操作後に待機を入れてから観測
mc-cli interact-block --pos 10,65,10 --delay 4

注意: interact-block は FakePlayer パターンでバニラの onUse を呼び出す正規の実装です。place-blocks で powered を直接書き換えるのは正規のプレイでは不可能であり、異常動作を引き起こすため絶対に使用しないでください。

---

6. アナログ信号は 5〜8 ブロック以内

トラップ

アナログ（0-15）信号を扱う回路で、入力からロジック端子（コンパレーター等）までの配線距離が長すぎると、信号強度が減衰して論理判定が壊れる。アナログ経路にリピーターを置くと強度15に二値化され、アナログ情報が完全に失われる。

正しい使い方

• アナログ信号の入力からロジック端子までは 最大 5〜8 ブロック以内 に収める。
• 超近接マージ配線で減衰を最小化する。
• アナログ経路にはリピーターを置かない（二値化されるため）。
• 信号強度を再強化したい場合は、アナログ情報が不要な箇所（二値化済みの経路）でのみリピーターを使う。

---

7. facing は「入力方向」を指す

トラップ

repeater / comparator / observer の facing は、バニラの感覚（出力方向）とは逆で、主入力が侵入する方向（入力面） を指す。これを間違えると信号が逆流し、回路が繋がらない。

正しい使い方

• これらのブロックは 必ず connects を使用 して配置する。connects が facing を自動計算するため、手動で facing を指定する必要はない。
• connects では src（入力元）→ dst（出力先）の順で指定。信号は src → dst に流れる。
• 直接 blocks に手動 facing 指定で置くことは禁止（--allow-direct-facing を指定しない限りエラーになる）。

// OK: connects 使用
{ "src": [10,64,10], "dst": [12,64,10], "component": "minecraft:repeater" }
// 中間 [11,64,10] にリピーターが配置され、facing=west（東から入力、西へ出力）になる

// NG: 直接 blocks に手動 facing
{ "x": 11, "y": 64, "z": 10, "block": "minecraft:repeater", "state": { "facing": "west" } }

---

8. トラップ/本質バグの切り分けフロー

テスト失敗時に、まず「フレームワーク/DSL/配置順序のトラップ」か「本質的な回路バグ」かを切り分ける。トラップなら設定を直すだけで解決し、本質バグなら回路構造を見直す。

1. エラーメッセージの確認: JSONパースエラー等は フェーズ配列誤り（トラップ1）。
2. 配置後の get-blocks で全体確認: レバーが存在しない / 空中に浮いている → フェーズ順序トラップ（トラップ3, 4）。
3. リピーターがOFFのまま: BUD-lock（トラップ3）または動的状態書き込み（トラップ2）。
4. 操作が効いていない: 同期ズレ（トラップ5）。--delay を増やして再確認。
5. アナログ計算が壊れる: 配線長（トラップ6）。アナログ経路を短くする。
6. 信号が逆流する: facing 誤り（トラップ7）。connects の src/dst を確認。
7. 上記いずれでもない: 本質的な回路バグ。circuit_debugging スキルに従い段階的にデバッグ。

---

9. レッドストーンダストは真下のみに動力を与える

トラップ

レッドストーンダストは、配置されているブロックの真下にしか動力を与えられない。水平方向や直上のブロックに直接給電しようとしても動力が伝わらず、NOT回路の入力やランプの点灯が期待通りに動作しない。

正しい使い方

• 入力を与えたい不透過ブロックの真上までレッドストーンダストを伸ばす。
• 横や斜めから給電したい場合は、リピーターやコンパレーターを使って対象ブロックまたはその手前のブロックを強動力化する。

.d.
dbt

（d: レッドストーンダスト、b: ブロック、t: レッドストーントーチ。横から見た図）

// OK: 土台ブロックの真上にダストを配置
{ "x": 10, "y": 64, "z": 10, "block": "minecraft:redstone_wire" }

// NG: 土台ブロックの横にダストを配置して入力を与えようとする
{ "x": 11, "y": 64, "z": 10, "block": "minecraft:redstone_wire" }

---

10. 推奨される設計前チェックリスト

設計開始前に以下を確認し、トラップを事前排除する。

• place-blocks の --blocks に渡すJSONが、単一オブジェクトまたは配列として正しい形になっている
• state に動的状態（powered/lit/power/extended/enabled）を書き込んでいない
• ソース（レバー等）はデバイスより後のフェーズに分離している
• レバー/ボタンの attaches は土台ブロックのフェーズより後に配置している
• interact-block の後に --delay または別途待機を入れている
• アナログ信号経路は 5〜8 ブロック以内、かつリピーターを置いていない
• repeater/comparator/observer は connects で配置している
• テスト前にテスト区域を fill 等で air クリアしている
• レッドストーンダストから給電するブロックは、ダストがそのブロックの真上に配置されている