| Crate | What it is |
|---|---|
blockwork-model |
The blocks and documents, with nothing that touches the machine: the macro document (macros/), block packs, canvas edits (editing.rs) and the wire shapes the editor speaks (frontend/). The website's editor links this alone. |
blockwork-core |
Everything that runs on this machine: the block runner (macros/runner.rs), input, screen, browser, config and system helpers. It re-exports blockwork-model under the same paths (blockwork_core::macros::Macro still works). |
blockwork-app |
Every command the editor can issue and the background watchers that fire trigger blocks (watch/). No UI toolkit. |
blockwork-daemon |
The long-lived process that owns blockwork-app's state, hotkeys and playback. |
blockwork-protocol |
Messages between the daemon and the Qt UI. |
blockwork-qt |
The Qt Quick editor (qml/) and its Rust/C++ glue (src/). |
blockwork-web |
The same editor commands in WebAssembly, for the website's demo. |
blockwork-ffi |
A C ABI for recording and playback inside another process (the Geometry Dash mod). |
blockwork-linux-bridge |
A native Linux input helper that the FFI starts when it runs under Proton/Wine. blockwork-ffi/build-windows.sh builds it, and the Geometry Dash mod ships it as linux-input.so. |
docs/architecture.md follows one command from the editor to the daemon and back.
The block canvas, palette and document model come from
blockstitch, pinned to one commit
in Cargo.toml. just blockstitch-local builds against a sibling checkout.
- Macro: one document. It holds strands (stacks of blocks on the canvas).
- Instruction or block: one block. Its kind is
InstructionKind. - Header or trigger: a
When...block at the top of a strand.WhenRanruns when you press Run; the others are started by a watcher inblockwork-app. - Value or reporter: what goes in a block's slot (
Value,Op). - Field id: the name the editor uses for one value slot (
FieldId). - Pack: a set of custom blocks from the community library.
You need Rust 1.91 or newer, just, Qt 6.10 or newer (CI and releases use 6.12.0; the website builds the editor with the Qt in blockworked.com/qt-demo/sources.env)
(qmake6 on PATH or QMAKE set; without one the build downloads a minimal
Qt) and Python 3 for the QML tests. just leaves out
blockwork-linux-bridge, which only builds on Linux; do the same with
--exclude blockwork-linux-bridge when calling cargo yourself. The QML tests need a
blockstitch checkout at the pinned commit (just test-qml fetches one into
../blockstitch if it is missing) and one build first, which stages the
Lucide icons.
just # build
just run # build and launch
just test # every Rust test
just test-qml # QML tests (needs Qt 6's qmltestrunner)
just translations # refresh blockwork-qt/i18n after changing UI textThree tests check generated files and rewrite them with BLESS=1:
--test operator_descriptors (the reporter table in BlockCatalog.qml),
--test editor_baseline (a saved macro in the current format) and
-p blockwork-core --test capabilities (blockwork-core/capabilities.json, which the community
site copies).
Rust is formatted with cargo fmt --all (rustfmt's defaults, as in
blockstitch), and CI fails on unformatted code. Whole-tree formatting commits
are listed in .git-blame-ignore-revs. CI also runs clippy and fails on any
warning, so run cargo clippy --workspace --all-targets before pushing.
A new .qml file goes in blockwork-qt/qml/module.json too; the build
refuses a file that isn't listed there, or a listed one that is missing.
The compiler catches most of these, since InstructionKind::info and the
BlockKind impl match every kind, and the tests in fields.rs and
blockwork-model/tests/wire_blocks.rs check the slot, variable and fixture lists against each
other. The rest are listed so nothing is missed.
-
blockwork-model/src/macros/kind.rs: add theInstructionKindvariant with a doc comment. A field added to an existing block needs#[serde(default)]so older files still load. -
blockwork-model/src/macros/info.rs: its row inInstructionKind::info, which says what the block is and does in one place:- its
Role:HeaderorTriggerif it heads a strand (that is whatis_headerreads),Commentif it does nothing, otherwise the runner file that runs it (Control,Data,Dialogs,Input,System,Vision,Browser); - its capabilities (commands, network, screen, ...), which drive the import review and the permission prompts for shared macros.
If it can do something, rerun
BLESS=1 cargo test -p blockwork-core --test capabilitiesto refreshblockwork-core/capabilities.json, then copy that into the community site (node scripts/sync-capabilities.jsthere). - its
-
blockwork-model/src/macros/block_kind.rs: its nested bodies inbody/body_mut, and any variable or list names it holds infor_each_ref. -
blockwork-model/src/macros/fields.rs: aFieldIdper value slot, and its slots inslots_mut(field id, value, type). That one list is what the canvas visits and what a drag or a typed edit resolves through. Add the field torequires_integerif it only takes whole numbers. -
blockwork-core/src/macros/runner/: what it does, in the file itsRolenames (apps.rsholds helpers for the system blocks).run_blockinrunner.rssends it there by its role and otherwise only handles tracing, the debugger, stop flags and call depth; a test fails if a file's arms and the roles disagree. -
blockwork-model/src/frontend/instructions.rs: its line inwire_blocks!, and a case inblockwork-model/tests/fixtures/wire_blocks.json. -
A trigger also needs a watcher in
blockwork-app(seewatch/system.rs) and a line inmacros/trigger.rsfor the run log. -
blockwork-qt/qml/BlockCatalog.qml: a palette section entry, a row in its palette category's function (eventRows,inputRows, ...: label, value and dropdown pieces, icon, andshape: "header"for a trigger;blockwork-model/tests/wire_blocks.rslists any block without one and checks the shape againstis_header), a prefab if a fresh block needs defaults, and its variable dropdowns inregisterVariableFields. -
blockwork-qt/qml/BlockHelp.qml: one sentence on what it does. -
just translations.
- An
ExtOperator(name, arity, default args, evaluation): inblockwork-model/src/input/value.rsif it only works on text, numbers or dates, else inblockwork-core/src/input/value.rs. One that reads the machine callspermissions::requirefirst; one with side effects goes inSIDE_EFFECT_OPERATORS. blockwork-model/src/capabilities.rs: its capability inoperator_capability, or its name inUNGUARDED_OPERATORS. A test fails until it is in one of them. A guarded one also needs thecapabilities.jsonrefresh described under adding a block.BLESS=1 cargo test -p blockwork-core --test operator_descriptorsto regeneratehostDescriptors.blockwork-qt/qml/BlockCatalog.qml: a palette section entry and its label pieces and result type inoperatorRows(); the palette'sextraOperatorslist is built from that and the descriptors.blockwork-qt/qml/BlockHelp.qmlandjust translations, as for a block.
--test operator_descriptors fails until steps 3 to 5 are done.
- A canvas edit (anything the website's editor should do too) goes in
blockwork-model/src/editing.rs: a function overD: Document, its arm indispatchand its name inCOMMANDS. Both the app and the page then answer it. Give it a step inblockwork-app/src/web_parity.rs. - Anything else is app-only: the function in
blockwork-app/src/commands/, in the file for its area (library,settings, ...). It takes&SharedStateand&AppHandle, and callsemit_state_updatedafter changing state. Then its arm inblockwork-app/src/dispatch.rs. - Arms read arguments with
arg. QML spells argument names in camelCase. - QML calls it with
invoke("name", {...}).blockwork-app/tests/qml_commands.rsfails if QML names a command neither dispatcher has, or sends an argument key in a{...}literal that the command's arm never reads.
blockwork-core/src/config/settings.rs: anOption<T>field onAppSettings, so older settings files still load.blockwork-app/src/state.rs: the field onStateDtoand its line inbuild_state_dto. A setting only the UI reads comes straight from the settings file there (likeanimation_speed); one the backend checks often also lives onAppState, loaded inlib.rsat start (likeclose_to_tray).- A
set_...command (see above) incommands/settings.rsthat checks the value and callssave_setting, which saves it and publishes the state. - QML reads it from
appStateuntil the first state snapshot arrives, so give it a fallback where it is read (appState.x ?? default), asanimation_speeddoes inMain.qml. Then its control inSettingsPage.qml, andjust translations.
- Keep comments short and plain. No em-dashes.
- A change to saved files needs a loader for the old shape (see
macros/saved_shapes.rsandmacros/migrate.rs). - Canvas edits live once, in
blockwork-model/src/editing.rs. A rule that isn't about one command goes onMacro(macros/document_rules.rs, or blockstitch if it isn't Blockwork-specific). A command only the website demo answers (blockwork-web/src/session.rs) gets a step in the parity script, or a line in itsNOT_REPLAYEDlist saying why not; a test fails until it has one. - Changelog entries go under the unreleased version in
CHANGELOG.md.