Execution Contexts

ModularMC operates in two distinct execution contexts during the build process: the mapping context and the compilation context. Understanding these contexts is crucial for effective scripting, as they affect how scripts are compiled, how imports are resolved, and how debugging works.

The mapping context is used for evaluating _map.ts files in Regolith’s temporary working directory. The compilation context is used for compiling script files listed in the SCRIPTS export using Esbuild in the project root. Compiling scripts directly in the project root allows debugging with the Minecraft Bedrock Debugger VSCode extension.

Note

%ROOT_DIR% and %FILTER_DIR% on this page refer to environment variables set by Regolith that point to the project root and the filter’s cache directory, respectively. See Regolith’s documentation for more information.

Mapping Context

The mapping context occurs in Regolith’s temporary working directory, where ModularMC evaluates _map.ts files. It uses the deno.json from %FILTER_DIR%, which is not directly user-configurable. However, the filter automatically copies import mappings from your project’s %ROOT_DIR%/deno.json to %FILTER_DIR%/deno.json, resolving relative paths to absolute file:// URLs.

Additionally, paths that point to locations within your project’s dataPath are redirected to the corresponding locations in the temporary data directory. This is particularly useful for import shortcuts in your deno.json, such as "#shared/": "./filters_data/modular_mc/shared/", which reference project files conveniently without relative paths. The redirection ensures these shortcuts work correctly in the temp environment.

Compilation Context

The compilation context occurs in the project root (%ROOT_DIR%), where ModularMC runs Esbuild to compile your TypeScript/JavaScript scripts into a bundled JavaScript file.

Scripts are compiled from the original files in your project directory (not from Regolith’s temporary location), ensuring faster compilation by avoiding copying large node_modules folders into the temporary location. Import resolution uses your project’s deno.json. This means that you get exactly what you see in your editor. The downside of this approach is that you cannot programmatically modify the script files before their compilation. The scripts from the Regolith’s temporary location aren’t used during compilation.

For tips setting up the debugging environment for compiled scripts, see debugging with the Minecraft Bedrock Debugger.