Shapez 2 Python Library

A library to code tools for Shapez 2.

Documentation

You can find below the documentation for the features this library offers.

Even if technically not enforced, all classes in this library should be considered immutable, unless said otherwise in the class description.

blueprints

blueprints.PREFIX: Literal["SHAPEZ2"]

The blueprint code prefix.

blueprints.SEPARATOR: Literal["-"]

The separator between the different blueprint code sections.

blueprints.SUFFIX: Literal["$"]

The blueprint code suffix.

blueprints.ISLAND_ROTATION_CENTER: utils.FloatPos

The center of an island tile, used for rotations.

blueprints.NUM_BP_ICONS: Literal[4]

The number of blueprint icons displayed ingame.

class blueprints.BlueprintError(Exception)

The error raised for all blueprint-related errors.

class blueprints.BlueprintType(enum.Enum)

The type of a blueprint.

Attributes

building: Literal["Building"]

A building blueprint.

island: Literal["Island"]

An island blueprint.

class blueprints.BlueprintIconType(enum.Enum)

The type of a blueprint icon.

Attributes

empty: Literal["empty"]

An empty icon.

icon: Literal["icon"]

A regular icon.

shape: Literal["shape"]

A shape icon.

class blueprints.BlueprintIcon(type: blueprints.BlueprintIconType, *, icon: str | None = None, shape: gameObjects.Shape | None = None)

Represents a blueprint icon.

Parameters

  • type : The type of blueprint icon.
  • icon : The icon ID if it's a regular icon.
  • shape : The shape if its a shape icon.

Attributes

The type of blueprint icon.

icon: str

The icon ID if it's a regular icon.

The shape if its a shape icon.

classmethod decode(raw: str | None) -> blueprints.BlueprintIcon

Create a blueprints.BlueprintIcon from an encoded string.

Parameters

  • raw : The raw string, None for an empty icon.
def encode() -> str | None

Encode the icon to a string or None if it's empty.

ⓘ This class is mutable.

Represents a building inside a blueprint.

Parameters

Attributes

The building's position.

rotation: utils.Rotation

The building's rotation.

The building's type.

The building's extra data.

class blueprints.BuildingBlueprint(entries: list[blueprints.BuildingEntry], icons: list[blueprints.BlueprintIcon] | None = None)

ⓘ This class is mutable.

Represents a building blueprint.

Parameters

  • entries : The buildings inside the blueprint.
  • icons : The blueprint's icons, if None then use the default building blueprint icons.

Attributes

The buildings inside the blueprint.

The blueprint's icons, without restrictions.

Creates a mapping of occupied building tiles to which building entry they are from.

def getSize() -> utils.Size

Returns the blueprint's size.

def getBuildingCount() -> int

Returns the numbers of buildings inside the blueprint.

def getBuildingCounts() -> dict[buildings.BuildingInternalVariant, int]

Returns the amount of each building type present in the blueprint.

def getTileCount() -> int

Returns the number of occupied tiles inside the blueprint.

def getValidIcons() -> list[blueprints.BlueprintIcon]

Returns the blueprint's icons as if they were displayed ingame, i.e. with invalid icons turned into empty icons and with the list cropped/padded to 4 elements.

class blueprints.IslandEntry(pos: utils.Pos, rotation: utils.Rotation, type: islands.Island, extra: blueprintsExtraData.IslandExtraData | blueprintsExtraData.IslandExtraDataHolder | None = None, buildingBP: blueprints.BuildingBlueprint | None = None)

ⓘ This class is mutable.

Represents a island inside a blueprint.

Parameters

  • pos : The island's position.
  • rotation : The island's rotation.
  • type : The island's type.
  • extra : The island's extra data. If None, then the default extra data for that island type will be used if it exists. If a blueprintsExtraData.IslandExtraData, a blueprintsExtraData.IslandExtraDataHolder will be created out of it.
  • buildingBP : The building blueprint contained inside that island, or None if there isn't one.

Attributes

The island's position.

rotation: utils.Rotation

The island's rotation.

The island's type.

The island's extra data.

buildingBP: blueprints.BuildingBlueprint | None

The building blueprint contained on that island, or None if there isn't one.

class blueprints.IslandBlueprint(entries: list[blueprints.IslandEntry], icons: list[blueprints.BlueprintIcon] | None = None)

ⓘ This class is mutable.

Represents an island blueprint.

Parameters

  • entries : The islands inside the blueprint.
  • icons : The blueprint's icons, if None then use the default island blueprint icons.

Attributes

entries: list[blueprints.IslandEntry]

The islands inside the blueprint.

The blueprint's icons, without restrictions.

Creates a mapping of occupied island tiles to which island entry they are from.

def getSize() -> utils.Size

Returns the blueprint's size.

def getIslandCount() -> int

Returns the numbers of islands inside the blueprint.

def getIslandCounts() -> dict[islands.Island, int]

Returns the amount of each island type present in the blueprint.

def getTileCount() -> int

Returns the number of occupied tiles inside the blueprint.

def getValidIcons() -> list[blueprints.BlueprintIcon]

Returns the blueprint's icons as if they were displayed ingame, i.e. with invalid icons turned into empty icons and with the list cropped/padded to 4 elements.

class blueprints.Blueprint(blueprint: blueprints.BuildingBlueprint | blueprints.IslandBlueprint, majorVersion: int = versions.LATEST_MAJOR_VERSION, version: int = versions.LATEST_GAME_VERSION)

Represents a blueprint container object.

Parameters

  • blueprint : The building or island blueprint contained.
  • majorVersion : The blueprint's major version, i.e. the number visible at the start of the blueprint code.
  • version : The blueprint's version number.

Attributes

The contained blueprint's type.

The contained blueprint.

buildingBP: blueprints.BuildingBlueprint | None

If a building blueprint, the contained blueprint. If an island blueprint, the building blueprints of all the island entries merged together, or None if there aren't any buildings.

The contained island blueprint or None if it's a building blueprint.

majorVersion: int

The blueprint's major version.

version: int

The blueprint's version number.

def getCost() -> int

Returns the blueprint points cost of placing the blueprint with a 'copy/paste cost' of 100%. Raises blueprints.BlueprintError if an OverflowError happens in the computation.

def getIslandUnitCost() -> int | float

Returns the platform units cost of placing the blueprint.

dataclass blueprints.TileEntry(referTo: blueprints.BuildingEntry | blueprints.IslandEntry)

Parameters/Attributes

Which building or island this tile belongs to.

blueprints.VALID_BP_ICONS: list[str]

The list of all valid blueprint icon IDs.

def blueprints.getBlueprintVersion(blueprint: str) -> int

Does as little as possible of the decoding process and returns the blueprint's version. Raises blueprints.BlueprintError if the blueprint format is invalid.

Parameters

  • blueprint : The raw blueprint code.
def blueprints.decodeBlueprint(rawBlueprint: str, migrate: bool = False) -> blueprints.Blueprint

Creates a blueprint object from a blueprint code. Raises blueprints.BlueprintError if the blueprint format is invalid or it contains invalid data. When migrate is False, runs the same migration features as ingame. When True, also runs additional migration features :

  • If an entry type is invalid, the entry is ignored instead of raising an error.
  • If the blueprint's version is less than 1024 (alpha 8), default stackers (which were changed from straight to bent in that update) are changed to straight stackers.
  • If the blueprint's version is less than 1119 (0.1.0-pre2), global wire transmitters are turned into global signal transmitters and global wire receivers that weren't set to a ROS channel get turned into global signal receivers.
  • For the rest of the migration features see here.

Parameters

  • rawBlueprint : The raw blueprint code.
  • migrate : Whether or not to run additional migration features.
def blueprints.encodeBlueprint(blueprint: blueprints.Blueprint) -> str

Creates a blueprint code from a blueprint object.

Parameters

  • blueprint : The blueprint object.
def blueprints.getPotentialBPCodesInString(string: str) -> list[str]

Returns the potential blueprint codes from a string, i.e. substrings starting with the blueprint code prefix (SHAPEZ2) and ending with the blueprint code suffix ($).

Parameters

  • string : The string to search.
def blueprints.getDefaultBlueprintIcons(bpType: blueprints.BlueprintType) -> list[blueprints.BlueprintIcon]

Returns the default blueprint icons for the specified blueprint type.

Parameters

  • bpType : The blueprint type.

blueprintsExtraData

class blueprintsExtraData.ShapeGeneratorType(enum.Enum)

The type of a blueprintsExtraData.ShapeGenerator.

Attributes

empty: Literal["empty"]

An empty shape generator, doesn't produce anything.

shape: Literal["shape"]

A shape generator producing a shape.

class blueprintsExtraData.ShapeGenerator(genType: blueprintsExtraData.ShapeGeneratorType, shape: gameObjects.Shape | None = None)

Represents a shape generator, used in blueprintsExtraData.SignalProducerExtraData and blueprintsExtraData.ItemProducerExtraData.

Parameters

  • genType : The type of shape generator.
  • shape : The shape if it's producing a shape.

Attributes

The type of shape generator.

The shape if it's producing a shape.

class blueprintsExtraData.FluidGeneratorType(enum.Enum)

The type of a blueprintsExtraData.FluidGenerator.

Attributes

empty: Literal["empty"]

An empty fluid generator, doesn't produce anything.

paint: Literal["paint"]

A fluid generator producing paint.

class blueprintsExtraData.FluidGenerator(genType: blueprintsExtraData.FluidGeneratorType, color: gameObjects.Color | None = None)

Represents a fluid generator, used in blueprintsExtraData.SignalProducerExtraData and blueprintsExtraData.FluidProducerExtraData.

Parameters

  • genType : The type of fluid generator.
  • color : The paint color if it's producing paint.

Attributes

The type of fluid generator.

The paint color if it's producing paint.

class blueprintsExtraData.SignalGeneratorType(enum.Enum)

The type of signal generated by a blueprintsExtraData.SignalProducerExtraData.

Attributes

empty: Literal["empty"]

No signal.

null: Literal["null"]

A null signal.

conflict: Literal["conflict"]

A conflict signal.

number: Literal["number"]

A number signal.

shape: Literal["shape"]

A shape signal.

fluid: Literal["fluid"]

A color signal.

class blueprintsExtraData.CompareMode(enum.Enum)

The mode of a comparison gate, used in blueprintsExtraData.ComparisonGateExtraData.

Attributes

Equal: Literal[1]

Equal to.

GreaterEqual: Literal[2]

Greater than or equal to.

Greater: Literal[3]

Greater than.

Less: Literal[4]

Less than.

LessEqual: Literal[5]

Less than or equal to.

NotEqual: Literal[6]

Not equal to.

dataclass blueprintsExtraData.LabelExtraData(text: str)

Represents the extra data of a label.

Parameters/Attributes

text: str

The label's text.

class blueprintsExtraData.SignalProducerExtraData(signalType: blueprintsExtraData.SignalGeneratorType, *, number: int | None = None, shapeGen: blueprintsExtraData.ShapeGenerator | None = None, fluidGen: blueprintsExtraData.FluidGenerator | None = None)

Represents the extra data of a signal producer.

Parameters

  • signalType : The type of signal generated.
  • number : The number if it's producing a number signal.
  • shapeGen : The shape generator if it's producing a shape signal.
  • fluidGen : The fluid generator if it's producing a color signal.

Attributes

The type of signal generated.

number: int

The number if it's producing a number signal.

The shape generator if it's producing a shape signal.

The fluid generator if it's producing a color signal.

dataclass blueprintsExtraData.ItemProducerExtraData(shapeGen: blueprintsExtraData.ShapeGenerator)

Represents the extra data of an item producer.

Parameters/Attributes

What the item producer is producing.

dataclass blueprintsExtraData.FluidProducerExtraData(fluidGen: blueprintsExtraData.FluidGenerator)

Represents the extra data of a fluid producer.

Parameters/Attributes

What the fluid producer is producing.

dataclass blueprintsExtraData.ButtonExtraData(activated: bool)

Represents the extra data of a button.

Parameters/Attributes

activated: bool

Whether or not the button is activated.

dataclass blueprintsExtraData.ComparisonGateExtraData(compareMode: blueprintsExtraData.CompareMode)

Represents the extra data of a comparison gate.

Parameters/Attributes

What comparison mode the gate is set to.

dataclass blueprintsExtraData.OperatorSignalReceiverExtraData(channel: Literal[0, 1])

Represents the extra data of an operator signal receiver.

Parameters/Attributes

channel: Literal[0, 1]

Which channel the receiver is set to.

blueprintsExtraData.BuildingExtraData: type

A union for all the building extra data classes listed above.

class blueprintsExtraData.BuildingExtraDataHolder(value: blueprintsExtraData.BuildingExtraData)

A holder class for a building extra data class.

Parameters

  • value : The building extra data class to hold.

Attributes

If it's holding a label extra data.

If it's holding a signal producer extra data.

If it's holding an item producer extra data.

If it's holding a fluid producer extra data.

If it's holding a button extra data.

If it's holding a comparison gate extra data.

If it's holding an operator signal receiver extra data.

dataclass blueprintsExtraData.RailConnectionAllowedColors(b: bool, g: bool, r: bool, w: bool, c: bool, m: bool, y: bool)

The allowed train colors on a rail connection.

Parameters/Attributes

b: bool

If blue trains are allowed.

g: bool

If green trains are allowed.

r: bool

If red trains are allowed.

w: bool

If white trains are allowed.

c: bool

If cyan trains are allowed.

m: bool

If magenta trains are allowed.

y: bool

If yellow trains are allowed.

dataclass blueprintsExtraData.RailExtraData(connectionColors: list[blueprintsExtraData.RailConnectionAllowedColors])

Represents the extra data of a rail.

Parameters/Attributes

The allowed train colors on each connection inside the rail.

dataclass blueprintsExtraData.DisableableTrainUnloadingLanesExtraData(disabledLanes: list[int])

Represents the extra data of an island with disableable train unloading lanes (i.e. unloaders and transfer stations).

Parameters/Attributes

disabledLanes: list[int]

Which lane (floor) indexes are disabled.

blueprintsExtraData.IslandExtraData: type

A union for all the island extra data classes listed above.

class blueprintsExtraData.IslandExtraDataHolder(value: blueprintsExtraData.IslandExtraData)

A holder class for an island extra data class.

Parameters

  • value : The island extra data class to hold.

Attributes

If it's holding a rail extra data.

If it's holding a disableable train unloading lanes extra data.

def blueprintsExtraData.decodeEntryExtraData(rawDecoded: bytes, entryType: str) -> blueprintsExtraData.BuildingExtraData | blueprintsExtraData.IslandExtraData | None

Decodes extra data from raw bytes and returns the custom class result or None if the entry isn't supposed to have extra data. Raises blueprints.BlueprintError if the raw bytes data format is invalid.

Parameters

  • rawDecoded : The bytes decoded from base64.
  • entryType : The entry type's ID this extra data belongs to.
def blueprintsExtraData.encodeEntryExtraData(extra: blueprintsExtraData.BuildingExtraDataHolder | blueprintsExtraData.IslandExtraDataHolder | None, entryType: str) -> bytes | None

Encodes extra data from a custom class into bytes and returns the result or None if the entry doesn't have extra data.

Parameters

  • extra : The extra data to encode or None so this function can be ran for all entries.
  • entryType : The entry type's ID this extra data belongs to.
def blueprintsExtraData.getDefaultEntryExtraData(entryType: str) -> blueprintsExtraData.BuildingExtraData | blueprintsExtraData.IslandExtraData | None

Returns the default extra data for an entry type or None if it doesn't have extra data.

Parameters

  • entryType : The entry type's ID.

buildings

class buildings.BuildingVariant(id: str, title: translations.MaybeTranslationString)

Represents a building variant.

Parameters

  • id : The variant's ID.
  • title : The variant's title.

Attributes

id: str

The variant's ID.

The variant's title.

internalVariants: list[buildings.BuildingInternalVariant]

The building internal variants this variant contains.

dataclass buildings.BuildingInternalVariant(id: str, tiles: list[utils.Pos], fromBuildingVariant: buildings.BuildingVariant)

Represents a building internal variant.

Parameters/Attributes

id: str

The internal variant's ID.

tiles: list[utils.Pos]

The internal variant's tiles.

fromBuildingVariant: buildings.BuildingVariant

The building variant this internal variant is from.

buildings.allBuildingVariants: dict[str, buildings.BuildingVariant]

A mapping of all the ingame building variant IDs to their corresponding building variant.

buildings.allBuildingInternalVariants: dict[str, buildings.BuildingInternalVariant]

A mapping of all the ingame building internal variant IDs to their corresponding building internal variant.

def buildings.getCategorizedBuildingCounts(counts: dict[buildings.BuildingInternalVariant, int]) -> dict[buildings.BuildingVariant, dict[buildings.BuildingInternalVariant, int]]

Categorizes counts of building internal variants into building variant groups.

Parameters

  • counts : The raw internal variant counts.

gameCode

This module ports over some of the ingame code originally in C#, except that if a C# class already has an equivalent python class in this library, the already existing class is used instead. All classes and functions in this module use fixedint.Int32 instead of int. Only objects with notable aspects are documented below.

gameCode.RandomResearchShapeGenerator

The code used by the random operator shapes.

class gameCode.RandomResearchShapeGenerator.RandomResearchShapeGenerator()

Attributes

def Generate(level: fixedint.Int32) -> gameObjects.Shape

The shape returned will be the cost to unlock the given level, so +1 from the level displayed ingame next to the shape.

Parameters

  • level : The level which will be unlocked by the shape.

gameCode.otherClasses

Similar to gameObjects, holds miscellaneous classes used by the other submodules of gameCode.

gameObjects

dataclass gameObjects.Color(code: str)

Represents an ingame color.

Parameters/Attributes

code: str

The color's one letter code.

dataclass gameObjects.ColorSkin(id: str, colors: dict[gameObjects.Color, tuple[int, int, int]])

A mapping of how each color should look.

Parameters/Attributes

id: str

The color skin's ID.

colors: dict[gameObjects.Color, tuple[int, int, int]]

The mapping of colors to how they look as an (R,G,B) tuple.

dataclass gameObjects.ColorMode(id: str, colorSkin: gameObjects.ColorSkin, colorblindPatterns: bool)

Represents an ingame color mode.

Parameters/Attributes

id: str

The color mode's ID.

The color mode's color skin.

colorblindPatterns: bool

If the color mode has colorblind patterns.

class gameObjects.ColorScheme(id: str, primaryColors: list[gameObjects.Color], secondaryColors: list[gameObjects.Color], tertiaryColors: list[gameObjects.Color], defaultColor: gameObjects.Color, colorModes: list[gameObjects.ColorMode], mixingRecipes: dict[frozenset[gameObjects.Color], gameObjects.Color])

Represents an ingame color scheme.

Parameters

  • id : The color scheme's ID.
  • primaryColors : The color scheme's primary colors.
  • secondaryColors : The color scheme's secondary colors.
  • tertiaryColors : The color scheme's tertiary colors.
  • defaultColor : The color scheme's default color.
  • colorModes : The color modes available in this color scheme.
  • mixingRecipes : The mixing recipes in this color scheme as a mapping of inputs to output, where the inputs are represented by a 2-elements frozenset.

Attributes

id: str

The color scheme's ID.

primaryColors: list[gameObjects.Color]

The color scheme's primary colors.

secondaryColors: list[gameObjects.Color]

The color scheme's secondary colors.

tertiaryColors: list[gameObjects.Color]

The color scheme's tertiary colors.

defaultColor: gameObjects.Color

The color scheme's default color.

colorModes: list[gameObjects.ColorMode]

The color modes available in this color scheme.

mixingRecipes: dict[frozenset[gameObjects.Color], gameObjects.Color]

The mixing recipes in this color scheme as a mapping of inputs to output, where the inputs are represented by a 2-elements frozenset.

colors: list[gameObjects.Color]

The color scheme's colors.

colorsByCode: dict[str, gameObjects.Color]

A mapping of each color code to its corresponding color.

colorModesById: dict[str, gameObjects.ColorMode]

A mapping of each color mode ID to its corresponding color mode.

def getMixResult(color1: gameObjects.Color, color2: gameObjects.Color) -> gameObjects.Color

Returns the result of mixing two colors. Abstracts the creation of a frozenset for the gameObjects.ColorScheme.mixingRecipes attribute.

Parameters

  • color1 : The first input color.
  • color2 : The second input color.
dataclass gameObjects.ShapePartType(code: str, hasColor: bool = True, canChangeColor: bool = True, connectsHorizontally: bool = True, crystalBehavior: bool = False, replacedByCrystal: bool = False)

The type of a shape part.

Parameters/Attributes

code: str

The part type's one letter code.

hasColor: bool = True

If the part can have a color.

canChangeColor: bool = True

If the part can change color, i.e. in a painter.

connectsHorizontally: bool = True

If the part connects to other parts horizontally and thus supports them and is supported by them.

crystalBehavior: bool = False

If the part has the behavior of crystals.

replacedByCrystal: bool = False

If the part is replaced by crystal in a crystal generator.

class gameObjects.ShapesConfiguration(id: str, numPartsPerLayer: int, pinPart: gameObjects.ShapePartType, crystalPart: gameObjects.ShapePartType, parts: list[tuple[gameObjects.ShapePartType, Literal[0, 1, 2, 3]]])

Represents an ingame shapes configuration.

Parameters

  • id : The shapes configuration's ID.
  • numPartsPerLayer : The number of parts each layer of a shape should have.
  • pinPart : The part type that should be considered a pin.
  • crystalPart : The part type that should be considered a crystal.
  • parts : The part types available in this shapes configuration. Each list element is a tuple of the shape part type and the map generation rareness : 0 for common, 1 for rare, 2 for very rare, 3 for doesn't generate on the map.

Attributes

id: str

The shapes configuration's ID.

numPartsPerLayer: int

The number of parts each layer of a shape should have.

The part type that should be considered a pin.

The part type that should be considered a crystal.

mapGenerationCommonParts: list[gameObjects.ShapePartType]

The part types that are considered common when generating shape asteroids.

mapGenerationRareParts: list[gameObjects.ShapePartType]

The part types that are considered rare when generating shape asteroids.

mapGenerationVeryRareParts: list[gameObjects.ShapePartType]

The part types that are considered very rare when generating shape asteroids.

The part types available in this shapes configuration.

partsByCode: dict[str, gameObjects.ShapePartType]

A mapping of each part type ID to its corresponding part type.

dataclass gameObjects.ShapePart(type: gameObjects.ShapePartType | None, color: gameObjects.Color | None)

Represents a part inside a shape.

Parameters/Attributes

The part's type or None if it's an empty part.

color: gameObjects.Color | None

The part's color or None if it doesn't have a color.

def toString() -> str

Returns the string representation of the shape part, like in a shape code.

def copy() -> gameObjects.ShapePart

Returns a shallow copy of the shape part.

class gameObjects.Shape(layers: list[list[gameObjects.ShapePart]])

Represents an ingame shape.

Parameters

  • layers : The shape's layers, each layer being a list of shape parts.

Attributes

layers: list[list[gameObjects.ShapePart]]

The shape's layers, each layer being a list of shape parts.

numLayers: int

The number of layers in the shape.

numParts: int

The number of parts each layer contains.

classmethod fromShapeCode(shapeCode: str, shapesConfig: gameObjects.ShapesConfiguration, colorScheme: gameObjects.ColorScheme = ingameData.DEFAULT_COLOR_SCHEME) -> gameObjects.Shape

Creates a shape object from a shape code.

Parameters

  • shapeCode : The shape code.
  • shapesConfig : The shapes configuration of the shape code.
  • colorScheme : The color scheme of the shape code, defaults to the ingame default color scheme.
def toShapeCode() -> str

Returns the shape code representing the shape.

def isEmpty() -> bool

Returns whether the shape is empty, i.e. whether it contains only empty parts.

def copy() -> gameObjects.Shape

Returns a copy of the shape, with the shape parts inside also copied.

ingameData

ingameData.DEFAULT_COLOR_SCHEME: gameObjects.ColorScheme

The default (and only) color scheme ingame.

ingameData.QUAD_SHAPES_CONFIG: gameObjects.ShapesConfiguration

The quad shapes configuration ingame.

ingameData.HEX_SHAPES_CONFIG: gameObjects.ShapesConfiguration

The hex shapes configuration ingame.

islands

dataclass islands.IslandTile(pos: utils.Pos, buildArea: list[utils.Rect])

Represents an island's tile.

Parameters/Attributes

The tile's position.

buildArea: list[utils.Rect]

The tile's buildable area, empty if not buildable.

class islands.Island(id: str, title: translations.MaybeTranslationString, tiles: list[islands.IslandTile], islandUnitCost: int | float, group: islands.IslandGroup)

Represents an island/platform.

Parameters

  • id : The island's ID.
  • title : The island's title.
  • tiles : The island's tiles.
  • islandUnitCost : The island's cost.
  • group : The island group this island belongs to.

Attributes

id: str

The island's ID.

The island's title.

tiles: list[islands.IslandTile]

The island's tiles.

islandUnitCost: int | float

The island's cost.

The island group this island belongs to.

totalBuildArea: list[utils.Rect]

The island's total build area, made from merging the build areas of all its tiles.

dataclass islands.IslandGroup(id: str, title: translations.MaybeTranslationString, islands: list[islands.Island])

Represents a group of similar islands, used for research unlocks.

Parameters/Attributes

id: str

The group's ID.

The group's title.

islands: list[islands.Island]

The islands this group contains.

islands.allIslands: dict[str, islands.Island]

A mapping of all the ingame island IDs to their corresponding island.

islands.allIslandGroups: dict[str, islands.IslandGroup]

A mapping of all the ingame island group IDs to their corresponding island group.

def islands.getCategorizedIslandCounts(counts: dict[islands.Island, int]) -> dict[islands.IslandGroup, dict[islands.Island, int]]

Categorizes counts of islands into island groups.

Parameters

  • counts : The raw island counts.

pygamePIL

The weird part of this library. The code of this library originates from ShapeBot 2, which was originally developed with pygame. To convert it to using Pillow, I created this interface which copies some of the pygame functions and classes to not have to change the code too much, although as a result, some functions might not be as efficient as if they were done with Pillow directly.

If you want to do further processing on a Surface generated by this library, there are 3 cases :

  • If you are using Pillow, you can use the _image attribute of Surface objects which points to the internal PIL.Image.Image.
  • If you are using pygame, use the instruction os.environ["SHAPEZ2_USE_PYGAME"] = "" before importing the shapez2 library. This will have the effect of replacing everything in the pygamePIL module with the real pygame objects. Additionally, if you have the shapez2 library listed as a dependency somewhere, you can use the optional dependency syntax shapez2[pygame] so that pygame will automatically be added as a dependency.
  • For other cases, use the pygamePIL.image.save function with either a file name to save it to a file, or a buffer to then load it using another library's image loading feature.

Thus, see the pygame documentation.

research

class research.Scenario()

Represents an ingame scenario. This class and all the classes contained inside roughly follow the scenario file format except that any object that's seriallized will instead be a custom class here, so their attributes won't be documented, except for the main differences.

dataclass research.FutureUpgrade(id: str)

Represents an upgrade (milestone/side upgrade) that doesn't exist in the current scenario.

Parameters/Attributes

id: str

The upgrade's ID.

class research.UnlockRequirements()

Replaces the RequiredUpgradeIds and RequiredMechanicIds keys of an object.

Attributes

requiredMilestones: list[research.Milestone]

The required milestones.

requiredSideUpgrades: list[research.SideUpgrade]

The required side upgrades.

requiredFutureUpgrades: list[research.FutureUpgrade]

The required future upgrades.

requiredMechanics: list[research.Mechanic]

The required mechanics.

class research.Rewards()

Replaces a list of reward objects.

Attributes

buildingVariants: list[buildings.BuildingVariant]

The rewarded building variants.

islandGroups: list[islands.IslandGroup]

The rewarded island groups.

mechanics: list[research.Mechanic]

The rewarded mechanics.

wikiEntries: list[str]

The rewarded knowledge panel pages.

blueprintCurrency: int

The amount of blueprint points rewarded.

chunkLimit: int

The amount of platform units rewarded.

researchPoints: int

The amount of research points rewarded.

buildingInternalVariants: list[buildings.BuildingInternalVariant]

The rewarded building internal variants. Not defined in the scenario but deduced from the rewarded building variants.

islands: list[islands.Island]

The rewarded islands. Not defined in the scenario but deduced from the rewarded island groups.

class research.ScenarioDecodeError(Exception)

The error raised if something is invalid while decoding a scenario.

def research.decodeScenario(rawScenario: str) -> tuple[research.Scenario, list[str]]

Creates a scenario object from a raw string of json data. Returns a tuple of the scenario and a list of warning messages. Raises research.ScenarioDecodeError if the given data is invalid.

Parameters

  • rawScenario : The raw json data.
def research.encodeScenario(scenario: research.Scenario) -> str

Encodes a scenario object into raw json data. Note : this function currently doesn't have an intended use as the modification or creation of scenario data classes is not supported.

Parameters

  • scenario : The scenario to encode.
research.ingameScenarios: dict[str, research.Scenario]

A mapping of each ingame scenario ID to its corresponding scenario object.

shapeCodes

shapeCodes.LAYER_SEPARATOR: Literal[":"]

The character that separates layers in shape codes.

shapeCodes.EMPTY_CHAR: Literal["-"]

The character that's used to indicate an empty shape or no color in shape codes.

def shapeCodes.isShapeCodeValid(potentialShapeCode: str, shapesConfig: gameObjects.ShapesConfiguration | None, emptyShapeInvalid: bool = False) -> tuple[bool, str | None, gameObjects.ShapesConfiguration | None]

Check if a shape code is valid. Returns a tuple with 3 elements : whether the shape code is valid, the error message or None if the shape code was valid, the shapes configuration that was used to check the shape code or None if it didn't make it to that step.

Parameters

  • potentialShapeCode : The shape code to check.
  • shapesConfig : If the shape is supposed to be in a specific shapes configuration, then that shapes config, otherwise None, which will check the shape in both ingame shapes configs and choose the first one that works.
  • emptyShapeInvalid : If the shape code represents a fully empty shape, whether or not to consider it invalid.

shapeOperations

This module contains all shape operations as functions. All of them share these properties :

class shapeOperations.InvalidOperationInputs(ValueError)

The error raised if a shape operation can't process some inputs.

dataclass shapeOperations.ShapeOperationConfig(maxShapeLayers: int, shapesConfig: gameObjects.ShapesConfiguration)

The configuration settings that are passed to shape operations.

Parameters/Attributes

maxShapeLayers: int

The maximum number of layers output shapes can have in operations that can increase the number of layers of input shapes.

The shapes configuration that will be used for the operation.

shapeViewer

Renders a shape as an image.

Parameters

  • shape : The shape to render.
  • surfaceSize : What size will the returned surface be.
  • colorMode : Which color mode to use to render the shape.
  • shapesConfig : Which shapes configuration to use to render the shape.

translations

class translations.TagType(enum.Enum)

The type of a translations.FeatureTag.

Attributes

single: Literal["single"]

A self closing tag, i.e. <tag/>.

start: Literal["start"]

An opening tag, i.e. <tag>.

end: Literal["end"]

An ending tag, i.e. </tag>.

class translations.ValueSep(enum.Enum)

The type of value separator in a translations.FeatureTag.

Attributes

colon: Literal[":"]

A colon separator, i.e. <name:value>.

equals: Literal["="]

An equals separator, i.e. <name="value"> or <name=value>.

dataclass translations.FeatureTag(type: translations.TagType, feature: str, value: str | None, valueSep: translations.ValueSep | None)

Represents a tag inside a translation string.

Parameters/Attributes

The type of tag.

feature: str

The name of this tag's feature.

value: str | None

The value associated with the feature, if any.

valueSep: translations.ValueSep | None

The type of value separator, if there is a value.

def toString() -> str

Returns the tag's string representation.

dataclass translations.FeatureString(components: list[str | translations.FeatureTag])

Represents a string with additonal styling and content modifying features using feature tags. Some rendering methods are provided with the functions listed below. For other rendering implementations, the translations.FeatureString.components attribute should be used.

Parameters/Attributes

components: list[str | translations.FeatureTag]

The list of strings and feature tags composing the feature string. When the object is created, components are sanitized : empty strings are removed and adjacent strings are merged together.

def replaceParams(params: dict[str, str], default: str | None) -> translations.FeatureString

Returns a new feature string with parameters inside the string replaced with some values. A parameter is any feature tag that's of type translations.TagType.single. The translations.FeatureTag.feature is considered to be the parameter name.

Parameters

  • params : A mapping of parameter names to what string they should be replaced with. If a parameter name is present in this dictionary but not inside the feature string, it will be silently ignored.
  • default : The string to use if the feature string contains a parameter name that's not in the params argument. If None, instead a ValueError is raised when an unknown parameter is encountered.
def renderToRawString() -> str

Returns a string representation of the components with feature tags included.

def renderToStringNoFeatures() -> str

Returns a concatenation of the string components without feature tags.

def renderToSurface(font: pygamePIL.font.Font, boldFont: pygamePIL.font.Font) -> pygamePIL.Surface

Returns an image representation of the string. New lines as well as the following tags are supported : <b>,<u>,<gl>,<link>,<color="#hex">, <color="named-color"> (supported named colors).

Parameters

  • font : The font to use to render regular text.
  • boldFont : The font to use to render bold text.
class translations.Language(enum.Enum)

A translation language.

Attributes

en_US: Literal["en-US"]

English.

translations.FALLBACK_LANGUAGE: Literal[translations.Language.en_US]

The language used as a fallback when a translation doesn't exist in an other language, also used as a default value for function arguments.

dataclass translations.TranslationString(key: str)

Represents a string that's ready to be translated.

Parameters/Attributes

key: str

The translation key, for example research.RNBlueprints.title.

Translate the string into a given language. If it isn't found in that language, translations.FALLBACK_LANGUAGE is used instead. If it isn't found there either, a feature string of just the translation key is returned.

Parameters

  • language : The language to translate into.
class translations.MaybeTranslationString(key: str)

ⓘ This class inherits from translations.TranslationString

Represents a translation string coming from a source that could either be a translation key or a raw feature string.

Parameters

  • key : The raw source. If the string starts with @, what's after the @ will be considered a translation key. Otherwise, the string will be treated as a raw feature string.

Attributes

key: str | None

The translation key or None if it's a raw feature string.

rawString: str | None

The raw feature string or None if it's a regular translation string.

If a regular translation string, same as translations.TranslationString.translate. Otherwise, returns a feature string from translations.MaybeTranslationString.rawString.

Parameters

  • language : The language to translate into.
def getRaw() -> str

Returns the source from which this string originated, i.e. the translation key with a @ in front or the raw feature string.

def translations.getRawTranslation(key: str, language: translations.Language = translations.FALLBACK_LANGUAGE) -> str

Returns the raw string associated to a translation key in a specific language. If it isn't found in that language, translations.FALLBACK_LANGUAGE is used instead. If it isn't found there either, the translation key is returned.

Parameters

  • key : The translation key.
  • language : The language to translate into.
def translations.featureStringFromRaw(rawString: str) -> translations.FeatureString

Returns a feature string object from a raw feature string.

Parameters

  • rawString : The raw feature string.

utils

def utils.isNumber(string: str) -> bool

Returns whether a string is non-empty and is composed of only digits.

Parameters

  • string : The string to search.
def utils.decodeStringWithLen(string: bytes, numBytesForLen: int = 2, emptyIsLengthNegative1: bool = True) -> bytes

Decode a byte string which has its length encoded as a prefix. This format is for example used in blueprints and savegames. Raises ValueError if the format is invalid.

Parameters

  • string : The string to decode.
  • numBytesForLen : The number of bytes used to encode the length.
  • emptyIsLengthNegative1 : Whether a length of -1 signifies a length of 0.
def utils.encodeStringWithLen(string: bytes, numBytesForLen: int = 2, emptyIsLengthNegative1: bool = True) -> bytes

Encode a byte string with its length as a prefix (see above for more details).

Parameters

  • string : The string to encode.
  • numBytesForLen : The number of bytes used to encode the length.
  • emptyIsLengthNegative1 : Whether the encoded length should be changed to -1 if the string's length is 0.
dataclass utils.Rotation(value: int)

Represents the rotation of something.

Parameters/Attributes

value: int

The rotation value as a number, 0 means East, 1 means South, 2 means West, 3 means North.

def rotateCW(numTimes: int | utils.Rotation) -> utils.Rotation

Creates a new Rotation rotated 90° clockwise some number of times.

Parameters

  • numTimes : The number of times to rotate clockwise. If a Rotation, the utils.Rotation.value is used.
dataclass utils.FloatPos(x: float, y: float, z: float = 0.0)

Represents a position with float coordinates.

Parameters/Attributes

x: float

The X coordinate.

y: float

The Y coordinate.

z: float = 0.0

The Z coordinate.

dataclass utils.Pos(x: int, y: int, z: int = 0)

Represents a position with integer coordinates.

Parameters/Attributes

x: int

The X coordinate.

y: int

The Y coordinate.

z: int = 0

The Z coordinate.

def rotateCW(numTimes: int | utils.Rotation, aroundCenter: utils.FloatPos = FloatPos(0,0)) -> utils.Pos

Returns a new position rotated 90° clockwise some number of times.

Parameters

  • numTimes : The number of times to rotate clockwise. If a Rotation, the utils.Rotation.value is used.
  • aroundCenter : The center of rotation to use.
dataclass utils.Size(width: int, height: int, depth: int = 0)

Represents the size of something.

Parameters/Attributes

width: int

The width, i.e. the size on the X axis.

height: int

The height, i.e. the size on the Y axis.

depth: int = 0

The depth, i.e. the size on the Z axis.

def rotateCW(numTimes: int | utils.Rotation) -> utils.Size

Creates a new Size rotated 90° clockwise some number of times.

Parameters

  • numTimes : The number of times to rotate clockwise. If a Rotation, the utils.Rotation.value is used.
dataclass utils.Rect(topLeft: utils.Pos, size: utils.Size)

Represents a rectangular area.

Parameters/Attributes

topLeft: utils.Pos

The position of the top left corner.

The size of the retangle, only the width and height attributes are used.

def rotateCW(numTimes: int | utils.Rotation, aroundCenter: utils.FloatPos = FloatPos(0,0)) -> utils.Rect

Returns a new rectangle rotated 90° clockwise some number of times.

Parameters

  • numTimes : The number of times to rotate clockwise. If a Rotation, the utils.Rotation.value is used.
  • aroundCenter : The center of rotation to use.
def containsPos(pos: utils.Pos) -> bool

Returns whether a position is contained inside the rectangle.

Parameters

  • pos : The position to check.
def utils.loadPos(raw: dict[str, int]) -> utils.Pos

Creates a Pos object from a raw dictionary with X, Y, and Z keys, where all of them can be missing and default to 0.

Parameters

  • raw : The raw data.
class utils.DirectionType(typing.TypedDict)

The return type of utils.loadDirection.

Attributes

The position.

The rotation.

def utils.loadDirection(raw: dict) -> utils.DirectionType

Creates a direction, a direction being a rotation associated to a position. The raw data is a dictionary with a Position_L key for the position (same format as in utils.loadPos) which defaults to a Pos(0,0,0), and a Direction_L key for the rotation which defaults to 0.

Parameters

  • raw : The raw data.

versions

versions.GAME_VERSIONS: dict[int, list[str]]

A mapping of version numbers to the corresponding list of version IDs.

versions.LATEST_GAME_VERSION: int

The latest game version number.

versions.LATEST_MAJOR_VERSION: int

The latest major version number, used in blueprints.

dataclass versions.AlphaSuffix(version: str, subVersion: str | None)

Represents an alpha suffix in a versions.VersionName. The alpha version takes the form of version.subVersion.

Parameters/Attributes

version: str

The main alpha version.

subVersion: str | None

The alpha sub version or None if there isn't one.

dataclass versions.ReleaseCandidateSuffix(number: str)

Represents a release candidate suffix in a versions.VersionName.

Parameters/Attributes

number: str

The release candidate number.

dataclass versions.PreviewSuffix(number: str)

Represents a preview suffix in a versions.VersionName.

Parameters/Attributes

number: str

The preview number.

class versions.DemoSuffix()

Represents a demo suffix in a versions.VersionName.

dataclass versions.VersionName(major: str, minor: str, patch: str, suffixes: list[versions.AlphaSuffix | versions.ReleaseCandidateSuffix | versions.PreviewSuffix | versions.DemoSuffix])

Represents the name of a version, in the form of major.minor.patch-suffix1-suffix2....

Parameters/Attributes

major: str

The version's major number.

minor: str

The version's minor number.

patch: str

The version's patch number.

The version's suffixes.

def versions.getVersionNameFromId(versionId: str) -> versions.VersionName

Returns a version name object from a version ID.

Parameters

  • versionId : The version ID.
def versions.versionNameToString(versionName: versions.VersionName) -> str

Returns a string representation of version name object.

Parameters

  • versionName : The version name.

This documentation is generated with code I made myself, but the style is inspired by the Sphinx documentation generator, and in particular the style used by the discord.py library documentation.