jsonte for VS Code

Language support for jsonte (JSON Templating Engine) files used in Minecraft Bedrock add-on projects.

Features

Languages

.templ — jsonte templates
.modl — jsonte modules ($module, used through $extend)
.jsonte — standalone jsonte scripts (scope scripts, $scope.x = ...)
#{...} expressions inside .molang and .mcfunction files and ##{...} inside .lang files (highlighting, hover, completion and syntax diagnostics are injected into those languages)

Highlighting

JSON-based TextMate grammar with dedicated scopes for reserved keys ($template, $extend, ...), override/prepend merge keys ($key, ^key) and $molang: keys
Semantic highlighting of {{...}} expressions and .jsonte scripts driven by the engine's ANTLR lexer (keywords, operators, numbers, strings, functions, variables, lambda parameters, comments)
Background decoration for expressions (jsonte.editor.expressionBackground) and bracket matching inside expressions

JSON schema support

Existing JSON schemas are applied to .templ and .modl files so that Bedrock add-on schemas keep working on templated files:

schemas from json.schemas, jsonte.validation.schemas and contributes.jsonValidation of installed extensions (for example the Blockception Minecraft Bedrock Development extension)
.templ/.modl files are matched as if they were the corresponding .json file, so entity.json patterns also cover entity.json.templ and entity.templ
the value of top-level $template is validated against the schema (jsonte.validation.unwrapTemplateKey)
$key, ^key and $molang:key are validated as key; $comment and $assert are never reported as unknown properties
properties inherited from $copy files and $extend modules count towards required checks
whole-value {{=...}} expressions that resolve to literals or scope values are validated with their real type
diagnostics under iteration/condition action keys ({{#...}}, {{?...}}) and around unresolved expressions are downgraded or hidden (jsonte.validation.dynamicTolerance)
schema-driven completion and hover, including $extend module name completion from workspace .modl files
jsonte: Go to Schema opens the schema matched for the current file

jsonte diagnostics

expression syntax errors from the engine grammar ({{...}}, #{...}, ##{...}, template strings, .jsonte scripts)
unmatched or empty {{ }} delimiters
misplaced action directives ({{#...}}/{{?...}} must be the whole key and start right after {{)
malformed merge keys ($/^ without a name, template expression as the base key)
$module in .templ files, missing $module in .modl files
unknown scope property access (data.missing) based on the project scope

Scope awareness

Scope files from the Regolith packs/data/jsonte folder (JSON files and .jsonte scripts) provide:

completion and hover for scope variables and scope-defined lambdas, with JSONC comments shown as documentation
static resolution of scope values in schema validation

Editing

built-in function completion and hover documentation (generated from the engine sources)
directive completion (#, ?, =) at the start of key expressions
snippets: jtefor, jteforas, jteif, jtelit
JSON formatting for .templ/.modl, selection range expansion, {{ }} auto-closing

Settings

Setting	Default	Description
`jsonte.validation.enableSemanticDiagnostics`	`true`	jsonte-specific diagnostics for template, module and embedded files
`jsonte.validation.enableSchemaOnTempl`	`true`	Validate `.templ`/`.modl` against matching JSON schemas
`jsonte.validation.unwrapTemplateKey`	`true`	Validate the value of top-level `$template` instead of the whole file
`jsonte.validation.schemas`	`[]`	Extra schema mappings in the `json.schemas` shape
`jsonte.validation.dynamicTolerance`	`warn`	`off` / `warn` / `ignore` handling of schema errors caused by dynamic expressions
`jsonte.validation.engineEvaluation`	`off`	`onDemand` / `always` lets validation resolve `{{=...}}` values with the jsonte CLI (trusted workspaces only)
`jsonte.validation.enginePath`	`jsonte`	Executable used when engine evaluation is enabled
`jsonte.validation.engineTimeoutMs`	`100`	Timeout per engine call
`jsonte.editor.expressionBackground`	`subtle`	`off` / `subtle` / `strong` background for `{{...}}` expressions

If files.associations maps *.templ or *.modl to another language (for example json), the extension offers to remove the override, because schema support only works with the jsonte languages.

Development

npm install
npm run build
npm test

Launch an Extension Development Host with F5 (optionally with the Bedrock extension enabled) or:

npm run test:manual            # extension only
npm run test:manual:bedrock    # with the Blockception Bedrock extension enabled

Pass -Workspace <path> to scripts/launch-dev-host.ps1 to open a real add-on project instead of this repository.

Keeping up with the engine

ANTLR parser/lexer: copy JsonTemplate.g4 and JsonTemplateLexer.g4 from the engine's grammar/ folder into grammar/ and run npm run generate:antlr (requires Java).
Built-in function catalog: npm run generate:functions -- --source <engine>/jsonte/functions.
Snapshot tests: npm run test:update-snapshots after reviewing the new output.

License

MIT

jsonte

MCDevKit