sctmgtool 0.3.1__tar.gz

sctmgtool-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Łukasz Gieryk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sctmgtool-0.3.1/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: sctmgtool
+Version: 0.3.1
+Summary: A combat analysis tool for StarCraft: Tabletop Miniatures Game
+Author-email: Łukasz Gieryk <108897150+lgieryk@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/lgieryk/sctmgtool
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: src/sctmgtool/units/NOTICE.txt
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: platformdirs
+Requires-Dist: customtkinter
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pyinstaller; extra == "dev"
+Dynamic: license-file
+
+# SC:TMG Tool
+
+A combat analysis tool for StarCraft: Tabletop Miniatures Game. It calculates
+the expected outcome of clashes between units to help players with list-building
+decisions.
+
+**Disclaimer:** This is an unofficial fan-made project. It is not affiliated
+with, sponsored by, or endorsed by the owners of the StarCraft or StarCraft:
+Tabletop Miniatures Game trademarks.
+
+Any references to unit names, factions, stats, or other game data are used
+solely for identification and analytical purposes under fair use — see
+[NOTICE.txt](src/sctmgtool/units/NOTICE.txt) for details.
+
+![Screenshot](https://raw.githubusercontent.com/lgieryk/repo/sctmgtool/main/assets/screenshot.png)
+
+## A word from the author
+Is that UpgradeX, which gives TAG-Y, worth Z minerals? I wanted to know, so I
+created SC:TMG Tool - an unofficial, poorly written, and _slow_ application
+written in my spare time.
+
+The main idea was to visualize how an upgrade affects the outcome of a clash
+between two units. So if an upgrade does not directly translate to a lost (or
+saved) hit point, it's not included.
+
+While the rules of SC:TMG are not that complex, they do not translate easily
+into a computer program. I applied multiple shortcuts to achieve the
+functionality I needed most. And - obviously - I might have gotten a more
+complex rule wrong. Typos (and a wrong stat here and there) are also to be
+expected.
+
+The tool is slow. It happens so as the result of every clash is simulated 10000
+times. The results are saved, though, so returning to an already simulated clash
+is slightly faster.
+
+## Installation
+### From PyPI
+    python3 -m venv env
+    source env/bin/activate
+    pip install --upgrade pip
+    pip install sctmgtool
+    python3 -m sctmgtool
+
+### Binary package for Windows
+Download a precompiled binary for Windows from
+https://github.com/lgieryk/sctmgtool/releases
+
+### Installation from sources
+    git clone https://github.com/lgieryk/sctmgtool.git
+    cd sctmgtool
+    python3 -m venv env
+    source env/bin/activate
+    pip install -e .
+    python3 -m sctmgtool
+
+You may need to install some additional system packages:
+
+    apt-get update && apt-get install python3-tk
+
+## License
+- Source code: [MIT License](LICENSE)
+- Data files in `src/sctmgtool/units/`: distributed under separate terms, see
+  [NOTICE.txt](src/sctmgtool/units/NOTICE.txt).

sctmgtool-0.3.1/README.md

@@ -0,0 +1,63 @@
+# SC:TMG Tool
+
+A combat analysis tool for StarCraft: Tabletop Miniatures Game. It calculates
+the expected outcome of clashes between units to help players with list-building
+decisions.
+
+**Disclaimer:** This is an unofficial fan-made project. It is not affiliated
+with, sponsored by, or endorsed by the owners of the StarCraft or StarCraft:
+Tabletop Miniatures Game trademarks.
+
+Any references to unit names, factions, stats, or other game data are used
+solely for identification and analytical purposes under fair use — see
+[NOTICE.txt](src/sctmgtool/units/NOTICE.txt) for details.
+
+![Screenshot](https://raw.githubusercontent.com/lgieryk/repo/sctmgtool/main/assets/screenshot.png)
+
+## A word from the author
+Is that UpgradeX, which gives TAG-Y, worth Z minerals? I wanted to know, so I
+created SC:TMG Tool - an unofficial, poorly written, and _slow_ application
+written in my spare time.
+
+The main idea was to visualize how an upgrade affects the outcome of a clash
+between two units. So if an upgrade does not directly translate to a lost (or
+saved) hit point, it's not included.
+
+While the rules of SC:TMG are not that complex, they do not translate easily
+into a computer program. I applied multiple shortcuts to achieve the
+functionality I needed most. And - obviously - I might have gotten a more
+complex rule wrong. Typos (and a wrong stat here and there) are also to be
+expected.
+
+The tool is slow. It happens so as the result of every clash is simulated 10000
+times. The results are saved, though, so returning to an already simulated clash
+is slightly faster.
+
+## Installation
+### From PyPI
+    python3 -m venv env
+    source env/bin/activate
+    pip install --upgrade pip
+    pip install sctmgtool
+    python3 -m sctmgtool
+
+### Binary package for Windows
+Download a precompiled binary for Windows from
+https://github.com/lgieryk/sctmgtool/releases
+
+### Installation from sources
+    git clone https://github.com/lgieryk/sctmgtool.git
+    cd sctmgtool
+    python3 -m venv env
+    source env/bin/activate
+    pip install -e .
+    python3 -m sctmgtool
+
+You may need to install some additional system packages:
+
+    apt-get update && apt-get install python3-tk
+
+## License
+- Source code: [MIT License](LICENSE)
+- Data files in `src/sctmgtool/units/`: distributed under separate terms, see
+  [NOTICE.txt](src/sctmgtool/units/NOTICE.txt).

sctmgtool-0.3.1/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.dynamic]
+version = {attr = "sctmgtool.__version__"}
+
+[project]
+name = "sctmgtool"
+description = "A combat analysis tool for StarCraft: Tabletop Miniatures Game"
+authors = [
+  { name="Łukasz Gieryk", email="108897150+lgieryk@users.noreply.github.com" },
+]
+license = "MIT"
+license-files = ["LICENSE", "src/sctmgtool/units/NOTICE.txt"]
+dynamic = ["version"]
+requires-python = ">=3.12"
+readme = "README.md"
+dependencies = [
+    "matplotlib",
+    "numpy",
+    "platformdirs",
+    "customtkinter",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-cov",
+    "ruff",
+    "pyinstaller",
+]
+
+[project.urls]
+Homepage = "https://github.com/lgieryk/sctmgtool"
+
+[tool.ruff]
+line-length = 160

sctmgtool-0.3.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sctmgtool-0.3.1/src/sctmgtool/__init__.py

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Łukasz Gieryk
+
+__version__ = "0.3.1"

sctmgtool-0.3.1/src/sctmgtool/__main__.py

@@ -0,0 +1,15 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Łukasz Gieryk
+
+import logging
+from multiprocessing import freeze_support
+from sctmgtool.tools import process_unit_list
+from sctmgtool.tk import tkinter_main
+from sctmgtool.units import ALL_UNITS
+
+
+if __name__ == "__main__":
+    freeze_support()
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
+    process_unit_list(ALL_UNITS)
+    tkinter_main(ALL_UNITS)

sctmgtool-0.3.1/src/sctmgtool/base.py

@@ -0,0 +1,257 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Łukasz Gieryk
+
+from enum import Flag, Enum, auto
+from typing import NamedTuple, Callable
+from dataclasses import dataclass
+import enum
+
+# pylint: disable=invalid-name
+
+
+class Faction(Flag):
+    Zerg = auto()
+    Terran = auto()
+    Protoss = auto()
+
+
+# fmt: off
+class Tag(Flag):
+    _None           = 0b0000000000000000000000000000000000000000000000
+    Biological      = 0b0000000000000000000000000000000000000000000001
+    Mechanical      = 0b0000000000000000000000000000000000000000000010
+    Flying          = 0b0000000000000000000000000000000000000000000100
+    Ground          = 0b0000000000000000000000000000000000000000001000
+    Light           = 0b0000000000000000000000000000000000000000010000
+    Armoured        = 0b0000000000000000000000000000000000000000100000
+    Psionic         = 0b0000000000000000000000000000000000000001000000
+    Sidearm         = 0b0000000000000000000000000000000000000010000000
+    Specialist      = 0b0000000000000000000000000000000000000100000000
+    _AntiEvade      = 0b0000000000000000000000000000000000001000000000
+    AntiEvade1      = 0b0000000000000000000000000000000000011000000000
+    AntiEvade2      = 0b0000000000000000000000000000000000101000000000
+    AntiEvade3      = 0b0000000000000000000000000000000001001000000000
+    _Precision      = 0b0000000000000000000000000000000010000000000000
+    Precision1      = 0b0000000000000000000000000000000110000000000000
+    Precision2      = 0b0000000000000000000000000000001010000000000000
+    Precision3      = 0b0000000000000000000000000000010010000000000000
+    Pinpoint        = 0b0000000000000000000000000000100000000000000000
+    _LockedIn       = 0b0000000000000000000000000001000000000000000000
+    LockedIn6       = 0b0000000000000000000001000001000000000000000000
+    _PierceArmoured = 0b0000000000000000000010000000000000000000000000
+    PierceArmoured2 = 0b0000000000000000001010000000000000000000000000
+    PierceArmoured3 = 0b0000000000000000010010000000000000000000000000
+    _PierceLight    = 0b0000000000000000100000000000000000000000000000
+    PierceLight2    = 0b0000000000000010100000000000000000000000000000
+    _Tough          = 0b0000000000001000000000000000000000000000000000
+    Tough1          = 0b0000000000011000000000000000000000000000000000
+    Tough2          = 0b0000000000101000000000000000000000000000000000
+    Unique          = 0b0000000001000000000000000000000000000000000000
+    IndirectFire    = 0b0000000010000000000000000000000000000000000000
+    Bulky           = 0b0000000100000000000000000000000000000000000000
+    BurstFire       = 0b0000001000000000000000000000000000000000000000
+    _CriticalHit    = 0b0000010000000000000000000000000000000000000000
+    CriticalHit2    = 0b0001010000000000000000000000000000000000000000
+    Instant         = 0b0010000000000000000000000000000000000000000000
+# fmt: on
+
+    def __str__(self):
+        masked_value = self.value & ~Tag(Tag._AntiEvade | Tag._Precision | Tag._PierceArmoured | Tag._Tough).value
+        first = True
+        ret = ""
+        for name, member in Tag.__members__.items():
+            if not name.startswith("_") and member.value & masked_value:
+                if not first:
+                    ret += "|"
+                first = False
+                ret += name
+        return ret
+
+    @staticmethod
+    def _lsb(val):
+        return (val & -val).bit_length() - 1
+
+    def sibling_bits(self):
+        siblings = 0
+        for _name, member in Tag.__members__.items():
+            if member.value & self.value:
+                siblings |= member.value
+        return siblings
+
+    def _extract(self, tag):
+        if tag not in self:
+            return 0
+        masked = ~((tag.value << 1) - 1) & self.value
+        return Tag._lsb(masked) - Tag._lsb(tag.value)
+
+    def anti_evade(self):
+        return self._extract(Tag._AntiEvade)
+
+    def precision(self):
+        return self._extract(Tag._Precision)
+
+    def pierce_armoured(self):
+        return self._extract(Tag._PierceArmoured)
+
+    def pierce_light(self):
+        return self._extract(Tag._PierceLight)
+
+    def tough(self):
+        return self._extract(Tag._Tough)
+
+    def critical_hit(self):
+        return self._extract(Tag._CriticalHit)
+
+
+class SurgeDie(Enum):
+    @enum.nonmember
+    class _Inner(NamedTuple):
+        d3:int
+        d6:int
+        add:int
+
+    D3 = _Inner(1, 0, 0)
+    D6 = _Inner(0, 1, 0)
+    D3P1 = _Inner(1, 0, 1)
+
+    def __str__(self):
+        return self.name
+
+
+@dataclass
+class Weapon():
+    name: str
+    range: (int | str)
+    target: Tag
+    rate_of_attack: int
+    hit: int
+    surge: Tag
+    surge_die: SurgeDie
+    damage: int
+    exchange_for:str = ""
+    # pylint: disable-next=protected-access
+    tags:Tag = Tag._None
+
+    def add_tag(self, tag:Tag):
+        if tag & self.tags:  # replace the existing value-tag with a new value, e.g., Pierce1 -> Pierce2
+            new = Tag(self.tags.value & ~tag.sibling_bits())
+            self.tags = new
+        self.tags |= tag
+
+    def add_surge_tag(self, tag:Tag):
+        if self.surge is None:
+            self.surge = tag
+        else:
+            self.surge |= tag
+
+    def set_surge_die(self, die:SurgeDie):
+        self.surge_die = die
+
+    def buff_roa(self, val:int):
+        self.rate_of_attack += val
+
+    def buff_hit(self, val:int):
+        self.hit = max(2, self.hit - val)
+
+    def set_damage(self, val:int):
+        self.damage = val
+
+    def type_letter(self):
+        return self.range if self.range in ("E", "C") else "R"
+
+    def __str__(self):
+        ef = f" FOR:{self.exchange_for}" if self.exchange_for != "" else ""
+        surge = f" {str(self.surge or ""):<16} {str(self.surge_die or ""):<4}"
+
+        if Tag.Flying in self.target and Tag.Ground in self.target:
+            tgt = "GF"
+        else:
+            tgt = "G " if Tag.Ground in self.target else "F "
+
+        return f"{self.name:<30} {self.range:>2} {tgt} {self.rate_of_attack}D6 {self.hit}+ {surge} DMG:{self.damage} {str(self.tags):<20}{ef}"
+
+
+class Range(NamedTuple):
+    start: int
+    stop: int
+
+
+class Squad(NamedTuple):
+    models: Range
+    supply: int
+    points: int
+
+
+@dataclass
+class Speed():
+    unit: int
+    model: int
+
+    def __str__(self):
+        return f"{self.unit}/{self.model}"
+
+
+@dataclass
+class Cost():
+    small: int|None = None
+    large: int|None = None
+    points: int|None = None
+
+    def __str__(self):
+        points = f"/{self.points}P" if self.points else ""
+        return f"{self.small or '-'}/{self.large or '-'}{points}"
+
+
+class Hook(Enum):
+    ModifyOwner = auto()
+    RollPoolsInitiated = auto()
+
+
+class Upgrade():
+    class Type(Flag):
+        Other = auto()
+        Defensive = auto()
+        Offensive = auto()
+
+    def __init__(self, name:str, /, apply:Callable|dict=None, *, message="", cost=None, upgrade_type=None):
+        if apply is Upgrade.activate_weapon:
+            def wrapper(unit):
+                return Upgrade.activate_weapon(unit, name)
+            apply = wrapper
+            message = "Upgrade weapon"
+
+        if callable(apply):
+            apply = {Hook.ModifyOwner: apply}
+        else:
+            assert isinstance(apply, dict)
+
+        self.name = name
+        self.apply = apply
+        self.upgrade_type = upgrade_type
+        self.message = message
+        self.cost = cost
+
+    def __str__(self):
+        return f"{self.name} {self.cost or "-"} {self.message}"
+
+    @staticmethod
+    def activate_weapon(unit, weapon_name:str):
+        unit.activate_weapon(weapon_name)
+
+
+@dataclass
+class Unit():
+    faction: Faction
+    name: str
+    shield: int
+    speed: Speed
+    evade: int
+    armour: int
+    hit_points: int
+    weapons: tuple[Weapon]
+    squad: tuple[Squad]
+    tags: Tag
+    upgrades: tuple[Upgrade]
+
+    def __str__(self):
+        return f"{self.name} SHLD:{self.shield} EVA:{self.evade}+ ARM:{self.armour}+ HP:{self.hit_points} {self.tags}"

sctmgtool-0.3.1/src/sctmgtool/cache.py

@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Łukasz Gieryk
+
+import pickle
+from multiprocessing import Process, Manager, Lock, Event, Value
+from pathlib import Path
+import hashlib
+import logging
+import sctmgtool
+
+
+class Cache:
+    MAJOR_REVISION = hashlib.sha256(sctmgtool.__version__.encode("utf-8")).hexdigest()
+    FILENAME = "cache.pkl"
+
+    def __init__(self, /, minor_revision: int, save_path: Path):
+        manager = Manager()
+        self.revision = (self.MAJOR_REVISION, minor_revision)
+        self.save_file_path = save_path / Cache.FILENAME
+
+        try:
+            logging.info("Cache path: %s", self.save_file_path)
+            with open(self.save_file_path, "rb") as file:
+                rev, data = pickle.load(file)
+                if rev == self.revision:
+                    self.data = manager.dict(data)
+                else:
+                    logging.warning("Cache version error; starting a new one from scratch")
+                    self.data = manager.dict()
+        except (FileNotFoundError, AttributeError):
+            logging.warning("Cache access error; starting a new one from scratch")
+            self.data = manager.dict()
+
+        self.lock = Lock()
+        self.stop_event = Event()
+        self.workers = []
+        self.new_inserts = Value("i", 0)
+
+    def start_worker_func(self, worker_func: callable, arguments=None):
+        if arguments is None:
+            worker = Process(target=worker_func)
+        else:
+            worker = Process(target=worker_func, args=arguments)
+        worker.start()
+        self.workers.append(worker)
+
+    def stop_and_save(self):
+        self.stop_event.set()
+
+        for worker in self.workers:
+            worker.join()
+
+        if self.new_inserts.value == 0:
+            return
+
+        with self.lock:
+            with open(self.save_file_path, "wb") as file:
+                pickle.dump((self.revision, dict(self.data)), file)
+
+    def __getitem__(self, obj):
+        key = self.obj_to_key(obj)
+
+        if key in self.data:
+            return self.data[key]
+
+        value = self.compute_func(obj)
+
+        with self.lock:
+            self.data.setdefault(key, value)
+
+        with self.new_inserts.get_lock():
+            self.new_inserts.value += 1
+
+        return value
+
+    def obj_to_key(self, obj):
+        return obj
+
+    def compute_func(self, _obj):
+        raise NotImplementedError()

sctmgtool-0.3.1/src/sctmgtool/hooks.py

@@ -0,0 +1,17 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Łukasz Gieryk
+
+from typing import NamedTuple, Any
+
+
+class RollHookArgs(NamedTuple):
+    attacker: Any
+    weapon_batch: Any
+    defender: Any
+
+
+class PoolHookArgs(NamedTuple):
+    attack_pool: Any
+    armour_pool: Any
+    damage_pool: Any
+    discard_pool: Any