Guild of Writers

I think SDL and Python are an important part in creating an interesting and interactive age. However, I found it very hard to find a comprehensive workflow for incorporating and using SDL and Python in an age. Some Wiki articles are old and deprecated. Others only mention parts of the process.

Here's what I've figured out so far (please correct me if some of these points are incorrect):
-Basically every age has an SDL file which stores the (default and current) states of variables of the age (for example which door is open or which buttons have been pushed)
-Every age also has a python file which can read and write the SDL variables and set the corresponding reactions in the age (e.g. if the player clicks on a button then play an animation and set an SDL variable to a new value)
-PlasmaShop can be used to create python and SDL files (is this still the program that's used by age creators?)
-plasma files need to be packed into pak files which can also be done with PlasmaShop
-the pak file (or the python file?) has to be attached to an object in your age and must be set to global so that it can have an effect on the age

I think I'll be able to create a general python file for my age and put it into a pak file as described in this tutorial: Andylegate's Tutorial on Python Files

So what I'm looking for right now is an overview over the many functions that you can use inside a python file.
I'd like to start out simple: there's a moving platform which is animated to move from left to right or vice versa. There's also a button which triggers the movement. So far I think this could also be achieved with the Plasma plugin in 3D Max. However, I'd like to have an SDL variable which stores the state of the platform so that it is remembered when I leave the age and come back later.

Any help or links to tutorials on the subject would be greatly appreciated

You are correct on what the SDL files do.
Every Age does have a python file component attached to it for the AgeSDLHook, correct (that is, Ages that are interactive. "Garden" type ages, where there is no interaction technically do not need this).

I use PlasmaShop, but there are other things out there.

Python files must be put into a .pak file if your Age is going to be used with Stand Alone Uru (Uru:CC), or on ALCUG type shards. For MOUL or MOSS your python files are not packed into a .pak file.
SDL files for MOUL and MOSS use a different format than for Stand Alone and ALCUGS.

Many things for interaction, the python files for are already there, and you do not need to make them or edit them (all the "global" python files, the ones who's name have the little "x" in front of them). You can use these to set states in the SDL file, use them to respond or react depending upon those states.

A good example is a door let's say. You would attach a python component to like the door button, and use the xAgeSDLBoolToggle.py file as your python. In your SDL file for that Age, you have a state line that looks like this:

Code: Select all

    VAR BOOL    neolOfficeDoor[1] DEFAULT=0

In Max, when you pick the xAgeSDLBoolToggle.py file, the roll out for it will have a text box where you would put the name in the code I just showed: "neolOfficeDoor"
There will be a button that is asking you what the Activator is. When you click on it, it will open up a window of your Helpers. You want to pick the clickable for the button (or region detector if that is what you are using).

What this does is, when the player clicks on that button to open the door, the value of the SDL will be changed from 0 to 1.

Now you need to attach a 2nd python file, this one is xAgeSDLBoolResponder.py
It's roll out will have a text box too, and again, you put the name of the SDL varible: "neolOfficeDoor"
You'll have 2 buttons now, asking you what responders to run, one responder for a True state, and another responder for a False state.

You can do this 2 ways: have 2 different responders (one that opens the door, and one that closes the door), or you can have a single responder, but with 2 States, one state that opens the door, and one that closes the door.

Make sure that when you use this python file, that in it's roll out you put check marks where it says:

F-Forward on Init

(Edited to reflect what D'Lanor said as he is correct)

Now what this does is, one player is in your age and opens up the door.
2nd player links in, and the door will already be open for them. If they click on the button, the door will close, if the first player had linked out, when they link back in, they'll find the door closed again.

This is just one example (there's another way to do this with xStandardDoor.py), and there are many, many ways you can do interactive, multiplayer things with your Age, just using the existing global Python files, without having to resort to making a custom python file for your Age.
There will be cases where you will need to do that however.

andylegate wrote:Make sure that when you use this python file, that in it's roll out you put check marks where it says:

F-Forward On VM
F-Forward on Init
Init SDL On First Update

Now what this does is, one player is in your age and opens up the door.
2nd player links in, and the door will already be open for them. If they click on the button, the door will close, if the first player had linked out, when they link back in, they'll find the door closed again.

Only "F-Forward on Init" should be checked for that.

"Init SDL On First Update" is for prp files that are not loaded initially at link in but are paged in later. It should be off for normal prp files. If you check this for normal prp files Python will execute the initialization code twice. Not really a problem but still a bit of a waste.

"F-Forward On VM" determines how your responder event is handled when a shard administrator manually toggles the SDL variable in the vault. Fan ages normally don't depend on this so it does not matter whether this is checked or not. Cyan however often uses this as the ONLY way to trigger an event. In that case it should NOT have "F-Forward On VM" checked because that makes the event go by mostly unnoticed. And that would be a lot of hard work for nothing...

Thank you very much for the information. Andy your tutorials are a great help as always.

I think I get the bigger picture. Now for the details. In PlasmaShop I've created a new python file and added the "dummy" age code from your tutorial. I changed the important lines and saved it as "testage.py" in my URU CC installation path (subfolder: Python/src).
What next? When I opened the python.pak file and wanted to add the testage.py it started to decompress all the files in the pak file which I thought was wrong. So I interrupted the process and now the python.pak file only consists of the first few files and the rest are gone.

Could you please describe to me which files (py, pyc, pak, sdl) I have to copy where in order to use them when building my age.

never repack the python.pak file.

You should create a new .pak file with the name of the age you are making, and put custom made python files in there.

Take the custom made python file, testage.py and put it in a folder called "python" in your plasma export folder. Then it should show up in max (you'll have to restart max when you do this).

I'm working my way through your instructions and a few questions have come up (because it's not working yet )

EDIT: Added answers from what I found out

-Does the SDL file also have to be in Max's export directory? (YES)
-Do I also have to add the SDL file somehow to one of the objects in my scene? (NO)
-Do the responder(s) which "xAgeSDLBoolResponder.py" refers to also have to be linked to the clickable object? (NO, the "detector" field can be left empty)

I've finished my first small project using Python and SDL.
The resulting 3D Max file can be found in THIS THREAD.
Thanks a lot D'Lanor and Andylegate for your help.

Of course this project made me want to explore Python in more detail. So, is there something like an overview of what the different Python functions do?
I mean, Andylegate ... where did you get all your Python knowledge from? From trial and error and looking at the existing files?

An excellent Python openbook (online, and in german language) can be found here:
http://openbook.galileocomputing.de/python/

The Plasma Python API in the WIKI:
http://www.guildofwriters.com/wiki/Plasma_Python_API

Okay ... that's a lot of functions Thanks for the link

By the way, I've come across this word quite often now, yet I have no idea what it means: "the vault".

The vault is a database that stores anything from age progress to clothing outfits. In offline Uru, the vault is stored in a binary file on your computer.* However, in online Uru the vault is stored on the server.