stack-chan

# ブロックエディタのチュートリアル

今回の生成コードにはhost API 8以降（9.5.0+stackchan.8以降）が必要です。旧XSAは編集用の `.stackchan-blocks.json` を開いて再ビルドします。

## 5分でシミュレーターを動かす

1. Webツールから「ブロックエディタ」を開きます。
2. サンプルボタンから「1. あいさつと表情」を選びます。
3. 「スタートしたとき」の内側に、好きな表情ブロックを置きます。
4. 「ビルド」を押します。
5. 診断にエラーがなければ「シミュレーターで実行」を押します。
6. シミュレーター内の顔と吹き出しが変わることを確認します。

## 15分で入力に反応させる

1. シミュレーターでは「イベント」からボタンを選びます。対応実機では頭部タッチセンサやIMUも選べます。
2. イベントの内側に、発話、表情、姿勢のブロックを接続します。
3. 対象機種を選び、診断欄に未対応能力がないことを確認します。
4. シミュレーターで実行し、ダイアログ上部のA、B、Cボタンで入力を試します。
5. 実機を使う場合は、シミュレーターで停止しないことを確認してから「実機へ書き込み」を押します。
6. チップ、実ファームウェア版、XS版、パーティション、サイズ、使用能力を確認して書き込みを承認します。

## 歌わせる

1. 「おしゃべり」から「テンポ 120 でリストを歌う」をイベントの内側へ置きます。
2. リストの各要素に「音符 ド4 を 1 拍で『き』と歌う」を入れます。
3. 各要素は「音階、拍、歌詞」のトリプルとして生成されます。
4. 音符1つにつき、かな1モーラ（「き」「きゃ」「ん」「ー」など）を指定します。
5. 間を空けるときは「拍の休符」をリストへ入れます。
6. M5Stack-chan CoreS3またはWebシミュレーターを選び、ビルドして再生を確認します。

生成コードでは、楽譜が次のようなトリプルのリストになります。

```js
;[
  ['C4', 1, 'き'],
  ['C4', 1, 'ら'],
  ['R', 0.5, ''],
]
```

長い音を続ける「ー」は、直前の歌詞の母音を引き継ぎます。
歌詞が複数モーラの場合や、1音が20〜8000ミリ秒の範囲を外れる場合は、MODの実行時にエラーになります。

## 30分でShape型Faceを組み込む

1. Webツールから「Shape顔エディタ」を開きます。
2. Face領域、左右の目、まぶた、口の位置と寸法を調整します。
3. プレビュー上で目と口をドラッグし、表情と配色を確認します。
4. 「ブロックエディタで使う」を押します。
5. ブロックエディタのアセット欄に「使用中」と表示されることを確認します。
6. 生成コードの `ui(app).setShapeFace(...)` に、編集した目・口のデータが渡されていることを確認します。
7. ビルドしてシミュレーターで実行します。
8. プロジェクト保存ボタンから`.stackchan-blocks.json`を保存します。
9. `.xsa`も保存し、編集用成果物と実行用成果物を分けて管理します。

## コードによる開発へ移る

生成コードタブの `mod.js` は、[SDK教材](../../firmware/lessons/README_ja.md)と同じ `defineApp({ setup(app) { … } })` を使います。

ボタンを離したときは `input(app).onRelease(...)`、周期処理は `app.time.every(...)` です。処理中の同じイベントは重ねて実行されません。待機には `task.sleep(ms)`、音声・姿勢の操作には `{ signal: task.signal }` を渡し、停止すると途中の処理も終了します。タイマーや機器の終了処理を自作する必要はありません。

歌唱は `singing(app).sing(bpm, score, { signal: task.signal })` を使います。ホストが歌詞と拍を検証し、音声出力の競合も扱います。顔の色は `{ r, g, b }`、姿勢は度、SDKの時間はミリ秒です。

ローカル開発へ移る場合は、生成コードをMODディレクトリの`mod.js`へ保存し、プロジェクトのmanifestとアセットを同じディレクトリへ配置します。

ブロックエディタへ戻る可能性がある間は、`.stackchan-blocks.json`も保持します。

生成コードを直接変更しても、元のBlocklyワークスペースへは逆変換されません。

## 失敗から復旧する

- host APIが足りない場合は、ファームウェアを更新してから再度書き込みます。
- `UNSUPPORTED` は機種または設定が未対応です。歌唱なら音声合成器を `stackchan-voice` に設定します。
- `BUSY` は同じ資源が使用中です。会話やラジオを停止してから操作します。
- ループ上限のエラーでは、診断で示されたブロックの回数や終了条件を修正します。
- 廃止した音符・休符の縦積み形式は、リストにトリプル形式の音符・休符を入れる形へ書き直します。

実機へ書き込む前に、対象機種、ファームウェア、XSアーカイブの互換性を自動で検証します。

検証を通過すると既存MODを置き換え、書き込み後の内容を読み戻して確認します。

MODを起動したくない場合は「実機のMODを削除」を使います。

ファームウェア本体はこれらの操作で消去しません。

ブラウザ内のプロジェクトを解析できない場合は、ヘッダーに警告ボタンが表示されます。

警告ボタンから元データとエラーを含む復旧用JSONを保存してください。