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.