The tsxPython Framework
The Basics
Because I will be spending very little time explaining Python syntax, I highly
recommend that you visit http://www.python.org
and download Python 1.5x. After installing, do the excellent tutorial by Guido van Rossum,
inventor of Python. This is where I started and it was an immense help in taking some of
the intimidation out learning Python. This does not provide any trueSpace specific
information, but it lays the foundation for what we will do in this tutorial.
The tsxPython Script Cycle
tsxPython scripts are all attached to an object in the scene, or the Scene object
itself. tsxPython scripts are subroutines that Python executes when the "Run
Scripts" button is clicked, or at load time if the "Autorun" toggle is
selected for that script. In order for a script to run correctly, it must be
"hooked" into one or more of the following: ontimestarted(), ontimechanged()
or ontimestopped().
ontimestarted()
This function is called once when script execution begins. It is useful for setting up
global variables and preconditions for the scene.
ontimechanged()
This where the main content of the script is usually placed. After this function
finishes executing, tsxPython proceeds to the ontimechanged() function for the
next object in the scene. The ontimechanged() functions continue executing in a
loop until ontimestopped() is called or the user presses the "Stop
Scripts" button.
ontimestopped()
This function is called when the "Stop Scripts" button is pressed. This
function can be used for "cleanup" or any other task that needs to be executed
once at the end of the script cycle.
Summary of the Script Cycle
The script cycle looks something like this:
- "Run Scripts" pressed.
- ontimestarted() function executes once for all scripts in the scene, one at a
time.
- ontimechanged() function executes for all scripts in the scene, one at a time
- "Stop Scripts" pressed? If yes, go to Step 5. If no, go back to Step 3.
- ontimestopped() function executes once for all scripts in the scene, one at a
time.
A Simple Example
Open trueSpace. Select "File->Scene->New" to clear out the masterpiece
you've been working on. Click on the ‘Script Editor’ button. The Python Script
Manager should open. The currently selected object will be the ‘Scene’ object.
The ‘Scene’ object is present in all trueSpace 4.x documents and cannot be
deleted. Since its right there in front of us, lets cut and paste the following into the
text editing field:
def
ontimestarted(): #Executed once
for each scene script
doc.ClearOutTxt() #Clear the output window
pass
#Exit this function
def
ontimechanged(): #Executed over
and over until
#'Stop Scripts' is pressed
print 'tsxPython is cool! ' #Send
something to the output field
pass
def ontimestopped(): #Executed once for each scene script
#when 'Stop Scripts' is pressed.
doc.ClearOutTxt() #Clean up the mess
pass
Now press the ‘Run Scripts’ button. To stop this flamboyant display, press
the ‘Stop Scripts’ button. Lets take a minute to dissect this simple script.
Just as predicted, the ontimestarted() function is called only once at the
beginning of the script. The ClearOutTxt() function clears any clutter that might
be in the text window. ClearOutTxt() is built into the trueSpace ‘doc’
object. The ‘doc’ object mostly includes functions that affect the
entire tsxPython environment. In this case, it clears the output text field. It also
should be noted here that the output text field is not unique to each script. All scripts
share this one output text area. Once ontimestarted() finishes (the ‘pass’
statement), the ontimechanged() loop begins. This is executed over and over until
scripts are halted with the ‘Stop Scripts’ button. One quirk that some Python
experts will notice is that tsxPython is much less liberal with newline (‘\n’)
characters than standard python. If you want newline characters in tsxPython, you have to
insert them yourself. When the user gets tired of seeing the simple tsxPython
advertisement and presses the ‘Stop Scripts’ button, the ontimestopped()
function executes. The second ClearOutTxt() cleans up the mess we made in the ontimechanged()
loop.
Moving Forward
In the next installment we'll cover how to manipulate different scene elements in
tsxPython. Until then I strongly recommend reading through the TSXPYTHON.DOC file provided
on the trueSpace 4.x CD-ROM. It contains a comprehensive list of the functions and
attributes available in tsxPython. |
