Difference between revisions of "SDL"

(Add some docs on SDL)
 
Line 1: Line 1:
SDL ("State Description Language") is the system that Uru uses to store data about an age in a persistent state. If you leave a door open, the door will still be open when you come back to the age later, because this is stored using SDL. The same happens if you have a kickable object in an age, and the game will remember where you left the object. When you play online, on a [[Shard]], SDL is used to synchronize the state of the age between everybody who's there.
+
SDL ("State Description Language") is the system that Uru uses to store data about an age in a persistent state.
  
Roughly speaking, an SDL file looks as follows:
+
= 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 [[PyPRP:Installing|PyPRP]], you can use [[PlasmaShop]] to create the file. For [[Korman:Installation|Korman]], creating a Python script can be done within Blender's text editor ([[SDL#Using SDL in Korman|see below]])
 +
 
 +
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 looks something like this:
  
 
  STATEDESC Ahnonay
 
  STATEDESC Ahnonay
Line 16: Line 44:
 
  }
 
  }
  
This is one ore more <tt>STATEDESC</tt> blocks, each containing of a version number and a bunch of variables.
+
Note that Ahnonay has more than one <tt>STATEDESC</tt> block, or version, each containing a version number and a series of variables.
  
== Variables in <tt>STATEDESC</tt> blocks ==
+
= Variables in STATEDESC blocks =
 +
 
 +
Every variable has a ''type''. Possible types are: <tt>INT, FLOAT, BOOL, STRING32, PLKEY, CREATABLE, TIME, BYTE, SDL STRUCT, SHORT, AGETIMEOFDAY, VECTOR3, POINT3, QUATERNION, RGB8</tt>.
  
Every variable has a ''type''. Possible types are: INT, FLOAT, BOOL, STRING32, PLKEY, CREATABLE, TIME, BYTE, SDL STRUCT, SHORT, AGETIMEOFDAY, VECTOR3, POINT3, QUATERNION, RGB8.
 
 
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.
 
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.
+
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 <tt>STATEDESC</tt> 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 <tt>STATEDESC</tt> version that you've already released.
 +
 
 +
== Modifying Existing Blocks ==
 +
 
 +
There are, however, a very small number of exceptions to this rule ([https://github.com/H-uru/Plasma/pull/999#discussion_r725592712 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.
 +
 
 +
<blockquote>'''These are the ''only'' things you can change in a currently released version! Anything else could break the Age's SAV file (offline) or cause problems on a multiplayer shard.'''</blockquote>
 +
 
 +
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 =
  
== Multiple <tt>STATEDESC</tt> blocks, and versions ==
+
When using the [[Korman:Installation|Korman]] plugin, you can edit an SDL file directly in Blender's text editor and export it along with the Age's other files.
  
The SDL <tt>STATEDESC</tt> blocks tell Uru how to store and load the state of an age.
+
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.
If you now 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.
+
If you later change the SDL file, there is a big problem: The old state stored on other computers is still using the old SDL! But once you replace the SDL, Uru does not know anymore how to read the old state. It will thus either read total garbage, or notice that something is wrong and be mad at you. (For example, Alcugs Shards will shut down the age immediately.)
+
  
It is this important that you '''never change anything in a <tt>STATEDESC</tt> block that you released'''!
+
In the '''World''' panel, where you [[Korman:Exporting|export]], under '''Plasma Settings''', be sure '''Age Global SDL''' is checked.
  
Instead, if you need to make a change, you ''copy'' the latest block, then you increase the version number.
+
Note that the Age's Python file can also be created here with a new text file named [YourAgeNameHere].py (again, without brackets) and for offline URU, Korman will automatically pack the file into an Age-specific PAK file.
Now you can make all the changes you want, and Uru will still know how to deal with the old state that's out there. Even better, once you ship an updated version of the age, Uru will automatically upgrade the old state to the new one, since it now knows both of their structure.
+

Revision as of 12:34, 10 October 2021

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 PyPRP, you can use PlasmaShop to create the file. For Korman, creating a Python script can be done within Blender's text editor (see below)

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 looks something like this:

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.

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 this 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 could break the Age's SAV file (offline) or 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) and for offline URU, Korman will automatically pack the file into an Age-specific PAK file.