mindustry-campaign-stats 2.4.1

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
• Mindustry >= 8

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
    )

    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

Several options are available to customize its output. Please read below.

Common options

These apply to all output formats.

Name	Effect
--refresh	Run the CLI indefinitely, listening for modification in the given settings.binfile until it's terminated (CTRL+C). This option implies different behavior changes in function of output format (documented below).

ASCII table options

These apply to the default output format.

Name	Effect
--compact	Enable compact mode: useless rows and columns (typically having all values equal to zero) will not be shown.
--totals	Display a simplified table with totals only.
--items	Display stats for the given (partial) item names only. Matching is done in a case-insensitive fashion, and multiple names may be given separated by commas.
--sectors	Display stats for the given (partial) sector names only. Matching is done in a case-insensitive fashion, and multiple names may be given separated by commas.

When --refresh is set as well, the table will be automatically updated in your terminal (the screen is cleared before any update happens).

JSON options

These apply to the JSON output format.

Name	Effect
--json	Switches output format to JSON, specifically JSON Lines.
--pretty	Pretty-print the outputted JSON (ignored if --refresh is set as well as it would break JSON Lines formatting).

When --refresh is set as well, a stream of JSON Lines will be sequentially written to stdout.

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
• serpulo.json
• 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.