Tutorial (Arena Scripting)

Arena Scripting


Sample Arena script

blank.py

import plus
import Arenas

class BlankArena(Arenas.SuperArena):
    "Blank Arena comment."
    name = "Blank Arena"
    preview = "blank/blank_preview.bmp"
    in_list = True
    game_types = ['DEATHMATCH', 'BATTLE ROYAL', 'TEAM MATCH', 'TABLETOP', 'KING OF THE HILL']
    extent = (-15.0, 15.0, 15.0, -15.0)

    def __init__(self):
        plus.Arena.__init__(self, "Arenas/box/boxarena.gmf")

    def Tick(self):
        "Do our stuff here -- called every tickInterval seconds."
        return plus.Arena.Tick(self)

Arenas.register(BlankArena)

Classes

Arena

Class Data

name
display name of this arena (list is sorted by this name)
preview
bitmap preview
in_list
allow this arena to be picked by player
game_types
game types that can be played in this arena
extent
rectangular area of this area
bHazardsOn
are hazards on or off

Functions

RegisterZone(rigid_body_name, callback_index)
Sets up a callback to the arena when the given phantom rigid body is entered or exited.
rigid_body_name: name of the (phantom) rigid body in the GMF file to be used as a zone
callback_index: an integer value supplied to the callback function:
ZoneEvent(self, direction, callback_index, player_index)
[direction = 1 for entering, -1 for exiting]
[player_index = 1-4]

AddPrismatic(base_rigid_body, attachment_rigid_body, x, y, z, start, end)
returns a new prismatic controller
Adds a prismatic controller to the arena.
x, y, z: sliding vector in base's object space
start: starting limit in meters
end: ending limit

GetHinge(name of hinge)
returns a hinge controller

SetSubMaterial(name of body, name of material, damage scalar)
set part of the arena to a different material; use the damage scalar to change its damaging potential
material names: rubber, arenium, metal

SetPinned(name of body, True or False)
pin or unpin this object
SetActive(name of body, True or False)
activate or deactivate this object

AddStaticCamera(name of camera, position, rotation, fov)
name: label for this camera
position: (x, y, z)
rotation: (pitch, yaw)
fov: field of view in radians
AddWatchCamera(name of camera, position, ranges)
ranges: (near distance, far distance, near field of view, far field of view)

ClearCameraBlockers
clears out list of primitives that can block the camera
AddCameraBlocker(name of body)
add primitive to list of objects that block the camera

Events

Tick
Called every Arena-tick-interval seconds.

PrismaticController

SetPowerSettings(max_velocity, gain)
Sets the power settings for the controller.
max_velocity: a velocity the controller will attempt not to exceed
gain: the maximum force the controller will apply at any one time

SetDirection(1 or -1)
Set the direction the controller will attempt to move its attached rigid body.
1 = toward end, -1 = toward start.

ApplyForce(amount)
Apply a force to the attached rigid body in the direction currently set.

Lock(True or False)
When locked, the attached rigid body will not move; unlocked, it is free to move between the controller's limits.

SetAutoLock(True or False)
When AutoLock is on, the controller will attempt to lock the rigid body into one limit or the other, depending on which direction has been set.

HingeController

SetPowerSettings(max_velocity, gain)
Sets the power settings for the controller.
max_velocity: a velocity the controller will attempt not to exceed
gain: the maximum force the controller will apply at any one time

SetDirection(1 or -1)
Set the direction the controller will attempt to move its attached rigid body.
1 = toward end, -1 = toward start.

ApplyTorque(amount)
Apply a torque to the attached rigid body in the direction currently set.

Lock(True or False)
When locked, the attached rigid body will not move; unlocked, it is free to move between the controller's limits.

SetAutoLocks(limit, power) accepts boolean values
Lock the controller when a) a limit is reached and/or b) power is set to zero.

Miscellaneous

describe(player id)
Returns a string with the index # and type for each of this player's components (one per line).

setBackColor(red, green, blue)
Change the background color of the full-screen render area.
All values should be between 0 and 1.

usePower(player id, 0 or 1)
Whether or not a player's bot needs batteries and air tanks or not.

disable(player id, 0 or 1)
Immobilize (or mobilize) this player's robot.

damage(player id, component index, amount of damage)
Applies an amount of damage to a player's component by index number.

getHitpoints(player id, component index)
Returns the number of hitpoints remaining for a player's component (by index number).

getHealth(player id, component index)
Returns the health (0 to 1) for a player's component by index number.

getWeight(player id)
Returns the weight of this player's robot.

getLocation(player id)
Returns tuple (x, y, z) for this player's robot.

getHeading(player id, nose offset)
Returns up-axis heading for this player, with nose offset radians being added to compensate for the BotLab orientation of the chassis.

getDirection(player id, nose offset)
Returns vector pointing in the forward direction for this player's robot (with nose offset radians added to compensate for BotLab orientation of the chassis).

areHazardsOn
Returns true or false depending on existence of hazards.