mindustry-campaign-stats 1.0.0

Python API and CLI tool to read Mindustry's campaign global stats.

Mindustry Campaign Stats

Python API and CLI tool to read Mindustry's campaign global stats.

PyPI - Documentation - Source code - Issue tracker - Changelog

Prerequisites

• Python >= 3.10

Installation

From PyPi

pip install mindustry-campaign-stats

Locally

After cloning/downloading the repo:

pip install .

Usage

API

The API consists of:

• A load() function, which reads data from the given binary file-like object and returns the raw parsed data as a dictionary
• A compute() function, which transforms the above dictionary to a Stats instance
• Utility functions to_table and to_jsonl(), both taking a Stats instance. They return a human-readable ASCII table representation of the data and the data formatted to a JSON Line, respectively
• A Planet enum (Serpulo, Erekir) to be used with compute()

import mindustry_campaign_stats
from pprint import pprint

try:
    with open('settings.bin', 'rb') as fp: # Note it's opened in binary mode
        raw_settings = mindustry_campaign_stats.load(fp)

    pprint(raw_settings)

    computed = mindustry_campaign_stats.compute(
        raw_settings,
        mindustry_campaign_stats.Planet.Erekir
    )

    print(computed.totals.storage.capacity)

    print(
      mindustry_campaign_stats.to_jsonl(computed, pretty=True)
    )
except Exception as e:
    print(e)

CLI

In its simplest form, the CLI reads data from the given settings.bin filename, then writes a human-readable ASCII table of computed stats to stdout. Note you must choose between the serpulo or erekir campaign.

mindustry-campaign-stats settings.bin erekir

When the --refresh option is set, the CLI is running indefinitely, listening for modification in the given settings.bin file until it's terminated. This feature allows the table to be automatically updated in your terminal (screen is cleared before any update happens).

The --json option switches output format to JSON, specifically JSON Lines. The --pretty option may be used to pretty-print the outputted JSON. When --refresh is set as well, the CLI will sequentially write a stream of JSON Lines. Note that --pretty is ignored in that case as it would break JSON Lines formatting.

settings.bin format

This file is designed much like a persistent key-value store. It is used to store both user settings and campaigns-related data. It is formatted as follows (everything is big-endian):

• 4 bytes (int32) - Number of fields to read (fields_count)
• Fields sequence (based on fields_count):
  • 2 bytes (uint16) - Length of the field name (field_name_length)
  • field_name_length bytes - MUTF-8-encoded field name
  • 1 byte (int8) - Field type ID (field_type_id)
  • field_type_id value determines how to read the next bytes:
    • 0:
      • 1 byte (boolean) - A boolean value
    • 1:
      • 4 bytes (int32) - A 32 bits integer
    • 2:
      • 8 bytes (int64) - A 64 bits integer
    • 3:
      • 4 bytes (float) - A single-precision floating-point number
    • 4:
      • 2 bytes (uint16) - Length of the field value (field_value_length)
      • field_value_length bytes - An MUTF-8-encoded string
    • 5:
      • 4 bytes (int32) - Length of the field value (field_value_length)
      • field_value_length bytes - A binary value. Most likely UBJSON data

References

• Settings.java

Development

Getting source code and installing the package with dev dependencies

1. Clone the repository
2. From the root directory, run: pip install -e ".[dev]"

Releasing the package

From the root directory, run python setup.py upload. This will build the package, create a git tag and publish on PyPI.

__version__ in mindustry_campaign_stats/__version__.py must be updated beforehand. It should adhere to Semantic Versioning.

An associated GitHub release must be created following the Keep a Changelog format.