SimTX API v24/Extension catalog protocol - Revision history

Clanker: Archive the v24 protocol reference: use the v24 templates, links and categories

2026-10-24T16:13:40Z

Archive the v24 protocol reference: use the v24 templates, links and categories

← Older revision		Revision as of 16:13, 24 October 2026
Line 1:		Line 1:
	{{SimTX API navigation}}		{{SimTX API v24 navigation}}
	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 [[SimTX API/Control session\|control session]], documented here. Users' view of the catalog is described in [[Extension catalog]]; the package format is in [[Lua extension manifest]].		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 [[SimTX API v24/Control session\|control session]], documented here. Users' view of the catalog is described in [[Extension catalog]]; the package format is in [[Lua extension manifest]].

	== Requests ==		== Requests ==
Line 6:		Line 6:
	! Request !! Response !! Permission		! Request !! Response !! Permission
	\|-		\|-
	\| [[SimTX API/Packets/CatalogListRequest\|CatalogListRequest]] (20) \|\| [[SimTX API/Packets/CatalogList\|CatalogList]] (24) \|\| None		\| [[SimTX API v24/Packets/CatalogListRequest\|CatalogListRequest]] (20) \|\| [[SimTX API v24/Packets/CatalogList\|CatalogList]] (24) \|\| None
	\|-		\|-
	\| [[SimTX API/Packets/CatalogFetch\|CatalogFetch]] (21) \|\| [[SimTX API/Packets/CatalogEntry\|CatalogEntry]] (25) \|\| None		\| [[SimTX API v24/Packets/CatalogFetch\|CatalogFetch]] (21) \|\| [[SimTX API v24/Packets/CatalogEntry\|CatalogEntry]] (25) \|\| None
	\|-		\|-
	\| [[SimTX API/Packets/CatalogUpload\|CatalogUpload]] (22) \|\| [[SimTX API/Packets/CatalogUploadResult\|CatalogUploadResult]] (21) \|\| <code>catalog.publish</code>		\| [[SimTX API v24/Packets/CatalogUpload\|CatalogUpload]] (22) \|\| [[SimTX API v24/Packets/CatalogUploadResult\|CatalogUploadResult]] (21) \|\| <code>catalog.publish</code>
	\|-		\|-
	\| [[SimTX API/Packets/CatalogDelete\|CatalogDelete]] (26) \|\| [[SimTX API/Packets/CatalogDeleteResult\|CatalogDeleteResult]] (29) \|\| <code>catalog.publish</code>, owner only		\| [[SimTX API v24/Packets/CatalogDelete\|CatalogDelete]] (26) \|\| [[SimTX API v24/Packets/CatalogDeleteResult\|CatalogDeleteResult]] (29) \|\| <code>catalog.publish</code>, owner only
	\|}		\|}

	All four count as heavy requests for [[SimTX API/Control session#Rate limits\|rate limiting]].		All four count as heavy requests for [[SimTX API v24/Control session#Rate limits\|rate limiting]].

	Browsing works anonymously. Publishing requires an authenticated control session: obtain a [[SimTX API/Game tickets\|game ticket]] with role <code>control</code> (which itself requires <code>catalog.publish</code>) and present it in the handshake.		Browsing works anonymously. Publishing requires an authenticated control session: obtain a [[SimTX API v24/Game tickets\|game ticket]] with role <code>control</code> (which itself requires <code>catalog.publish</code>) and present it in the handshake.

	== Entries ==		== Entries ==
Line 30:		Line 30:
	\|}		\|}

	Extensions also report their package ID, version, dependencies and [[SimTX API/Packets/CatalogList#Catalog types\|types]], read from the manifest at upload time.		Extensions also report their package ID, version, dependencies and [[SimTX API v24/Packets/CatalogList#Catalog types\|types]], read from the manifest at upload time.

	=== Ownership and revisions ===		=== Ownership and revisions ===
Line 51:		Line 51:

	== Upload rules ==		== Upload rules ==
	The server validates every upload. A failure is reported in [[SimTX API/Packets/CatalogUploadResult\|CatalogUploadResult]] with <code>ok = false</code> and a message.		The server validates every upload. A failure is reported in [[SimTX API v24/Packets/CatalogUploadResult\|CatalogUploadResult]] with <code>ok = false</code> and a message.

	{\| class="wikitable"		{\| class="wikitable"
Line 77:		Line 77:
	\|}		\|}

	{{SimTX API navbox}}		{{SimTX API v24 navbox}}
	[[Category:SimTX API]]		[[Category:SimTX API v24]]
	[[Category:SimTX API sessions]]		[[Category:SimTX API v24 sessions]]

Clanker: Clanker moved page SimTX API/Extension catalog protocol to SimTX API v24/Extension catalog protocol: Archive the v24 protocol reference

2026-10-24T16:12:28Z

Clanker moved page SimTX API/Extension catalog protocol to SimTX API v24/Extension catalog protocol: Archive the v24 protocol reference

← Older revision	Revision as of 16:12, 24 October 2026
(No difference)

Clanker: SimTX API documentation

2026-10-24T09:56:42Z

SimTX API documentation

New page

{{SimTX API navigation}}
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 [[SimTX API/Control session|control session]], documented here. Users' view of the catalog is described in [[Extension catalog]]; the package format is in [[Lua extension manifest]].

== Requests ==
{| class="wikitable"
! Request !! Response !! Permission
|-
| [[SimTX API/Packets/CatalogListRequest|CatalogListRequest]] (20) || [[SimTX API/Packets/CatalogList|CatalogList]] (24) || None
|-
| [[SimTX API/Packets/CatalogFetch|CatalogFetch]] (21) || [[SimTX API/Packets/CatalogEntry|CatalogEntry]] (25) || None
|-
| [[SimTX API/Packets/CatalogUpload|CatalogUpload]] (22) || [[SimTX API/Packets/CatalogUploadResult|CatalogUploadResult]] (21) || <code>catalog.publish</code>
|-
| [[SimTX API/Packets/CatalogDelete|CatalogDelete]] (26) || [[SimTX API/Packets/CatalogDeleteResult|CatalogDeleteResult]] (29) || <code>catalog.publish</code>, owner only
|}

All four count as heavy requests for [[SimTX API/Control session#Rate limits|rate limiting]].

Browsing works anonymously. Publishing requires an authenticated control session: obtain a [[SimTX API/Game tickets|game ticket]] with role <code>control</code> (which itself requires <code>catalog.publish</code>) and present it in the handshake.

== Entries ==
A catalog entry has a numeric ID, a '''kind''', a name, an author, a revision number and a set of text files.

{| class="wikitable"
! Kind !! Content
|-
| <code>extension</code> || A Lua extension package: an <code>extension.properties</code> manifest and one or more <code>.lua</code> files.
|-
| <code>preset</code> || A station preset: exactly one <code>.stxpreset</code> file.
|}

Extensions also report their package ID, version, dependencies and [[SimTX API/Packets/CatalogList#Catalog types|types]], read from the manifest at upload time.

=== Ownership and revisions ===
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 <code>Updated</code>.
* 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 ==
'''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 <code>extension.properties</code> and every <code>.lua</code> file 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 ==
The server validates every upload. A failure is reported in [[SimTX API/Packets/CatalogUploadResult|CatalogUploadResult]] with <code>ok = false</code> and a message.

{| class="wikitable"
! Rule !! Limit
|-
| Kind || <code>extension</code> or <code>preset</code>
|-
| 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, <code>/</code> separators only, no empty, <code>.</code> or <code>..</code> segments, unique without regard to case
|-
| File names || Extension: <code>extension.properties</code> or <code>*.lua</code>. Preset: <code>*.stxpreset</code>.
|-
| 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.
|}

{{SimTX API navbox}}
[[Category:SimTX API]]
[[Category:SimTX API sessions]]