Blockly Integration — Megahub IDE

Overview

• Blockly 12.3.1 with the built-in Lua code generator (blockly/lua)
• Custom Web Component <custom-blockly> in frontend/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.md is 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

1. Create frontend/src/components/blockly/mh_myblock.js using the pattern above
2. Import and register in all three files:
   • frontend/src/components/blockly/component.js — add import + entry in customBlocks
   • frontend/scripts/block-renderer.js — add import + entry in customBlocks
   • frontend/scripts/generate-block-docs-simple.js — add dynamic import in blockModules + entry in customBlocks
3. Toolbox: automatic — generateToolbox() groups by category field
4. Write unit tests — REQUIRED for every new block (see below)
5. Test in dev mode: npm run dev or npm test
6. Regenerate docs — REQUIRED after every block add/modify/remove:

   cd frontend
   npm run generate-docs
   

   This regenerates BLOCKS.md and all PNG images in docs/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:

1. Generator output — correct Lua string emitted for representative inputs
2. Field values — all dropdown options generate the correct Lua variant
3. Statement vs. value form (for dual-mode blocks like mh_startthread pattern) — both forms generate correct output
4. 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):

1. Runs vite build to produce a renderer bundle
2. Launches Puppeteer (headless Chrome)
3. Loads block-renderer.html which runs Blockly in the browser
4. For each block: renders to SVG → screenshot to PNG at 2× DPI
5. Saves PNGs to docs/blocks/{category}/{blocktype}.png
6. Generates Markdown with: block image, tooltip description, type, message template, inputs table, fields table
7. 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:

1. Init block (mh_alg_*_init.js) — creates a filter/controller instance, returns a handle string. The user stores this in a variable.
2. 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.js
• frontend/scripts/block-renderer.js
• frontend/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.