Getting started

In this page we explain how to start using the Python API and how to make a very simple script to show some of your game character information.

The following tutorials assume that you already have knowledge about programming in Python. If this is not the case we recommend you to learn the language first using online tutorials like https://www.learnpython.org/

Installation

There is an existing Python package that contains all the client code needed to interact with the bot. Before installing the package creating a virtual environment for your project is recommended but optional:

mkdir my_project
cd my_project
python -m venv venv
.\venv\Scripts\activate

If you don't have any alias in Windows for the python command the correct command would be py instead of python.

Next, we install the package:

pip install phoenix-bot-api

Hello world

We are going to make a very simple script that connects to the bot using your character name and shows some of your character information.

Frist we begin importing the necessary modules from the package:

from phoenixapi.finder import create_api_from_name
from phoenixapi.api import PhoenixApi
from phoenixapi.clients.player_manager import PlayerObjManager

The api module contains a class PhoenixApi to encapsulates all the client managers to interact with the exposed bot services. The finder module contains functions that allows us to list all the opened bot ports that we can connect to aswell as creating instances of the PhoenixApi class using the character name. The PlayerObjManagerClient is a class that allows interacting and reading information about our character. It is defined in the phoenixapi.clients.player_manager module.

Next, we create an instance of the PhoenixApi class using the finder module with your character name:

CHAR_NAME = "Insert your character name here"
client: PhoenixApi = create_api_from_name(CHAR_NAME)

Now that we have a client connected to the bot you can use any of the available clients to interact with the different services. In this case we are going to use the PlayerObjManagerClient to request an object of the PlayerObjManager type to the bot:

player_obj_manager: PlayerObjManager = client.player_obj_manager.get_player_obj_manager()

The PlayerObjManager class contains the following fields as specified in the API Reference:

{
    "position": {
        "x": 5,
        "y": 8
    },
    "dest_position": {
        "x": 15,
        "y": 20
    },
    "state": 1,
    "player": {
        "entity_type": 1,
        "id": 5492,
        "position": {
            "x": 5,
            "y": 8,
        },
        "direction": 5,
        "animation_status": 9,
        "speed": 12,
        "is_in_combat": true,
        "health_percent": 95,
        "mana_percent": 60,
        "level": 99,
        "champion_level": 80,
        "current_map_id": 2610,
        "sp": 15,
        "name": "Hatz",
        "title": "Eternal",
        "family": "PhoenixEnjoyers",
        "is_gm": false,
        "reputation_rank": 10
    },
    "id": 5492,
    "is_resting": false
}

As we can see there are many fields we can look at. In this case we are going to print the name, id, family and position of our character to the console:

name = player_obj_manager["player"]["name"]
player_id = player_obj_manager["id"]
family = player_obj_manager["player"]["family"]
x = player_obj_manager['position']['x']
y = player_obj_manager['position']['y']

print(f"Name:\t\t{name}")
print(f"ID:\t\t{player_id}")
print(f"Family:\t\t{family}")
print(f"Position:\t({x}, {y})")

Now we can run the script:

python hello_world.py

And we get the following output:

Name:           Hatz
ID:             4538
Family:         PhoenixEnjoyer
Position:       (12, 32)

You can find the full source code of this example here.

Now that you have a basic understanding of how the Python API works you can read the next page were you will learn how to make your own packetlogger to read the packets the are being sent between the game server and client.