Echo VR API

Python bindings for Echo VR’s HTTP API.

Echo VR API Reference

The primary entry point of the API is through the fetch_state() method. This method returns a GameState object which you can then traverse to find any information you could want.

If for some reason you need more direct control over how the API is accessed, you may instead decide to use the API class directly.

Installation

If you haven’t already, first install Python 3 and Pipenv.

Now, in your project directory, run:

pipenv install echovr-api

Basic Usage

Example:

import echovr_api

try:
    game_state = echovr_api.fetch_state()

    print(f"Game status: {game_state.game_status}")
    print(f"Seconds on clock: {game_state.game_clock}")
    print(f"Score: {game_state.blue_team.score} - {game_state.orange_team.score}")

    # See `GameState` reference for available properties/methods
except ConnectionError as e:
    # Echo VR is not running, or you didn't pass the -http parameter when
    # starting it.
except json.decoder.JSONDecodeError as e:
    # Echo VR is currently not in an Arena match

Reference

For a complete listing of available modules, classes, and methods, see Module Index.

You can also view comprehensive documentation of the raw HTTP API itself at the Unofficial Echo VR API Documentation.

README

Python bindings for Echo VR’s HTTP API.

Installation

If you haven’t already, install Python 3 and Pipenv.

Now, in your project directory, run:

pipenv install echovr-api

Usage

Basic usage example:

from requests.exceptions import ConnectionError
import json
import echovr_api

try:
    game_state = echovr_api.fetch_state()

    print(f"Game status: {game_state.game_status}")
    print(f"Seconds on clock: {game_state.game_clock}")

    if (game_state.blue_team.score > game_state.orange_team.score):
        print("Blue team is winning!")
    elif (game_state.orange_team.score > game_state.blue_team.score):
        print("Orange team is winning!")
    else:
        print("It's tied!")

    print(f"Score: {game_state.blue_team.score} - {game_state.orange_team.score}")

except ConnectionError as e:
    print("Connection refused. Make sure you're running Echo VR with the -http option and that you're in a match.")
except json.decoder.JSONDecodeError as e:
    print("Could not decode response. (Not valid JSON.)")

For comprehensive documentation of the available methods and classes, please see the full API Documentation on Read The Docs.

Contributing

To get everything you need to start making changes to this package, first install Python 3 and Pipenv, clone this repository, then run:

pipenv install

Try it

To play around with the API, open an instance of Echo VR with the -http flag, then run:

pipenv run python -i ./test.py

Release process

First, update CHANGELOG.md and the version number in setup.py and docs/source/conf.py. Then commit, tag, and push these changes.

Next, build the package:

pipenv install --dev
pipenv run python setup.py sdist bdist_wheel

Finally, upload the built packages to PyPi. You can do this using twine (pip install twine):

twine upload dist/*

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

0.2.0 - 2018-11-18

Added

  • API Documentation on Read the Docs
  • Support for new API response properties in Echo VR Combat release patch
  • players property on GameSate for listing all players in the game
  • find_team and find_player methods on GameState
  • Alias Player#name as Player#username
  • Team.Color#by_name

0.1.1 - 2018-11-06

Fixed

  • Properly declare dependencies in setup.py

0.1.0 - 2018-11-05

Added

  • A changelog
  • Shortcut methods for accessing the default API on localhost
  • Concept of team colors, with special methods on the GameState and Team objects
  • Team#score shortcut method for getting a team’s score
  • More extensive README documentation on how to install and use the package

Changed

  • Fix imports to work when __init__.py is not executed directly

0.0.1 - 2018-11-01

Added

  • Simple system for fetching JSON from the API
  • Simple object model exposing the basic functionality of the API

Indices and tables