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

2026-08-06T09:12:24Z

Add and update user documentation for Lua extensions and the catalog

New page

Every Lua extension package contains an <code>extension.properties</code> file. The manifest identifies the package, states its compatibility, and declares the types that the entry file provides.

== Fields ==
{| class="wikitable"
! Field !! Required !! Meaning
|-
| <code>id</code> || Yes || Stable lowercase package identifier. It must contain at least one separator and may use letters, digits, periods, underscores, and hyphens, for example <code>net.example.my-addon</code>.
|-
| <code>name</code> || Yes || Display name, at most 80 characters.
|-
| <code>version</code> || Yes || Package version in semantic versioning form, such as <code>1.2.0</code>, optionally with prerelease or build information.
|-
| <code>api</code> || Yes || Required SimTX Lua API version. The current version is <code>1</code>.
|-
| <code>entry</code> || No || Relative path of the entry Lua file. The default is <code>init.lua</code>.
|-
| <code>types</code> || Yes || Comma-separated list of <code>modulation</code>, <code>audio-addon</code>, <code>action</code>, <code>theme</code>, and <code>library</code>.
|-
| <code>description</code> || No || Package description, at most 300 characters.
|-
| <code>dependencies</code> || No || Comma-separated package requirements in <code>package.id@version-range</code> form.
|-
| <code>exports</code> || For libraries || Comma-separated Lua module names made available to dependent packages.
|}

Unknown fields are rejected. The entry path must stay within the package and end in <code>.lua</code>. The declared types must exactly match the types registered by the entry file, apart from <code>library</code>, which represents exported modules rather than a registration.

== Example ==
<syntaxhighlight lang="ini">
id=net.example.voice-tools
name=Voice Tools
version=1.3.0
api=1
entry=init.lua
types=audio-addon,library
description=Audio processing tools and a reusable level module.
dependencies=org.example.filters@^2.1.0
exports=level,codec.tone
</syntaxhighlight>

The exported names correspond to <code>level.lua</code> and <code>codec/tone.lua</code>. A package with the <code>library</code> type must export at least one module. A package without that type cannot declare exports.

== Version ranges ==
{| class="wikitable"
! Form !! Meaning for version 1.2.3
|-
| <code>*</code> || Any installed version
|-
| <code>1.2.3</code> || Exactly 1.2.3
|-
| <code>>=1.2.3</code> || 1.2.3 or later
|-
| <code>~1.2.3</code> || At least 1.2.3 but earlier than 1.3.0
|-
| <code>^1.2.3</code> || At least 1.2.3 but earlier than 2.0.0
|}

For a zero-major version, a caret range ends at the next nonzero component. For example, <code>^0.2.3</code> accepts versions below 0.3.0, while <code>^0.0.3</code> accepts versions below 0.0.4.

== Modules and dependencies ==
A package loads one of its own modules with a plain module name:
<syntaxhighlight lang="lua">
local tone = require("codec.tone")
</syntaxhighlight>

A module exported by a declared dependency uses <code>package.id:module</code>:
<syntaxhighlight lang="lua">
local level = require("org.example.filters:level")
</syntaxhighlight>

Cross-package loading succeeds only when the dependency is declared, the installed version satisfies the range, and the other package exports the requested module. Dependency cycles are rejected. The [[Extension catalog]] offers to install missing catalog dependencies before the selected package.

[[Category:Lua extensions]]

Lua extension manifest - Revision history

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