Arena Logic API

The Arena Logic is a small, secure sub-set of JavaScript used for the following:

  1. Managing the arena timer
  2. Scoring
  3. Programmatic moving/rotation of objects in the arena (experimental)

There is a singleton arena object and then body objects that can be manipulated. You can also define your own variables for use within the arena logic.

This is a simple, low-level API, but can be used to achieve many effects. In the future we may add higher-level object-oriented constructs such as trigger objects, planes etc.

This post will define the arena and body objects.

arena object
The arena object is a singleton (there’s only one of them) global (it’s already defined for you) object.

arena.onReady assign a function which is called when the physics engine is ready to start. No parameters. Use onReady to perform initial setup and configuration.

arena.onPhysics assign a function which is called after every iteration of the physics engine and which takes parameters (time: number, timeStep: number)

  • time is the time in seconds since the start of the mimic execution
  • timeStep is the time in seconds since the last call to onPhysics

onPhysics is called very rapidly and so shouldn’t do any significant processing.

arena.body is a dictionary object containing physics bodies indexed by part ID. The part ID can be set in the Properties Pane (bottom section of the Groups tab). Part IDs can be set by you and must be unique in the arena.

arena.foreachBodyByReference(reference: string, fn: callback) will iterate through all bodies in the arena of a particular reference and call the callback function for each one.

  • reference is the reference (type) of part to look iterate over. It is the Part field of the Properties Pane without the suffix after the period, e.g. ‘GhostGreen’.
  • fn is the callback function. The callback takes a single parameter, the body.

arena.startTimer(length?: number) will start the arena timer. This function should be called in the onReady implementation.

  • length when specified is the length of the timer in seconds and the timer counts down to zero. If no length is specified, then the timer counts up from zero.

arena.addTime(length: number) will add time to an existing timer.

  • length (seconds) to add to existing timer

arena.score(score: number) will set the displayed score.

  • score is the score to display

arena.stop(success: boolean) will stop the run of the mimic

  • success is a boolean (true or false) to indicate if the robot was successful in the task at hand

body object
Body objects represent parts of the arena. You can access them via the arena.body dictionary if you’ve specified IDs on the parts, or via the callback on arena.foreachBodyByReference.

body.setStatic() will make the body static (i.e. it won’t move under gravity or being pushed)

body.setGhost() will make the body a ghost (i.e. it won’t affect other parts physically)

body.getCollisionCount() will return the number of bodies currently colliding with this body.

body.destroy() will remove a body from the mimic environment.

body.isAlive() will return true if destroy hasn’t been called on this body.

body.getPosition() will return the global position of the body as an object (units in mm) {x, y, z}. Where positive y is up.

The following methods are experimental for moving and rotating bodies in the arena

body.setKinematic() will set the body as being moved programatically by the methods below. This will need to be called every onPhysics on the body if you move it.

body.move(x, y, z, vx, vy, vz) will set the body’s position relative to it’s initial position (as defined by the arena editor).

  • x, y, z parameters are the position of the body in mm relative to its initial position.
  • vx, vy, vz parameters are the velocity of the body in mm/s in order that objects touching this one can be correctly moved by the physics engine.

body.rotate(x, y, z, vx, vy, vz) will set the body’s rotation (angle) in space relative to it’s initial rotation.

  • x, y, z parameters are Euler angles (in radians) of the body relative to its initial position.
  • vx, vy, vz parameters are the angular velocities of the body in radians/s in the x, y, z axis.

Arena API questions:

Is there any functionality for the Arena code to access the position of a robot? Ie, I build an IQ mimic and set it to use this arena, but I’d like this arena code to be able to know the location of the robot.

Is there any functionality to be able to create or clone objects from Arena code?

What is the significance of setting an object’s position and velocity? If I’m going to change its position every onPhysics() call, wouldn’t velocity be redundant?

I’m brainstorming ideas where Arena could spawn an object (green ghost perhaps) as a breadcrumb trail where the robot has been.

Thank you for the feedback. There’s currently no way to get the robot position, or to create objects from the arena code. We’ll look into adding that.

A poor substitute for creating objects is to have a number of objects positioned out of the way, and move them in to position when needed.

With regards to body.move the need to set the velocity is so the physics engine can move objects in contact with the body correctly. If you don’t expect objects to be ontop of the body you’re moving, try leaving the velocity as 0,0,0 and see if it behaves correctly.


Thanks for reply. I had thought of the concept of moving off-screen bodies but realized I would have a fixed amount available. But this will work until those features are implemented.

As for robot tracking, my current, clunky idea is to have the arena code define a certain object that students will manually attach to their robots before execution.