StatCalc / StatCalcAsync API¶

StatCalc and StatCalcAsync perform local stat and Galactic Power (GP) calculations for game units without requiring an external swgoh-stats service.

Quick Start¶

from swgoh_comlink import SwgohComlink, StatCalc

comlink = SwgohComlink()
calc = StatCalc()  # fetches game data from GitHub on init

player = comlink.get_player(allycode=245866537)
calc.calc_roster_stats(player["rosterUnit"])

# Each unit in rosterUnit now has "stats" and "gp" keys
for unit in player["rosterUnit"]:
    print(unit.get("stats"), unit.get("gp"))

Initialization¶

# Default — fetches latest game data from GitHub
calc = StatCalc()

# Offline — supply pre-loaded game data
calc = StatCalc(game_data=my_game_data_dict)

The game_data parameter accepts the JSON payload from the swgoh-utils/gamedata repository.

Usage Examples¶

Calculate stats for a single character¶

unit = {
    "defId": "BOSSK",
    "rarity": 7,
    "level": 85,
    "gear": 13,
    "equipped": [],
    "skills": [],
}
calc.calc_char_stats(unit)
print(unit["stats"])  # base, mods, and gear stats
print(unit["gp"])     # galactic power

Calculate stats for a full roster¶

player = comlink.get_player(allycode=245866537)
calc.calc_roster_stats(player["rosterUnit"])

Characters are processed first, then ships (which depend on their crew stats). A ship whose crew is not fully present in the roster is skipped (no stats or gp key) with a logged warning, and processing continues with the remaining ships.

Calculate stats for one or more players¶

# Single player dict
player = comlink.get_player(allycode=245866537)
calc.calc_player_stats(player)

# List of player dicts
players = [
    comlink.get_player(allycode=245866537),
    comlink.get_player(allycode=123456789),
]
calc.calc_player_stats(players)

Calculate GP only¶

gp = calc.calc_char_gp(unit)
ship_gp = calc.calc_ship_gp(ship_unit, crew_list)

Async Usage (`StatCalcAsync`)¶

StatCalcAsync inherits all calculation methods from StatCalc. The only difference is initialization: use the async create() factory to fetch game data without blocking the event loop.

from swgoh_comlink import SwgohComlinkAsync, StatCalcAsync

async with SwgohComlinkAsync() as comlink:
    calc = await StatCalcAsync.create()  # async fetch from GitHub

    player = await comlink.get_player(allycode=245866537)
    calc.calc_roster_stats(player["rosterUnit"])

With pre-loaded data (no async fetch):

calc = StatCalcAsync(game_data=my_game_data_dict)

GameDataBuilder / GameDataBuilderAsync¶

Instead of fetching game data from a static GitHub file, you can build it dynamically from a running Comlink service.

Sync¶

from swgoh_comlink import SwgohComlink, StatCalc, GameDataBuilder

comlink = SwgohComlink()
game_data = GameDataBuilder(comlink).build()
calc = StatCalc(game_data=game_data)

Async¶

from swgoh_comlink import SwgohComlinkAsync, StatCalcAsync, GameDataBuilderAsync

async with SwgohComlinkAsync() as comlink:
    game_data = await GameDataBuilderAsync(comlink).build()
    calc = StatCalcAsync(game_data=game_data)

The builder fetches only the collections required for stat calculation (units, skills, equipment, tables, statProgression, statModSets, relicTierDefinitions, categories) in a single get_game_data() call and transforms them into the dict format expected by StatCalc.set_game_data().

API Reference¶

StatCalc¶

`StatCalc` ¶

SWGOH stat calculator

Parameters:

Name	Type	Description	Default
`game_data`	`dict[str, Any] \| None`	Optional preloaded game data payload. If omitted, the calculator fetches the latest payload from the swgoh-utils GitHub game data repository.	`None`

`init(game_data=None)` ¶

Initialize a calculator instance.

Parameters:

Name	Type	Description	Default
`game_data`	`dict[str, Any] \| None`	Optional game data payload to load immediately.	`None`

`calc_char_stats(unit)` ¶

Calculate stats and GP for a character unit.

Parameters:

Name	Type	Description	Default
`unit`	`dict[str, Any]`	Character object in either normalized (`defId`) or raw game format (`definitionId`).	required

Returns:

Type	Description
`dict[str, Any]`	The input unit with `stats` and `gp` keys added, containing the calculated stats and GP.

`calc_ship_stats(unit, crew_member)` ¶

Calculate stats and GP for a ship unit.

Parameters:

Name	Type	Description	Default
`unit`	`dict[str, Any]`	Ship object in either normalized (`defId`) or raw game format.	required
`crew_member`	`list[dict[str, Any]]`	Crew member list for the ship.	required

Returns:

Type	Description
`dict[str, Any]`	The input unit with `stats` and `gp` keys added, containing the calculated stats and GP.

`calc_roster_stats(units)` ¶

Calculate stats for all units in a roster-like payload.

Parameters:

Name	Type	Description	Default
`units`	`Any`	Either a list of units or a legacy dict keyed by unit id.	required

Returns:

Type	Description
`Any`	Input object with `stats` and `gp` fields added for each unit. Ships
`Any`	whose crew is not fully present in a list-format roster are skipped
`Any`	(no `stats` or `gp` added) and a warning is logged.

`calc_player_stats(players)` ¶

Calculate stats for one or more player payloads.

Parameters:

Name	Type	Description	Default
`players`	`dict[str, Any] \| list[dict[str, Any]]`	One player object, or a list of player objects, each with a `rosterUnit` element.	required

Returns:

Type	Description
`dict[str, Any] \| list[dict[str, Any]]`	The input object with `stats` and `gp` fields added for each player's roster.

Raises:

Type	Description
`RuntimeError`	If a dict player is missing a 'rosterUnit' key.
`TypeError`	If the input object is not a list or dict.

`calc_char_gp(char)` ¶

Calculate GP for a character.

Parameters:

Name	Type	Description	Default
`char`	`dict[str, Any]`	Character object in normalized or raw format.	required

Returns:

Type	Description
`int`	Character GP value.

`calc_ship_gp(ship, crew)` ¶

Calculate GP for a ship.

Parameters:

Name	Type	Description	Default
`ship`	`dict[str, Any]`	Ship object in normalized or raw format.	required
`crew`	`list[dict[str, Any]]`	Crew member list corresponding to the ship.	required

Returns:

Type	Description
`int`	Ship GP value.

StatCalcAsync¶

`StatCalcAsync` ¶

Bases: StatCalc

Async-capable SWGOH stat calculator.

Inherits all computation methods from :class:StatCalc. The only difference is how game data is fetched during initialization: this class uses httpx.AsyncClient instead of blocking urllib.request.

Because __init__ cannot be async, use the :meth:create classmethod factory when game data needs to be fetched from GitHub:

.. code-block:: python

calc = await StatCalcAsync.create()

If you already have game data loaded, pass it directly:

.. code-block:: python

calc = StatCalcAsync(game_data=my_data)

Parameters:

Name	Type	Description	Default
`game_data`	`dict[str, Any]`	Game data payload. Required — use :meth:`create` for automatic async fetching.	required

`init(game_data)` ¶

Initialize with pre-loaded game data.

Unlike the sync :class:StatCalc, this constructor does not auto-fetch from GitHub. Use :meth:create for that.

Parameters:

Name	Type	Description	Default
`game_data`	`dict[str, Any]`	Game data payload containing unit, gear, CR, GP, relic, and mod set tables.	required

`create(game_data=None)` `async` `classmethod` ¶

Factory method to create a :class:StatCalcAsync instance.

If game_data is None, the latest payload is fetched asynchronously from the swgoh-utils GitHub repository.

Parameters:

Name	Type	Description	Default
`game_data`	`dict[str, Any] \| None`	Optional pre-loaded game data payload.	`None`

Returns:

Type	Description
`StatCalcAsync`	A fully initialized :class:`StatCalcAsync` instance.

GameDataBuilder¶

`GameDataBuilder` ¶

Bases: GameDataBuilderBase

Build StatCalc game data from a running Comlink service (sync).

Parameters:

Name	Type	Description	Default
`client`	`SwgohComlink`	An active `SwgohComlink` instance used to fetch raw game data.	required

Example::

from swgoh_comlink import SwgohComlink, StatCalc
from swgoh_comlink.StatCalc.data_builder import GameDataBuilder

comlink = SwgohComlink()
game_data = GameDataBuilder(comlink).build()
calc = StatCalc(game_data=game_data)

`init(client)` ¶

`build()` ¶

Fetch game data from Comlink and transform it.

Returns:

Type	Description
`dict[str, Any]`	Dict suitable for `StatCalc(game_data=...)` or
`dict[str, Any]`	`StatCalc.set_game_data()`.

GameDataBuilderAsync¶

`GameDataBuilderAsync` ¶

Bases: GameDataBuilderBase

Build StatCalc game data from a running Comlink service (async).

Parameters:

Name	Type	Description	Default
`client`	`SwgohComlinkAsync`	An active `SwgohComlinkAsync` instance used to fetch raw game data.	required

Example::

from swgoh_comlink import SwgohComlinkAsync, StatCalcAsync
from swgoh_comlink.StatCalc.data_builder import GameDataBuilderAsync

async with SwgohComlinkAsync() as comlink:
    game_data = await GameDataBuilderAsync(comlink).build()
    calc = StatCalcAsync(game_data=game_data)

`init(client)` ¶

`build()` `async` ¶

Fetch game data from Comlink and transform it.

Returns:

Type	Description
`dict[str, Any]`	Dict suitable for `StatCalcAsync(game_data=...)` or
`dict[str, Any]`	`StatCalc.set_game_data()`.

StatCalc / StatCalcAsync API¶

Quick Start¶

Initialization¶

Usage Examples¶

Calculate stats for a single character¶

Calculate stats for a full roster¶

Calculate stats for one or more players¶

Calculate GP only¶

Async Usage (StatCalcAsync)¶

GameDataBuilder / GameDataBuilderAsync¶

Sync¶

Async¶

API Reference¶

StatCalc¶

StatCalc ¶

__init__(game_data=None) ¶

calc_char_stats(unit) ¶

calc_ship_stats(unit, crew_member) ¶

calc_roster_stats(units) ¶

calc_player_stats(players) ¶

calc_char_gp(char) ¶

calc_ship_gp(ship, crew) ¶

StatCalcAsync¶

StatCalcAsync ¶

__init__(game_data) ¶

create(game_data=None) async classmethod ¶

GameDataBuilder¶

GameDataBuilder ¶

__init__(client) ¶

build() ¶

GameDataBuilderAsync¶

GameDataBuilderAsync ¶

__init__(client) ¶

build() async ¶

Async Usage (`StatCalcAsync`)¶

`StatCalc` ¶

`init(game_data=None)` ¶

`calc_char_stats(unit)` ¶

`calc_ship_stats(unit, crew_member)` ¶

`calc_roster_stats(units)` ¶

`calc_player_stats(players)` ¶

`calc_char_gp(char)` ¶

`calc_ship_gp(ship, crew)` ¶

`StatCalcAsync` ¶

`init(game_data)` ¶

`create(game_data=None)` `async` `classmethod` ¶

`GameDataBuilder` ¶

`init(client)` ¶

`build()` ¶

`GameDataBuilderAsync` ¶

`init(client)` ¶

`build()` `async` ¶