Python Scripting API

Welcome to the Foxvoid Engine Python API reference. All components and systems exposed here can be accessed directly in your Python scripts.

Animation2d

Bases: Component

Handles frame-by-frame animation by controlling a SpriteSheetRenderer. Performance is maximized as the timer logic runs natively in C++.

Source code in foxvoid/__init__.pyi

class Animation2d(Component):
    """
    Handles frame-by-frame animation by controlling a SpriteSheetRenderer.
    Performance is maximized as the timer logic runs natively in C++.
    """

    def __init__(self, frames: List[int], speed: float, loop: bool = True, flip_x: bool = False, flip_y: bool = False) -> None: 
        """
        Initializes the animation sequence.

        Args:
            frames: Sequence of frame indices to play (e.g., [0, 1, 2, 3]).
            speed: Time in seconds each frame is displayed.
            loop: If True, the animation repeats indefinitely.
        """
        ...

__init__(frames, speed, loop=True, flip_x=False, flip_y=False)

Initializes the animation sequence.

Parameters:

Name	Type	Description	Default
frames	List[int]	Sequence of frame indices to play (e.g., [0, 1, 2, 3]).	required
speed	float	Time in seconds each frame is displayed.	required
loop	bool	If True, the animation repeats indefinitely.	True

Source code in foxvoid/__init__.pyi

def __init__(self, frames: List[int], speed: float, loop: bool = True, flip_x: bool = False, flip_y: bool = False) -> None: 
    """
    Initializes the animation sequence.

    Args:
        frames: Sequence of frame indices to play (e.g., [0, 1, 2, 3]).
        speed: Time in seconds each frame is displayed.
        loop: If True, the animation repeats indefinitely.
    """
    ...

Animator2d

Bases: Component

Manages and plays 2D frame-based animations using an attached SpriteSheetRenderer.

Source code in foxvoid/__init__.pyi

class Animator2d(Component):
    """
    Manages and plays 2D frame-based animations using an attached SpriteSheetRenderer.
    """

    def __init__(self) -> None:
        """Initializes an empty Animator2d."""
        ...

    @property
    def playback_speed(self) -> float:
        """The global speed multiplier for the animator (1.0 is normal speed)."""
        ...

    @playback_speed.setter
    def playback_speed(self, value: float) -> None:
        ...

    def add_animation(self, name: str, frames: list[int], frame_duration: float, loop: bool, flip_x: bool = False, flip_y: bool = False, events: dict[int, List[str]] = {}) -> None:
        """
        Registers a new animation state.

        :param name: The identifier for the animation (e.g., "walk", "idle").
        :param frames: A list of frame indices in the sprite sheet.
        :param frame_duration: Time in seconds each frame is displayed.
        :param loop: If True, the animation restarts automatically.
        """
        ...

    def play(self, name: str) -> None:
        """
        Switches the current playback to the specified animation.
        Does nothing if the animation is already playing.
        """
        ...

    def pause(self) -> None:
        """Pauses the current animation. It can be resumed later."""
        ...

    def resume(self) -> None:
        """Resumes a paused animation from where it left off."""
        ...

    def stop(self) -> None:
        """Stops the animation and resets it to the first frame."""
        ...

    def is_playing(self) -> bool:
        """Returns True if an animation is currently playing and not paused/stopped."""
        ...

    def is_finished(self) -> bool:
        """
        Returns True if the current non-looping animation has reached its final frame,
        or if the animator is currently stopped.
        """
        ...

playback_speed property writable

The global speed multiplier for the animator (1.0 is normal speed).

__init__()

Initializes an empty Animator2d.

Source code in foxvoid/__init__.pyi

def __init__(self) -> None:
    """Initializes an empty Animator2d."""
    ...

add_animation(name, frames, frame_duration, loop, flip_x=False, flip_y=False, events={})

Registers a new animation state.

:param name: The identifier for the animation (e.g., "walk", "idle"). :param frames: A list of frame indices in the sprite sheet. :param frame_duration: Time in seconds each frame is displayed. :param loop: If True, the animation restarts automatically.

Source code in foxvoid/__init__.pyi

def add_animation(self, name: str, frames: list[int], frame_duration: float, loop: bool, flip_x: bool = False, flip_y: bool = False, events: dict[int, List[str]] = {}) -> None:
    """
    Registers a new animation state.

    :param name: The identifier for the animation (e.g., "walk", "idle").
    :param frames: A list of frame indices in the sprite sheet.
    :param frame_duration: Time in seconds each frame is displayed.
    :param loop: If True, the animation restarts automatically.
    """
    ...

is_finished()

Returns True if the current non-looping animation has reached its final frame, or if the animator is currently stopped.

Source code in foxvoid/__init__.pyi

def is_finished(self) -> bool:
    """
    Returns True if the current non-looping animation has reached its final frame,
    or if the animator is currently stopped.
    """
    ...

is_playing()

Returns True if an animation is currently playing and not paused/stopped.

Source code in foxvoid/__init__.pyi

def is_playing(self) -> bool:
    """Returns True if an animation is currently playing and not paused/stopped."""
    ...

pause()

Pauses the current animation. It can be resumed later.

Source code in foxvoid/__init__.pyi

def pause(self) -> None:
    """Pauses the current animation. It can be resumed later."""
    ...

play(name)

Switches the current playback to the specified animation. Does nothing if the animation is already playing.

Source code in foxvoid/__init__.pyi

def play(self, name: str) -> None:
    """
    Switches the current playback to the specified animation.
    Does nothing if the animation is already playing.
    """
    ...

resume()

Resumes a paused animation from where it left off.

Source code in foxvoid/__init__.pyi

def resume(self) -> None:
    """Resumes a paused animation from where it left off."""
    ...

stop()

Stops the animation and resets it to the first frame.

Source code in foxvoid/__init__.pyi

def stop(self) -> None:
    """Stops the animation and resets it to the first frame."""
    ...

Button

Bases: Component

Component that provides a clickable interaction area. If a ShapeRenderer is attached to the same GameObject, the Button will automatically update its color based on the current interaction state.

Source code in foxvoid/__init__.pyi

class Button(Component):
    """
    Component that provides a clickable interaction area.
    If a ShapeRenderer is attached to the same GameObject, the Button will 
    automatically update its color based on the current interaction state.
    """

    width: float
    """The width of the clickable hitbox."""

    height: float
    """The height of the clickable hitbox."""

    is_hud: bool
    """
    Determines how mouse coordinates are calculated.
    Ensure this matches the 'is_hud' property of your visual renderer (Text/Shape).
    """

    transition: ButtonTransition

    normal_color: Color
    """Color applied to an attached ShapeRenderer when inactive."""

    hover_color: Color
    """Color applied to an attached ShapeRenderer when the mouse hovers over it."""

    pressed_color: Color
    """Color applied to an attached ShapeRenderer when the mouse button is held down."""

    def __init__(self) -> None:
        """
        Initializes a Button with default dimensions and UI colors.
        """
        ...

    def is_clicked(self) -> bool:
        """
        Checks if the button was successfully clicked.

        Returns:
            bool: True only on the exact frame the user releases the left mouse button 
                  while still hovering the button bounds.
        """
        ...

    def get_state(self) -> ButtonState:
        """
        Retrieves the current visual state of the button.

        Returns:
            ButtonState: The interaction state (Normal, Hovered, or Pressed).
        """
        ...

height instance-attribute

The height of the clickable hitbox.

hover_color instance-attribute

Color applied to an attached ShapeRenderer when the mouse hovers over it.

is_hud instance-attribute

Determines how mouse coordinates are calculated. Ensure this matches the 'is_hud' property of your visual renderer (Text/Shape).

normal_color instance-attribute

Color applied to an attached ShapeRenderer when inactive.

pressed_color instance-attribute

Color applied to an attached ShapeRenderer when the mouse button is held down.

width instance-attribute

The width of the clickable hitbox.

__init__()

Initializes a Button with default dimensions and UI colors.

Source code in foxvoid/__init__.pyi

def __init__(self) -> None:
    """
    Initializes a Button with default dimensions and UI colors.
    """
    ...

get_state()

Retrieves the current visual state of the button.

Returns:

Name	Type	Description
ButtonState	ButtonState	The interaction state (Normal, Hovered, or Pressed).

Source code in foxvoid/__init__.pyi

def get_state(self) -> ButtonState:
    """
    Retrieves the current visual state of the button.

    Returns:
        ButtonState: The interaction state (Normal, Hovered, or Pressed).
    """
    ...

is_clicked()

Checks if the button was successfully clicked.

Returns:

Name	Type	Description
bool	bool	True only on the exact frame the user releases the left mouse button while still hovering the button bounds.

Source code in foxvoid/__init__.pyi

def is_clicked(self) -> bool:
    """
    Checks if the button was successfully clicked.

    Returns:
        bool: True only on the exact frame the user releases the left mouse button 
              while still hovering the button bounds.
    """
    ...

ButtonState

Represents the current interaction state of a Button component.

Source code in foxvoid/__init__.pyi

class ButtonState:
    """Represents the current interaction state of a Button component."""
    Normal: 'ButtonState'
    Hovered: 'ButtonState'
    Pressed: 'ButtonState'

Camera2d

Bases: Component

Component that controls the viewport for rendering the game world. The camera automatically looks at the Transform2d of the GameObject it is attached to.

Source code in foxvoid/__init__.pyi

class Camera2d(Component):
    """
    Component that controls the viewport for rendering the game world.
    The camera automatically looks at the Transform2d of the GameObject it is attached to.
    """

    zoom: float
    """The zoom level of the camera. 1.0 is default, > 1.0 zooms in, < 1.0 zooms out."""

    offset: Vector2
    """
    Custom pixel offset applied ON TOP of the anchor point.
    Useful for shifting the camera view (e.g., aiming slightly higher or looking ahead).
    """

    anchor: Camera2dAnchor
    """The base screen alignment (default is CameraAnchor.Center)."""

    is_main: bool
    """
    If True, the Engine will use this camera to render the final Game View.
    Make sure only one active camera is marked as main at a time.
    """

    background_color: Color
    """
    The color used to clear the background before rendering the scene.
    Modify this to dynamically change the atmosphere or sky color of the level.
    """

    def __init__(self) -> None:
        """
        Initializes a Camera2d component with default values 
        (zoom=1.0, offset=(0,0), anchor=CameraAnchor.Center, is_main=True).
        """
        ...

    def shake(self, intensity: float, duration: float):
        """Triggers a screen shake (intensity, duration) """
        ...

anchor instance-attribute

The base screen alignment (default is CameraAnchor.Center).

background_color instance-attribute

The color used to clear the background before rendering the scene. Modify this to dynamically change the atmosphere or sky color of the level.

is_main instance-attribute

If True, the Engine will use this camera to render the final Game View. Make sure only one active camera is marked as main at a time.

offset instance-attribute

Custom pixel offset applied ON TOP of the anchor point. Useful for shifting the camera view (e.g., aiming slightly higher or looking ahead).

zoom instance-attribute

The zoom level of the camera. 1.0 is default, > 1.0 zooms in, < 1.0 zooms out.

__init__()

Initializes a Camera2d component with default values (zoom=1.0, offset=(0,0), anchor=CameraAnchor.Center, is_main=True).

Source code in foxvoid/__init__.pyi

def __init__(self) -> None:
    """
    Initializes a Camera2d component with default values 
    (zoom=1.0, offset=(0,0), anchor=CameraAnchor.Center, is_main=True).
    """
    ...

shake(intensity, duration)

Triggers a screen shake (intensity, duration)

Source code in foxvoid/__init__.pyi

def shake(self, intensity: float, duration: float):
    """Triggers a screen shake (intensity, duration) """
    ...

Camera2dAnchor

Bases: Enum

Defines the base screen position that the camera uses as its focal point.

Source code in foxvoid/__init__.pyi

class Camera2dAnchor(Enum):
    """
    Defines the base screen position that the camera uses as its focal point.
    """

    TopLeft = 0
    """Anchors the camera to the top-left corner of the screen (0, 0)."""

    Center = 1
    """Anchors the camera to the exact center of the screen."""

Center = 1 class-attribute instance-attribute

Anchors the camera to the exact center of the screen.

TopLeft = 0 class-attribute instance-attribute

Anchors the camera to the top-left corner of the screen (0, 0).

CapsuleCollider

Bases: Component

A capsule-shaped collider, consisting of a cylinder with hemispherical ends. This is the industry standard shape for 2D character controllers as it slides smoothly over small bumps and does not catch on tile edges.

Source code in foxvoid/__init__.pyi

class CapsuleCollider(Component):
    """
    A capsule-shaped collider, consisting of a cylinder with hemispherical ends.
    This is the industry standard shape for 2D character controllers as it slides
    smoothly over small bumps and does not catch on tile edges.
    """
    radius: float
    height: float
    offset: Vector2
    is_trigger: bool

    def __init__(self, radius: float = 25.0, height: float = 50.0) -> None: 
        """
        Initializes a CapsuleCollider. The height is the total vertical span
        and cannot be strictly smaller than radius * 2.
        """
        ...

__init__(radius=25.0, height=50.0)

Initializes a CapsuleCollider. The height is the total vertical span and cannot be strictly smaller than radius * 2.

Source code in foxvoid/__init__.pyi

def __init__(self, radius: float = 25.0, height: float = 50.0) -> None: 
    """
    Initializes a CapsuleCollider. The height is the total vertical span
    and cannot be strictly smaller than radius * 2.
    """
    ...

Checkbox

Bases: Component

A toggleable UI element. Triggers on_gui_click() when pressed.

Source code in foxvoid/__init__.pyi

class Checkbox(Component):
    """
    A toggleable UI element. Triggers on_gui_click() when pressed.
    """
    is_on: bool
    use_sprite: bool
    color_on: 'Color'
    color_off: 'Color'

    def __init__(self) -> None: ...

CircleCollider

Bases: Component

A perfect circle collider. Ideal for characters and rolling objects to prevent snagging on TileMap corners.

Source code in foxvoid/__init__.pyi

class CircleCollider(Component):
    """
    A perfect circle collider.
    Ideal for characters and rolling objects to prevent
    snagging on TileMap corners.
    """
    radius: float
    offset: Vector2
    is_trigger: bool

    def __init__(self, radius: float = 25.0) -> None: 
        """
        Initializes a CircleCollider with a given radius.
        """
        ...

__init__(radius=25.0)

Initializes a CircleCollider with a given radius.

Source code in foxvoid/__init__.pyi

def __init__(self, radius: float = 25.0) -> None: 
    """
    Initializes a CircleCollider with a given radius.
    """
    ...

Collision2D

Contains information about a physics collision event.

Source code in foxvoid/__init__.pyi

class Collision2D:
    """Contains information about a physics collision event."""

    other: GameObject | None
    """The GameObject collided with. Will be None if the collision was with the static TileMap."""

    normal: Vector2
    """The direction vector of the surface hit. e.g., (0, -1) means you hit the floor."""

normal instance-attribute

The direction vector of the surface hit. e.g., (0, -1) means you hit the floor.

other instance-attribute

The GameObject collided with. Will be None if the collision was with the static TileMap.

Color

Represents an RGBA color.

Source code in foxvoid/__init__.pyi

class Color:
    """Represents an RGBA color."""
    r: int
    g: int
    b: int
    a: int

    def __init__(self, r: int = 0, g: int = 0, b: int = 0, a: int = 255) -> None: ...
    def __repr__(self) -> str: ...

Component

Base class for all engine scripts and components.

Source code in foxvoid/__init__.pyi

class Component:
    """Base class for all engine scripts and components."""

    __categories__: Dict[str, List[str]]
    """
    (Optional) Editor metadata to group variables in the Inspector.
    Format: {"Category Name": ["var1", "var2"]}

    Example:
        __categories__ = {
            "Movement": ["speed", "jump_force"],
            "Combat": ["health", "damage"]
        }
    """

    def __init__(self) -> None: 
        """Initializes the C++ base component memory."""
        ...

    @property
    def game_object(self) -> GameObject:
        """The owning GameObject of this component (Read-only)."""
        ...

    def start(self) -> None: 
        """Called once when the component is initialized."""
        ...

    def update(self, delta_time: float) -> None: 
        """Called every frame for logic and physics."""
        ...

    def on_collision(self, collision: 'Collision2D') -> None: 
        """Called when this object's collider intersects with another."""
        ...

    def on_animation_event(self, event_name: str) -> None:
        """
        Called automatically by an attached Animator2d when a specific frame is reached.
        Override this method in your script to handle animation events (e.g., footsteps, attacks).
        """
        ...

    def on_gui_click(self, button_name: str) -> None:
        """
        Called when a Button component on the same GameObject is clicked
        """
        ...

__categories__ instance-attribute

(Optional) Editor metadata to group variables in the Inspector. Format: {"Category Name": ["var1", "var2"]}

Example

categories = { "Movement": ["speed", "jump_force"], "Combat": ["health", "damage"] }

game_object property

The owning GameObject of this component (Read-only).

__init__()

Initializes the C++ base component memory.

Source code in foxvoid/__init__.pyi

def __init__(self) -> None: 
    """Initializes the C++ base component memory."""
    ...

on_animation_event(event_name)

Called automatically by an attached Animator2d when a specific frame is reached. Override this method in your script to handle animation events (e.g., footsteps, attacks).

Source code in foxvoid/__init__.pyi

def on_animation_event(self, event_name: str) -> None:
    """
    Called automatically by an attached Animator2d when a specific frame is reached.
    Override this method in your script to handle animation events (e.g., footsteps, attacks).
    """
    ...

on_collision(collision)

Called when this object's collider intersects with another.

Source code in foxvoid/__init__.pyi

def on_collision(self, collision: 'Collision2D') -> None: 
    """Called when this object's collider intersects with another."""
    ...

on_gui_click(button_name)

Called when a Button component on the same GameObject is clicked

Source code in foxvoid/__init__.pyi

def on_gui_click(self, button_name: str) -> None:
    """
    Called when a Button component on the same GameObject is clicked
    """
    ...

start()

Called once when the component is initialized.

Source code in foxvoid/__init__.pyi

def start(self) -> None: 
    """Called once when the component is initialized."""
    ...

update(delta_time)

Called every frame for logic and physics.

Source code in foxvoid/__init__.pyi

def update(self, delta_time: float) -> None: 
    """Called every frame for logic and physics."""
    ...

DataManager

Global system responsible for loading, caching, and saving ScriptableObject assets.

Source code in foxvoid/__init__.pyi

class DataManager:
    """
    Global system responsible for loading, caching, and saving ScriptableObject assets.
    """

    @staticmethod
    def load_asset(filepath: str) -> Optional[ScriptableObject]:
        """
        Loads a .asset file from disk. If the asset has already been loaded, 
        it returns the cached instance to save memory and performance.

        Args:
            filepath: The relative path to the .asset file (e.g., 'assets/data/sword.asset').

        Returns:
            The fully instantiated Python object, or None if loading failed.
        """
        ...

    @staticmethod
    def save_asset(asset: ScriptableObject, filepath: str) -> None:
        """
        Serializes a ScriptableObject instance and saves it to a .asset JSON file.
        """
        ...

    @staticmethod
    def clear_cache() -> None:
        """
        Clears all loaded assets from memory. 
        Usually called by the engine during scene transitions.
        """
        ...

clear_cache() staticmethod

Clears all loaded assets from memory. Usually called by the engine during scene transitions.

Source code in foxvoid/__init__.pyi

@staticmethod
def clear_cache() -> None:
    """
    Clears all loaded assets from memory. 
    Usually called by the engine during scene transitions.
    """
    ...

load_asset(filepath) staticmethod

Loads a .asset file from disk. If the asset has already been loaded, it returns the cached instance to save memory and performance.

Parameters:

Name	Type	Description	Default
filepath	str	The relative path to the .asset file (e.g., 'assets/data/sword.asset').	required

Returns:

Type	Description
Optional[ScriptableObject]	The fully instantiated Python object, or None if loading failed.

Source code in foxvoid/__init__.pyi

@staticmethod
def load_asset(filepath: str) -> Optional[ScriptableObject]:
    """
    Loads a .asset file from disk. If the asset has already been loaded, 
    it returns the cached instance to save memory and performance.

    Args:
        filepath: The relative path to the .asset file (e.g., 'assets/data/sword.asset').

    Returns:
        The fully instantiated Python object, or None if loading failed.
    """
    ...

save_asset(asset, filepath) staticmethod

Serializes a ScriptableObject instance and saves it to a .asset JSON file.

Source code in foxvoid/__init__.pyi

@staticmethod
def save_asset(asset: ScriptableObject, filepath: str) -> None:
    """
    Serializes a ScriptableObject instance and saves it to a .asset JSON file.
    """
    ...

Debug

Source code in foxvoid/__init__.pyi

class Debug:
    @staticmethod
    def log(msg: str) -> None:
        """
        Prints a message directly to the C++ engine console.
        Bypasses Python's standard stdout to prevent crashes with graphics libraries.
        """
        ...

    @staticmethod
    def error(msg: str) -> None:
        """
        Prints an error directly to the C++ engine console.
        Bypasses Python's standard stdout to prevent crashes with graphics libraries.
        """
        ...

error(msg) staticmethod

Prints an error directly to the C++ engine console. Bypasses Python's standard stdout to prevent crashes with graphics libraries.

Source code in foxvoid/__init__.pyi

@staticmethod
def error(msg: str) -> None:
    """
    Prints an error directly to the C++ engine console.
    Bypasses Python's standard stdout to prevent crashes with graphics libraries.
    """
    ...

log(msg) staticmethod

Prints a message directly to the C++ engine console. Bypasses Python's standard stdout to prevent crashes with graphics libraries.

Source code in foxvoid/__init__.pyi

@staticmethod
def log(msg: str) -> None:
    """
    Prints a message directly to the C++ engine console.
    Bypasses Python's standard stdout to prevent crashes with graphics libraries.
    """
    ...

GameObject

Source code in foxvoid/__init__.pyi

class GameObject:
    name: str

    # Tag used to group and identify objects (e.g., "Enemy", "Player", "Projectile")
    # Defaults to "Untagged"
    tag: str

    # Allow enabling or disabling the GameObject and its components
    is_active: bool

    # Read-only unique identifier
    @property
    def id(self) -> int: ...

    def is_active_in_hierarchy(self) -> bool:
        """
        Checks if this object is currently active in the scene.
        Returns False if this object OR any of its parents are inactive.
        """
        ...

    def set_parent(self, new_parent: Optional['GameObject']) -> None:
        """Attaches this object to a new parent. Pass None to unparent (move to root)."""
        ...

    def get_parent(self) -> Optional['GameObject']:
        """Returns the current parent of this object, or None if it's at the root."""
        ...

    def get_children(self) -> List['GameObject']:
        """Returns a list of all direct children attached to this object."""
        ...

    """Represents an entity within the engine's scene."""
    @staticmethod
    def spawn(name: str) -> GameObject:
        """
        Creates a new empty GameObject in the active scene.

        Args:
            name: The name of the new entity.

        Returns:
            The newly created GameObject instance.
        """
        ...

    @staticmethod
    def instantiate(prefab_path: str) -> Optional[GameObject]:
        """
        Instantiates a new GameObject from a saved JSON prefab file.

        Args:
            prefab_path: The relative path to the .json prefab file (e.g., 'assets/prefabs/Bullet.json').

        Returns:
            The newly instantiated GameObject instance, or None if the file could not be loaded.
        """
        ...

    def destroy(self) -> None:
        """
        Marks this GameObject for destruction. 
        It will be safely removed from memory at the end of the current C++ frame.
        """
        ...

    def get_component(self, type_obj: Type[T]) -> Optional[T]:
        """
        Retrieves a component attached to this GameObject.

        Args:
            type_obj: The class type of the component to retrieve (e.g., Transform2d).

        Returns:
            The component instance if found, otherwise None.
        """
        ...

    def add_component(self, type_obj: Type[T], *args) -> T:
        """
        Dynamically instantiates and attaches a new component to this GameObject.

        Args:
            type_obj: The class type of the component to create.
            *args: Variable arguments passed directly to the C++ constructor of the component.

        Returns:
            The newly created and attached component instance.
        """
        ...

add_component(type_obj, *args)

Dynamically instantiates and attaches a new component to this GameObject.

Parameters:

Name	Type	Description	Default
type_obj	Type[T]	The class type of the component to create.	required
*args		Variable arguments passed directly to the C++ constructor of the component.	()

Returns:

Type	Description
T	The newly created and attached component instance.

Source code in foxvoid/__init__.pyi

def add_component(self, type_obj: Type[T], *args) -> T:
    """
    Dynamically instantiates and attaches a new component to this GameObject.

    Args:
        type_obj: The class type of the component to create.
        *args: Variable arguments passed directly to the C++ constructor of the component.

    Returns:
        The newly created and attached component instance.
    """
    ...

destroy()

Marks this GameObject for destruction. It will be safely removed from memory at the end of the current C++ frame.

Source code in foxvoid/__init__.pyi

def destroy(self) -> None:
    """
    Marks this GameObject for destruction. 
    It will be safely removed from memory at the end of the current C++ frame.
    """
    ...

get_children()

Returns a list of all direct children attached to this object.

Source code in foxvoid/__init__.pyi

def get_children(self) -> List['GameObject']:
    """Returns a list of all direct children attached to this object."""
    ...

get_component(type_obj)

Retrieves a component attached to this GameObject.

Parameters:

Name	Type	Description	Default
type_obj	Type[T]	The class type of the component to retrieve (e.g., Transform2d).	required

Returns:

Type	Description
Optional[T]	The component instance if found, otherwise None.

Source code in foxvoid/__init__.pyi

def get_component(self, type_obj: Type[T]) -> Optional[T]:
    """
    Retrieves a component attached to this GameObject.

    Args:
        type_obj: The class type of the component to retrieve (e.g., Transform2d).

    Returns:
        The component instance if found, otherwise None.
    """
    ...

get_parent()

Returns the current parent of this object, or None if it's at the root.

Source code in foxvoid/__init__.pyi

def get_parent(self) -> Optional['GameObject']:
    """Returns the current parent of this object, or None if it's at the root."""
    ...

instantiate(prefab_path) staticmethod

Instantiates a new GameObject from a saved JSON prefab file.

Parameters:

Name	Type	Description	Default
prefab_path	str	The relative path to the .json prefab file (e.g., 'assets/prefabs/Bullet.json').	required

Returns:

Type	Description
Optional[GameObject]	The newly instantiated GameObject instance, or None if the file could not be loaded.

Source code in foxvoid/__init__.pyi

@staticmethod
def instantiate(prefab_path: str) -> Optional[GameObject]:
    """
    Instantiates a new GameObject from a saved JSON prefab file.

    Args:
        prefab_path: The relative path to the .json prefab file (e.g., 'assets/prefabs/Bullet.json').

    Returns:
        The newly instantiated GameObject instance, or None if the file could not be loaded.
    """
    ...

is_active_in_hierarchy()

Checks if this object is currently active in the scene. Returns False if this object OR any of its parents are inactive.

Source code in foxvoid/__init__.pyi

def is_active_in_hierarchy(self) -> bool:
    """
    Checks if this object is currently active in the scene.
    Returns False if this object OR any of its parents are inactive.
    """
    ...

set_parent(new_parent)

Attaches this object to a new parent. Pass None to unparent (move to root).

Source code in foxvoid/__init__.pyi

def set_parent(self, new_parent: Optional['GameObject']) -> None:
    """Attaches this object to a new parent. Pass None to unparent (move to root)."""
    ...

spawn(name) staticmethod

Creates a new empty GameObject in the active scene.

Parameters:

Name	Type	Description	Default
name	str	The name of the new entity.	required

Returns:

Type	Description
GameObject	The newly created GameObject instance.

Source code in foxvoid/__init__.pyi

@staticmethod
def spawn(name: str) -> GameObject:
    """
    Creates a new empty GameObject in the active scene.

    Args:
        name: The name of the new entity.

    Returns:
        The newly created GameObject instance.
    """
    ...

Globals

Access global game variables managed in the Editor.

Source code in foxvoid/__init__.pyi

class Globals:
    """Access global game variables managed in the Editor."""
    @staticmethod
    def set_int(key: str, value: int) -> None: ...

    @staticmethod
    def get_int(key: str, default_val: int = 0) -> int: ...

    @staticmethod
    def set_float(key: str, value: float) -> None: ...

    @staticmethod
    def get_float(key: str, default_val: float = 0.0) -> float: ...

    @staticmethod
    def set_bool(key: str, value: int) -> None: ...

    @staticmethod
    def get_bool(key: str, default_val: bool = False) -> bool: ...

    @staticmethod
    def set_string(key: str, value: str) -> None: ...

    @staticmethod
    def get_string(key: str, default_val: str = "") -> str: ...

HBoxContainer

Bases: Component

Automatically aligns child UI elements horizontally based on their RectTransforms. Perfect for toolbars, dialog buttons, and side-by-side layouts.

Source code in foxvoid/__init__.pyi

class HBoxContainer(Component):
    """
    Automatically aligns child UI elements horizontally based on their RectTransforms.
    Perfect for toolbars, dialog buttons, and side-by-side layouts.
    """

    # Space between each child element in pixels
    spacing: float

    # Inner margins at the left and right
    padding_left: float
    padding_right: float

    # Forces vertical alignment of children (0.0 = Top, 0.5 = Center, 1.0 = Bottom)
    vertical_alignment: float

    def __init__(self) -> None: ...

ImageRenderer

Bases: Component

Renders an image/texture. Uses RectTransform if is_hud is True (Screen Space), or Transform2d if is_hud is False (World Space).

Source code in foxvoid/__init__.pyi

class ImageRenderer(Component):
    """
    Renders an image/texture. Uses RectTransform if is_hud is True (Screen Space), 
    or Transform2d if is_hud is False (World Space).
    """

    # Color tint applied to the image
    color: Color

    # Determines if the image is drawn in UI space or world space
    is_hud: bool

    def __init__(self, texture_path: str = "") -> None:
        """Initializes the ImageRenderer, optionally loading a texture immediately."""
        ...

    def set_texture(self, path: str) -> None:
        """
        Updates the displayed texture from a file path.
        Example: self.image.set_texture("assets/textures/menu_bg.png")
        """
        ...

__init__(texture_path='')

Initializes the ImageRenderer, optionally loading a texture immediately.

Source code in foxvoid/__init__.pyi

def __init__(self, texture_path: str = "") -> None:
    """Initializes the ImageRenderer, optionally loading a texture immediately."""
    ...

set_texture(path)

Updates the displayed texture from a file path. Example: self.image.set_texture("assets/textures/menu_bg.png")

Source code in foxvoid/__init__.pyi

def set_texture(self, path: str) -> None:
    """
    Updates the displayed texture from a file path.
    Example: self.image.set_texture("assets/textures/menu_bg.png")
    """
    ...

Input

Handles keyboard and mouse inputs from the engine.

Source code in foxvoid/__init__.pyi

class Input:
    """Handles keyboard and mouse inputs from the engine."""

    @staticmethod
    def is_key_down(key: int) -> bool:
        """
        Checks if a key is currently being held down.
        Returns True every frame the key remains pressed.
        """
        ...

    @staticmethod
    def is_key_pressed(key: int) -> bool:
        """
        Checks if a key has been pressed once.
        Returns True only on the exact frame the key was pushed down.
        """
        ...

    @staticmethod
    def is_action_down(action: str) -> bool:
        """
        Checks if ANY of the keys bound to this named action are currently held down.
        Useful for continuous movement (e.g., Input.is_action_down("MoveRight")).
        """
        ...

    @staticmethod
    def is_action_pressed(action: str) -> bool:
        """
        Checks if ANY of the keys bound to this named action were pressed this frame.
        Useful for single actions like jumping or shooting (e.g., Input.is_action_pressed("Jump")).
        """
        ...

is_action_down(action) staticmethod

Checks if ANY of the keys bound to this named action are currently held down. Useful for continuous movement (e.g., Input.is_action_down("MoveRight")).

Source code in foxvoid/__init__.pyi

@staticmethod
def is_action_down(action: str) -> bool:
    """
    Checks if ANY of the keys bound to this named action are currently held down.
    Useful for continuous movement (e.g., Input.is_action_down("MoveRight")).
    """
    ...

is_action_pressed(action) staticmethod

Checks if ANY of the keys bound to this named action were pressed this frame. Useful for single actions like jumping or shooting (e.g., Input.is_action_pressed("Jump")).

Source code in foxvoid/__init__.pyi

@staticmethod
def is_action_pressed(action: str) -> bool:
    """
    Checks if ANY of the keys bound to this named action were pressed this frame.
    Useful for single actions like jumping or shooting (e.g., Input.is_action_pressed("Jump")).
    """
    ...

is_key_down(key) staticmethod

Checks if a key is currently being held down. Returns True every frame the key remains pressed.

Source code in foxvoid/__init__.pyi

@staticmethod
def is_key_down(key: int) -> bool:
    """
    Checks if a key is currently being held down.
    Returns True every frame the key remains pressed.
    """
    ...

is_key_pressed(key) staticmethod

Checks if a key has been pressed once. Returns True only on the exact frame the key was pushed down.

Source code in foxvoid/__init__.pyi

@staticmethod
def is_key_pressed(key: int) -> bool:
    """
    Checks if a key has been pressed once.
    Returns True only on the exact frame the key was pushed down.
    """
    ...

Keys

Raylib keyboard key codes.

Source code in foxvoid/__init__.pyi

class Keys:
    """Raylib keyboard key codes."""
    KEY_NULL: int
    KEY_APOSTROPHE: int
    KEY_COMMA: int
    KEY_MINUS: int
    KEY_PERIOD: int
    KEY_SLASH: int

    KEY_ZERO: int
    KEY_ONE: int
    KEY_TWO: int
    KEY_THREE: int
    KEY_FOUR: int
    KEY_FIVE: int
    KEY_SIX: int
    KEY_SEVEN: int
    KEY_EIGHT: int
    KEY_NINE: int

    KEY_SEMICOLON: int
    KEY_EQUAL: int

    KEY_A: int
    KEY_B: int
    KEY_C: int
    KEY_D: int
    KEY_E: int
    KEY_F: int
    KEY_G: int
    KEY_H: int
    KEY_I: int
    KEY_J: int
    KEY_K: int
    KEY_L: int
    KEY_M: int
    KEY_N: int
    KEY_O: int
    KEY_P: int
    KEY_Q: int
    KEY_R: int
    KEY_S: int
    KEY_T: int
    KEY_U: int
    KEY_V: int
    KEY_W: int
    KEY_X: int
    KEY_Y: int
    KEY_Z: int

    KEY_LEFT_BRACKET: int
    KEY_BACKSLASH: int
    KEY_RIGHT_BRACKET: int
    KEY_GRAVE: int

    KEY_SPACE: int
    KEY_ESCAPE: int
    KEY_ENTER: int
    KEY_TAB: int
    KEY_BACKSPACE: int
    KEY_INSERT: int
    KEY_DELETE: int
    RIGHT: int
    LEFT: int
    DOWN: int
    UP: int
    KEY_PAGE_UP: int
    KEY_PAGE_DOWN: int
    KEY_HOME: int
    KEY_END: int
    KEY_CAPS_LOCK: int
    KEY_SCROLL_LOCK: int
    KEY_NUM_LOCK: int
    KEY_PRINT_SCREEN: int
    KEY_PAUSE: int

    KEY_F1: int
    KEY_F2: int
    KEY_F3: int
    KEY_F4: int
    KEY_F5: int
    KEY_F6: int
    KEY_F7: int
    KEY_F8: int
    KEY_F9: int
    KEY_F10: int
    KEY_F11: int
    KEY_F12: int

    KEY_LEFT_SHIFT: int
    KEY_LEFT_CONTROL: int
    KEY_LEFT_ALT: int
    KEY_LEFT_SUPER: int
    KEY_RIGHT_SHIFT: int
    KEY_RIGHT_CONTROL: int
    KEY_RIGHT_ALT: int
    KEY_RIGHT_SUPER: int
    KEY_KB_MENU: int

    KEY_KP_0: int
    KEY_KP_1: int
    KEY_KP_2: int
    KEY_KP_3: int
    KEY_KP_4: int
    KEY_KP_5: int
    KEY_KP_6: int
    KEY_KP_7: int
    KEY_KP_8: int
    KEY_KP_9: int

    KEY_KP_DECIMAL: int
    KEY_KP_DIVIDE: int
    KEY_KP_MULTIPLY: int
    KEY_KP_SUBTRACT: int
    KEY_KP_ADD: int
    KEY_KP_ENTER: int
    KEY_KP_EQUAL: int

    KEY_BACK: int
    KEY_MENU: int
    KEY_VOLUME_UP: int
    KEY_VOLUME_DOWN: int

LoopMode

Bases: Enum

Defines how an animation should behave when it reaches the end.

Source code in foxvoid/__init__.pyi

class LoopMode(Enum):
    """Defines how an animation should behave when it reaches the end."""
    Once = 0
    Loop = 1
    PingPong = 2

Mask

Bases: Component

Clips (hides) all child UI elements that render outside of this GameObject's RectTransform bounds.

Source code in foxvoid/__init__.pyi

class Mask(Component):
    """
    Clips (hides) all child UI elements that render outside of 
    this GameObject's RectTransform bounds.
    """

    # Allows turning the clipping effect on or off
    is_active: bool

    def __init__(self) -> None: ...

ParticleSystem2d

Bases: Component

A versatile 2D particle emitter for creating visual effects like fire, rain, and explosions. All properties can be modified in real-time from Python to dynamically animate the emitter.

Source code in foxvoid/__init__.pyi

class ParticleSystem2d(Component):
    """
    A versatile 2D particle emitter for creating visual effects like fire, rain, and explosions.
    All properties can be modified in real-time from Python to dynamically animate the emitter.
    """

    is_emitting: bool
    """If True, the system continuously spawns particles according to the emission_rate."""

    emission_rate: float
    """Number of particles generated per second."""

    life_min: float
    """Minimum lifetime of a generated particle in seconds."""

    life_max: float
    """Maximum lifetime of a generated particle in seconds."""

    speed_min: float
    """Minimum initial speed of a particle."""

    speed_max: float
    """Maximum initial speed of a particle."""

    emission_angle: float
    """The main direction the particles are fired in degrees (-90.0 is straight up)."""

    angle_spread: float
    """The cone width in degrees where particles can randomly spawn around the emission_angle."""

    gravity: float
    """Downward force applied to particles over time. Use negative values to make them float up."""

    start_color: Color
    """The color of the particle when it is born."""

    end_color: Color
    """The color of the particle when it dies (useful for fading out with alpha)."""

    start_size: float
    """The size in pixels of the particle when it is born."""

    end_size: float
    """The size in pixels of the particle when it dies."""

    def __init__(self) -> None:
        """Initializes a new ParticleSystem2d with default values."""
        ...

    def emit_burst(self, count: int) -> None:
        """
        Instantly fires a specific number of particles, ignoring the is_emitting state.
        Perfect for instantaneous effects like explosions, hit sparks, or item collection.

        Args:
            count: The number of particles to spawn immediately.
        """
        ...

angle_spread instance-attribute

The cone width in degrees where particles can randomly spawn around the emission_angle.

emission_angle instance-attribute

The main direction the particles are fired in degrees (-90.0 is straight up).

emission_rate instance-attribute

Number of particles generated per second.

end_color instance-attribute

The color of the particle when it dies (useful for fading out with alpha).

end_size instance-attribute

The size in pixels of the particle when it dies.

gravity instance-attribute

Downward force applied to particles over time. Use negative values to make them float up.

is_emitting instance-attribute

If True, the system continuously spawns particles according to the emission_rate.

life_max instance-attribute

Maximum lifetime of a generated particle in seconds.

life_min instance-attribute

Minimum lifetime of a generated particle in seconds.

speed_max instance-attribute

Maximum initial speed of a particle.

speed_min instance-attribute

Minimum initial speed of a particle.

start_color instance-attribute

The color of the particle when it is born.

start_size instance-attribute

The size in pixels of the particle when it is born.

__init__()

Initializes a new ParticleSystem2d with default values.

Source code in foxvoid/__init__.pyi

def __init__(self) -> None:
    """Initializes a new ParticleSystem2d with default values."""
    ...

emit_burst(count)

Instantly fires a specific number of particles, ignoring the is_emitting state. Perfect for instantaneous effects like explosions, hit sparks, or item collection.

Parameters:

Name	Type	Description	Default
count	int	The number of particles to spawn immediately.	required

Source code in foxvoid/__init__.pyi

def emit_burst(self, count: int) -> None:
    """
    Instantly fires a specific number of particles, ignoring the is_emitting state.
    Perfect for instantaneous effects like explosions, hit sparks, or item collection.

    Args:
        count: The number of particles to spawn immediately.
    """
    ...

Physics

Global physics engine.

Source code in foxvoid/__init__.pyi

class Physics:
    """Global physics engine."""

    @staticmethod
    def raycast(origin: Tuple[float, float], direction: Tuple[float, float], distance: float) -> RaycastHit:
        """
        Casts an invisible ray into the scene to detect collisions.

        Example: Physics.raycast((x, y), (0, 1), 100.0) casts a ray downwards.
        """
        ...

raycast(origin, direction, distance) staticmethod

Casts an invisible ray into the scene to detect collisions.

Example: Physics.raycast((x, y), (0, 1), 100.0) casts a ray downwards.

Source code in foxvoid/__init__.pyi

@staticmethod
def raycast(origin: Tuple[float, float], direction: Tuple[float, float], distance: float) -> RaycastHit:
    """
    Casts an invisible ray into the scene to detect collisions.

    Example: Physics.raycast((x, y), (0, 1), 100.0) casts a ray downwards.
    """
    ...

PolygonCollider

Bases: Component

A custom polygonal shape collider. Warning: The shape MUST be convex (no hollow parts/indentations), and the vertices should ideally be defined in a clockwise order.

Source code in foxvoid/__init__.pyi

class PolygonCollider(Component):
    """
    A custom polygonal shape collider.
    Warning: The shape MUST be convex (no hollow parts/indentations),
    and the vertices should ideally be defined in a clockwise order.
    """
    local_vertices: list[Vector2]
    offset: Vector2
    is_trigger: bool

    def __init__(self) -> None: 
        """
        Initializes a PolygonCollider with a default triangle shape.
        """
        ...

__init__()

Initializes a PolygonCollider with a default triangle shape.

Source code in foxvoid/__init__.pyi

def __init__(self) -> None: 
    """
    Initializes a PolygonCollider with a default triangle shape.
    """
    ...

RaycastHit

Contains information about a raycast impact.

Source code in foxvoid/__init__.pyi

class RaycastHit:
    """Contains information about a raycast impact."""

    hit: bool
    """True if the ray hit a solid object or a TileMap."""

    collider: Optional[GameObject]
    """The object hit by the ray (can be None if nothing was hit)."""

    point: Tuple[float, float]
    """The exact (x, y) world coordinates of the impact point."""

    distance: float
    """The distance between the ray's origin and the impact point."""

collider instance-attribute

The object hit by the ray (can be None if nothing was hit).

distance instance-attribute

The distance between the ray's origin and the impact point.

hit instance-attribute

True if the ray hit a solid object or a TileMap.

point instance-attribute

The exact (x, y) world coordinates of the impact point.

RectCollider

Bases: Component

Component that defines a 2D rectangular collision shape. It does not apply physics forces by itself, it only defines the boundary.

Source code in foxvoid/__init__.pyi

class RectCollider(Component):
    """
    Component that defines a 2D rectangular collision shape.
    It does not apply physics forces by itself, it only defines the boundary.
    """

    size: Vector2
    """The width and height of the collision box (default is 50x50)."""

    offset: Vector2
    """The local offset of the collider relative to the GameObject's center position."""

    is_trigger: bool
    """
    If true, this collider will not physically block or bounce off other objects.
    It will only be used to detect overlapping areas (e.g., coins, checkpoints, damage zones).
    """

    def __init__(self, width: float = 50.0, height: float = 50.0) -> None:
        """
        Initializes a RectCollider.
        :param width: The width of the collision bounding box.
        :param height: The height of the collision bounding box.
        """
        ...

is_trigger instance-attribute

If true, this collider will not physically block or bounce off other objects. It will only be used to detect overlapping areas (e.g., coins, checkpoints, damage zones).

offset instance-attribute

The local offset of the collider relative to the GameObject's center position.

size instance-attribute

The width and height of the collision box (default is 50x50).

__init__(width=50.0, height=50.0)

Initializes a RectCollider. :param width: The width of the collision bounding box. :param height: The height of the collision bounding box.

Source code in foxvoid/__init__.pyi

def __init__(self, width: float = 50.0, height: float = 50.0) -> None:
    """
    Initializes a RectCollider.
    :param width: The width of the collision bounding box.
    :param height: The height of the collision bounding box.
    """
    ...

RectTransform

Bases: Component

Component responsible for UI layout, managing anchors, pivots, and screen-space coordinates. Replaces Transform2d for HUD elements.

Source code in foxvoid/__init__.pyi

class RectTransform(Component):
    """
    Component responsible for UI layout, managing anchors, pivots, and screen-space coordinates.
    Replaces Transform2d for HUD elements.
    """

    # The width and height of the UI element in pixels
    size: Vector2

    # The pixel offset relative to the calculated anchor point
    position: Vector2

    # Normalized screen anchor point (0.0 to 1.0)
    # (0,0) is top-left, (1,1) is bottom-right, (0.5, 0.5) is center
    anchor: Vector2

    # Normalized pivot point on the element itself (0.0 to 1.0)
    # Determines which part of the element corresponds to the 'position'
    pivot: Vector2

    def __init__(self) -> None:
        """Initializes a new RectTransform with default centered values."""
        ...

    def get_screen_rect(self) -> Rectangle:
        """
        Calculates the absolute pixel coordinates of the element on the screen.

        :return: A Rectangle object containing (x, y, width, height) ready for Raylib drawing.
        """
        ...

__init__()

Initializes a new RectTransform with default centered values.

Source code in foxvoid/__init__.pyi

def __init__(self) -> None:
    """Initializes a new RectTransform with default centered values."""
    ...

get_screen_rect()

Calculates the absolute pixel coordinates of the element on the screen.

:return: A Rectangle object containing (x, y, width, height) ready for Raylib drawing.

Source code in foxvoid/__init__.pyi

def get_screen_rect(self) -> Rectangle:
    """
    Calculates the absolute pixel coordinates of the element on the screen.

    :return: A Rectangle object containing (x, y, width, height) ready for Raylib drawing.
    """
    ...

Rectangle

A standard Raylib Rectangle containing x, y, width and height

Source code in foxvoid/__init__.pyi

class Rectangle:
    """A standard Raylib Rectangle containing x, y, width and height"""
    x: float
    y: float
    width: float
    height: float

    def __init__(self, x: float = 0.0, y: float = 0.0, width: float = 0.0, height: float = 0.0):
        ...

RigidBody2d

Bases: Component

Component that puts the GameObject under the control of the physics engine. It requires a Collider component on the same GameObject to actually hit things.

Source code in foxvoid/__init__.pyi

class RigidBody2d(Component):
    """
    Component that puts the GameObject under the control of the physics engine.
    It requires a Collider component on the same GameObject to actually hit things.
    """

    velocity: Vector2
    """The current linear speed and direction of the object."""

    mass: float
    """The weight of the object. Heavier objects push lighter objects during collisions."""

    gravity_scale: float
    """
    Multiplier applied to the world's gravity. 
    1.0 is normal gravity, 0.0 means the object floats, negative values make it fall upwards.
    """

    is_kinematic: bool
    """
    If true, the physics engine will NOT apply forces, gravity, or push this object during collisions.
    Useful for moving platforms or objects controlled entirely by animations/scripts.
    """

    @property
    def is_grounded(self) -> bool: ...

    def __init__(self) -> None:
        """
        Initializes a RigidBody2d with default values (mass=1.0, gravity=1.0, non-kinematic).
        """
        ...

gravity_scale instance-attribute

Multiplier applied to the world's gravity. 1.0 is normal gravity, 0.0 means the object floats, negative values make it fall upwards.

is_kinematic instance-attribute

If true, the physics engine will NOT apply forces, gravity, or push this object during collisions. Useful for moving platforms or objects controlled entirely by animations/scripts.

mass instance-attribute

The weight of the object. Heavier objects push lighter objects during collisions.

velocity instance-attribute

The current linear speed and direction of the object.

__init__()

Initializes a RigidBody2d with default values (mass=1.0, gravity=1.0, non-kinematic).

Source code in foxvoid/__init__.pyi

def __init__(self) -> None:
    """
    Initializes a RigidBody2d with default values (mass=1.0, gravity=1.0, non-kinematic).
    """
    ...

Scene

Represents the currently active game scene, containing all active GameObjects. Provides global access and search utilities.

Source code in foxvoid/__init__.pyi

class Scene:
    """
    Represents the currently active game scene, containing all active GameObjects.
    Provides global access and search utilities.
    """

    @staticmethod
    def find_object_by_name(name: str) -> Optional[GameObject]:
        """
        Searches for a GameObject by its exact name across the entire active scene.
        This is a global search and will find the object regardless of its parent.

        Args:
            name (str): The exact name of the GameObject to search for.

        Returns:
            Optional[GameObject]: The found GameObject instance, or None if no object matches the name.

        Example:
            camera = Scene.find_object_by_name("Main Camera")
            if camera:
                print("Camera found!")
        """
        ...

    @staticmethod
    def find_objects_with_tag(target_tag: str) -> List[GameObject]:
        """
        Searches for all active GameObjects matching the given tag across the entire scene.
        This method is highly optimized in C++ for fast radar and collision queries.

        Args:
            target_tag (str): The tag to search for (e.g., "Enemy").

        Returns:
            List[GameObject]: A list of all active GameObjects that possess the requested tag.
                              Returns an empty list if no objects match.

        Example:
            enemies = Scene.find_objects_with_tag("Enemy")
            for enemy in enemies:
                enemy_transform = enemy.get_component(Transform2d)
                # Calculate distance...
        """
        ...

find_object_by_name(name) staticmethod

Searches for a GameObject by its exact name across the entire active scene. This is a global search and will find the object regardless of its parent.

Parameters:

Name	Type	Description	Default
name	str	The exact name of the GameObject to search for.	required

Returns:

Type	Description
Optional[GameObject]	Optional[GameObject]: The found GameObject instance, or None if no object matches the name.

Example

camera = Scene.find_object_by_name("Main Camera") if camera: print("Camera found!")

Source code in foxvoid/__init__.pyi

@staticmethod
def find_object_by_name(name: str) -> Optional[GameObject]:
    """
    Searches for a GameObject by its exact name across the entire active scene.
    This is a global search and will find the object regardless of its parent.

    Args:
        name (str): The exact name of the GameObject to search for.

    Returns:
        Optional[GameObject]: The found GameObject instance, or None if no object matches the name.

    Example:
        camera = Scene.find_object_by_name("Main Camera")
        if camera:
            print("Camera found!")
    """
    ...

find_objects_with_tag(target_tag) staticmethod

Searches for all active GameObjects matching the given tag across the entire scene. This method is highly optimized in C++ for fast radar and collision queries.

Parameters:

Name	Type	Description	Default
target_tag	str	The tag to search for (e.g., "Enemy").	required

Returns:

Type	Description
List[GameObject]	List[GameObject]: A list of all active GameObjects that possess the requested tag. Returns an empty list if no objects match.

Example

enemies = Scene.find_objects_with_tag("Enemy") for enemy in enemies: enemy_transform = enemy.get_component(Transform2d) # Calculate distance...

Source code in foxvoid/__init__.pyi

@staticmethod
def find_objects_with_tag(target_tag: str) -> List[GameObject]:
    """
    Searches for all active GameObjects matching the given tag across the entire scene.
    This method is highly optimized in C++ for fast radar and collision queries.

    Args:
        target_tag (str): The tag to search for (e.g., "Enemy").

    Returns:
        List[GameObject]: A list of all active GameObjects that possess the requested tag.
                          Returns an empty list if no objects match.

    Example:
        enemies = Scene.find_objects_with_tag("Enemy")
        for enemy in enemies:
            enemy_transform = enemy.get_component(Transform2d)
            # Calculate distance...
    """
    ...

SceneManager

Handles loading and transitioning between different scenes/levels.

Source code in foxvoid/__init__.pyi

class SceneManager:
    """Handles loading and transitioning between different scenes/levels."""

    @staticmethod
    def load_scene(name: str) -> None:
        """
        Requests the engine to load a new scene at the start of the next frame.
        The name should not include the extension or path (e.g., 'main_menu', 'level_01').
        """
        ...

load_scene(name) staticmethod

Requests the engine to load a new scene at the start of the next frame. The name should not include the extension or path (e.g., 'main_menu', 'level_01').

Source code in foxvoid/__init__.pyi

@staticmethod
def load_scene(name: str) -> None:
    """
    Requests the engine to load a new scene at the start of the next frame.
    The name should not include the extension or path (e.g., 'main_menu', 'level_01').
    """
    ...

ScriptableObject

Base class for all data-driven assets in Foxvoid Engine. Inherit from this class to create custom data containers (e.g., Items, Stats, Quests). The engine will automatically inspect your custom properties and generate an ImGui interface.

Source code in foxvoid/__init__.pyi

class ScriptableObject:
    """
    Base class for all data-driven assets in Foxvoid Engine.
    Inherit from this class to create custom data containers (e.g., Items, Stats, Quests).
    The engine will automatically inspect your custom properties and generate an ImGui interface.
    """

    asset_id: str
    """The unique string identifier used to load this asset from disk."""

    name: str
    """The display name of the asset."""

    def __init__(self) -> None: 
        """Initializes an empty ScriptableObject."""
        ...

asset_id instance-attribute

The unique string identifier used to load this asset from disk.

name instance-attribute

The display name of the asset.

__init__()

Initializes an empty ScriptableObject.

Source code in foxvoid/__init__.pyi

def __init__(self) -> None: 
    """Initializes an empty ScriptableObject."""
    ...

ShapeRenderer

Bases: Component

Component that renders a basic geometric rectangle. It can be drawn in world space or locked to the screen as a HUD element.

Source code in foxvoid/__init__.pyi

class ShapeRenderer(Component):
    """
    Component that renders a basic geometric rectangle.
    It can be drawn in world space or locked to the screen as a HUD element.
    """

    width: float
    """The base width of the shape in pixels (before Transform scale)."""

    height: float
    """The base height of the shape in pixels (before Transform scale)."""

    color: Color
    """The RGBA color of the shape."""

    is_hud: bool
    """
    If True, the shape is rendered in Screen Space (sticks to the camera viewport).
    If False, it is rendered in World Space.
    """

    def __init__(self) -> None:
        """
        Initializes a ShapeRenderer with default values (50x50, white).
        """
        ...

color instance-attribute

The RGBA color of the shape.

height instance-attribute

The base height of the shape in pixels (before Transform scale).

is_hud instance-attribute

If True, the shape is rendered in Screen Space (sticks to the camera viewport). If False, it is rendered in World Space.

width instance-attribute

The base width of the shape in pixels (before Transform scale).

__init__()

Initializes a ShapeRenderer with default values (50x50, white).

Source code in foxvoid/__init__.pyi

def __init__(self) -> None:
    """
    Initializes a ShapeRenderer with default values (50x50, white).
    """
    ...

Slider

Bases: Component

An interactive UI element that allows selecting a numerical value by dragging a handle along a track. Triggers on_gui_click() dynamically.

Source code in foxvoid/__init__.pyi

class Slider(Component):
    """
    An interactive UI element that allows selecting a numerical value 
    by dragging a handle along a track. Triggers on_gui_click() dynamically.
    """
    value: float
    min_value: float
    max_value: float

    track_color: 'Color'
    handle_color: 'Color'
    active_handle_color: 'Color'

    def __init__(self) -> None: ...

SpriteRenderer

Bases: Component

Renders a 2D texture at the position defined by the entity's Transform2d.

Source code in foxvoid/__init__.pyi

class SpriteRenderer(Component):
    """Renders a 2D texture at the position defined by the entity's Transform2d."""

    def __init__(self, texture_path: str) -> None: 
        """
        Loads an image file into GPU memory for rendering.

        Args:
            texture_path: The relative path to the image file (e.g., 'assets/player.png').
        """
        ...

    @property
    def width(self) -> float: ...

    @property
    def height(self) -> float: ...

__init__(texture_path)

Loads an image file into GPU memory for rendering.

Parameters:

Name	Type	Description	Default
texture_path	str	The relative path to the image file (e.g., 'assets/player.png').	required

Source code in foxvoid/__init__.pyi

def __init__(self, texture_path: str) -> None: 
    """
    Loads an image file into GPU memory for rendering.

    Args:
        texture_path: The relative path to the image file (e.g., 'assets/player.png').
    """
    ...

SpriteSheetRenderer

Bases: Component

Renders a specific frame from a grid-based spritesheet texture.

Source code in foxvoid/__init__.pyi

class SpriteSheetRenderer(Component):
    """Renders a specific frame from a grid-based spritesheet texture."""

    def __init__(self, texture_path: str, columns: int, rows: int) -> None: 
        """
        Loads a spritesheet into GPU memory.

        Args:
            texture_path: The relative path to the image file.
            columns: The number of columns in the spritesheet grid.
            rows: The number of rows in the spritesheet grid.
        """
        ...

    @property
    def frame(self) -> int:
        """The current frame index being rendered (0 to frame_count - 1)."""
        ...

    @frame.setter
    def frame(self, value: int) -> None: ...

    @property
    def frame_count(self) -> int:
        """Total number of frames in the spritesheet (Read-only)."""
        ...

frame property writable

The current frame index being rendered (0 to frame_count - 1).

frame_count property

Total number of frames in the spritesheet (Read-only).

__init__(texture_path, columns, rows)

Loads a spritesheet into GPU memory.

Parameters:

Name	Type	Description	Default
texture_path	str	The relative path to the image file.	required
columns	int	The number of columns in the spritesheet grid.	required
rows	int	The number of rows in the spritesheet grid.	required

Source code in foxvoid/__init__.pyi

def __init__(self, texture_path: str, columns: int, rows: int) -> None: 
    """
    Loads a spritesheet into GPU memory.

    Args:
        texture_path: The relative path to the image file.
        columns: The number of columns in the spritesheet grid.
        rows: The number of rows in the spritesheet grid.
    """
    ...

TextInput

Bases: Component

An interactive text field. Captures keyboard input when clicked. Triggers on_gui_click() when the user presses 'Enter'.

Source code in foxvoid/__init__.pyi

class TextInput(Component):
    """
    An interactive text field. Captures keyboard input when clicked.
    Triggers on_gui_click() when the user presses 'Enter'.
    """
    text: str
    max_length: int
    font_size: int
    spacing: float

    text_color: 'Color'
    bg_color: 'Color'
    focused_bg_color: 'Color'

    def __init__(self) -> None: ...
    def is_focused(self) -> bool: ...

    def set_font(self, path: str) -> None:
        """
        Updates the font used by the text input.
        Example: self.input.set_font("assets/fonts/arial.ttf")
        """
        ...

set_font(path)

Updates the font used by the text input. Example: self.input.set_font("assets/fonts/arial.ttf")

Source code in foxvoid/__init__.pyi

def set_font(self, path: str) -> None:
    """
    Updates the font used by the text input.
    Example: self.input.set_font("assets/fonts/arial.ttf")
    """
    ...

TextRenderer

Bases: Component

Renders text either in the game world or attached to the screen (HUD).

Source code in foxvoid/__init__.pyi

class TextRenderer(Component):
    """
    Renders text either in the game world or attached to the screen (HUD).
    """

    text: str
    """The string of text to display. Supports line breaks (\\n)."""

    font_size: float
    """The size of the rendered text."""

    is_hud: bool
    """If True, renders in screen space (ignoring the camera). If False, renders in world space."""

    font_path: str
    """The path to the custom .ttf or .otf font file. Leave empty to use the default engine font."""

    def __init__(self) -> None:
        """Initializes a new TextRenderer."""
        ...

font_path instance-attribute

The path to the custom .ttf or .otf font file. Leave empty to use the default engine font.

font_size instance-attribute

The size of the rendered text.

is_hud instance-attribute

If True, renders in screen space (ignoring the camera). If False, renders in world space.

text instance-attribute

The string of text to display. Supports line breaks (\n).

__init__()

Initializes a new TextRenderer.

Source code in foxvoid/__init__.pyi

def __init__(self) -> None:
    """Initializes a new TextRenderer."""
    ...

TileLayer

Represents a single layer of tiles within a TileMap.

Source code in foxvoid/__init__.pyi

class TileLayer:
    """Represents a single layer of tiles within a TileMap."""

    name: str
    """The display name of the layer."""

    is_visible: bool
    """Determines if the layer is currently rendered on screen."""

    is_solid: bool
    """Determines if the layer generates collision boxes for the physics engine."""

is_solid instance-attribute

Determines if the layer generates collision boxes for the physics engine.

is_visible instance-attribute

Determines if the layer is currently rendered on screen.

name instance-attribute

The display name of the layer.

TileMap

Bases: Component

Manages a grid-based tile map with multiple layers and physics collision support. Useful for level design and procedural generation.

Source code in foxvoid/__init__.pyi

class TileMap(Component):
    """
    Manages a grid-based tile map with multiple layers and physics collision support.
    Useful for level design and procedural generation.
    """

    grid_width: int
    """The number of columns in the grid."""

    grid_height: int
    """The number of rows in the grid."""

    tile_spacing: int
    """The gap in pixels between each tile in the source texture."""

    def __init__(self) -> None:
        """Initializes a new TileMap with a default 'Background' layer."""
        ...

    def load_tileset(self, path: str) -> None:
        """
        Loads a tileset texture from the specified file path.
        """
        ...

    def resize(self, new_width: int, new_height: int) -> None:
        """
        Resizes the map grid while safely preserving existing tile data.
        """
        ...

    def add_layer(self, name: str) -> None:
        """
        Adds a new empty layer on top of the existing ones.
        """
        ...

    def get_tile(self, layer_index: int, x: int, y: int) -> int:
        """
        Returns the tile ID at the given grid coordinates.
        Returns -1 if the tile is empty or if the coordinates are out of bounds.
        """
        ...

    def set_tile(self, layer_index: int, x: int, y: int, tile_id: int) -> None:
        """
        Sets the tile ID at the given grid coordinates on a specific layer.
        Use -1 as the tile_id to erase a tile.
        """
        ...

    @overload
    def get_layer(self, index: int) -> Optional[TileLayer]:
        """
        Retrieves a layer by its numerical index (0 is the bottom layer).
        Returns None if the index is out of bounds.
        """
        ...

    @overload
    def get_layer(self, name: str) -> Optional[TileLayer]:
        """
        Retrieves a layer by its assigned name.
        Returns None if no layer with this name exists.
        """
        ...

grid_height instance-attribute

The number of rows in the grid.

grid_width instance-attribute

The number of columns in the grid.

tile_spacing instance-attribute

The gap in pixels between each tile in the source texture.

__init__()

Initializes a new TileMap with a default 'Background' layer.

Source code in foxvoid/__init__.pyi

def __init__(self) -> None:
    """Initializes a new TileMap with a default 'Background' layer."""
    ...

add_layer(name)

Adds a new empty layer on top of the existing ones.

Source code in foxvoid/__init__.pyi

def add_layer(self, name: str) -> None:
    """
    Adds a new empty layer on top of the existing ones.
    """
    ...

get_tile(layer_index, x, y)

Returns the tile ID at the given grid coordinates. Returns -1 if the tile is empty or if the coordinates are out of bounds.

Source code in foxvoid/__init__.pyi

def get_tile(self, layer_index: int, x: int, y: int) -> int:
    """
    Returns the tile ID at the given grid coordinates.
    Returns -1 if the tile is empty or if the coordinates are out of bounds.
    """
    ...

load_tileset(path)

Loads a tileset texture from the specified file path.

Source code in foxvoid/__init__.pyi

def load_tileset(self, path: str) -> None:
    """
    Loads a tileset texture from the specified file path.
    """
    ...

resize(new_width, new_height)

Resizes the map grid while safely preserving existing tile data.

Source code in foxvoid/__init__.pyi

def resize(self, new_width: int, new_height: int) -> None:
    """
    Resizes the map grid while safely preserving existing tile data.
    """
    ...

set_tile(layer_index, x, y, tile_id)

Sets the tile ID at the given grid coordinates on a specific layer. Use -1 as the tile_id to erase a tile.

Source code in foxvoid/__init__.pyi

def set_tile(self, layer_index: int, x: int, y: int, tile_id: int) -> None:
    """
    Sets the tile ID at the given grid coordinates on a specific layer.
    Use -1 as the tile_id to erase a tile.
    """
    ...

Transform2d

Bases: Component

Component managing spatial position, rotation, and scale.

Source code in foxvoid/__init__.pyi

class Transform2d(Component):
    """Component managing spatial position, rotation, and scale."""

    position: Vector2 # Local position
    scale: Vector2    # Local scale
    rotation: float   # Local rotation
    z_index: int      # Local z-index order

    def __init__(self, x: float = 0.0, y: float = 0.0) -> None: 
        """Creates a new Transform2d component."""
        ...

    def get_global_position(self) -> Vector2:
        """Returns the true world position, taking all parent transforms into account."""
        ...

    def get_global_rotation(self) -> float:
        """Returns the true world rotation in degrees."""
        ...

    def get_global_scale(self) -> Vector2:
        """Returns the true world scale."""
        ...

    def get_global_z_index(self) -> int:
        """Returns the accumulated rendering order."""
        ...

    def set_global_position(self, target_global_pos: Vector2) -> None:
        """Moves the object to a world position by automatically calculating the required local position."""
        ...

    def set_global_rotation(self, target_global_rot: float) -> None:
        """Sets the world rotation by automatically calculating the required local rotation."""
        ...

    def set_global_scale(self, target_global_scale: Vector2) -> None:
        """Sets the world scale by automatically calculating the required local scale."""
        ...

__init__(x=0.0, y=0.0)

Creates a new Transform2d component.

Source code in foxvoid/__init__.pyi

def __init__(self, x: float = 0.0, y: float = 0.0) -> None: 
    """Creates a new Transform2d component."""
    ...

get_global_position()

Returns the true world position, taking all parent transforms into account.

Source code in foxvoid/__init__.pyi

def get_global_position(self) -> Vector2:
    """Returns the true world position, taking all parent transforms into account."""
    ...

get_global_rotation()

Returns the true world rotation in degrees.

Source code in foxvoid/__init__.pyi

def get_global_rotation(self) -> float:
    """Returns the true world rotation in degrees."""
    ...

get_global_scale()

Returns the true world scale.

Source code in foxvoid/__init__.pyi

def get_global_scale(self) -> Vector2:
    """Returns the true world scale."""
    ...

get_global_z_index()

Returns the accumulated rendering order.

Source code in foxvoid/__init__.pyi

def get_global_z_index(self) -> int:
    """Returns the accumulated rendering order."""
    ...

set_global_position(target_global_pos)

Moves the object to a world position by automatically calculating the required local position.

Source code in foxvoid/__init__.pyi

def set_global_position(self, target_global_pos: Vector2) -> None:
    """Moves the object to a world position by automatically calculating the required local position."""
    ...

set_global_rotation(target_global_rot)

Sets the world rotation by automatically calculating the required local rotation.

Source code in foxvoid/__init__.pyi

def set_global_rotation(self, target_global_rot: float) -> None:
    """Sets the world rotation by automatically calculating the required local rotation."""
    ...

set_global_scale(target_global_scale)

Sets the world scale by automatically calculating the required local scale.

Source code in foxvoid/__init__.pyi

def set_global_scale(self, target_global_scale: Vector2) -> None:
    """Sets the world scale by automatically calculating the required local scale."""
    ...

VBoxContainer

Bases: Component

Automatically aligns child UI elements vertically based on their RectTransforms. Perfect for lists, menus, and inventories.

Source code in foxvoid/__init__.pyi

class VBoxContainer(Component):
    """
    Automatically aligns child UI elements vertically based on their RectTransforms.
    Perfect for lists, menus, and inventories.
    """

    # Space between each child element in pixels
    spacing: float

    # Inner margins at the top and bottom
    padding_top: float
    padding_bottom: float

    # Forces horizontal alignment of children (0.0 = Left, 0.5 = Center, 1.0 = Right)
    horizontal_alignment: float

    def __init__(self) -> None: ...

Vector2

A 2D vector representing mathematical points or directions.

Source code in foxvoid/__init__.pyi

class Vector2:
    """A 2D vector representing mathematical points or directions."""
    x: float
    y: float
    def __init__(self, x: float = 0.0, y: float = 0.0) -> None: ...

is_pixel_art_mode()

Returns whether the engine is currently in pixel art mode.

Source code in foxvoid/__init__.pyi

def is_pixel_art_mode() -> bool:
    """Returns whether the engine is currently in pixel art mode."""
    ...

set_pixel_art_mode(enable)

Globally configures texture filtering. Call this BEFORE instantiating GameObjects with sprites. - True: Nearest-neighbor filtering (Sharp, blocky, perfect for pixel art). - False: Bilinear filtering (Smooth, interpolated edges).

Source code in foxvoid/__init__.pyi

def set_pixel_art_mode(enable: bool) -> None:
    """
    Globally configures texture filtering. 
    Call this BEFORE instantiating GameObjects with sprites.
    - True: Nearest-neighbor filtering (Sharp, blocky, perfect for pixel art).
    - False: Bilinear filtering (Smooth, interpolated edges).
    """
    ...