Python Script Engine  7.1
GL Studio Editor Python Script API
Python Script Engine API Reference Index

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

1 # import the Editor module
2 import Editor
3 
4 # Create a new Document
5 newDoc = Editor.NewDocument()

Create a Basic GLPolygon and Manipulate Groups

1 # Import all referenced modules
2 import Editor
3 import EditorLog
4 import GLPolygon
5 import Group
6 import VertexArray
7 import Vertex
8 
9 # Get the currently open and in focus document
10 currentDoc = Editor.GetCurrentDocument()
11 
12 # Create some vertices to use as the bounds of the GLPolygon
14 verts.Insert(Vertex.Vertex( 10, 10, 0, 100, 0, 0, 185))
15 verts.Insert(Vertex.Vertex(210, 10, 0, 100, 0, 0, 185))
16 verts.Insert(Vertex.Vertex(210, 110, 0, 100, 0, 0, 185))
17 verts.Insert(Vertex.Vertex( 10, 110, 0, 100, 0, 0, 185))
18 
19 # Create the GLPolygon, passing in the vertices we just created
20 polygon = GLPolygon.GLPolygon(verts)
21 polygon.SetPolygonMode( polygon.POLY_MODE_FILLED )
22 polygon.SetName('poly')
23 
24 # Add the new GLPolygon to our current Document
25 currentDoc.InsertObject( polygon )
26 
27 # New in GL Studio 6.0.1.
28 # How to create a Yellow GLPolygon from a Python list of Vertices.
29 vertsList = [
30  Vertex.Vertex( 50, 50, 0, 200, 220, 0, 255),
31  Vertex.Vertex(120, 50, 0, 200, 220, 0, 255),
32  Vertex.Vertex(120, 120, 0, 200, 220, 0, 255),
33  Vertex.Vertex( 50, 120, 0, 200, 220, 0, 255),
34 ]
35 
36 # Create a polygon and set its fill mode to filled.
37 yellowPolygon = GLPolygon.GLPolygon( vertsList )
38 yellowPolygon.SetPolygonMode( yellowPolygon.POLY_MODE_FILLED )
39 yellowPolygon.SetName('yellow')
40 
41 currentDoc.InsertObject( yellowPolygon )
42 
43 # Make a larger polygon and set a location.
44 multiPolygon = GLPolygon.GLPolygon([
45  Vertex.Vertex( 80, 65, 0, 0, 40, 0, 0),
46  Vertex.Vertex( 95, 35, 0, 0, 40, 0, 0),
47  Vertex.Vertex(180, 35, 0, 0, 40, 150, 100),
48  Vertex.Vertex(195, 65, 0, 0, 255, 150, 100),
49  Vertex.Vertex(180, 100, 0, 255, 40, 150, 255),
50  Vertex.Vertex( 95, 100, 0, 0, 40, 0, 0),
51  ],
52  Vertex.Vertex(-130, 0, 0)
53 )
54 # Fill and outline mode, and turn on Gouraud shading
55 multiPolygon.SetPolygonMode( multiPolygon.POLY_MODE_FILL_AND_OUTLINE )
56 multiPolygon.SetShadingMode( multiPolygon.SHADING_GOURAUD )
57 multiPolygon.SetName('multi')
58 
59 # Insert a group and add objects to it
60 group = Group.Group()
61 group.SetName('group')
62 currentDoc.InsertObject(group)
63 
64 # Add an object with no parent doc into the group
65 group.InsertObject(multiPolygon)
66 
67 # Move an object already in the document into the group
68 group.MoveObjectToGroup(yellowPolygon)
69 
70 
71 # Find an object in the document by its name
72 lookup = currentDoc.GetObjectByName('group')
73 
74 # Objects are generally returned as instances of the base class DisplayObject
75 EditorLog.PrintInfo( str( type(lookup) ) + ', really a ' + lookup.GetObjectClassName() ) # Prints "<class 'GLPolygon.DisplayObject'>, really a Group"
76 
77 # Try casting it to other objects that it might be.
78 poly = GLPolygon.CastToGLPolygon(lookup) # Returns None because this is a Group, not a polygon
79 group = Group.CastToGroup(lookup) # Succeeds
80 
81 EditorLog.PrintInfo(poly.GetName() if poly else 'Not a polygon') # Prints "Not a polygon" because the cast failed
82 EditorLog.PrintInfo(group.GetName() if group else 'Not a Group') # Prints "group"
83 
84 # New in GL Studio 6.2: Iterate over a Group's objects
85 for x in group:
86  EditorLog.PrintInfo( x.GetName() + ' is in ' + x.GetParent().GetName() )
87 
88 
89 # Define a simple processing function prints some info about the object (used below)
90 def Process(prefix, x):
91  EditorLog.PrintInfo( '%s.%s: %s' % (prefix, x.GetName(), x.GetObjectClassName()) )
92 
93 # Recurse into groups for processing
94 def PrintNames(group, prefix=''):
95  prefix = (prefix + '.' if prefix else '') + group.GetName()
96  for x in group:
97  Process(prefix, x)
98  subgroup = Group.CastToGroup(x)
99  if subgroup:
100  PrintNames(subgroup, prefix)
101 
102 PrintNames( currentDoc.GetObjectList() )

Truth Value Checking

1 import Editor
2 import Vertex
3 import VertexArray
4 
5 # Opening two documents, one new document, and one that doesn't exist
6 docExists = Editor.NewDocument()
7 nullDoc = Editor.OpenDocument( "nonExistentDoc.gls" )
8 
9 # Will be True because the document object exists
10 if docExists:
11  print( "Document exists." )
12 
13 # Will be considered False since the object is null
14 if not nullDoc:
15  print( 'Document does not exist' )
16 
17 # Creating an empty VertexArray
18 vertexArray = VertexArray.VertexArray()
19 
20 # Will be considered False because the array object is empty
21 if not vertexArray:
22  print( 'The array is empty' )
23 
24 # Adding a vertex to the array
25 vertex = Vertex.Vertex( 0, 0, 0 )
26 vertexArray.Insert( vertex )
27 
28 # Will now be considered True because the array is not empty
29 if vertexArray:
30  print( 'The array is not empty' )
31 
32 # Retrieving the document's sound list and adding a sound to it
33 soundList = docExists.GetSoundList()
34 soundList.AddSound( "someSound.mp3" )
35 soundItem = soundList.GetSoundItem( 0 )
36 
37 # The SoundItem exists as long as it's in the SoundList
38 if soundItem:
39  print( 'This SoundItem exists' )
40 
41 # Once the SoundItem is removed, it is considered null, and therefore false
42 soundList.RemoveSound( soundItem )
43 if not soundItem:
44  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.