Object Properties (OP) is a script that streamlines the management of notecard-based configuration settings to be used an object's main script.

Introduction

Opject Properties uses Linkset Data to manage the configuration settings read from a notecard.

From LSL Wiki: "Linksets may store up to 128KiB of data as key/value pairs available to LSL scripts. This data is attached to the root prim in the linkset and survives transfer, script reset and object copying, it does not count against the memory usage of any script."

-- https://wiki.secondlife.com/wiki/Category:LSL_LinksetData

How to use

Save properties

The OP loader script (found inside the box named Scripts Inside: OP Loader script (rez to open)) will scan for changes in the object's inventory and, when a notecard named object-props.ini is detected, the script will read it and store the settings as name spaced properties.

Optional self-destroy

Once the settings from the notecard are stored in the object, the OP loader script op-loader is no longer needed; However, in some cases we want to keep the possibility to read a new notecard with new values.

To handle these possible scenarios we can use a special setting called SSOP_SelfDestroy. If we want the OP loader script to self-destruct after reading the notecard, we will include this setting in the configuration file as follows:

SSOP_SelfDestroy = self destroy

The value must be typed exactly as shown above for this to work. If you want the loader to remain in the object, remove any mention of SSOP_SelfDestroy from the configuration file you ship to your customers.

Use saved properties

The OP loader stores the data in the Linkset Data space using a mechanism that abstracts it from any other data stored in the linkset.

For this reason, this package includes a library called op-lib with all the functions needed to read, update and delete properties. The advantage of using the helper functions from the library is that they handle the properties index thus giving you better control over properties that specifically come from the OP configuration notecard object-properties.ini.

For example:

Check if a property "Color" exists

if (ssOpDataExists("color")) {
    llSay(0, "Color exists");
}

Check if the the value of color is set

string sProp = ssOpRead("color");

if (sProp == NOT_SET) {
    llSay(0, "The property is null");
}

The constant NOT_SET is an empty string so we can only use this technique with string values. If the stored value is supposed to be of some other type such as a number, a vector, etc; you need to implement your own logic to determine if a property has a value considered valid, for example:

integer iSpeed = ssOpReadInteger("speed");

if (iSpeed < 0 || iSpeed > 100) {
  llSay(0, "Invalid speed");
}

Configuration file

The OP loader scans the object's inventory for a file called object-properties.ini. This is the only file that will trigger the loader.

The configuration file is expected to provide settings using a standard INI formatting that goes like this:

PropertyName = value

Organizing the file

For organization and documentation purposes we can divide the properties in sections. Section names are enclosed between [ and ] like this:

[General]

[EngineProperties]

The section names themselves are not stored anywhere in the object.

Special text properties

Object Properties supports a non-standard form to create multi line text values. Here's how we define these properties for OP:

PropertyName = BOT
The text here
in multiple lines

also empty lines are supported.
EOT

We begin by setting the value of the property to BOT which stands for Begin Of Text. Every text between this line and the line having the code EOT - which stands for End Of Text- is considered the value of the property. The codes BOT and EOT are not included in the value.

Ignored lines

The configuration INI file is meant to be human friendly so there are elements that we can include in the file that are ignored during processing.

Comments

Lines having the first character being: ; or # are considered comments.

Empty lines

We can use empty lines to make the file easy to read. All empty lines are discarded EXCEPT those that appear between BOT and EOT. Empty lines between these text delimiters are considered part of the text thus kept as part of the value.

Section names

We mentioned that section names are enclosed between a pair of: [ and ]. The reality is however that only the first one is considered. In other words: Any line having [ as the first character will be ignored, regardless of the ending symbol. Nevertheless, make sure to write name sections with the closing ]. Also instruct your customers to respect the notation when they edit the properties.