Code-Reference

class game_core.src.core.Core(title='GameCore <3', start_scene=None, size=(480, 480), background_color=(0, 0, 0, 0), fps=30, display=0, window_flags=pygame.DOUBLEBUF, window_depth=32)

Main game framework for managing the game loop, rendering, and engines.

Variables:

• window – main draw surface.

• window_size – (X,Y) Dimensions of the game window.

• background_color – Background color of the game window.

• is_running – Indicates if the game is running.

• locked_fps – Target frames per second for the game loop.

__init__(title='GameCore <3', start_scene=None, size=(480, 480), background_color=(0, 0, 0, 0), fps=30, display=0, window_flags=pygame.DOUBLEBUF, window_depth=32)

Initializes the Core framework.

Parameters:

• title (str) – Title of the game window.

• size (tuple) – Dimensions of the game window.

• background_color (tuple) – Background color of the window.

• fps (int) – Target frames per second.

• display (int) – Display index for the game window.

• window_flags (int) – Pygame flags for the window.

• window_depth (int) – Bit depth for the window.

get_scene_manager()

Retrieves the SceneManager instance.

Returns:

The SceneManager instance.

Return type:

SceneManager

get_layer_surface(name)

Retrieves the surface associated with a specific layer by its name.

Parameters:

name (str) – The name of the layer whose surface is to be retrieved.

Returns:

The surface object of the specified layer.

Return type:

pygame.Surface

remove_layer_surface(name)

Removes a layer and its associated surface by name.

Parameters:

name (str) – The name of the layer to remove.

move_layer_surface(name, position)

Updates the position of an existing layer’s surface.

Parameters:

• name (str) – The name of the layer whose surface position is to be updated.

• position (tuple[int, int]) – The new top-left position of the surface in (x, y) coordinates.

create_layer_surface(name=None, width=0, height=0, x=0, y=0, render_layer: int = 0, fill_after_draw=True)

Creates a new rendering layer surface.

Parameters:

• name (str) – Name of the surface.

• width (int) – Width of the surface.

• height (int) – Height of the surface.

• x (int) – X-coordinate of the surface.

• y (int) – Y-coordinate of the surface.

• render_layer (int) – Rendering order of the surface.

• fill_after_draw (bool) – Auto-fill the surface after drawing.

Returns:

The created surface.

Return type:

pygame.Surface

create_surface(size=None)

Creates a new surface with specified dimensions.

Parameters:

size (tuple[int, int], optional) – The size of the surface as a (width, height) tuple. Defaults to the size of the main window if not specified.

Returns:

A new surface object with the specified or default size.

Return type:

pygame.Surface

draw_surface(surface, position=None)

Draws a surface onto the main window at a specified position.

Parameters:

• surface (pygame.Surface) – The surface to draw.

• position (tuple[int, int], optional) – The top-left position where the surface will be drawn, specified as a (x, y) tuple. Defaults to (0, 0).

__weakref__

list of weak references to the object (if defined)

instantiate(engine, **kwargs)

Creates and initializes a new instance of an engine class at runtime. This method is particularly suitable for creating prefabs, which are reusable templates as engines.

Parameters:

• engine (type) – The engine class to instantiate. Must be a subclass of Engine.

• kwargs – Optional parameters to pass to the engine’s awake method.

Returns:

The instantiated and initialized engine instance.

Return type:

Engine

Raises:

TypeError – If the provided engine is not a subclass of Engine.

destroy(engine)

Destroys an engine instance and removes it from the list of active engines.

Parameters:

engine (Engine) – The engine instance to destroy.

Raises:

TypeError – If the provided engine is not an instance of Engine.

class game_core.src.core.Coroutine(func, interval=None, loop_condition=<function Coroutine.<lambda>>, call_delay=None, func_args=None, func_kwargs=None)

Represents a coroutine that periodically executes a function.

Variables:

is_dead – Indicates whether the coroutine is inactive.

__init__(func, interval=None, loop_condition=<function Coroutine.<lambda>>, call_delay=None, func_args=None, func_kwargs=None)

Initializes the Coroutine.

Parameters:

• func (callable) – The function to execute periodically. The function can update the ‘interval’, ‘func_args’, and ‘func_kwargs’ by returning them in a dictionary.

• interval (float) – The time interval (in milliseconds) between executions.

• loop_condition (callable) – A function returning a boolean that determines if the coroutine should continue.

• call_delay (float) – Initial delay before the first execution (in milliseconds).

• func_args (tuple) – Positional arguments to pass to func.

• func_kwargs (dict) – Keyword arguments to pass to func.

__weakref__

list of weak references to the object (if defined)

class game_core.src.core.Engine(core)

Represents a game engine responsible for managing coroutines and state machines.

Variables:

• core – Reference to the Core instance managing the game loop.

• is_enabled – Indicates whether the engine is active.

• priority_layer – Determines the order of engine execution.

• state_machines – List of state machines managed by the engine.

__init__(core)

Initializes the Engine.

Parameters:

core (Core) – The Core instance managing the game loop.

enable(**kwargs)

Enables the engine and triggers related events.

Parameters:

kwargs (dict) – Additional data passed to the on_enable method.

disable()

Disables the engine and triggers related events.

start_func_as_coroutine(func, **kwargs)

Starts a function as a coroutine.

Parameters:

• func (callable) – The function to execute as a coroutine.

• kwargs (dict) – Arguments for the coroutine, including interval, call_delay, and all other parameters of the Coroutine class.

start_coroutine(coroutine)

Adds a Coroutine instance to the list of active coroutines.

Parameters:

coroutine (Coroutine) – The Coroutine instance to start.

start_coroutines(coroutines)

Adds multiple Coroutine instances to the list of active coroutines.

Parameters:

coroutines (list) – List of Coroutine instances to start.

awake(**kwargs)

Called once at the beginning of the engine’s lifecycle for initialization.

Parameters:

kwargs (dict) – Optional arguments for initialization.

on_enable(inject=None)

Triggered when the engine is enabled via the enable() method.

Parameters:

inject (dict) – Optional data to be injected during the enabling process.

on_disable()

Called when the engine is disabled, via the disable() method.

start()

Called when the engine starts.

update()

Called continuously during the game loop.

fixed_update()

Called at fixed intervals during the game loop.

on_destroy()

This method is called when the engine is about to be destroyed or when a scene change occurs.

__weakref__

list of weak references to the object (if defined)

class game_core.src.a_star.Grid(grid_size)

Represents a grid of nodes for pathfinding.

Parameters:

grid_size (tuple) – The size of the grid (width, height).

__init__(grid_size)

Initializes a Grid object.

Parameters:

grid_size (tuple) – The size of the grid (width, height).

get_node(position)

Retrieves the node at the specified position.

Parameters:

position (tuple) – The position of the node (x, y).

Returns:

The node at the specified position.

Return type:

Node

Raises:

Exception – If the position is out of bounds.

get_path(start_node, destination_node, open_nodes=None, closed_nodes=None)

Calculates the path from the start node to the destination node.

Parameters:

• start_node (Node) – The starting node.

• destination_node (Node) – The destination node.

• open_nodes (list, optional) – The list of open nodes. (optional)

• closed_nodes (list, optional) – The list of closed nodes. (optional)

Returns:

The path from the start node to the destination node.

Return type:

NodePath

Note:

The open_nodes and closed_nodes parameters are optional and will be initialized as empty lists if not provided.

__weakref__

list of weak references to the object (if defined)

class game_core.src.a_star.Node(grid_position, is_accessible=True)

Represents a node in a grid.

Parameters:

• grid_position (tuple) – The position of the node in the grid.

• is_accessible (bool) – Indicates if the node is accessible or not. Default is True.

__init__(grid_position, is_accessible=True)

get_position()

Get the position of the node in the grid.

Returns:

The position of the node.

Return type:

tuple

get_f()

Calculate and get the total cost of the node (g + h).

Returns:

The total cost of the node.

Return type:

float

calc_heuristic(destination_node)

Calculate the heuristic value (h) of the node based on the destination node.

Parameters:

destination_node (Node) – The destination node.

set_weighting(g)

Set the weighting value (g) of the node.

Parameters:

g (float) – The weighting value.

is_accessible()

Check if the node is accessible.

Returns:

True if the node is accessible, False otherwise.

Return type:

bool

set_accessibility(accessibility)

Set the accessibility of the node.

Parameters:

accessibility (bool) – The accessibility value.

reset()

Reset the node by setting the heuristic (h) and weighting (g) values to 0.

__repr__()

Return repr(self).

__str__()

Return str(self).

__eq__(other)

Check if the node is equal to another node.

Parameters:

other (Node) – The other node to compare.

Returns:

True if the nodes are equal, False otherwise.

Return type:

bool

__hash__ = None

__weakref__

list of weak references to the object (if defined)

class game_core.src.a_star.NodePath(path)

Represents a path of nodes.

Parameters:

path – Initial path (optional). If provided, it should be a list of nodes.

__init__(path)

Initializes a NodePath object.

Parameters:

path – Initial path (optional). If provided, it should be a list of nodes.

get_path()

Returns the path.

Returns:

The path as a list of nodes.

add(node)

Adds a node to the path.

Parameters:

node – The node to add.

count()

Returns the number of nodes in the path.

Returns:

The number of nodes in the path.

get_path_cost()

Calculates and returns the total cost of the path.

Returns:

The total cost of the path.

__eq__(other)

Checks if two NodePath objects have the same path cost.

Parameters:

other – The other NodePath object to compare.

Returns:

True if the path costs are equal, False otherwise.

__lt__(other)

Checks if the path cost of this NodePath object is less than the path cost of another NodePath object.

Parameters:

other – The other NodePath object to compare.

Returns:

True if this path cost is less than the other path cost, False otherwise.

__repr__()

Returns a string representation of the NodePath object.

Returns:

A string representation of the NodePath object.

__str__()

Returns a string representation of the path.

Returns:

A string representation of the path.

__hash__ = None

__weakref__

list of weak references to the object (if defined)

class game_core.src.surface_stack.SurfaceStack

Manages a stack of rendering surfaces for organized layer-based rendering.

__init__()

Initializes a SurfaceStack.

add_element(name, surface, render_layer: int, surface_render_position: tuple, fill_after_draw=True)

Adds a new surface element to the stack.

Parameters:

• name (str) – Unique name for the surface.

• surface (pygame.Surface) – The surface to add.

• render_layer (int) – The rendering order.

• surface_render_position (tuple) – Position of the surface in the window.

• fill_after_draw (bool) – Indicates if the surface should auto-fill after rendering.

remove_element(name)

Removes a surface element from the stack.

Parameters:

name (str) – Name of the surface to remove.

get_surface(name)

Retrieves a surface by name.

Parameters:

name (str) – Name of the surface.

Returns:

The requested surface.

Return type:

pygame.Surface

get_element(name)

Retrieves a SurfaceStackElement by name.

Parameters:

name (str) – Name of the element.

Returns:

The requested element.

Return type:

SurfaceStackElement:

draw(core)

Draws all surfaces in the stack.

Parameters:

core (Core) – Reference to the Core instance for rendering.

print()

Prints information about all surfaces in the stack.

__weakref__

list of weak references to the object (if defined)

class game_core.src.surface_stack.SurfaceStackElement

Represents an individual element in a stack of rendering surfaces.

Variables:

• name – Name identifier for the surface.

• surface – The surface object to render.

• render_layer – The rendering order for the surface.

• surface_render_position – Position of the surface in the window.

• auto_fill – Indicates if the surface should auto-fill after rendering.

__init__()

Initializes a SurfaceStackElement.

print()

Prints information about the surface element.

__weakref__

list of weak references to the object (if defined)

class game_core.src.sprite.Slicer

Base class for slicing a surface into smaller sections. Provides a generic interface for subclasses to implement specific slicing behavior.

slice(surface: pygame.Surface)

Placeholder function, returns the input surface without modification.

Parameters:

surface – A pygame.Surface object to be sliced.

Returns:

The original surface.

__weakref__

list of weak references to the object (if defined)

class game_core.src.sprite.SizeSlicer(width, height, x_gap=0, y_gap=0, top_padding=0, left_padding=0, right_padding=0, bottom_padding=0)

Slices a surface into tiles of specified width and height, with optional gaps and padding.

__init__(width, height, x_gap=0, y_gap=0, top_padding=0, left_padding=0, right_padding=0, bottom_padding=0)

Initializes a SizeSlicer instance with slicing dimensions and padding.

Parameters:

• width – Width of each tile.

• height – Height of each tile.

• x_gap – Horizontal gap between tiles.

• y_gap – Vertical gap between tiles.

• top_padding – Padding at the top of the image.

• left_padding – Padding at the left side of the image.

• right_padding – Padding at the right side of the image.

• bottom_padding – Padding at the bottom of the image.

slice(surface: pygame.Surface)

Splits the surface into tiles based on the specified size and gaps.

Parameters:

surface – A pygame.Surface to be sliced.

Returns:

A list of pygame.Surface tiles.

__weakref__

list of weak references to the object (if defined)

class game_core.src.sprite.AmountSlicer(rows=1, cols=1, x_gap=0, y_gap=0, top_padding=0, left_padding=0, right_padding=0, bottom_padding=0)

Slices a surface into a specified number of rows and columns, with optional gaps and padding.

__init__(rows=1, cols=1, x_gap=0, y_gap=0, top_padding=0, left_padding=0, right_padding=0, bottom_padding=0)

Initializes an AmountSlicer instance with slicing rows, columns, and padding.

Parameters:

• rows – Number of rows to divide the surface into.

• cols – Number of columns to divide the surface into.

• x_gap – Horizontal gap between tiles.

• y_gap – Vertical gap between tiles.

• top_padding – Padding at the top of the image.

• left_padding – Padding at the left side of the image.

• right_padding – Padding at the right side of the image.

• bottom_padding – Padding at the bottom of the image.

slice(surface: pygame.Surface)

Splits the surface into a grid of tiles based on the number of rows and columns.

Parameters:

surface – A pygame.Surface to be sliced.

Returns:

A list of pygame.Surface tiles.

__weakref__

list of weak references to the object (if defined)

class game_core.src.sprite.SimpleSprite(*args: Any, **kwargs: Any)

A basic sprite that displays a colored rectangle.

__init__(color=(200, 200, 200, 255), width=None, height=None)

Initializes a sprite with a single color and optional dimensions.

Parameters:

• color – Color of the sprite as an RGBA tuple.

• width – Width of the sprite.

• height – Height of the sprite.

get_image()

Returns the image surface of the sprite.

Returns:

A pygame.Surface object representing the sprite.

get_rect()

Returns the rectangular area of the sprite.

Returns:

A pygame.Rect object.

update_rect(rect: pygame.Rect)

Updates the rectangular position and size of the sprite.

Parameters:

rect – A pygame.Rect object.

__call__(*args: Any, **kwargs: Any) → Any

Call self as a function.

static __new__(cls, *args: Any, **kwargs: Any) → Any

__repr__() → str

Return repr(self).

__weakref__

list of weak references to the object (if defined)

class game_core.src.sprite.SimpleImageSprite(*args: Any, **kwargs: Any)

A sprite that displays an image, optionally sliced by a Slicer object.

__init__(image_path, slicer: Optional[Slicer] = None)

Initializes the sprite with an image and an optional slicer.

Parameters:

• image_path – Path to the image file.

• slicer – An optional Slicer object to slice the image.

flip(flip_x=False, flip_y=False)

Flips the image horizontally and/or vertically.

Parameters:

• flip_x – If True, flip the image horizontally.

• flip_y – If True, flip the image vertically.

get_image()

Returns the image or a sliced version of it.

Returns:

A pygame.Surface or list of surfaces if sliced.

get_rect()

Returns the rectangular area of the image.

Returns:

A pygame.Rect object.

update_rect(rect: pygame.Rect)

Updates the rectangular position and size of the image.

Parameters:

rect – A pygame.Rect object.

__call__(*args: Any, **kwargs: Any) → Any

Call self as a function.

static __new__(cls, *args: Any, **kwargs: Any) → Any

__repr__() → str

Return repr(self).

__weakref__

list of weak references to the object (if defined)

class game_core.src.sprite.SimpleSpriteAnimator(anim_sprites: dict, start_state: str, anim_state_decision: callable, sprite_size: tuple, fps=30)

Manages animation states for sprites and cycles through frames based on time.

__init__(anim_sprites: dict, start_state: str, anim_state_decision: callable, sprite_size: tuple, fps=30)

Initializes the animator with animations, state logic, and frame timing.

Parameters:

• anim_sprites – Dictionary mapping states to animation frames.

• start_state – The initial animation state.

• anim_state_decision – Callable to decide the current state.

• sprite_size – Size of the animation surface.

• fps – Frames per second for the animation.

get_size()

Returns the size of the animation surface.

Returns:

Tuple representing the size (width, height).

get_image(delta_time=None)

Returns the current animation frame.

Parameters:

delta_time – Time since the last frame, used for timing animations.

Returns:

A pygame.Surface of the current frame.

get_rect()

Returns the rectangular area of the animation surface.

Returns:

A pygame.Rect object.

update_rect(rect: pygame.Rect)

Updates the rectangular position and size of the animation surface.

Parameters:

rect – A pygame.Rect object.

animate(delta_time=None)

Cycles through animation frames based on time and state.

Parameters:

delta_time – Time since the last frame, used for timing animations.

Returns:

A pygame.Surface of the current frame.

__weakref__

list of weak references to the object (if defined)

class game_core.src.sprite.SpriteDirectoryAnimation(project_path, slicer: Optional[Slicer] = None)

Parses a directory structure to create animations for sprites.

__init__(project_path, slicer: Optional[Slicer] = None)

Initializes the parser with a project directory and an optional slicer.

Parameters:

• project_path – Path to the directory containing animations.

• slicer (Slicer) – An optional Slicer object to slice images.

parse()

Parses the directory and loads animations.

Returns:

A dictionary mapping animation names to frames.

__weakref__

list of weak references to the object (if defined)