updated 30 May 2008

Python Scripting Language:

Desired Behaviour

Event handlers will be called on input events, itterations, initialisation, collision etc.

Event Handlers

Current event handlers are: | EVENT_INIT | when workstate is loaded | |:------------|:-------------------------| | EVENT_KEYDOWN | when a key is pressed. Multiply by the pygame key constant to specify a key, (should this be changed to passing key as a parameter?) | | EVENT_KEYUP | when a key is pressed. Multiply by the pygame key constant to specify a key, (should this be changed to passing key as a parameter?) | | EVENT_ITERATION | called every frame | | EVENT_LMOUSEUP | left mouse button up on object | | EVENT_RMOUSEUP | right mouse button up event | | EVENT_OFFSCREEN | called when an object if off-screen | | EVENT_TIMER | see gameobject.set_timer() |

Objects

The game object which is having an event called is referred to as self, and is a standard python object. It holds variables/methods and is not the same object which is used internally in the engine (so no worry about scripts setting variables they shouldn't). every game object also has a dict called “vars” for object variables. e.g.

self.vars[“myname”]=myvalue

Game Object Instances

Game objects (the object will normally be named self):

Methods

``` .move_velocity()

moves with velocity vx,xy (which are properties of the object)

.clear()

clears the object with a plain colour

.resize()

resizes the object

.draw_text(string,size=12,colour = (0,0,0))

paints a string on the object

.set_timer(delay,message="")

sets a timer (gamebaker >= 0.1.3)

after [seconds] seconds TIMER_EVENT will be called, with a

local variable timermsg = [message]

```

Properties

.color # RGB background colour (r,g,b) .x .y .vx # x velocity .vy # y velocity .sprite # string, name of the sprite .path # Path object (see below) .workstate # string, name of the workstate

Path instances

These will normally be called self.path

Methods

``` .new_path(style=“linear”)

creates a new path – must be called before using a path

style must be “linear” in 0.2.0

.add_point(x,y)

Adds a point to the path – x and y should be relative

to the gamescreen coordinates

.start_path(speed=None)

places an object at the beginning of a path, and optionally

sets the speed along the path in pixels/second

.set_speed(speed)

Sets the speed along the path in pixels/second

.get_speed()

Gets the speed of an object along a path

.follow_path(loop=False,speed=None,t=None)

Moves an object along a path – do not call move_velocity() afterwards

If loop is True then if the object has reached the end of the path it will

start again from scratch.

If speed is set, it will replace the existing speed

If t is passed, it should be between 0. and 1., and is the distance

along the entire path length.

```

Properties

none

Game Screen Instances

This will normally be called gamescreen

Methods

``` .gameobjects

dict-like

to access a gameobject by name you would enter

gamescreen.gameobjects[“name”]

Do not remove objects direct from here – the object will remain,

but the scripting interface will be removed.

To get the list of names of game objects, use .gameobjects.keys()

.add_object(obj,name)

Adds a new game object to the gamescreen.

“obj” should be the name of a type of game object

“name” should be the name used to refer to this instance of a game object

.remove_object(name)

removes an object from .gameobjects

.check_collisions(name1,name2)

Checks for a collision between two game object instances

You may pass names of gameobjects, or lists of names of objects.

For checking large numbers of collisions, you should use .get_collisions

.get_collisions(obj1,obj2=[])

Returns pairs of game objects that have collided

obj1 and obj2 should be names of game objects, or lists of

names of game objects. All objects are compared with each other.

.move_gamescreen(target,gradual=False,maxspeed=10,acceleration=2)# moves the gamescreen to centre target ( = [x,y] ) on screen.

Set gradual = True and call each frame to move the gamescreen gently

if (gradual == False), then maxspeed and acceleration are not used.

.get_object(name) # Depreciated – set for removal in 0.3.0 # use gamescreen.gameobjects[name] instead

gets a game object instance from the current screen (by name)

```

Properties

.color

Game

Methods

``` .change_game_screen(gs=,savestate=False)

changes the gamescreen, optionally saving the state of the screen and all objects

```

Properties

.score

Implementation

(for those coding game baker itself)

Scripts are called using exec() in the do_event method of RunGameObject (in runtime.py). I don't think we need to secure this much - the finished game will be in python anyway so if someone wants to run malicious code they can just tag it to the end of the game.

We pass two dicts to exec - one for local vars and one for globals, but I suggest we pass all variables as "locals", as properties of objects. This is partly to ensure all variables are mutable, while keeping a local scope that can be garbage collected. If a user needs to optimise and prevent garbage collection between frames they can set variables self.whatever, which will be persistent between frames. (obviously only for the people who already know python, but I was worrying about it myself for storing large levels in script as lists)

Each game object now has a property "scriptvar", which is an instance of "scriptgameobj", and holds methods and properties accessible from scripts.

(have to rush off again, more to come... )