Clanker: Add and update user documentation for Lua extensions and the catalog

2026-08-06T09:12:23Z

Add and update user documentation for Lua extensions and the catalog

New page

A SimTX Lua extension is a folder containing an <code>extension.properties</code> manifest and one or more Lua files. The graphical creator is the usual starting point because it produces a valid manifest and an editable example.

== Creating a package ==
# Open '''Extensions''' in the transmitter footer.
# Select '''Create extension'''.
# Enter a stable package ID, display name, semantic version, API version, entry file, types, and description.
# Add dependencies or exported modules when the package uses them.
# Select '''Create'''.
# Select the package in the '''Installed''' tab and use '''Edit package''', or open the user folder in an external text editor.
# Select '''Reload now''' after saving changes. Loading errors appear in the '''Problems''' tab.

The stable package ID cannot be changed in the built-in editor after creation. A new package should therefore use an identifier controlled by its author, such as <code>net.example.voice-tools</code>.

== Minimal audio add-on ==
The following package supplies one gain control and processes the selected audio source.

<code>extension.properties</code>:
<syntaxhighlight lang="ini">
id=net.example.gain
name=Gain Example
version=1.0.0
api=1
entry=init.lua
types=audio-addon
description=Applies adjustable gain to mono audio.
</syntaxhighlight>

<code>init.lua</code>:
<syntaxhighlight lang="lua">
simtx.require_api(1)

simtx.addon {
name = "Gain",
description = "Applies adjustable gain to mono audio.",
controls = {
simtx.controls.slider("gain", {
label = "Gain", unit = "x",
min = 0, max = 2, step = 0.01, default = 1,
}),
},
process = function(audio, ctx)
audio:gain(ctx:control("gain"))
audio:limit(1)
end,
}
</syntaxhighlight>

== Package layout ==
Only the file named by <code>entry</code> is run as the package entry point. Other Lua files are modules and are loaded with <code>require</code>.

<syntaxhighlight lang="text">
gain-package/
extension.properties
init.lua
filters.lua
codec/
tone.lua
</syntaxhighlight>

Within the same package, <code>require("filters")</code> loads <code>filters.lua</code>, and <code>require("codec.tone")</code> loads <code>codec/tone.lua</code>. A module should return its public value. A module that returns no value is treated as returning <code>true</code>.

== Development cycle ==
The entry file registers features when the package is loaded. Each running modulation or audio add-on session receives an isolated copy of the script state. Values declared as controls remain live, so an operator may adjust them during transmission.

A practical development cycle is:
# Begin with one of the supplied examples or the generated template.
# Keep the manifest <code>types</code> list consistent with the registrations in the entry file.
# Reload the package and inspect the '''Problems''' tab.
# Test controls and required inputs before transmitting.
# Use '''Catalog''' > '''Preview Selected''' to review the exact shared files before or after publication.

== Publishing ==
The package can be shared with '''Catalog''' > '''Share Extension Folder...'''. Publishing requires a linked access token in the transmitter's '''Token''' field. [[Extension catalog]] describes publication, categories, revisions, and updates.

== Further reference ==
* [[Lua extension manifest]] lists every manifest field and version range.
* [[Lua extension API]] lists registration tables, controls, inputs, helper functions, and aliases.
* [[Lua modulation API]], [[Lua audio add-on API]], [[Lua action API]], and [[Lua theme API]] describe each extension type.

[[Category:Lua extensions]]

Creating Lua extensions - Revision history

Clanker: Add and update user documentation for Lua extensions and the catalog