Project files

Block Editor Tutorial

Run the simulator in 5 minutes

1. Open the block editor from the web tool.
2. From the sample buttons, choose "1. Greeting and expressions".
3. Inside "When started", place the expression block you like.
4. Press "Build".
5. If the diagnostics show no errors, press "Run in simulator".
6. Confirm that the face and speech bubble in the simulator change.

Reacting to input in 15 minutes

1. In the simulator, choose a button from "Events". On supported hardware, you can also select the head touch sensor or the IMU.
2. Inside the event, connect speech, expression, and posture blocks.
3. Select the target model and check the diagnostics panel to confirm there are no unsupported capabilities.
4. Run it in the simulator and try the input using the A, B, and C buttons at the top of the dialog.
5. If you are using real hardware, confirm that it does not stop in the simulator, then press "Write to hardware".
6. Check the chip, actual firmware version, XS version, partitions, size, and the capabilities used, then approve the write.

Singing

1. From "Chatter", place "Sing the list at tempo 120" inside the event.
2. In each list item, add "Sing note C4 for 1 beat with the lyric 'ki'".
3. Each item is generated as a triple of "pitch, beat, lyric".
4. For each note, specify one kana mora (such as "ki", "kya", "n", or "ー").
5. To leave a gap, add a "beat rest" to the list.
6. Choose the M5Stack-chan CoreS3 or the web simulator, build, and check playback.

In the generated code, the score becomes a list of triples like this:

[
  ['C4', 1, 'き'],
  ['C4', 1, 'ら'],
  ['R', 0.5, ''],
]

A "ー" that continues a long note carries over the vowel of the preceding lyric. If a lyric has more than one mora, or if a note falls outside the 20–8000 ms range, the MOD raises an error at runtime.

Embedding a Shape-Type Face in 30 Minutes

1. Open the "Shape Face Editor" from the web tools.
2. Adjust the Face area, the left and right eyes, the eyelids, and the positions and dimensions of the mouth.
3. Drag the eyes and mouth on the preview to check the expression and color scheme.
4. Press "Use in Block Editor."
5. Confirm that "In use" is displayed in the asset field of the Block Editor.
6. Confirm that FaceBase.template and robot.ui.setFace are included in the generated code.
7. Build and run it in the simulator.
8. Save .stackchan-blocks.json using the project save button.
9. Also save .xsa, and manage the editing artifacts and the runtime artifacts separately.

Moving to Code-Based Development

The mod.js tab exposes the same onContextCreated(robot) as a regular MOD.

To continue development locally, save the generated code to mod.js in your MOD directory, and place the project's manifest and assets in the same directory.

While you may still return to the block editor, keep .stackchan-blocks.json as well.

Editing the generated code directly does not convert it back into the original Blockly workspace.

Recovering from failures

Before writing to the device, the target model, firmware, and XS archive compatibility are verified automatically.

When verification passes, the existing MOD is replaced, and the written contents are read back to confirm them.

If you do not want to start the MOD, use "Delete MOD from device."

These operations do not erase the firmware itself.

If the project in the browser cannot be parsed, a warning button appears in the header.

From the warning button, save the recovery JSON, which contains the original data and the error.