Editing Creating Lua extensions

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]]