SimTX API v24/Extension catalog protocol
The extension catalog is the server's shared library of Lua extensions and station presets. The official transmitter's catalog browser is built on four requests of the control session, documented here. Users' view of the catalog is described in Extension catalog; the package format is in Lua extension manifest.
Requests[edit | edit source]
| Request | Response | Permission |
|---|---|---|
| CatalogListRequest (20) | CatalogList (24) | None |
| CatalogFetch (21) | CatalogEntry (25) | None |
| CatalogUpload (22) | CatalogUploadResult (21) | catalog.publish
|
| CatalogDelete (26) | CatalogDeleteResult (29) | catalog.publish, owner only
|
All four count as heavy requests for rate limiting.
Browsing works anonymously. Publishing requires an authenticated control session: obtain a game ticket with role control (which itself requires catalog.publish) and present it in the handshake.
Entries[edit | edit source]
A catalog entry has a numeric ID, a kind, a name, an author, a revision number and a set of text files.
| Kind | Content |
|---|---|
extension |
A Lua extension package: an extension.properties manifest and one or more .lua files.
|
preset |
A station preset: exactly one .stxpreset file.
|
Extensions also report their package ID, version, dependencies and types, read from the manifest at upload time.
Ownership and revisions[edit | edit source]
Entry names are unique on a server, compared without regard to case. The account that first publishes a name owns it.
- When the owner uploads an entry with the same name again, the existing entry is replaced: it keeps its ID, its files are replaced, and its revision increases by one. The result message is
Updated. - When another account uploads that name, the upload fails with An item named 'X' already exists (by Author).
- An extension's package ID must also be unique across the catalog and cannot change between revisions.
- Only the owner can delete an entry. There is no protocol-level override.
Typical flows[edit | edit source]
Browsing
- Send CatalogListRequest. Show the entries from CatalogList.
- When the user opens one, send CatalogFetch with its ID and read the files from CatalogEntry.
- Cache files by entry ID and revision; a changed revision in the list means the entry was updated.
Publishing
- Collect the files. For an extension, include
extension.propertiesand every.luafile the manifest refers to. - Send CatalogUpload. Read CatalogUploadResult. On success, it carries the entry ID.
- On failure, show the message to the user. It explains exactly which rule was broken.
Upload rules[edit | edit source]
The server validates every upload. A failure is reported in CatalogUploadResult with ok = false and a message.
| Rule | Limit |
|---|---|
| Kind | extension or preset
|
| Name | 1–64 characters after trimming; unique per server |
| Description | At most 500 characters |
| Categories | At most 12; each 1–32 characters, no commas or control characters; duplicates ignored without regard to case. Categories are free text. |
| Files | 1–64 (a preset: exactly 1) |
| File path | At most 128 characters, relative, / separators only, no empty, . or .. segments, unique without regard to case
|
| File names | Extension: extension.properties or *.lua. Preset: *.stxpreset.
|
| File content | Not blank; at most 60,000 bytes of UTF-8 per file |
| Manifest | Must be valid. See Lua extension manifest. Manifest errors are reported verbatim. |
| Quotas | 32 entries and 64 MiB per author; 512 MiB per server. These are server defaults and may differ. |