stewbeet.plugins.source_maps
The source_maps plugin records where every generated line came from, and writes a
Source Map v3 .mcfunction.map sidecar next to each generated function.
An editor or a debugger reading one of those maps can jump from a command in the built datapack
straight to the write_function call in your Python that produced it.
The format is the same one JavaScript tooling has used for a decade, so it is readable by anything
that already speaks source maps, including the Minecraft debugger Sniffer.
What it looks like
The Python that wrote the command, the command, and the sidecar that links them
Required: Nothing. It is off unless you ask for it.
Position: One entry in require. See below.
Source Code: stewbeet/plugins/source_maps/__init__.py
Source Code: stewbeet/plugins/source_maps/emit/__init__.py
Source Code: stewbeet/plugins/source_maps/mecha/__init__.py
What it does
- Records every
write_function,write_versioned_function,.obj.append(...)and friends, in call order - Resolves each write back to the line and column of the Python that made it
- Follows a variable back to every literal it was assigned and grown with, so a command built in a loop maps to the literal line that spells it
- Follows a parameter annotated
McFunctionback to the call that passed it, so a function wrappingwrite_functionmaps to the literal its caller wrote - Realigns the recorded lines against the final text, so post-processing like
auto.headersdoes not shift the mapping - Writes one
<name>.mcfunction.mapper function, beside the function and named after it. The function itself is untouched - Maps content a plugin generated from one of your declarations back to that
Block(...)orItem(...)call - Maps what mecha compiled as well, so a
.boltmodule and a.mcfunctionholding bolt lead back to their own lines - Maps each line of a function both wrote to, like a load function a plugin prepends to, back to its own origin
- Never names a file inside StewBeet, beet, bolt, mecha or stouputils: a mapping points at your own source or at nothing
Configuration
There is nothing to configure, and one entry to add:
require:
- "stewbeet"
- "stewbeet.plugins.source_maps"stewbeet.plugins.source_maps goes in require, next to stewbeet itself. Everything in require runs
before the pack is even loaded, so nothing can write a function before recording starts. Its position
within require does not matter. Recording the pack's own hand-written .mcfunction files as they
load costs nothing: they have no Python behind them, so they get no map.
To try it without editing beet.yml, or in a project whose snapshot tests compare the whole pack, ask for it on the command line:
beet -s "require[]=stewbeet.plugins.source_maps" build.
That is the whole configuration, mecha included: beet unwinds require last, so by the time this
plugin finishes, mecha has compiled and its compilation units are still there to be read.
stewbeet.plugins.archive writes the maps itself before it zips, so both the build directory and the zip that ends up in saves/<world>/datapacks carry the same thing.
If you package the pack some other way, add stewbeet.plugins.source_maps.emit to your pipeline, after every plugin that writes or rewrites functions and before whichever plugin packages it.
Forget it and the maps are still written at the very end of the build, with a warning naming the count whenever a packaging plugin already ran.
A project with no StewBeet writes in it
A pure bolt or mecha project needs the same single line. Nothing calls the helpers, so nothing is recorded, and every function mecha compiled is mapped from its AST:
require:
- "bolt"
- "stewbeet.plugins.source_maps"What you get
A generated function is exactly what it always was:
say Starting root
function tns:helper/do_workAnd the sidecar beside it, root.mcfunction.map, names your own source relative to the project root:
{
"version": 3,
"file": "root.mcfunction",
"sources": ["src/link.py"],
"names": [],
"mappings": "AAKA;AACA;AACA"
}sourcesContent is deliberately absent. Consumers read your sources from disk, and inlining a whole project into every map would cost tens of megabytes.
There is no sourceRoot either: Sniffer resolves it itself, so sources are plain paths from the project root and a consumer looks for the first folder above the map that holds them.
What mecha compiled carries more, for an editor showing your source to a vanilla parser:
- A segment for each end of each AST node, after the one at column 0, so a value bolt computed or a
~/childpath mecha resolved is found in the generated line column for column. x_stewbeet_bolt: the indices of thesourcesno vanilla parser reads, because bolt generated Python for them, mecha nested a function in them, one of their commands spans several lines, or one comes from a plugin.x_stewbeet_opaque:[source, line, column]where syntax a plugin added to mecha's command tree begins, read against the tree mecha ships for your Minecraft version.
Fields starting with x_ are the standard's own room for vendors, so every other consumer ignores them.
What is mapped, and what is not
A command you wrote yourself maps to the line you wrote it on. A command a plugin generated from one
of your declarations maps to the declaration, not to the plugin: ctrl+clicking inside a custom
block's place_main leads to your Block(...) call.
Scoped so far: datapack.custom_blocks, and the parts of custom_recipes that write a function per
item (smithed, furnace, pulverizer, awakened forge). Everything else a plugin generates on its own
account stays unmapped, which is the designed behaviour rather than a failure: an unmapped line costs
you nothing, a line pointing at the wrong place costs you a wasted search.
Two more things stay unmapped by design:
- Pack-level scaffolding.
custom_blocks/get_rotationand friends are written once for the whole pack and belong to no declaration, so they are attributed to none. - Definitions with no Python declaration, loaded from JSON or coming from
external_definitions. There is no call to point at.
Shipping a release
The maps are only in your build because you asked for them. A release build that does not ask for them produces exactly the same datapack it always did, byte for byte, with no maps beside the functions.
Next steps
- Writing functions and files: the calls this plugin records.
- All plugins: the rest of the pipeline, in the order it runs.
- Configuring the build: enabling, ordering and configuring plugins.