Editor support
The StewBeet extension for VSCode is editor support for the whole beet ecosystem: beet, bolt, mecha and StewBeet.
.bolt files get their own language, and the mcfunction strings inside your Python get highlighting, completion, errors and links to the built datapack.
Install: search StewBeet in the Extensions panel, or open it on the marketplace.
Needs your venv: no. It reads your sources and the files your build writes, nothing else.
Source Code: extension/vscode
| You write | You get |
|---|---|
.bolt modules | The Bolt language: highlighting, completion and ctrl+click on the commands, and a lens per function the module writes |
bolt inside a .mcfunction | The same, and Spyglass taken off a file it cannot parse |
plain beet, ctx.data.functions[p] = Function(...) | The commands inside are commands: coloured, completed, checked, and linked to what the build wrote |
| mecha | Navigation from every generated line back to the source line it came from |
StewBeet write_* helpers | All of the above, plus every {...} path resolved to what it really is |
Setup
- Install Spyglass. It provides the completion, hover and errors the extension routes into your blocks.
- For navigation to the build, add the source_maps plugin to your
beet.yml:
require:
- "stewbeet"
- "stewbeet.plugins.source_maps" # writes the .mcfunction.map files the editor navigates withThat is the whole setup. The extension works without step 2, minus the links between your Python and the built pack.
Bolt
.bolt files open as Bolt, with a grammar generated from mecha's command tree: item = 3 is Python, item modify entity @s ... is a command.
- Completion, errors and ctrl+click on the commands, through Spyglass. Python expressions are masked.
- A lens per function the module writes, leading to the generated file.
- Computed paths stay clickable:
function gui.openresolves to what the last build wrote.
A .mcfunction holding bolt gets the bolt language id too. Spyglass still indexes it, so the functions it defines are known to the files that call them, and the errors Spyglass reports on its bolt lines are dropped.
See Approach 4: Bolt for the language itself.
beet
Plugins using beet's own API need nothing beyond stewbeet.plugins.source_maps:
- Errors as you type, no build needed. Build errors are relayed onto the Python that wrote the command.
- Navigation both ways: go to definition lands on the call that wrote a function, find references lists every writer, and a lens above each block opens what it generated.
StewBeet
write_function(f"{ns}:machines/tick", f"""
execute unless score @s energy.storage >= @s {ns}.energy_rate run return fail
execute if entity @s[tag={ns}.turbine] run function {ns}:turbine/tick
""")Each {...} is filled with what the last build resolved it to, so ctrl+click and completion work on computed paths.
A name resolved on one line is reused where the build covers nothing, such as commands collected in a list.
Nothing evaluates your Python, and what stays unknown keeps a _ mask.
What counts as a block
| Written as | Example |
|---|---|
write_* helpers | write_function, write_versioned_function, write_load_file, ... |
| A variable | content = f"""...""", every += up to the call that consumes it, and a literal the call adds to it |
| A list | .append, += [...], literals, comprehensions, "\n".join(lines) |
| Your own function | Any parameter annotated McFunction |
| beet's own API | Function(...) from a string or a list[str], plus .append, .prepend and .lines |
Highlighting a variable needs the McFunction annotation (a plain str alias from stewbeet). Everything else works without it.
Commands
From the palette: Go to Generated Function, Go to Python Source, Reload Source Maps, Refresh Build Diagnostics, Show Diagnostics Status, Install Spyglass Language Server.
Settings
All under StewBeet.*:
| Setting | Default | |
|---|---|---|
languageFeatures | true | Completion, hover, signature help and go to definition inside the blocks |
suggestSpyglass | true | Offer the Spyglass install once, when it is missing |
buildOutput | "" | Where the generated pack is, absolute or relative to the workspace. Empty searches the workspace |
sourceMapDiagnostics | true | Relay build errors onto the Python that wrote the command |
resolveInterpolations | true | Fill each {...} with what the last build resolved it to |
diagnosticRuleDenylist | ["undeclaredSymbol"] | Rules never relayed onto Python |
codeLens | true | The link above a block that produced a function |
headerLinks | true | Resource locations in a generated file's #> header |
boltInMcfunction | true | Give a .mcfunction holding bolt the bolt language id |
enableBlockDecorations | true | The coloured box around a block |
backgroundColor | rgba(80,40,0,0.15) | Any CSS colour |
borderColor | rgba(200,120,30,0.30) | Any CSS colour |
borderWidth | "2px" |
Coming from Aegis
Compared to Aegis, StewBeet is lighter and easier to install, but it does not provide Python symbols in completion yet.
| Aegis | StewBeet | |
|---|---|---|
.bolt highlighting | None, read as mcfunction | Bolt grammar |
| Commands in Python strings | No | Yes |
| Source to build navigation | No | Both directions |
| Needs | ms-python.python and your environment | Nothing |
.bolt completion | Full compiler, Python symbols included | Commands only, through Spyglass |
Keep Aegis if you need that last row.
Next steps
- Writing functions and files: everything the extension reads, including Bolt.
- stewbeet.plugins.source_maps: the source maps behind the navigation.