mirkosertic/Megahub / .claude/skills/blockly
blockly
VerifiedBlockly visual programming context for the Megahub project. Use when adding, modifying, or debugging custom Blockly blocks, the Lua code generator, the toolbox, block colors, or the BLOCKS.md documentation generation script.
Blockly Integration — Megahub IDE
Overview
- Blockly 12.3.1 with the built-in Lua code generator (
blockly/lua) - Custom Web Component
<custom-blockly>infrontend/src/components/blockly/component.js - Each custom block is a self-contained JS file with definition + Lua generator + color
- All 25 custom blocks auto-register;
BLOCKS.mdis auto-generated via Puppeteer
File Structure
frontend/src/components/blockly/
component.js Main component — init, toolbox, workspace, Lua generation
component.html Minimal web component template
colors.js Color hue constants for all categories (0–360)
mh_*.js 20 Megahub core blocks (motors, GPIO, threads, debug)
lego_*.js 2 LEGO Powered Up blocks
ui_*.js 1 UI display block
Block Definition Pattern
Every block is one file. All fields are required unless noted:
export const definition = {
category: 'Category Name', // Groups this block in the toolbox
colour: colorConstant, // Import from colors.js — never hardcode
blockdefinition: { // Standard Blockly JSON definition
type: 'mh_block_name', // Must match filename (minus .js)
message0: 'label %1 %2', // %N = input/field placeholders
args0: [ /* inputs */ ],
previousStatement: null, // Include for statement blocks
nextStatement: null, // Include for statement blocks
// OR: output: null // For value blocks that return a value
tooltip: 'Description for BLOCKS.md and hover UI',
helpUrl: ''
},
generator: (block, generator) => {
// Return string + "\n" for statement blocks
// Return [ "code", precedence ] for value blocks
},
inputsForToolbox: { /* optional shadow defaults */ }
};
Statement block generator pattern
generator: (block, generator) => {
const val = generator.valueToCode(block, 'VALUE', 0);
const stmt = generator.statementToCode(block, 'DO');
const field = block.getFieldValue('FIELD_NAME');
return `myFunction(${val}, ${field})\n`;
}
Value block generator pattern
generator: (block, generator) => {
const val = block.getFieldValue('VALUE');
return [ val, 0 ]; // [ code, precedence ]
}
Naming Conventions
| Prefix | Category | Example |
|---|---|---|
mh_ | Megahub core | mh_set_motor_speed, mh_wait, mh_startthread |
lego_ | LEGO Powered Up | lego_get_mode_dataset, lego_select_mode |
ui_ | User interface | ui_show_value |
- All lowercase, underscores only
- Block type ID must match the JS filename (e.g.,
mh_wait.js→type: 'mh_wait')
Color System (colors.js)
Colors are Blockly hue values (0–360). Always import — never hardcode a number.
| Constant | Hue | Category |
|---|---|---|
colorControlFlow | 20 | Control flow |
colorLogic | 40 | Logic |
colorMath | 60 | Math |
colorText | 80 | Text |
colorLists | 100 | Lists |
colorIO | 120 | I/O |
colorLego | 140 | LEGO© |
colorGamepad | 160 | Gamepad |
colorFastLED | 180 | FastLED |
colorIMU | 200 | IMU |
colorUI | 220 | UI |
colorAlgorithms | 230 | Algorithms |
colorDebug | 240 | Debug |
Adding a New Block
- Create
frontend/src/components/blockly/mh_myblock.jsusing the pattern above - Import and register in all three files:
frontend/src/components/blockly/component.js— add import + entry incustomBlocksfrontend/scripts/block-renderer.js— add import + entry incustomBlocksfrontend/scripts/generate-block-docs-simple.js— add dynamic import inblockModules+ entry incustomBlocks
- Toolbox: automatic —
generateToolbox()groups bycategoryfield - Write unit tests — REQUIRED for every new block (see below)
- Test in dev mode:
npm run devornpm test - Regenerate docs — REQUIRED after every block add/modify/remove:
This regeneratescd frontend npm run generate-docsBLOCKS.mdand all PNG images indocs/blocks/. Never skip this step.
Unit Tests — REQUIRED for Every New Block
Every new block file must have a corresponding test file. This is a hard requirement.
Location: frontend/test/blockly/{block_type}.test.js
Test file must cover:
- Generator output — correct Lua string emitted for representative inputs
- Field values — all dropdown options generate the correct Lua variant
- Statement vs. value form (for dual-mode blocks like
mh_startthreadpattern) — both forms generate correct output - Edge cases — empty inputs, zero values, boundary field options
Minimal test pattern:
import { describe, it, expect } from 'vitest';
// Import the block definition
import { definition } from '../../../../src/components/blockly/mh_myblock.js';
describe('mh_myblock generator', () => {
it('generates correct Lua for basic case', () => {
const mockBlock = {
getFieldValue: (name) => name === 'MY_FIELD' ? 'VALUE' : '',
outputConnection: null,
};
const mockGenerator = {
valueToCode: (_b, _name, _prec) => '42',
};
const result = definition.generator(mockBlock, mockGenerator);
expect(result).toBe('myFunction(42, "VALUE")\n');
});
});
Run tests:
cd frontend
npm test
When to create tests: Immediately after creating the block file, before registering it in component.js. Tests run in CI — a block without tests is incomplete.
The component.js registration loop handles everything:
// Blockly block definition
Blockly.Blocks[type].init = function() { this.jsonInit(def.blockdefinition); }
// Lua generator
luaGenerator.forBlock[type] = (block) => def.generator(block, luaGenerator);
Lua Code Generation
The workspace generates Lua code on every change:
// In component.js — called on workspace change events
generateLUAPreview() {
const code = luaGenerator.workspaceToCode(this.workspace);
// code is the complete Lua script
}
Generated Lua script structure (from mh_init and mh_startthread blocks):
hub.init(function()
-- initialization block contents
end)
hub.startthread('Thread Name', blockId, stackSize, false, function()
-- thread loop contents
end)
BLOCKS.md Auto-Generation
BLOCKS.md is automatically generated — never edit it manually.
Command:
cd frontend
npm run generate-docs
How it works (frontend/scripts/generate-block-docs-simple.js):
- Runs
vite buildto produce a renderer bundle - Launches Puppeteer (headless Chrome)
- Loads
block-renderer.htmlwhich runs Blockly in the browser - For each block: renders to SVG → screenshot to PNG at 2× DPI
- Saves PNGs to
docs/blocks/{category}/{blocktype}.png - Generates Markdown with: block image, tooltip description, type, message template, inputs table, fields table
- Appends a statistics summary (block counts by type and category)
Output structure:
docs/blocks/
control flow/mh_init.png
lego©/lego_get_mode_dataset.png
...
BLOCKS.md ← regenerated in full
When to regenerate: after adding, removing, or changing any block definition, tooltip, inputs, or fields. The tooltip field in blockdefinition becomes the description in BLOCKS.md — keep it informative.
Stateful Algorithm Block Pattern
All stateful algorithm blocks in the Algorithms category follow an explicit handle pattern. This is a hard convention — never use block.id as an implicit state key.
Pattern: Init + Compute (same as PID and DR)
A stateful algorithm requires two Blockly blocks:
- Init block (
mh_alg_*_init.js) — creates a filter/controller instance, returns a handle string. The user stores this in a variable. - Compute block (
mh_alg_*.js) — takes the handle as first input, plus algorithm parameters.
Firmware side (libluaalg.cpp)
// State map keyed by handle string ("ma_0", "ma_1", ...)
static std::map<std::string, MyState> myStates;
static int myHandleCounter = 0;
// Init: creates instance, returns handle
int alg_init_my(lua_State* L) {
std::string handle = "my_" + std::to_string(myHandleCounter++);
myStates[handle] = MyState{};
lua_pushstring(L, handle.c_str());
return 1;
}
// Compute: looks up by handle
int alg_my(lua_State* L) {
const char* handle = luaL_checkstring(L, 1);
auto it = myStates.find(handle);
if (it == myStates.end()) {
WARN("alg_my: handle '%s' not found", handle);
lua_pushnumber(L, 0.0);
return 1;
}
// ... use it->second ...
}
// Clear all: called in alg_library() at init
int alg_clear_all_my(lua_State* L) {
myStates.clear();
myHandleCounter = 0;
return 0;
}
Register all three in alg_library(), and call alg_clear_all_my at the top of alg_library().
Blockly side
Init block — no inputs, output is a handle value:
generator: (block, generator) => {
return [`alg.initMy()`, 0];
},
Compute block — HANDLE is first input, uses variables_get shadow:
inputsForToolbox: {
HANDLE: {
shadow: { type: 'variables_get', fields: { VAR: { name: 'myFilter' } } },
},
// ... other inputs ...
},
generator: (block, generator) => {
const handle = generator.valueToCode(block, 'HANDLE', 0) || '"my_0"';
// ...
return [`alg.my(${handle}, ...)`, 0];
},
Registration
Both blocks must be added to all three registration files:
frontend/src/components/blockly/component.jsfrontend/scripts/block-renderer.jsfrontend/scripts/generate-block-docs-simple.js
Stateless algorithms (alg.map)
Stateless algorithms (no persistent state) need only one block, no handle, no init, no clearAll. Register only the single block file.
Toolbox Toolbox Shadow Defaults (inputsForToolbox)
To pre-populate inputs in the toolbox with useful defaults, add inputsForToolbox:
inputsForToolbox: {
VALUE: {
shadow: {
type: 'math_number',
fields: { NUM: 500 }
}
}
}
The generateToolbox() function reads this and adds <shadow> elements automatically.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 197k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |