am4 0.1.8a1

Tools and utilities for the game Airline Manager 4.

am4

Airline Manager 4 is an online multiplayer game whose goal is to build an airline from scratch. Rapid progression in the game requires thorough market research and route planning to high demand destinations, while considering recurring fuel/CO2 costs, and conforming to aircraft range/runway requirement constraints.

The weekly leaderboards and alliances are highly competitive arenas which require extensive knowledge in the game: this repository contains a set of high-performance foundational tools, built for the more technical-oriented players. The project is structured as follows:

• core calculations written in C++ for exhaustive searches (src/am4/utils)
• a Python web API exposing the core (src/am4/api)
• an sqlite database storing user settings (src/am4/db)
• a Python discord bot for our community (src/am4/bot)
• am4help.com: a SolidJS frontend calling the API (under construction, src/am4/web)

[!WARNING] The code here represents my journey of learning various programming languages: parts of it are poorly written. Feel free to contribute by opening issues or pull requests!

Usage

The easiest way to get started is Docker.

Clone the repository and run inside:

docker build -t am4 .
docker run -d -p 8002:8002 -p 8090:8090 --name am4-dev am4
# sudo docker exec -it am4-dev bash

Access the API docs at localhost:8002/docs and database admin UI at localhost:8090/_.

If you would also like to run the discord bot, you must load your custom configuration file (more info):

docker run -d -p 8002:8002 -p 8090:8090 --name am4-dev am4 tail -f /dev/null
mv config.example.json config.json
# edit config.json
docker cp config.json am4-dev:/app/config.json
docker exec am4-dev python3 -m src.am4 cfg set config.json
docker exec -d am4-dev python3 -m src.am4 start api,bot

Development

If you are using VSCode, install the recommended extensions and use Tasks instead of manually executing the commands.

Core Utils

The core utils is the most important part of the project, as it is used by the API, bot and web.

Modifying it

The main entry point is the debug executable.

A C++17 compliant compiler and Linux system is required to build it.

[!TIP] VSCode users: set build target and launch.

sudo apt-get install build-essential
# optionally install vtune for profiling

cd src/am4/utils
mkdir build
cd build
cmake .. && cmake --build . --target _core_executable && ./_core_executable

Note that the BUILD_PYBIND definition/directives controls whether the pybind11 bindings are included. It is set to 0 when building the executable.

Create the Python bindings

[!TIP] VSCode users: run the py: reinstall task.

# in root dir:
sudo apt-get install python3-dev python3-pip
pip3 install virtualenv
virtualenv .venv
source .venv/bin/activate

pip3 install --verbose ".[dev,api,bot]" --config-settings=cmake.define.COPY_DATA=1
pytest
cd src/am4/utils
python3 generate-stubs.py
# pip3 uninstall src/am4/utils -y

The am4 package and data files will then be installed in your site-packages, ready for use:

from am4.utils.db import init
from am4.utils.aircraft import Aircraft
init() # IMPORTANT: loads the aircraft, airport and routes etc.
a = Aircraft.search("b744")
print(a.ac)

To learn more on how to use it, check out the tests or the generated stubs.

Configuration File

The database and API can run out of the box without any configuration file, by using the defaults. However, running the discord bot/building the frontend will require you to provide custom config.

To do this, rename ./config.example.json to ./config.json and modify it. Then, run:

python3 -m src.am4 cfg set config.json

This will verify and persist the settings to ./src/am4/.config.json, which is used in future calls.

Database

User authentication is handled by pocketbase, a lightweight SQLite-based backend supporting OAuth2.0.

It is automatically started before the API/discord bot when using the CLI.

Web API

The core utils are exposed to the web using FastAPI. Validation on query params/body is handled by Pydantic models defined under ./src/am4/db/models.

To start it, use:

python3 -m src.am4 start api

Discord bot

It is similar to the API in design, but is more sophisticated in that it reads users' roles to determine their game mode.

To start it, use:

python3 -m src.am4 start bot

Web Frontend

Under construction!

Documentation for Legacy Code

• src-old: the very first iteration of the discord bot.
• src-v2-v3: my first attempts at rewriting in C/Cython
• research: parts of my attempts to figure out the demand formula

Features

Old bot:

• calculates essential statistics
  • most distance-efficient stopovers
  • route demands, best seat configurations, best ticket prices, estimated income
  • player rank, mode, achievements, fleet
  • alliance rank, share value, contribution
  • aircraft characteristics and profit
  • airport characteristics
• CSV export for route queries
• fuel/CO2 notifications
• aircraft characteristics comparisons
• internal Star Alliance tools (now disbanded)
  • adding competitor alliances to watchlist
  • alliance comparisons over time: value,contribution/day, rate of changes
  • realtime alliance-member comparisons: SV/contribution distribution
  • member tracking: cheat detection tools, departure pattern identification

Public

• $route|stop <airport> <airport> <aircraft> [flights_per_day] [reputation]: finds the best route between two airports

  

• $routes <airport> <aircraft> <max_distance> <flights_per_day> [reputation]: finds the best destinations from a certain airport, sorted by decreasing estimated income

  

• $user [player]: shows player (and associated alliance if found) statistics

  

• $fleet [player]: shows player fleet and estimated income

  

• $info <aircraft>: shows basic aircraft information and rough profit estimations

  

• $compare <aircraft>: compares two aircrafts

  

• $search <aircraft>: finds the associated aircraft shortname for aircraft commands

  

• $airport <airport>: shows airport information

  

• $price f[fuel_price] c[co2_price]: notifies everyone for the fuel price

  

Internal Alliance Tools

• $memberCompare <player> <player>: compares descending structure of contribution/day and SV

  

• $alliance <alliance>: shows AV progression and d(AV)/dt.

  

• $allianceCompare <alliance> <alliance>: compares AV progression and gap difference over time, shows 48h/12h-average contribution/day graphs

  

• $member <player> [player[]] shows contribution/day, total contribution and SV history for 1+ members

  

• $actions <player> [maxResults]: shows log of estimated departures, contributions and income

  

• $watchlist [add|+, remove|rm|-] [alliance]: shows, adds or remove alliance(s) to the watchlist