Runtimes and packing

Supported runtimes

runtime	Entry	Notes
java	.jar	Requires Java 8+ on the machine
python	.py	Requires python3 / python in PATH
node	.js	Requires node in PATH
c / cpp	binary	Native executable
go	binary	go build output
rust	binary	cargo build --release output
zig	binary	zig build-exe output
native	binary	Generic fallback for the above

Native runtimes need no interpreter on the target machine, but you must build per platform:

Platform	Artifact
Windows x64	.exe
Linux x64 / arm64	no extension, executable bit
macOS arm64 / x64	no extension, code signed

manifest.json

{
  "id": "hello-go",
  "name": "Hello Go",
  "version": "1.0.0",
  "runtime": "go",
  "entry": "bin/hello-go.exe",
  "author": "you",
  "permissions": ["ui"],
  "description": "Sample extension"
}

Field	Required	Notes
id	yes	[a-z0-9-], immutable after install
name	yes	Display name
version	yes	Semver
runtime	yes	See table above
entry	yes	Relative path inside the package
author	no
description	no
homepage	no
permissions	no	Array
minHost	no	Minimum launcher version
args	no	Extra argv for native runtimes
env	no	Environment variables

entry rules: forward slashes, no .., no absolute paths, and for native runtimes point directly at the binary.

Packing

python extensions/pack.py extensions/examples/hello-go -o dist/hello-go.zip

What it does:

1. Validates manifest.json.
2. Builds native runtimes (go build -ldflags "-s -w", cargo build --release).
3. Normalises zip permissions to 0644; the host adds 0755 to the entry when extracting.
4. Enforces size limits.
5. Writes the zip.

Manual packing works too, but keep zip entries non-executable and strip build directories.

Examples and SDKs

Path	Runtime	Shows
extensions/examples/hello-java	java	Minimal runnable extension
extensions/examples/hello-go	go	Native binary + host API
extensions/examples/hello-rust	rust	Zero-dependency JSON + native binary

Language	SDK
Go	extensions/sdk/go (package tmlext, stdlib only)
Rust	extensions/sdk/rust (crate tml-ext, no deps)

SDKs and template repos

The protocol has exactly one source: extensions/schema in this repository. The SDKs come in two flavours — Go and Rust reference extensions/sdk here as a dependency (never a copy), while the Java / Python / Node / C templates ship their own zero-dependency protocol implementation:

Language	Template repo	How it gets the SDK
Java	https://github.com/TYWStudio/template-tml-extension-java	Bundled Json.java, no external deps
Python	https://github.com/TYWStudio/template-tml-extension-python	Bundled tml.py
Node.js	https://github.com/TYWStudio/template-tml-extension-node	Bundled tml.js
C	https://github.com/TYWStudio/template-tml-extension-c	Bundled zero-dependency implementation
Rust	https://github.com/TYWStudio/template-tml-extension-rust	tml-ext = { git = "https://github.com/TYWStudio/TML", tag = "sdk-rust-v1.0.0" }
Go	https://github.com/TYWStudio/template-tml-extension-go	require github.com/TYWStudio/TML/extensions/sdk/go v1.0.0

Clone / build / import steps per language: Language templates.

Shipping a protocol change: edit extensions/sdk/* and schema/ here first, tag a new version (extensions/sdk/go/vX.Y.Z for Go, sdk-rust-vX.Y.Z for Rust), then bump the dependency in the templates. Doing it the other way round forks the implementation.

Debugging

cd extensions/my-ext
./bin/hello-go        # speak the stdio protocol directly

Click Refresh in Settings → Extensions after changes. Logs: logs/ext-*.log. See Import & manage for the rest.

Symptom	Cause
Not listed	Invalid JSON or duplicate id
"Package was modified"	Content changed but trust record not refreshed
"Runtime unavailable"	Missing interpreter, or missing exec bit / wrong architecture
Exits immediately	Entry does not read stdin, or crashed — check the log