mindustry-campaign-stats 2.3.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
• 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,
        True, # Compute totals only (False by default)
        ['phase'], # Items to filter by
        ['planetary'] # Sectors to filter by
    )

    print(computed.totals.storage.capacity)

    pprint(
      computed.to_dict()
    )
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.

The --compact option will enable compact mode: useless rows and columns (typicall having all values equal to zero) will not be shown.

There's also the --totals option, which computes totals only. In other words, if the --json option is given along, stats for each sector will not be returned. Without --json, a simplified table with only totals will be displayed in the terminal output.

Finally, the --items and --sectors options may be used to get stats for items and sectors matching the given (partial) name(s), respectively. Match is done in a case-insensitive fashion, and multiple names may be given separated by commas.

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
• SectorPresets.java
• Items.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.