TSA Game Object Reference

TSA Game Object Reference

Documentation for the TSA Software Development elective, detailing parts of the tsagame.py game development library. This page includes detailed examples for using the Object features for individual game objects, including user-interface objects like mice, icons and text boxes, and for simulated physics objects such as boxes, characters and platforms.

ob = Object(OBJECTDEF, x, y, handler) – create an object of the type indicated by OBJECTDEF at the location indicated by the x, y positions. The handler is optional.

ob.delete() – delete an object

 

This sample places several random objects using Object(). When the mouse left-clicks on an object, it is deleted:

from tsagame import *

def runcircle(c) :
    if c.ismouseover() and game.ispressing(LEFTBUTTON) :
        c.delete()

def startgame() :
    for n in range(10) :
        Object(CIRCLE, random() * 8, random() * 6, runcircle)

startgame()
game.run()

ob.x, ob.y or ob.getx(), ob.gety() – position

ob.z – overlap order (defaults to 100)

ob.angle – rotation(in degrees)

ob.width, ob.height – size

 

For ICON and TEXTBOX types and other objects set to be non-physics objects, you can set the x/y/angle/width/height directly. For CIRCLE and BOX types and other physics simulation objects, you must use the OBJECTDEF to create the object with an appropriate width/height/density, etc., and you must only move them using move/goto/point/etc. These are functions that use physics to manipulate the objects

This sample shows two objects at different positions and rotations. The green rocket is on top of the blue rocket because the z value is larger (higher.)

from tsagame import *

def startgame() :
    b = Object(ICON, 3, 3)
    b.setimage('bluerocket')
    b.width, b.height = 3, 2
    b.angle = 45
    b.z = 100
    g = Object(ICON, 4, 3)
    g.setimage('greenrocket')
    g.width, g.height = 4, 3
    g.angle = 135
    g.z = 200 

startgame()
game.run()

ob.isflipped – False = right, True = left

Set this to true to reverse the image.

from tsagame import *

def runman(m) :
    m.move(2, game.animate([0, 180], 0.5))
    m.isflipped = game.animate([False, True], 0.5)

def startgame() :
    Object(CHARACTER, 2, 3, runman)

startgame()
game.run()

ob.iscentered – True: x, y refers to center, False: x, y refers to top/left

from tsagame import *

def startgame() :
    b = Object(ICON, 0, 0)
    b.setimage('bluerocket')
    b.iscentered = False
    g = Object(ICON, 0, 0)
    g.setimage('greenrocket')

startgame()
game.run()

ob.isoverlay – False: object stays with board as view moves, True: object stays on screen as board view moves. TEXTBOX objects are set to isoverlay=True by default:

from tsagame import *

MAP = '''
a                   a
a                   a
aaaaaaaaaaaaaaaaaaaaa
'''

def runtext(t) :
    t.settext('distance: %d ' % game.viewx)
    game.viewx += game.persec(1)

def startgame() :
    game.setboard(MAP)
    Object(TEXTBOX, 1, 1, runtext)

startgame()
game.run()

Objects use an image from a file or a piece of text. Physics objects can also be set to use a polygon that matches the physics shape.

 

ob.setimage(‘filename’) – change the image (use None for no image)

ob.setimage(LINECOLOR, FILLCOLOR) – use a polygon for a physics object

ob.setfont(‘fontname’, 0.5) – set the font and size

ob.settext(‘text’, WHITE) – change the image to text and optional color

 

This code demonstrates setting an image using the animate function, and setting a piece of text to tell us which image it is showing. It also shows two polygon objects.

from tsagame import *

def runplayer(m) :
    imagename = game.animate(['blueman1', 'blueman2', 'blueman3', 'blueman4'], 3)
    m.setimage(imagename)
    game.message.settext('Image: ' + imagename)

def startgame() :
    Object(CHARACTER, 4, 3, runplayer)
    game.message = Object(TEXTBOX, 4, 1)
    game.message.setfont('Arial', 0.5)

startgame()
game.run()

ob.ismouseover() returns True/False

You can tell if the mouse is over an object, whether a button is being pressed or not. This allows rollover highlighting:

from tsagame import *

def runcircle(c) :
    if c.ismouseover() :
        c.setimage('bluecircle')
    else :
        c.setimage('redcircle')

def startgame() :
    for n in range(10) :
        Object(CIRCLE, random() * 8, random() * 6, runcircle)

startgame()
game.run()

ob.move(speed, angle, force) – move at max speed m/s in direction indicated by angle accelerating with optional force

ob.moveto(speed, other, force) or (speed, x, y, force)move at max speed m/s towards another object or x, y coordinate, and with optional force

ob.spin(degrees, force)spin at plus or minus degrees per second with optional force

ob.point(angle)instantly rotate to a new angle

ob.pointto(other) or (x, y)rotate to point to something

ob.goto(other) or (x, y) – go instantly to a new position

 

Physics objects should always be moved and rotated with these functions. Note that the force is always optional. If you use no force, the object is instantly set to that velocity. Otherwise, it accelerates toward that velocity as a maximum. For example, move(4, 90, 8) would accelerate an object directly upwards (90 degrees) at 8 meters per second per second, to a maximum speed of 4 meters per second. Here is an example of each type of movement.

The player uses goto to jump instantly to the cursor. The circle uses moveto to follow the mouse at a set velocity. The left/right keys cause the circle to spin left or right. The rocket points at the mouse, and the up arrow causes the rocket to accelerate in the direction it is pointing.

from tsagame import *

def runplayer(p) :
    p.goto(game.mouse)

def runcircle(c) :
    c.moveto(2, game.mouse)
    if game.isholding(LEFT) :
        c.spin(-360)
    elif game.isholding(RIGHT) :
        c.spin(360)

def runrocket(r) :
    r.pointto(game.mouse)
    if game.isholding(UP) :
        r.move(2, r.angle, 2)

def startgame() :
    Object(CHARACTER, 1, 1, runplayer)
    Object(CIRCLE, 5, 1, runcircle)
    Object(ROCKET, 4, 4, runrocket)

startgame()
game.run()

ob.ontile() returns ‘c’ – find out what board tile the center of the object is touching

 

In this variation on a previous example, the player function uses ontile to see if the player is on a tree tile, and if it is, it sets the tree tile to a space, erasing it. (This is the basic principle behind all pac-man style arcade games. Note that the tree tile type must be set to GHOSTTYPE to allow the player to pass through it instead of colliding)

from tsagame import *

MAP = '''
aaaaaaaaaaaa
a          a
a  a    a  a
a          a
a t t t t  a
a  t t t   a
a t t t a  a
a  t t aa  a
a          a
aaaaaaaaaaaa
'''

def runplayer(p) :
    p.moveto(1, game.mouse)
    game.centerview(p)
    if p.ontile() == 't' :
        game.settile(p.x, p.y, ' ')

def startgame() :
    game.player = Object(CHARACTER, 1, 1, runplayer)
    game.setbackground('paper')
    game.settileinfo('a', BLOCKS)
    TREE.type = GHOSTTYPE
    game.settileinfo('t', TREE)
    game.setboard(MAP)

startgame()
game.run()

 

ob.iscolliding(other) – True if the object has just collided with something. Leave other blank to test colliding with the board

ob.istouching(other) – True if the object is still touching something else. Leave other blank to test touching the board

ob.touching – the board tile letter that the object is touching

from tsagame import *

MAP = '''
t      t
t    c t
t      t
t      t
t p    t
aaaaaaaa
'''

def runplayer(p) :
    if game.isholding(LEFT) : p.move(2, 180, 50)
    elif game.isholding(RIGHT) : p.move(2, 0, 50)
    if game.ispressing(UP) and p.istouching() and p.touching == 'a' : 
        p.move(10, 90, 1000)

def runcircle(c) :
    if c.iscolliding() : game.playsound('boing')
    if c.iscolliding(game.player) :
        game.playsound('bonk')

def builder(tile, x, y) :
    if tile == 'p' :
        game.player = Object(CHARACTER, x, y, runplayer)
    elif tile == 'c' :
        CIRCLE.bounce = 1.0
        Object(CIRCLE, x, y, runcircle)

def startgame() :
    game.setgravity(0, 10)
    game.setboardbuilder(builder)
    game.settileinfo('a', BLOCKS)
    game.settileinfo('t', TOWER)
    game.setboard(MAP)

startgame()
game.run()

ob.distanceto(otherobject) or (x, y) returns a number

 

Check how close another object is. This sample will follow the mouse if it’s close by, otherwise it will stop:

from tsagame import *

def runcircle(c) :
    if c.distanceto(game.mouse) < 2 :
        c.moveto(1, game.mouse)
    else :
        c.move(0)

def startgame() :
    Object(CIRCLE, 0, 0, runcircle)

startgame()
game.run()

ob.getclosest(DEF) – return closest object with that definition

 

This sample draws a line between the player and the closest circle. When the player touches that circle, it’s deleted.

from tsagame import *

def runcircle(c) :
    c.move(1, game.animate([0, 90, 180, 270], 0.5))

def runplayer(p) :
    p.goto(game.mouse)
    c = p.getclosest(CIRCLE)
    if c != None :
        game.drawline(p.x, p.y, c.x, c.y, RED)
    if p.iscolliding(c) :
        c.delete()

def startgame() :
    Object(CHARACTER, 0, 0, runplayer)
    for n in range(10) :
        Object(CIRCLE, random() * 8, random() * 6, runcircle)

startgame()
game.run()

ob.isonscreen() – returns True/False

 

It is often a good idea to remove objects if they go off the screen, such as bullets or particles being used for particle effect animations. The easiest way is this:

def runparticle(p) :
    if not p.isonscreen() : p.delete()

Object(PARTICLE, x, y, runparticle)

 

ob.weldto(other, x, y)weld this object to another. They lock together and essentially behave as one object.

from tsagame import *

def runplayer(p) :
    p.moveto(2, game.mouse)

def startgame() :
    player = Object(CHARACTER, 4, 3, runplayer)
    Object(CIRCLE).weldto(player, 0, -1)

startgame()
game.run()

ob.springto(other, x, y, my_x, my_y, 0.5)connect by an invisible spring (0.0 = no flex, 1.0 = very flexible).
One end of the spring will be at x, y on the other object and my_x, my_y of this object. Note that springs allow rotation, but will try to keep two objects at a constant distance from each other.

from tsagame import *

def runplayer(p) :
    p.goto(game.mouse)

def startgame() :
    player = Object(BOX, 4, 3, runplayer)
    CIRCLE.slowing = 1.0
    Object(CIRCLE, 4, 4).springto(player)

startgame()
game.run()

ob.axleto(other, x, y, my_x, my_y, minangle, maxangle) – connect by a freely rotating joint with optional angle limits.

Attach the axle to point x, y of the other object, and through the my_x, my_y point of this object. You can leave the “my” parameters blank to use the center of the current object. Axles can be used for many things, such as freely rotating wheels on a vehicle, the links of a chain, and the min/max angles can be used to limit rotation for things like catapult arms or pinball flippers.

from tsagame import *

def runplayer(p) :
    p.moveto(2, game.mouse)

def startgame() :
    game.setgravity(0, 10)
    player = Object(BOX, 4, 3, runplayer)
    Object(CIRCLE, 4, 4).axleto(player, 0.5, 0.5)
    Object(PLATFORM, 4, 5)

startgame()
game.run()

 

Object definitions:

 

There are a number of built-in object definitions that you can use with little to no customization. Here is a description of these built-ins.

 

User-interface object types:

 

These object types do not interact with the physics world at all, so they do not collide with other objects, nor are they affected by gravity or other forces

MOUSE – there is exactly one mouse object in the game engine. Keep in mind that you can refer to the mouse using game.mouse and can use many of the normal object functions, including things like game.mouse.setimage(‘filename’) to change the mouse pointer graphics

TEXTBOX – A textbox is set to a non-centered overlay object, meaning that if you set it to location 0, 0 it will always show up at the top-left no matter where the map scrolls. This is handy for in-game status displays.

MENUBACK – A large square background for displaying menus or dialogs such as inventory screens.

ICON – A graphic object that is overlayed on top of the game, like a text box, and does not interact with the physics world at all. Use this for on-screen indications of game states such as selected weapons, or in-game controls such as command buttons that can be clicked with the mouse.

 

Physics object types:

 

The following objects all behave according to physics rules. By default, they all collide with each other and with the game board and are affected by gravity. Unless otherwise noted, they are all 1 meter on a side.

 

CIRCLE – A basic circle object. There are a variety of colored circle images that can be substituted for the red one.

BOX – A basic square object. Note that changing the initial width/height to different values can turn it into a rectangle. A gray square is the default image.

TRIANGLE – An isosceles triangle of base 1 and height 1 (not equilateral.)

TRAPEZOID – A gray trapezoid with a top approximately 2/3 the width of the bottom.

CHARACTER – The template for a human-shaped character object. It is taller than it is wide and has the rotation locked so that it cannot fall over. It also has no bounce so that it will stay in contact with the ground when it lands to avoid control problems with players trying to jump, for example, while the character has just bounced off the ground and would no longer be touching it if it had any bounce.

ROCKET – The template for a top-down object. This object also has a custom shape which generally fits the image, with a wide base and center and a narrowed top.

BULLET – A bullet image, with a custom shape to create a pointed tip. It is also set to be extremely small, and with the “isfast” collision flag turned on to make sure very fast bullets do not pass through objects.

PLATFORM – An extra-wide, but thin, object with a wood texture. It is also locked in place so that it will interact with physical objects without being affected by them. Players dropping on it will not knock it out of place, and it is not affected by gravity. It is still possible to move it manually to create rotating or moving platforms, elevators, etc.

RAMPLEFT, RAMPLEFTLOW, RAMPLEFTHIGH, RAMPRIGHT, RAMPRIGHTLOW, RAMPRIGHTHIGH – A series of ramp shapes that can be used with tile-based maps to create slopes. If smooth curved slopes are needed, don’t use these. It is possible to write custom code to create object shapes on the fly to accomplish this.

 

Note that any of these object types can be extended by using the “copy” command:


SUPERBALL = copy(CIRCLE)

SUPERBALL.image = ‘bluecircle’

SUPERBALL.bounce = 0.8

SUPERBALL.width = SUPERBALL.height = 0.2


If you add this definition at the beginning of your program, you will be making a copy of everything about a CIRCLE object, but changing just the image, how much it bounces, and the width. Everything else will be the same, such as the shape, friction, density, etc. You can then use Object(SUPERBALL) to create one of these custom versions.

 

You can also change the definitions themselves in your program, but be aware that changes it permanently for the rest of your program. The following line would cause all future CIRCLE objects in your program to be green:

 

CIRCLE.image = ‘greencircle’

Object definition parameters:

 

Here is a list of all of the parameters that can be changed with any object. You should always start by copying a default item, such as BOX, then applying changes to any of the following parameters. All of the parameters shown here will be the default values that BOX already has, and which all built-in objects have unless otherwise described.

 

DEF = copy(BOX)

DEF.image = ‘square’ (or .image = (BLACK, RED) to use a drawn polygon)

DEF.shape = BOXSHAPE (or .shape = CIRCLESHAPE or a list of points in clockwise order, such as .shape = [(0, -0.5), (0.5, 0.5), (-0.5, 0.5)] noting that points should always be between -0.5 and 0.5 since they’re relative to the size of the object, which is centered.)

DEF.isflipped = False – (set True to reverse the image and shape left-to-right.)

DEF.width = 1.0 – initial width of the object

DEF.height = 1.0 – initial height of the object

DEF.depth = 100 – initial z-order of the object

DEF.angle = 0 – initial angle of the object. Rockets, for example usually start pointing straight up, so the ROCKET object initializes to 90 degrees by default.

DEF.density = 1.0 – kilogram per square meter. This will significantly affect collisions and other physics-related interactions such as actions on a lever.

DEF.bounce = 0.3 – how much does the object bounce? 1.0 is perfectly elastic. 0.0 has no elasticity at all. Bounce greater than 1.0 can be used for objects that are intended to add energy during a collision.

DEF.friction = 0.5 – The coefficient of friction. 1.0 would be like glue. 0.0 would be frictionless. Try to avoid these extremes for better realism.

DEF.slowing = 0.0 – meters per second per second of drag. Use this for top-down games to represent friction, air resistance, etc., for games such as billiards, croquet, etc., to slow down the balls or for racing games to slow down the cars when they’re not accelerating.

DEF.spinslowing = 0 – degrees per second per second of rotational drag. Use any time an object should slow down its spin when forces are not acting on it.

DEF.isfast = False – Set to True for objects that are moving fast enough for them to completely pass through other objects between animation frames, such as bullets or characters in distance achievement games.

DEF.isturnable = True – Set to False to lock the angle of the image. Use for characters in platformers, for example, so that they can’t simply fall over if standing on something, such as the edge of a platform.

DEF.isoverlay = False – Set to True to separate object from the board motion so that the object stays in a location relative to the screen instead. Use for menus/text/icons, etc.

DEF.type = 1 – use values 1-15 for physical objects, 16 and up for visual-only objects that should not interact with the physics world.

DEF.collidetypes = [0, 1] – a list of types that this object collides with. Note that object type 0 is the game board.

 

Note that if either type is set to collide with another, the collision will happen. If objects are going to pass through each other, they must agree on that.

Example 1: An object A of type 3 is set to collide with [0, 1, 5, 6] and an object B of type 4 is set to collide with [0, 1, 5, 7]. A doesn’t collide with 4, and B doesn’t collide with 3, so neither one collides with each other and they simply pass through each other.

Example 2: An object A of type 3 is set to collide with [0, 1, 5] and an object B of type 4 is set to collide with [0, 1, 3, 7]. A and B will still collide, even though A is set not to collide with objects of type 4 (like B) because B is set to collide with objects of type 3 (like A.)

Use this feature when manipulating objects that are only supposed to collide under certain circumstances. For example, if you create rockets inside a launcher object which is being held by a player, and they are supposed to emerge from the barrel, then the rocket object should definitely not be able to collide with the player or with the launcher, but it definitely should be able to collide with the other characters in the game.

 

css.php