Scripting Manual

The Python Script Engine allows the execution of python scripts. These scripts can be used to influence a GL Studio design in multiple ways, including creating objects, adding code and properties, and changing settings for the GL Studio design. The Python Script extension allows users to create scripts that automate common functions within GL Studio, including creating objects and code, and making changes to GL Studio editor and document settings. These scripts can also be mapped to custom toolbar buttons directly within the GL Studio interface, providing a quick and easy way to enact commonly used scripts.

Examples

A few examples to get you familiar with the scripting API.

Start a New Document

 # import the Editor module
 import Editor
 
 # Create a new Document
 newDoc = Editor.NewDocument()

Create a Basic GLPolygon and Manipulate Groups

 # Import all referenced modules
 import Editor
 import EditorLog
 import GLPolygon
 import Group
 import VertexArray
 import Vertex
 
 # Get the currently open and in focus document
 currentDoc = Editor.GetCurrentDocument()
 
 # Create some vertices to use as the bounds of the GLPolygon
 verts = VertexArray.VertexArray()
 verts.Insert(Vertex.Vertex( 10,  10, 0, 100, 0, 0, 185))
 verts.Insert(Vertex.Vertex(210,  10, 0, 100, 0, 0, 185))
 verts.Insert(Vertex.Vertex(210, 110, 0, 100, 0, 0, 185))
 verts.Insert(Vertex.Vertex( 10, 110, 0, 100, 0, 0, 185))
 
 # Create the GLPolygon, passing in the vertices we just created
 polygon = GLPolygon.GLPolygon(verts)
 polygon.SetPolygonMode( polygon.POLY_MODE_FILLED )
 polygon.SetName('poly')
 
 # Add the new GLPolygon to our current Document
 currentDoc.InsertObject( polygon )
 
 # New in GL Studio 6.0.1. 
 # How to create a Yellow GLPolygon from a Python list of Vertices.
 vertsList = [
     Vertex.Vertex( 50,  50, 0, 200, 220, 0, 255),
     Vertex.Vertex(120,  50, 0, 200, 220, 0, 255),
     Vertex.Vertex(120, 120, 0, 200, 220, 0, 255),
     Vertex.Vertex( 50, 120, 0, 200, 220, 0, 255),
 ]
 
 # Create a polygon and set its fill mode to filled.
 yellowPolygon = GLPolygon.GLPolygon( vertsList )
 yellowPolygon.SetPolygonMode( yellowPolygon.POLY_MODE_FILLED )
 yellowPolygon.SetName('yellow')
 
 currentDoc.InsertObject( yellowPolygon )
 
 # Make a larger polygon and set a location.
 multiPolygon = GLPolygon.GLPolygon([
         Vertex.Vertex( 80,  65, 0,   0,  40,   0,   0),
         Vertex.Vertex( 95,  35, 0,   0,  40,   0,   0),
         Vertex.Vertex(180,  35, 0,   0,  40, 150, 100),
         Vertex.Vertex(195,  65, 0,   0, 255, 150, 100),
         Vertex.Vertex(180, 100, 0, 255,  40, 150, 255),
         Vertex.Vertex( 95, 100, 0,   0,  40,   0,   0),
     ],
     Vertex.Vertex(-130, 0, 0)
 )
 # Fill and outline mode, and turn on Gouraud shading
 multiPolygon.SetPolygonMode( multiPolygon.POLY_MODE_FILL_AND_OUTLINE )
 multiPolygon.SetShadingMode( multiPolygon.SHADING_GOURAUD )
 multiPolygon.SetName('multi')
 
 # Insert a group and add objects to it
 group = Group.Group()
 group.SetName('group')
 currentDoc.InsertObject(group)
 
 # Add an object with no parent doc into the group
 group.InsertObject(multiPolygon)
 
 # Move an object already in the document into the group
 group.MoveObjectToGroup(yellowPolygon)
 
 
 # Find an object in the document by its name
 lookup = currentDoc.GetObjectByName('group') 
 
 # Objects are generally returned as instances of the base class DisplayObject
 EditorLog.PrintInfo( str( type(lookup) ) + ', really a ' + lookup.GetObjectClassName() ) # Prints "<class 'GLPolygon.DisplayObject'>, really a Group"
 
 # Try casting it to other objects that it might be.
 poly  = GLPolygon.CastToGLPolygon(lookup) # Returns None because this is a Group, not a polygon
 group = Group.CastToGroup(lookup)         # Succeeds
 
 EditorLog.PrintInfo(poly.GetName()  if poly  else 'Not a polygon') # Prints "Not a polygon" because the cast failed
 EditorLog.PrintInfo(group.GetName() if group else 'Not a Group')   # Prints "group"
 
 # New in GL Studio 6.2: Iterate over a Group's objects
 for x in group:
     EditorLog.PrintInfo( x.GetName() + ' is in ' + x.GetParent().GetName() )
 
 
 # Define a simple processing function prints some info about the object (used below)
 def Process(prefix, x):
     EditorLog.PrintInfo( '%s.%s: %s' % (prefix, x.GetName(), x.GetObjectClassName()) )
 
 # Recurse into groups for processing
 def PrintNames(group, prefix=''):
     prefix = (prefix + '.' if prefix else '') + group.GetName()
     for x in group:
         Process(prefix, x)
         subgroup = Group.CastToGroup(x)
         if subgroup:
             PrintNames(subgroup, prefix)
             
 PrintNames( currentDoc.GetObjectList() )

Truth Value Checking

 import Editor
 import Vertex
 import VertexArray
 
 # Opening two documents, one new document, and one that doesn't exist
 docExists = Editor.NewDocument()
 nullDoc = Editor.OpenDocument( "nonExistentDoc.gls" )
 
 # Will be True because the document object exists
 if docExists:
     print( "Document exists." )
 
 # Will be considered False since the object is null
 if not nullDoc:
     print( 'Document does not exist' )
 
 # Creating an empty VertexArray
 vertexArray = VertexArray.VertexArray()
 
 # Will be considered False because the array object is empty
 if not vertexArray:
     print( 'The array is empty' )
 
 # Adding a vertex to the array
 vertex = Vertex.Vertex( 0, 0, 0 )
 vertexArray.Insert( vertex )
 
 # Will now be considered True because the array is not empty
 if vertexArray:
     print( 'The array is not empty' )
 
 # Retrieving the document's sound list and adding a sound to it
 soundList = docExists.GetSoundList()
 soundList.AddSound( "someSound.mp3" )
 soundItem = soundList.GetSoundItem( 0 )
 
 # The SoundItem exists as long as it's in the SoundList
 if soundItem:
     print( 'This SoundItem exists' )
 
 # Once the SoundItem is removed, it is considered null, and therefore false
 soundList.RemoveSound( soundItem )
 if not soundItem:
     print( 'This SoundItem no longer exists' )

Additional References

See the GL Studio Users Manual as well as the Cpp Tutorial for more information on Custom Script Buttons and examples.