Scripting reference

Previous section < More clients and interfaces

This page fully documents the API that will enable anyone with scripting knowledge to create a script accessing the Theme-O-Matic features in a fully integrated manner.

Scripting knowledge is assumed beyond this point! If you have a specific need just feel free to contact me!

Overview

Modularity has been a concern in designing the Theme-O-Matic. The main T-O-M Core script concentrates on doing theme activation and preloader coordination while featuring a simple API for clients scripts to use. This is done by sending and receiving link_messages.

Another concern was that the Theme-O-Matic scripts have minimal interference with other scripts so that they can coexist peacefully. This requires some message validation.

Message validation

All messages sent by or to the Theme-O-Matic scripts are required to have (key)"T-O-M" as their id (key) parameter. If they don't they will be ignored and client scripts should ignore them too, or at least be aware that they are not Theme-O-Matic-related.

Message formatting

All the messages exchanged by the Theme-O-Matic system use the number (integer) part of the message to specify the message class and the message (string) parameter to pass arguments if required.

Of course since parameters are passed in the message part, they must first be cast to (or from) the string type. We are generally using the newline character (\n in LSL strings) as a separator. It is to be noted that sometimes parameters like Theme_name can be the empty string, so be sure to use llParseStringKeepNulls() and not llParseStringToList() to process them.

Usual parameters

The table below lists all (public) messages you can send to or receive from the Theme-O-Matic. Many of them require parameters:

(string) Theme_name: name of a theme notecard being loaded, applied or just referred to. May be empty sometimes. As of version 3.0 it can also be (generally) be a notecard UUID (caveat).
(integer) line_number: a line number in a notecard, counting from 0. If equal to -1 it means "undefined".
(integer) Preloader_ID: Unique ID of a preloader (starting from 1).
(integer) version: major version number. Currently 3.
(integer) revision: minor revision number. Currently 0.
(integer) status: a status code explained in the message descriptions.
(integer) preloaders: number of active preloaders. Useful if you make a script that adapts to the number of preloaders: their IDs will range from 1 to this value inclusive. This number may be 0 if no preloaders were found (or if their version mismatches the core version number).
(string) LSD_name : the name of an LSD theme.

Message reference

The spreadsheet below lists all (public) messages you can send to or receive from the Theme-O-Matic. Indications on how to use them may be gathered from studying the standard client scripts, of course. In a normal running mode, the matter will be to either apply themes by sending the APPLY command, or preload them with the PRELOAD command and apply them with APPLYPRELOADED.

When your script boots, and depending on the context (whether or nor you use auto-loading), it may be wise to send the RESET command and wait for the READY reply before doing anything else.

Note that to enhance readability you can use the icon to open this table in Google Spreadsheet.

T-O-M Message reference v3.0

What you do with informative messages is up to you. Presenting them to the user in a readable form is probably good practice. Note however that when the CORRUPTED or CORRUPTEDLSD message is issued, some of the theme lines may have already been interpreted and applied, leaving your object in an intermediary state. You were working on a safe copy, weren't you?

More messages are exchanged between the scripts that make up the Theme-O-Matic system. They are private and must not be relied upon. Things have changed there in the past and will continue to change.

Helper scripts

Two small full perm scripts ship to help you diagnose problems with your scripts talking with the Theme-O-Matic, you can find them in the dev folder of the Theme-O-Matic distribution:

T-O-M-DEV Reset will send the RESET (77027) message to the Theme-O-Matic and remove itself from the object's inventory. Useful if you recently added or removed preloaders so that the T-O-M becomes aware of the change ;
T-O-M-DEV Report will display Theme-O-Matic messages in a human-readable form;
T-O-M-DEV Message will help you send a message to the Theme-O-Matic by talking on a private channel (6 is the default), like in the following example:

/6 77000;Theme1