Skip to main content
Join the official 2020 Python Developers SurveyStart the survey!

Draw objects in the ARENA using Python!

Project description

ARENA Py - Python Examples

Draw objects in the ARENA using Python.

Install package using pip:

pip3 install arena-py


cd examples

(view results at

import arena
arena.init("", "realm", "hello")
arena.handle_events() library

The above is the simplest example of an ARENA Python program. This library sits above the ARENA pub/sub MQTT message protocol: JSON messages described in more detail at which runs in a browser. That forms a layer, in turn, on top of A-Frame and THREE.js javascript libraries.

Here is a breakdown of the currently available functions


The init function takes 3 string positional arguments, and 2 optional arguments in order:

  • the DNS name of a pub/sub MQTT broker (currently Mosquitto v1.6.3, which runs the v3.1.1 protocol)
  • realm, currently the fixed string "realm" to indicate hierarchy level
  • scene name, a string
  • callback - a callback function to be called when ARENA network events are received. The function is passed a string argument, the network message, a JSON encoded string. (See below for more callback information)
  • port - a numerical port to connect if MQTT is running on a nonstandard port e.g. 3003 These are composed together to form an MQTT topic, in the example, "realm/s/hello". A successful init results in a connection with the MQTT server, ready to send and receive messages.

Object (create method)

Object takes multiple optional arguments and on success creates in the scene and returns a Python ARENA object. Accepted arguments are:

  • objName - Object name, a string. Object names should be unique within a scene
  • objType - an arena.objType enum from the set
    • cube
    • sphere
    • circle
    • cone
    • cylinder
    • dodecahedron
    • icosahedron
    • tetrahedron
    • octahedron
    • plane
    • ring
    • torus
    • torusKnot
    • triangle
    • gltf-model (see for more details on GLTF format 3D models)
    • line
    • thickline
    • text
    • image
    • particle
    • light
  • location - a triple (x, y, z) coordinate in meters
  • rotation - a quad (x, y, z, w) rotation in quaternions
  • scale - a triple scaling factor in 3 dimensions
  • color - a triple RGB color where each component is in the range 0-255
  • persist - a boolean indicating whether to persist the created ARENA object to a database, such that it is visible when revisiting a scene. If False, the object will still be visible to everyone currently viewing the scene, but go away upon reload.
  • ttl - an integer for time to live, in seconds. objects will self-delete after this many seconds, and will not be persisted
  • parent - a string object name; sets this object to be one of possibly several children of the parent object with this objId
  • physics - an arena.Physics enum from
    • none - object remains fixed in place and does not interact with other physical objects
    • static - object remains fixed in place but DOES interact with other physical objects (collision, bounce off, etc.) Updates to the object's position can change it's location
    • dynamic - object roughly follows rough laws of gravity, and interacts with other physical objects. Updates to the object's position will not change it's location; it is under the control of physics engines, which are not consistent across multiple browsers viewing the scene
  • clickable - a boolean indicating whether the object has a click-listener component, allowing it to receive events from the arena.Event enum:
    • mousedown
    • mouseup
    • mouseenter
    • mouseleave
  • url - some objects use this parameter to refer to, e.g. a bitmap image, GLTF model, or web URL. See:
  • data - accepts arbitrary JSON data to specify additional attribute-value pairs not specified above to be added to the object's A-Frame entity; see A-Frame and ARENA-core documentation for more detail. An example of a somewhat fancy data message would look like
    data='{"impulse": {"on": "mouseup","force":"0 40 0","position":"10 1 1"},"material": {"color":"(0, 255, 0)", "transparent": false, "opacity": 1}}'

(this example adds an impulse component which fires on mouseup event, with a force of 40 in the Y direction, and sets the object color to green, and sets the object to be non-transparent)

Methods on Object

  • fireEvent takes 3 optional arguments
    • event - arena.Enum event to be sent to the object, e.g. mouseup, mousedown (default), mouseenter, mouseleave
    • position - a triple (x, y, z) where the event was fired in World coordinates (meters) default: (0, 0, 0)
    • source - an objName string indicating the object from which the event originated, default 'arenaLibrary'
  • update - takes multiple optional arguments to update values originally specified at object create time
    • location
    • rotation
    • scale
    • color
    • physics
    • data
    • clickable
  • delete - deletes the object from the scene


takes 3 positional arguments

  • camera id for example "camera_er1k_er1k" if visiting ARENA URL with &fixedCamera=er1k
  • location - a triple (x, y, z) coordinate in meters
  • rotation - a quad (x, y, z, w) rotation in quaternions


After synchronously drawing objects to the scene, it is necessary to start a loop to listen to and handle network events and call the callback function (specified at init() time)


Empty out the buffer of sent/received network events; call this from main thread rather than sleep() or during loops.


The data passed to the ARENA callback function is a JSON string best interpreted with json.loads() which turns it into a dictionary. These messages are the full contents of all MQTT messages pertaining to the scene, as specified in Most of them may not be of interest, and should be filtered to just events, with code like:

def callback(msg)
    jsonMsg = json.loads(msg)
    # filter non-event messages
    if jsonMsg["action"] != "clientEvent":

    # look for only mousedown messages
    if jsonMsg["type"] != "mousedown":

    # handle mousedown message, breaking out message data from the dict, e.g
    # jsonMsg["object_id"], jsonMsg[

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for arena-py, version 0.0.2
Filename, size File type Python version Upload date Hashes
Filename, size arena_py-0.0.2-py3-none-any.whl (11.0 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size arena-py-0.0.2.tar.gz (13.0 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page