foundry.game package#

Subpackages#

Submodules#

foundry.game.Data module#

class MapscreenPointerLocation(count, offset)#

Bases: tuple

count#: Alias for field number 0

offset#: Alias for field number 1

class Mario3Level(game_world, level_in_world, rom_level_offset, enemy_offset, real_obj_set, name)#

Bases: NamedTuple

enemy_offset: int#: Alias for field number 3

game_world: int#: Alias for field number 0

level_in_world: int#: Alias for field number 1

name: str#: Alias for field number 5

real_obj_set: int#: Alias for field number 4

rom_level_offset: int#: Alias for field number 2

class ObjectInfo(index, subindex, x, y, width, height, x2, y2, obj, objtype, rect, drag)#

Bases: tuple

drag#: Alias for field number 11

height#: Alias for field number 5

index#: Alias for field number 0

obj#: Alias for field number 8

objtype#: Alias for field number 9

rect#: Alias for field number 10

subindex#: Alias for field number 1

width#: Alias for field number 4

x#: Alias for field number 2

x2#: Alias for field number 6

y#: Alias for field number 3

y2#: Alias for field number 7

read_string_dict(path)#

foundry.game.Definitions module#

pydantic model Definition#

Bases: BaseModel

Show JSON schema

{
   "title": "Definition",
   "type": "object",
   "properties": {
      "description": {
         "title": "Description",
         "default": "",
         "type": "string"
      },
      "warnings": {
         "title": "Warnings",
         "default": [],
         "type": "array",
         "items": {
            "$ref": "#/definitions/WarningCreator"
         }
      },
      "overlays": {
         "title": "Overlays"
      }
   },
   "definitions": {
      "WarningCreator": {
         "title": "WarningCreator",
         "type": "object",
         "properties": {}
      }
   }
}

Config:

use_enum_values: bool = True

Fields:

description (str)
overlays (list[foundry.core.drawable.Drawable])
warnings (list[foundry.core.warnings.WarningCreator.WarningCreator])

field description: str = ''#

field overlays: list[foundry.core.drawable.Drawable] = []#

field warnings: list[foundry.core.warnings.WarningCreator.WarningCreator] = []#

get_overlays() → list[foundry.core.drawable.Drawable]#

get_warnings() → list[foundry.core.warnings.Warning.Warning]#

foundry.game.EnemyDefinitions module#

pydantic model EnemyDefinition#

Bases: Definition

Show JSON schema

{
   "title": "EnemyDefinition",
   "type": "object",
   "properties": {
      "description": {
         "title": "Description",
         "default": "",
         "type": "string"
      },
      "warnings": {
         "title": "Warnings",
         "default": [],
         "type": "array",
         "items": {
            "$ref": "#/definitions/WarningCreator"
         }
      },
      "overlays": {
         "title": "Overlays"
      },
      "bmp_width": {
         "title": "Bmp Width",
         "default": 1,
         "type": "integer"
      },
      "bmp_height": {
         "title": "Bmp Height",
         "default": 1,
         "type": "integer"
      },
      "rect_width": {
         "title": "Rect Width",
         "default": 0,
         "type": "integer"
      },
      "rect_height": {
         "title": "Rect Height",
         "default": 0,
         "type": "integer"
      },
      "rect_x_offset": {
         "title": "Rect X Offset",
         "default": 0,
         "type": "integer"
      },
      "rect_y_offset": {
         "title": "Rect Y Offset",
         "default": 0,
         "type": "integer"
      },
      "icon_width": {
         "title": "Icon Width",
         "default": 0,
         "type": "integer"
      },
      "icon_height": {
         "title": "Icon Height",
         "default": 0,
         "type": "integer"
      },
      "icon_x_offset": {
         "title": "Icon X Offset",
         "type": "integer"
      },
      "icon_y_offset": {
         "title": "Icon Y Offset",
         "type": "integer"
      },
      "sprites": {
         "title": "Sprites",
         "type": "array",
         "items": {
            "$ref": "#/definitions/Sprite"
         }
      },
      "blocks": {
         "title": "Blocks",
         "type": "array",
         "items": {
            "type": "integer"
         }
      },
      "pages": {
         "title": "Pages",
         "type": "array",
         "items": {
            "type": "integer"
         }
      },
      "orientation": {
         "default": 9,
         "allOf": [
            {
               "$ref": "#/definitions/GeneratorType"
            }
         ]
      },
      "check_level_bounds": {
         "title": "Check Level Bounds",
         "default": true,
         "type": "boolean"
      },
      "check_compatibility": {
         "title": "Check Compatibility",
         "default": true,
         "type": "boolean"
      }
   },
   "definitions": {
      "WarningCreator": {
         "title": "WarningCreator",
         "type": "object",
         "properties": {}
      },
      "Sprite": {
         "title": "Sprite",
         "description": "Defines a given sprite and its properties",
         "type": "object",
         "properties": {
            "index": {
               "title": "Index",
               "type": "integer"
            },
            "palette_index": {
               "title": "Palette Index",
               "default": 1,
               "type": "integer"
            },
            "x_offset": {
               "title": "X Offset",
               "default": 0,
               "type": "integer"
            },
            "y_offset": {
               "title": "Y Offset",
               "default": 0,
               "type": "integer"
            },
            "horizontal_mirror": {
               "title": "Horizontal Mirror",
               "default": false,
               "type": "boolean"
            },
            "vertical_mirror": {
               "title": "Vertical Mirror",
               "default": false,
               "type": "boolean"
            }
         },
         "required": [
            "index"
         ]
      },
      "GeneratorType": {
         "title": "GeneratorType",
         "description": "\n    The various different ways enemies can be represented inside the game.\n    ",
         "enum": [
            0,
            9,
            10
         ],
         "type": "integer"
      }
   }
}

Config:

use_enum_values: bool = True

Fields:

blocks (list[int])
bmp_height (int)
bmp_width (int)
check_compatibility (bool)
check_level_bounds (bool)
icon_height (int)
icon_width (int)
icon_x_offset (int | None)
icon_y_offset (int | None)
orientation (foundry.game.EnemyDefinitions.GeneratorType)
pages (list[int])
rect_height (int)
rect_width (int)
rect_x_offset (int)
rect_y_offset (int)
sprites (list[foundry.game.EnemyDefinitions.Sprite])

field blocks: list[int] [Optional]#

field bmp_height: int = 1#

field bmp_width: int = 1#

field check_compatibility: bool = True#

field check_level_bounds: bool = True#

field icon_height: int = 0#

field icon_width: int = 0#

field icon_x_offset: int | None = None#

field icon_y_offset: int | None = None#

field orientation: GeneratorType = GeneratorType.SINGLE_BLOCK_OBJECT#

field pages: list[int] [Optional]#

field rect_height: int = 0#

field rect_width: int = 0#

field rect_x_offset: int = 0#

field rect_y_offset: int = 0#

field sprites: list[foundry.game.EnemyDefinitions.Sprite] [Optional]#

get_warnings() → list[foundry.core.warnings.Warning.Warning]#

property suggested_icon_height: int#

Provides the suggested icon height, as the icon height my not be set.

Returns:

int: The suggested icon height.

property suggested_icon_width: int#

Provides the suggested icon width, as the icon width my not be set.

Returns:

int: The suggested icon width.

property suggested_icon_x_offset: int#

Provides the suggested icon x offset, as the icon x offset may be None.

Returns:

int: The suggested icon x offset.

property suggested_icon_y_offset: int#

Provides the suggested icon y offset, as the icon y offset may be None.

Returns:

int: The suggested icon y offset.

pydantic model EnemyDefinitions#

Bases: BaseModel

Show JSON schema

{
   "title": "EnemyDefinitions"
}

Fields:

__root__ (list[foundry.game.EnemyDefinitions.EnemyDefinition])

class GeneratorType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: int, Enum

The various different ways enemies can be represented inside the game.

CENTERED = 10#

SINGLE_BLOCK_OBJECT = 9#

SINGLE_SPRITE_OBJECT = 0#

pydantic model Sprite#

Bases: BaseModel

Defines a given sprite and its properties

Show JSON schema

{
   "title": "Sprite",
   "description": "Defines a given sprite and its properties",
   "type": "object",
   "properties": {
      "index": {
         "title": "Index",
         "type": "integer"
      },
      "palette_index": {
         "title": "Palette Index",
         "default": 1,
         "type": "integer"
      },
      "x_offset": {
         "title": "X Offset",
         "default": 0,
         "type": "integer"
      },
      "y_offset": {
         "title": "Y Offset",
         "default": 0,
         "type": "integer"
      },
      "horizontal_mirror": {
         "title": "Horizontal Mirror",
         "default": false,
         "type": "boolean"
      },
      "vertical_mirror": {
         "title": "Vertical Mirror",
         "default": false,
         "type": "boolean"
      }
   },
   "required": [
      "index"
   ]
}

Fields:

horizontal_mirror (bool)
index (int)
palette_index (int)
vertical_mirror (bool)
x_offset (int)
y_offset (int)

field horizontal_mirror: bool = False#

field index: int [Required]#

field palette_index: int = 1#

field vertical_mirror: bool = False#

field x_offset: int = 0#

field y_offset: int = 0#

get_enemy_metadata() → EnemyDefinitions#

foundry.game.File module#

class INESHeader(program_banks: int, character_banks: int, mapper: int, horizontal_mirroring: bool, battery_backed_ram: bool)#

Bases: object

The representation of the header inside the ROM, following the INES format. Regarding the specifics of the INES format, more information can be found at INES.

Attributes:

INESHEADER_PREFIX: ClassVar[bytes]: The required prefix for any INES header.
BASE_PROGRAM_SIZE: ClassVar[int]: The base program size for a standard copy of SMB3.
PROGRAM_BANK_SIZE: ClassVar[int]: The size of any program bank.
CHARACTER_BANK_SIZE: ClassVar[int]: The size of any character bank.
INES_HEADER_SIZE: The size of the INES header.
program_banks: int: The amount of 8kb banks of program data inside the file.
character_banks: int: The amount of 4kb banks of graphical data inside the file.
mapper: int: The memory mapper used by the file.
horizontal_mirroring: bool: If the file uses horizontal mirroring, otherwise it is assumed it uses vertical mirroring. See Nametable_Mirroring for more information.
battery_backed_ram: bool: If the file contains battery-backed RAM between 0x6000 and 0x7FFF or any other form of persistent memory.

BASE_PROGRAM_SIZE: ClassVar[int] = 262144#

CHARACTER_BANK_SIZE: ClassVar[int] = 8192#

INESHEADER_PREFIX: ClassVar[bytes] = b'NES\x1a'#

INES_HEADER_SIZE: ClassVar[int] = 16#

PROGRAM_BANK_SIZE: ClassVar[int] = 16384#

static address_is_global(address: int, program_banks: int) → bool#

Determines if the address is inside the last two, global, banks of SMB3.

Parameters:

addressint: The address to check.
program_banksint: The amount of program banks.

Returns:

bool: If the address is global.

battery_backed_ram: bool#

character_banks: int#

property character_size: int#

The amount of space dedicated to character data.

Returns:

int: The amount of bytes provided for character data.

classmethod from_data(data: bytes, path: str | None = None) → Self#

Generates an INES header from a file following the header.

Parameters:

databytes: The data to generate the header from.
pathOptional[str], optional: The path used for better exception information, by default None

Returns:

INESHeader: The newly generated header.

Raises:

InvalidINESHeader: If the data does not follow an INES header.

horizontal_mirroring: bool#

mapper: int#

normalized_address(address: int, program_size: int = 262144) → int#

Finds an address that would better account for ROM expansions.

Parameters:

addressint: The address to normalize.
program_sizeint, optional: The program size of the original ROM, by default BASE_PROGRAM_SIZE

Returns:

int: The normalized address.

static program_address(address: int) → int#

Provides the address shifted to make the start of the program data start at the first index.

Parameters:

addressint: To shift to account for the size of the header.

Returns:

int: The absolute program address.

program_banks: int#

property program_size: int#

The amount of space dedicated to program data.

Returns:

int: The amount of bytes provided for program banks.

static relative_address(address: int) → int#

Provides the relative address that would be references inside the ROM.

Parameters:

addressint: The absolute address.

Returns:

int: The relative address.

property vertical_mirroring: bool#

Determines if the file uses vertical mirroring. See Nametable_Mirroring for more information.

Returns:

bool: If the file uses vertical mirroring.

exception InvalidINESHeader(file_path: str | None = None)#

Bases: TypeError

An exception that is raised if a file does not follow an INES header when it is meant to.

class ROM(path: str | None = None)#

Bases: Rom

MARKER_VALUE: ClassVar[bytes] = b'SMB3FOUNDRY'#

NINTENDO_MARKER_VALUE: ClassVar[bytes] = b'SUPER MARIO 3'#

W_INIT_OS_LIST: list[int] = []#

bulk_read(count: int, position: int, *, is_graphics: bool = False) → bytearray#

bulk_write(data: bytearray, position: int)#

generate_tag() → int | None#

Generates a identification tag for a file. This enables the file to be references later on.

This tag will include the ROM_MARKER value and eight random bytes that serve as the ID of the file.

Returns:

Optional[int]: The ID of the file, if the tag was successfully generated and applied.

get_byte(position: int) → int#

get_id() → int | None#

Determines the ID of the file.

Returns:

Optional[int]: The ID of the file, if one can exist.

static get_tsa_data(tileset: int) → bytearray#

header: INESHeader#

property identifier: str#

Provides an identifier for the file.

Returns:

str: The identifier associated with this file.

static is_loaded() → bool#

static load_from_file(path: str)#

name: str = ''#

path: str = ''#

rom_data = bytearray(b'')#

static save_to_file(path: str, set_new_path=True)#

static set_additional_data(additional_data)#

property settings: FileSettings#

Provides the settings for the file.

Returns:

FileSettings: The settings associated with this file.

static write_tsa_data(tileset: int, tsa_data: bytearray)#

getrandbits(k, /)#

foundry.game.ObjectDefinitions module#

class EndType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: int, Enum

Some level objects have blocks designated to be used at their ends. For example pipes, which can be extended, but always end at one side with the same couple of blocks. To keep track of where those special blocks are to be placed, this enum is used. When the value is TWO_ENDS they are always on opposite sides and whether they are left and right or top and bottom depends on the generator type of the object.

END_ON_BOTTOM_OR_RIGHT = 2#

END_ON_TOP_OR_LEFT = 1#

TWO_ENDS = 3#

UNIFORM = 0#

class GeneratorType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: int, Enum

Level objects are generated using different methods, depending on their generator type. Some objects extend until they hit another object, some extend up to the sky. To identify in what way a specific type of level object is constructed, this enum lists the known generator types.

CENTERED = 10#

DESERT_PIPE_BOX = 3#

DIAG_DOWN_LEFT = 2#

DIAG_DOWN_RIGHT = 4#

DIAG_UP_RIGHT = 5#

DIAG_WEIRD = 8#

ENDING = 14#

HORIZONTAL = 0#

HORIZONTAL_2 = 7#

HORIZ_TO_GROUND = 6#

PYRAMID_2 = 12#

PYRAMID_TO_GROUND = 11#

SINGLE_BLOCK_OBJECT = 9#

TO_THE_SKY = 13#

VERTICAL = 1#

pydantic model Tileset#

Bases: BaseModel

Show JSON schema

{
   "title": "Tileset"
}

Fields:

__root__ (list[foundry.game.ObjectDefinitions.TilesetDefinition])

pydantic model TilesetDefinition#

Bases: Definition

Show JSON schema

{
   "title": "TilesetDefinition",
   "type": "object",
   "properties": {
      "description": {
         "title": "Description",
         "default": "",
         "type": "string"
      },
      "warnings": {
         "title": "Warnings",
         "default": [],
         "type": "array",
         "items": {
            "$ref": "#/definitions/WarningCreator"
         }
      },
      "overlays": {
         "title": "Overlays"
      },
      "domain": {
         "title": "Domain",
         "type": "integer"
      },
      "min_value": {
         "title": "Min Value",
         "type": "integer"
      },
      "max_value": {
         "title": "Max Value",
         "type": "integer"
      },
      "bmp_width": {
         "title": "Bmp Width",
         "type": "integer"
      },
      "bmp_height": {
         "title": "Bmp Height",
         "type": "integer"
      },
      "blocks": {
         "title": "Blocks",
         "type": "array",
         "items": {
            "type": "integer"
         }
      },
      "orientation": {
         "$ref": "#/definitions/GeneratorType"
      },
      "ending": {
         "$ref": "#/definitions/EndType"
      },
      "size": {
         "title": "Size",
         "default": 3,
         "type": "integer"
      },
      "check_level_bounds": {
         "title": "Check Level Bounds",
         "default": true,
         "type": "boolean"
      }
   },
   "required": [
      "domain",
      "min_value",
      "max_value",
      "bmp_width",
      "bmp_height",
      "blocks",
      "orientation",
      "ending"
   ],
   "definitions": {
      "WarningCreator": {
         "title": "WarningCreator",
         "type": "object",
         "properties": {}
      },
      "GeneratorType": {
         "title": "GeneratorType",
         "description": "\n    Level objects are generated using different methods, depending on their generator type. Some objects extend until\n    they hit another object, some extend up to the sky. To identify in what way a specific type of level object is\n    constructed, this enum lists the known generator types.\n    ",
         "enum": [
            0,
            1,
            2,
            3,
            4,
            5,
            6,
            7,
            8,
            9,
            10,
            11,
            12,
            13,
            14
         ],
         "type": "integer"
      },
      "EndType": {
         "title": "EndType",
         "description": "\n    Some level objects have blocks designated to be used at their ends. For example pipes, which can be extended, but\n    always end at one side with the same couple of blocks. To keep track of where those special blocks are to be placed,\n    this enum is used. When the value is TWO_ENDS they are always on opposite sides and whether they are left and right\n    or top and bottom depends on the generator type of the object.\n    ",
         "enum": [
            0,
            1,
            2,
            3
         ],
         "type": "integer"
      }
   }
}

Config:

use_enum_values: bool = True

Fields:

blocks (list[int])
bmp_height (int)
bmp_width (int)
check_level_bounds (bool)
domain (int)
ending (foundry.game.ObjectDefinitions.EndType)
max_value (int)
min_value (int)
orientation (foundry.game.ObjectDefinitions.GeneratorType)
size (int)

field blocks: list[int] [Required]#

field bmp_height: int [Required]#

field bmp_width: int [Required]#

field check_level_bounds: bool = True#

field domain: int [Required]#

field ending: EndType [Required]#

field max_value: int [Required]#

field min_value: int [Required]#

field orientation: GeneratorType [Required]#

field size: int = 3#

get_warnings() → list[foundry.core.warnings.Warning.Warning]#

property is_4byte: bool#

property object_design_length: int#

pydantic model Tilesets#

Bases: BaseModel

Show JSON schema

{
   "title": "Tilesets"
}

Fields:

__root__ (list[foundry.game.ObjectDefinitions.Tileset])

get_object_metadata() → Tilesets#

foundry.game.Tileset module#

class Tileset(tileset: int)#

Bases: object

get_definition_of(object_id: int) → TilesetDefinition#

get_ending_offset() → int#

get_object_byte_length(domain: int, object_id: int) → int#

object_type(domain: int, index: int) → int#

foundry.game package#

Subpackages#

Submodules#

foundry.game.Data module#

foundry.game.Definitions module#

foundry.game.EnemyDefinitions module#

foundry.game.File module#

foundry.game.ObjectDefinitions module#

foundry.game.Tileset module#

Module contents#