kraken-engine 1.2.1__cp313-cp313-macosx_11_0_arm64.whl

pykraken/_core/math.pyi

@@ -0,0 +1,184 @@
+"""
+Math related functions
+"""
+from __future__ import annotations
+import pykraken._core
+import typing
+__all__: list[str] = ['angle_between', 'clamp', 'cross', 'dot', 'from_polar', 'lerp', 'normalize', 'remap', 'rotate', 'scale_to_length', 'to_deg', 'to_rad']
+def angle_between(a: pykraken._core.Vec2, b: pykraken._core.Vec2) -> float:
+    """
+    Calculate the angle between two vectors.
+    
+    Args:
+        a (Vec2): The first vector.
+        b (Vec2): The second vector.
+    
+    Returns:
+        float: The angle between the vectors in radians [0, π].
+    """
+@typing.overload
+def clamp(vec: pykraken._core.Vec2, min_vec: pykraken._core.Vec2, max_vec: pykraken._core.Vec2) -> pykraken._core.Vec2:
+    """
+    Clamp a vector between two boundary vectors.
+    
+    Args:
+        vector (Vec2): The vector to clamp.
+        min_vec (Vec2): The minimum boundary vector.
+        max_vec (Vec2): The maximum boundary vector.
+    
+    Returns:
+        Vec2: A new vector with components clamped between min and max.
+    """
+@typing.overload
+def clamp(value: typing.SupportsFloat, min_val: typing.SupportsFloat, max_val: typing.SupportsFloat) -> float:
+    """
+    Clamp a value between two boundaries.
+    
+    Args:
+        value (float): The value to clamp.
+        min_val (float): The minimum boundary.
+        max_val (float): The maximum boundary.
+    
+    Returns:
+        float: The clamped value.
+    """
+def cross(a: pykraken._core.Vec2, b: pykraken._core.Vec2) -> float:
+    """
+    Calculate the 2D cross product of two vectors.
+    
+    Args:
+        a (Vec2): The first vector.
+        b (Vec2): The second vector.
+    
+    Returns:
+        float: The 2D cross product (a.x * b.y - a.y * b.x).
+    """
+def dot(a: pykraken._core.Vec2, b: pykraken._core.Vec2) -> float:
+    """
+    Calculate the dot product of two vectors.
+    
+    Args:
+        a (Vec2): The first vector.
+        b (Vec2): The second vector.
+    
+    Returns:
+        float: The dot product (a.x * b.x + a.y * b.y).
+    """
+@typing.overload
+def from_polar(angle: typing.SupportsFloat, radius: typing.SupportsFloat) -> pykraken._core.Vec2:
+    """
+    Convert polar coordinates to a Cartesian vector.
+    
+    Args:
+        angle (float): The angle in radians.
+        radius (float): The radius/distance from origin.
+    
+    Returns:
+        Vec2: The equivalent Cartesian vector.
+    """
+@typing.overload
+def from_polar(polar: pykraken._core.PolarCoordinate) -> pykraken._core.Vec2:
+    """
+    Convert a PolarCoordinate object to a Cartesian vector.
+    
+    Args:
+        polar (PolarCoordinate): The polar coordinate to convert.
+    
+    Returns:
+        Vec2: The equivalent Cartesian vector.
+    """
+@typing.overload
+def lerp(a: pykraken._core.Vec2, b: pykraken._core.Vec2, t: typing.SupportsFloat) -> pykraken._core.Vec2:
+    """
+    Linearly interpolate between two Vec2s.
+    
+    Args:
+        a (Vec2): The start vector.
+        b (Vec2): The end vector.
+        t (float): The interpolation factor [0.0, 1.0].
+    
+    Returns:
+        Vec2: The interpolated vector.
+    """
+@typing.overload
+def lerp(a: typing.SupportsFloat, b: typing.SupportsFloat, t: typing.SupportsFloat) -> float:
+    """
+    Linearly interpolate between two values.
+    
+    Args:
+        a (float): The start value.
+        b (float): The end value.
+        t (float): The interpolation factor [0.0, 1.0].
+    
+    Returns:
+        float: The interpolated value.
+    """
+def normalize(vec: pykraken._core.Vec2) -> pykraken._core.Vec2:
+    """
+    Normalize a vector to unit length.
+    
+    Args:
+        vector (Vec2): The input vector.
+    
+    Returns:
+        Vec2: A new normalized vector.
+    """
+def remap(in_min: typing.SupportsFloat, in_max: typing.SupportsFloat, out_min: typing.SupportsFloat, out_max: typing.SupportsFloat, value: typing.SupportsFloat) -> float:
+    """
+    Remap a value from one range to another.
+    
+    Args:
+        in_min (float): Input range minimum.
+        in_max (float): Input range maximum.
+        out_min (float): Output range minimum.
+        out_max (float): Output range maximum.
+        value (float): The value to remap.
+    
+    Returns:
+        float: The remapped value in the output range.
+    
+    Raises:
+        ValueError: If in_min equals in_max.
+    """
+def rotate(vec: pykraken._core.Vec2, radians: typing.SupportsFloat) -> pykraken._core.Vec2:
+    """
+        Rotate a vector by the given angle (non-mutating).
+    
+        Args:
+            vec (Vec2): The vector to rotate.
+            radians (float): Angle in radians.
+    
+        Returns:
+            Vec2: A new rotated vector.
+    """
+def scale_to_length(vector: pykraken._core.Vec2, length: typing.SupportsFloat) -> pykraken._core.Vec2:
+    """
+    Scale a vector to a given length.
+    
+    Args:
+        vector (Vec2): The input vector.
+        length (float): The target length.
+    
+    Returns:
+        Vec2: A new vector scaled to the specified length.
+    """
+def to_deg(radians: typing.SupportsFloat) -> float:
+    """
+    Convert radians to degrees.
+    
+    Args:
+        radians (float): The angle in radians.
+    
+    Returns:
+        float: The angle in degrees.
+    """
+def to_rad(degrees: typing.SupportsFloat) -> float:
+    """
+    Convert degrees to radians.
+    
+    Args:
+        degrees (float): The angle in degrees.
+    
+    Returns:
+        float: The angle in radians.
+    """

pykraken/_core/mouse.pyi

@@ -0,0 +1,85 @@
+"""
+Mouse related functions
+"""
+from __future__ import annotations
+import pykraken._core
+__all__: list[str] = ['get_pos', 'get_rel', 'hide', 'is_hidden', 'is_just_pressed', 'is_just_released', 'is_locked', 'is_pressed', 'lock', 'show', 'unlock']
+def get_pos() -> pykraken._core.Vec2:
+    """
+    Get the current position of the mouse cursor.
+    
+    Returns:
+        tuple[float, float]: The current mouse position as (x, y) coordinates.
+    """
+def get_rel() -> pykraken._core.Vec2:
+    """
+    Get the relative mouse movement since the last frame.
+    
+    Returns:
+        tuple[float, float]: The relative movement of the mouse as (dx, dy).
+    """
+def hide() -> None:
+    """
+    Hide the mouse cursor from view.
+    
+    The cursor will be invisible but mouse input will still be tracked.
+    """
+def is_hidden() -> bool:
+    """
+    Check if the mouse cursor is currently hidden.
+    
+    Returns:
+        bool: True if the cursor is hidden.
+    """
+def is_just_pressed(button: pykraken._core.MouseButton) -> bool:
+    """
+    Check if a mouse button was pressed this frame.
+    
+    Args:
+        button (MouseButton): The mouse button to check.
+    
+    Returns:
+        bool: True if the button was just pressed.
+    """
+def is_just_released(button: pykraken._core.MouseButton) -> bool:
+    """
+    Check if a mouse button was released this frame.
+    
+    Args:
+        button (MouseButton): The mouse button to check.
+    
+    Returns:
+        bool: True if the button was just released.
+    """
+def is_locked() -> bool:
+    """
+    Check if the mouse is currently locked to the window.
+    
+    Returns:
+        bool: True if the mouse is locked.
+    """
+def is_pressed(button: pykraken._core.MouseButton) -> bool:
+    """
+    Check if a mouse button is currently pressed.
+    
+    Args:
+        button (MouseButton): The mouse button to check (e.g., kn.MOUSE_LEFT).
+    
+    Returns:
+        bool: True if the button is currently pressed.
+    """
+def lock() -> None:
+    """
+    Lock the mouse to the center of the window.
+    
+    Useful for first-person controls where you want to capture mouse movement
+    without letting the cursor leave the window area.
+    """
+def show() -> None:
+    """
+    Show the mouse cursor if it was hidden.
+    """
+def unlock() -> None:
+    """
+    Unlock the mouse from the window, allowing it to move freely.
+    """

pykraken/_core/rect.pyi

@@ -0,0 +1,93 @@
+"""
+Rectangle related functions
+"""
+from __future__ import annotations
+import pykraken._core
+import typing
+__all__: list[str] = ['clamp', 'move', 'scale_by', 'scale_to']
+@typing.overload
+def clamp(rect: pykraken._core.Rect, min: pykraken._core.Vec2, max: pykraken._core.Vec2) -> pykraken._core.Rect:
+    """
+    Clamp a rectangle to be within the specified bounds.
+    
+    Args:
+        rect (Rect): The rectangle to clamp.
+        min (Vec2): The minimum bounds as (min_x, min_y).
+        max (Vec2): The maximum bounds as (max_x, max_y).
+    
+    Returns:
+        Rect: A new rectangle clamped within the bounds.
+    
+    Raises:
+        ValueError: If min >= max or rectangle is larger than the clamp area.
+    """
+@typing.overload
+def clamp(rect: pykraken._core.Rect, other: pykraken._core.Rect) -> pykraken._core.Rect:
+    """
+    Clamp a rectangle to be within another rectangle.
+    
+    Args:
+        rect (Rect): The rectangle to clamp.
+        other (Rect): The rectangle to clamp within.
+    
+    Returns:
+        Rect: A new rectangle clamped within the other rectangle.
+    
+    Raises:
+        ValueError: If rect is larger than the clamp area.
+    """
+def move(rect: pykraken._core.Rect, offset: pykraken._core.Vec2) -> pykraken._core.Rect:
+    """
+    Move a rectangle by the given offset.
+    
+    Args:
+        rect (Rect): The rectangle to move.
+        offset (Vec2): The offset to move by as (dx, dy).
+    
+    Returns:
+        Rect: A new rectangle moved by the offset.
+    """
+@typing.overload
+def scale_by(rect: pykraken._core.Rect, factor: typing.SupportsFloat) -> pykraken._core.Rect:
+    """
+    Scale a rectangle by a uniform factor.
+    
+    Args:
+        rect (Rect): The rectangle to scale.
+        factor (float): The scaling factor (must be > 0).
+    
+    Returns:
+        Rect: A new rectangle scaled by the factor.
+    
+    Raises:
+        ValueError: If factor is <= 0.
+    """
+@typing.overload
+def scale_by(rect: pykraken._core.Rect, factor: pykraken._core.Vec2) -> pykraken._core.Rect:
+    """
+    Scale a rectangle by different factors for width and height.
+    
+    Args:
+        rect (Rect): The rectangle to scale.
+        factor (Vec2): The scaling factors as (scale_x, scale_y).
+    
+    Returns:
+        Rect: A new rectangle scaled by the factors.
+    
+    Raises:
+        ValueError: If any factor is <= 0.
+    """
+def scale_to(rect: pykraken._core.Rect, size: pykraken._core.Vec2) -> pykraken._core.Rect:
+    """
+    Scale a rectangle to the specified size.
+    
+    Args:
+        rect (Rect): The rectangle to scale.
+        size (Vec2): The new size as (width, height).
+    
+    Returns:
+        Rect: A new rectangle scaled to the specified size.
+    
+    Raises:
+        ValueError: If width or height is <= 0.
+    """

pykraken/_core/renderer.pyi

@@ -0,0 +1,74 @@
+"""
+Functions for rendering graphics
+"""
+from __future__ import annotations
+import pykraken._core
+import typing
+__all__: list[str] = ['clear', 'draw', 'get_res', 'present', 'read_pixels']
+@typing.overload
+def clear(color: typing.Any = None) -> None:
+    """
+    Clear the renderer with the specified color.
+    
+    Args:
+        color (Color, optional): The color to clear with. Defaults to black (0, 0, 0, 255).
+    
+    Raises:
+        ValueError: If color values are not between 0 and 255.
+    """
+@typing.overload
+def clear(r: typing.SupportsInt, g: typing.SupportsInt, b: typing.SupportsInt, a: typing.SupportsInt = 255) -> None:
+    """
+    Clear the renderer with the specified color.
+    
+    Args:
+        r (int): Red component (0-255).
+        g (int): Green component (0-255).
+        b (int): Blue component (0-255).
+        a (int, optional): Alpha component (0-255). Defaults to 255.
+    """
+@typing.overload
+def draw(texture: pykraken._core.Texture, dst: pykraken._core.Rect, src: typing.Any = None) -> None:
+    """
+    Render a texture with specified destination and source rectangles.
+    
+    Args:
+        texture (Texture): The texture to render.
+        dst (Rect): The destination rectangle on the renderer.
+        src (Rect, optional): The source rectangle from the texture. Defaults to entire texture if not specified.
+    """
+@typing.overload
+def draw(texture: pykraken._core.Texture, pos: typing.Any = None, anchor: pykraken._core.Anchor = pykraken._core.Anchor.CENTER) -> None:
+    """
+    Render a texture at the specified position with anchor alignment.
+    
+    Args:
+        texture (Texture): The texture to render.
+        pos (Vec2, optional): The position to draw at. Defaults to (0, 0).
+        anchor (Anchor, optional): The anchor point for positioning. Defaults to CENTER.
+    """
+def get_res() -> pykraken._core.Vec2:
+    """
+    Get the resolution of the renderer.
+    
+    Returns:
+        Vec2: The current rendering resolution as (width, height).
+    """
+def present() -> None:
+    """
+    Present the rendered content to the screen.
+    
+    This finalizes the current frame and displays it. Should be called after
+    all drawing operations for the frame are complete.
+    """
+def read_pixels(src: typing.Any = None) -> pykraken._core.PixelArray:
+    """
+    Read pixel data from the renderer within the specified rectangle.
+    
+    Args:
+        src (Rect, optional): The rectangle area to read pixels from. Defaults to entire renderer if None.
+    Returns:
+        PixelArray: An array containing the pixel data.
+    Raises:
+        RuntimeError: If reading pixels fails.
+    """

pykraken/_core/time.pyi

@@ -0,0 +1,75 @@
+"""
+Time related functions
+"""
+from __future__ import annotations
+import typing
+__all__: list[str] = ['delay', 'get_delta', 'get_elapsed', 'get_fps', 'get_scale', 'set_max_delta', 'set_scale', 'set_target']
+def delay(milliseconds: typing.SupportsInt) -> None:
+    """
+    Delay the program execution for the specified duration.
+    
+    This function pauses execution for the given number of milliseconds.
+    Useful for simple timing control, though using time.set_cap() is generally
+    preferred for precise frame rate control with nanosecond accuracy.
+    
+    Args:
+        milliseconds (int): The number of milliseconds to delay.
+    """
+def get_delta() -> float:
+    """
+    Get the time elapsed since the last frame in seconds.
+    
+    For stability, the returned delta is clamped so it will not be
+    smaller than 1/12 seconds (equivalent to capping at 12 FPS). This prevents
+    unstable calculations that rely on delta when very small frame times are
+    measured.
+    
+    Returns:
+        float: The time elapsed since the last frame, in seconds.
+    """
+def get_elapsed() -> float:
+    """
+    Get the elapsed time since the program started.
+    
+    Returns:
+        float: The total elapsed time since program start, in seconds.
+    """
+def get_fps() -> float:
+    """
+    Get the current frames per second of the program.
+    
+    Returns:
+        float: The current FPS based on the last frame time.
+    """
+def get_scale() -> float:
+    """
+    Get the current global time scale factor.
+    
+    Returns:
+        float: The current time scale factor.
+    """
+def set_max_delta(max_delta: typing.SupportsFloat) -> None:
+    """
+    Set the maximum allowed delta time between frames.
+    
+    Parameters:
+        max_delta (float): The maximum delta time in seconds, greater than 0.0.
+                           This is useful to prevent large delta values during
+                           frame drops or pauses that could destabilize physics or animations.
+    """
+def set_scale(scale: typing.SupportsFloat) -> None:
+    """
+    Set the global time scale factor.
+    
+    Args:
+        scale (float): The time scale factor. Values < 0.0 are clamped to 0.0.
+                       A scale of 1.0 represents normal time, 0.5 is half speed,
+                       and 2.0 is double speed.
+    """
+def set_target(frame_rate: typing.SupportsInt) -> None:
+    """
+    Set the target framerate for the application.
+    
+    Args:
+        frame_rate (int): Target framerate to enforce. Values <= 0 disable frame rate limiting.
+    """

pykraken/_core/transform.pyi

@@ -0,0 +1,141 @@
+"""
+Functions for transforming pixel arrays
+"""
+from __future__ import annotations
+import pykraken._core
+import typing
+__all__: list[str] = ['box_blur', 'flip', 'gaussian_blur', 'grayscale', 'invert', 'rotate', 'scale_by', 'scale_to']
+def box_blur(pixel_array: pykraken._core.PixelArray, radius: typing.SupportsInt, repeat_edge_pixels: bool = True) -> pykraken._core.PixelArray:
+    """
+    Apply a box blur effect to a pixel array.
+    
+    Box blur creates a uniform blur effect by averaging pixels within a square kernel.
+    It's faster than Gaussian blur but produces a more uniform, less natural look.
+    
+    Args:
+        pixel_array (PixelArray): The pixel array to blur.
+        radius (int): The blur radius in pixels. Larger values create stronger blur.
+        repeat_edge_pixels (bool, optional): Whether to repeat edge pixels when sampling
+                                            outside the pixel array bounds. Defaults to True.
+    
+    Returns:
+        PixelArray: A new pixel array with the box blur effect applied.
+    
+    Raises:
+        RuntimeError: If pixel array creation fails during the blur process.
+    """
+def flip(pixel_array: pykraken._core.PixelArray, flip_x: bool, flip_y: bool) -> pykraken._core.PixelArray:
+    """
+    Flip a pixel array horizontally, vertically, or both.
+    
+    Args:
+        pixel_array (PixelArray): The pixel array to flip.
+        flip_x (bool): Whether to flip horizontally (mirror left-right).
+        flip_y (bool): Whether to flip vertically (mirror top-bottom).
+    
+    Returns:
+        PixelArray: A new pixel array with the flipped image.
+    
+    Raises:
+        RuntimeError: If pixel array creation fails.
+    """
+def gaussian_blur(pixel_array: pykraken._core.PixelArray, radius: typing.SupportsInt, repeat_edge_pixels: bool = True) -> pykraken._core.PixelArray:
+    """
+    Apply a Gaussian blur effect to a pixel array.
+    
+    Gaussian blur creates a natural, smooth blur effect using a Gaussian distribution
+    for pixel weighting. It produces higher quality results than box blur but is
+    computationally more expensive.
+    
+    Args:
+        pixel_array (PixelArray): The pixel array to blur.
+        radius (int): The blur radius in pixels. Larger values create stronger blur.
+        repeat_edge_pixels (bool, optional): Whether to repeat edge pixels when sampling
+                                            outside the pixel array bounds. Defaults to True.
+    
+    Returns:
+        PixelArray: A new pixel array with the Gaussian blur effect applied.
+    
+    Raises:
+        RuntimeError: If pixel array creation fails during the blur process.
+    """
+def grayscale(pixel_array: pykraken._core.PixelArray) -> pykraken._core.PixelArray:
+    """
+    Convert a pixel array to grayscale.
+    
+    Converts the pixel array to grayscale using the standard luminance formula:
+    gray = 0.299 * red + 0.587 * green + 0.114 * blue
+    
+    This formula accounts for human perception of brightness across different colors.
+    The alpha channel is preserved unchanged.
+    
+    Args:
+        pixel_array (PixelArray): The pixel array to convert to grayscale.
+    
+    Returns:
+        PixelArray: A new pixel array converted to grayscale.
+    
+    Raises:
+        RuntimeError: If pixel array creation fails.
+    """
+def invert(pixel_array: pykraken._core.PixelArray) -> pykraken._core.PixelArray:
+    """
+    Invert the colors of a pixel array.
+    
+    Creates a negative image effect by inverting each color channel (RGB).
+    The alpha channel is preserved unchanged.
+    
+    Args:
+        pixel_array (PixelArray): The pixel array to invert.
+    
+    Returns:
+        PixelArray: A new pixel array with inverted colors.
+    
+    Raises:
+        RuntimeError: If pixel array creation fails.
+    """
+def rotate(pixel_array: pykraken._core.PixelArray, angle: typing.SupportsFloat) -> pykraken._core.PixelArray:
+    """
+    Rotate a pixel array by a given angle.
+    
+    Args:
+        pixel_array (PixelArray): The pixel array to rotate.
+        angle (float): The rotation angle in degrees. Positive values rotate clockwise.
+    
+    Returns:
+        PixelArray: A new pixel array containing the rotated image. The output pixel array may be
+                larger than the input to accommodate the rotated image.
+    
+    Raises:
+        RuntimeError: If pixel array rotation fails.
+    """
+def scale_by(pixel_array: pykraken._core.PixelArray, factor: typing.SupportsFloat) -> pykraken._core.PixelArray:
+    """
+    Scale a pixel array by a given factor.
+    
+    Args:
+        pixel_array (PixelArray): The pixel array to scale.
+        factor (float): The scaling factor (must be > 0). Values > 1.0 enlarge,
+                       values < 1.0 shrink the pixel array.
+    
+    Returns:
+        PixelArray: A new pixel array scaled by the specified factor.
+    
+    Raises:
+        ValueError: If factor is <= 0.
+        RuntimeError: If pixel array creation or scaling fails.
+    """
+def scale_to(pixel_array: pykraken._core.PixelArray, size: pykraken._core.Vec2) -> pykraken._core.PixelArray:
+    """
+    Scale a pixel array to a new exact size.
+    
+    Args:
+        pixel_array (PixelArray): The pixel array to scale.
+        size (Vec2): The target size as (width, height).
+    
+    Returns:
+        PixelArray: A new pixel array scaled to the specified size.
+    
+    Raises:
+        RuntimeError: If pixel array creation or scaling fails.
+    """