Latest revision as of 06:18, 26 May 2022

SDL ("State Description Language") is the system that Uru uses to store data about an age in a persistent state.

Introduction

SDL states are essentially used to "save your progress" and also to sync various aspects of the Age for multiplayer. If you leave a door open, the door will still be open when you come back to the age later because its state is stored using SDL. It also tells anyone else coming in to visit the Age that that door should be in the state you left it instead of its default state.

A prominent example of an unsynced state in multiplayer in need of SDL are the doors in the Ahnonay Cathedral. If you Link in, use the doors, then someone else follows, the doors will suddenly appear closed, then open again when the new player uses them while looking perfectly normal on the new player's end. This is because the doors are not using an SDL state to sync it on the server.

Requirements

For an SDL file to work properly, the Age must also have its own Python file named [YourAgeNameHere].py (as in your Age's filename, without the brackets).

When using Korman, this script is automatically generated when you check Age Global SDL in the World panel, under Plasma Settings, so you can safely ignore the rest of this section.

When using PyPRP however, you need to use PlasmaShop to create the file.

A very basic Age py file would look something like this:

from Plasma import *
from PlasmaTypes import *
class [YourAgeNameHere](ptResponder):
    def __init__(self):
        ptResponder.__init__(self)
        self.id = -1
        self.version = 0

Again, for [YourAgeNameHere], simply put your Age's filename in its place (without the brackets).

For offline URU, this py file will need to be packed into the Age's PAK file.

SDL File Structure

A typical SDL file (Ahnonay):

STATEDESC Ahnonay
{
	VERSION 1
	VAR BYTE    ahnyCurrentSphere[1]   DEFAULT=1 
}

STATEDESC Ahnonay
{
	VERSION 2
	VAR BYTE	ahnyCurrentSphere[1]   DEFAULT=0 
	VAR BYTE	ahnyCurrentSaveCloth[2] DEFAULT=0 
}

Note that Ahnonay has more than one STATEDESC block, or version, each containing a version number and a series of variables.

Variables in STATEDESC blocks

Every variable has a type. Possible types are: INT, FLOAT, BOOL, STRING32, PLKEY, CREATABLE, TIME, BYTE, SDL STRUCT, SHORT, AGETIMEOFDAY, VECTOR3, POINT3, QUATERNION, RGB8.

About the Types

• INT: Uses an integer to switch between multiple states.
  • Example: KI Light Machine status in Descent

• FLOAT: To Be Added
• BOOL: Uses True and False values. Usually used for something that only has two states, such as object(s) visibility (true=on and false=off).
  • Example: Museum Linking Books in Ae'gura.

• STRING32: To Be Added
• PLKEY: To Be Added
• CREATABLE: To Be Added
• TIME: To Be Added
• BYTE: Similar to INT in that it uses integers.
  • Example: Which Sphere to Link to in Ahnonay

• SDLSTRUCT: To Be Added
• SHORT: To Be Added
• AGETIMEOFDAY: Used to set aspects of an Age to a day/night cycle, the length of which is determined by the DayLength variable in the Age's AGE file.
• VECTOR3: To Be Added
• POINT3: To Be Added
• QUATERNION: To Be Added
• RGB8: To Be Added

Typically, when you use a Python script in your age that needs an SDL variable, the documentation will tell you what the type should be.

Variables also have a default value, which is the value the variable is set to initially when first entering an Age.

Multiple STATEDESC blocks (versions)

The SDL STATEDESC blocks tell Uru how to store and load the state of an Age, with the Age using the latest version listed.

If you send your Age to someone for testing, or you release your Age, then those people will have the Age's state stored according to the SDL file.

It is important that you try not to change anything drastically in a STATEDESC version that you've already released.

Modifying Existing Blocks

There are, however, a very small number of exceptions to the "do not modify current versions" rule (referenced here). They are:

• Change a BOOL variable to a BYTE and vice-versa.
• Change the DEFAULTOPTION or DISPLAYOPTION.
• Rename (not delete or remove) a variable.

These are the only things you can change in a currently released version! Anything else will likely break the Age's SAV file (offline) and cause problems on a multiplayer shard.

Note that the first two options, when dealing with multiplayer, require the client and server to be resynced.

Adding New Blocks

If you later add states to an SDL file, you must copy the contents of the last version and start a new one with the new values and an incrementally higher VERSION number. For instance, if your Age's SDL file was released with a VERSION 4 at the end, the next VERSION should be VERSION 5.

Offline URU will automatically see the latest version. Online shards will need to be resynced with the newest version of the SDL file in the manifest.

Using SDL in Korman

When using the Korman plugin, you can edit an SDL file directly in Blender's text editor and export it along with the Age's other files.

Simply switch to the Text Editor window and add a new file. Rename it from the default "Text" to [YourAge].SDL. The ".sdl" portion must be included for it to export properly.

In the World panel, where you export, under Plasma Settings, be sure Age Global SDL is checked.

Note that the Age's Python file can also be created here with a new text file named [YourAgeNameHere].py (again, without brackets). This is only necessary if the default script generated when checking Age Global SDL isn't enough for you and needs to be customized. For offline URU, Korman will automatically pack the file into an Age-specific PAK file.