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