`simvx.core.animation.sprite`¶

Sprite nodes with frame-based animation support.

Module Contents¶

Classes¶

`Sprite2D`	2D sprite node – renders a texture via Draw2D.draw_texture().
`SpriteAnimation`	Named sprite animation with frame range.
`AnimatedSprite2D`	Sprite with frame-based animation from sprite sheets.

API¶

class simvx.core.animation.sprite.Sprite2D(texture: Any = None, position=None, rotation: float = 0.0, scale=None, colour: tuple = (1.0, 1.0, 1.0, 1.0), width: int = 0, height: int = 0, filter: str = 'linear', flip_h: bool = False, flip_v: bool = False, **kwargs)[source]¶

Bases: simvx.core.nodes_2d.node2d.Node2D

2D sprite node – renders a texture via Draw2D.draw_texture().

The texture property holds a file path; the graphics backend loads it via TextureManager and stores the GPU index in _texture_id. The draw() callback emits a textured quad through the renderer (Draw2D).

Attributes: texture: Path to the image file (PNG/JPG). colour: RGBA tint (0.0-1.0 floats). width: Display width in pixels (0 = use texture native size). height: Display height in pixels (0 = use texture native size).

Initialization

texture¶: ‘Property(…)’

colour¶: ‘Colour(…)’

width¶: ‘Property(…)’

height¶: ‘Property(…)’

filter¶: ‘Property(…)’

flip_h¶: ‘Property(…)’

flip_v¶: ‘Property(…)’

preload() → None[source]¶

Synchronously upload the texture and resolve width / height.

Call after enter_tree (so self.app is available) and before the first frame to avoid the size-flash that happens when SceneAdapter lazily resolves the texture: until that resolve runs, _texture_id is -1 and the renderer skips the draw, so a sprite that relies on the texture’s native dimensions briefly renders at the default 64×64 fallback once the resolve catches up.

After preload(): * _texture_id is non-negative. * width / height are set from the texture’s native pixels if they were both 0 (i.e. “native size” was requested).

No-ops gracefully when the node is not in a tree, when no App is attached (headless / unit tests), or when the texture is already loaded. Logs a WARNING on resolve failure but does not raise: the renderer will fall back to its draw-time path.

on_draw(renderer) → None[source]¶

Emit a textured quad via the renderer (Draw2D).

flip_h / flip_v flip the source UV rectangle rather than the node’s scale, so the sprite pivot stays at world_position (the Godot semantics ports rely on).

to_dict() → dict[source]¶: Serialize sprite state (used by clipboard + PlayMode snapshot).

classmethod from_dict(data: dict)[source]¶: Deserialize sprite state.

position¶: ‘_SpatialVecProperty(…)’

rotation¶: ‘Property(…)’

scale¶: ‘_SpatialVecProperty(…)’

z_index¶: ‘Property(…)’

z_as_relative¶: ‘Property(…)’

render_layer¶: ‘Property(…)’

set_render_layer(index: int, enabled: bool = True) → None¶

is_on_render_layer(index: int) → bool¶

property absolute_z_index: int¶

property rotation_degrees: float¶

property world_position: simvx.core.math.types.Vec2¶

property world_rotation: float¶

property world_scale: simvx.core.math.types.Vec2¶

property world_transform: tuple[simvx.core.math.types.Vec2, simvx.core.math.types.Vec2, float]¶

property forward: simvx.core.math.types.Vec2¶

property right: simvx.core.math.types.Vec2¶

translate(offset: tuple[float, float] | numpy.ndarray)¶

rotate(radians: float)¶

rotate_deg(degrees: float)¶

look_at(target: tuple[float, float] | numpy.ndarray)¶

transform_points(points: list[simvx.core.math.types.Vec2]) → list[simvx.core.math.types.Vec2]¶

draw_polygon(renderer, points: list[simvx.core.math.types.Vec2], closed=True, colour=None)¶

wrap_screen(margin: float = 20)¶

strict_errors: ClassVar[bool]¶: True

script_error_raised¶: ‘Signal(…)’

classmethod __init_subclass__(**kwargs)¶

property name: str¶

property process_mode: simvx.core.descriptors.ProcessMode¶

property visible: bool¶

reset_error() → None¶

add_child(node: simvx.core.node.Node) → simvx.core.node.Node¶

remove_child(node: simvx.core.node.Node)¶

reparent(new_parent: simvx.core.node.Node)¶

get_node(path: str) → simvx.core.node.Node¶

find_child(name: str, recursive: bool = False) → simvx.core.node.Node | None¶

find(target: type | str, recursive: bool = True) → simvx.core.node.Node | None¶

find_all(node_type: type, recursive: bool = True) → list¶

walk(*, include_self: bool = True) → collections.abc.Iterator[simvx.core.node.Node]¶

property path: str¶

add_to_group(group: str)¶

remove_from_group(group: str)¶

is_in_group(group: str) → bool¶

on_ready() → None¶

on_enter_tree() → None¶

on_exit_tree() → None¶

on_process(dt: float) → None¶

on_physics_process(dt: float) → None¶

on_picked(event: simvx.core.events.InputEvent) → None¶

on_unhandled_input(event: simvx.core.events.TreeInputEvent) → None¶

start_coroutine(gen: simvx.core.descriptors.Coroutine) → simvx.core.descriptors.CoroutineHandle¶

stop_coroutine(gen_or_handle)¶

clear_children()¶

destroy()¶

property app¶

property tree: simvx.core.scene_tree.SceneTree¶

__getitem__(key: str)¶

classmethod get_properties() → dict[str, simvx.core.descriptors.Property]¶

__repr__()¶

class simvx.core.animation.sprite.SpriteAnimation[source]¶

Named sprite animation with frame range.

name: str¶: None

frames: list[int]¶: None

fps: float¶: 10.0

loop: bool¶: True

class simvx.core.animation.sprite.AnimatedSprite2D(texture: str = None, frames_horizontal: int = 1, frames_vertical: int = 1, frame_width: int | None = None, frame_height: int | None = None, **kwargs)[source]¶

Bases: simvx.core.animation.sprite.Sprite2D

Sprite with frame-based animation from sprite sheets.

Inherits from Sprite2D (Node2D), so it participates in the scene tree and gets on_process(dt) and on_draw(renderer) called automatically.

Example: sprite = AnimatedSprite2D( texture=”player.png”, frames_horizontal=4, frames_vertical=4 ) sprite.add_animation(“walk”, frames=[0, 1, 2, 3], fps=10, loop=True) sprite.add_animation(“jump”, frames=[4, 5, 6], fps=15, loop=False) sprite.play(“walk”)

Initialization

add_animation(name: str, frames: list[int], fps: float = 10.0, loop: bool = True)[source]¶: Register a named animation.

play(animation_name: str = 'default')[source]¶: Play named animation.

stop()[source]¶

Stop animation and reset to the start of the current animation.

playing becomes False and the frame counter resets so a subsequent play() or resume() begins from frame 0.

pause()[source]¶

Pause animation, preserving the current frame and frame time.

playing becomes False but no state is reset; resume() continues from where playback left off.

resume()[source]¶: Resume animation from the current frame.

on_process(dt: float)[source]¶: Advance sprite animation each frame.

on_draw(renderer) → None[source]¶

Draw the current animation frame as a textured quad with proper UVs.

flip_h / flip_v (inherited from Sprite2D) swap the UV endpoints: pivot remains at world_position regardless.

property current_frame_index: int[source]¶: Absolute frame index in the sprite sheet.

property frame_uv: tuple[simvx.core.math.types.Vec2, simvx.core.math.types.Vec2][source]¶: UV coordinates for the current frame (top-left, bottom-right).

to_dict() → dict[source]¶: Serialize animated sprite.

classmethod from_dict(data: dict)[source]¶: Deserialize animated sprite.

classmethod from_frames(frames: list[Any] | str | pathlib.Path, fps: float = 10.0, *, name: str = 'default', loop: bool = True, play: bool = True, **kwargs) → simvx.core.animation.sprite.AnimatedSprite2D[source]¶

Build a flipbook AnimatedSprite2D from a list of frame textures or a folder.

frames accepts any of: * list: each element is a per-frame texture source (file path, PNG bytes, or H×W×4 uint8 ndarray). Frames are stitched into a single horizontal strip atlas. * str / Path to a directory: every *.png (recursive: no, top-level only) is sorted alphabetically and treated as one frame. An empty directory or no PNG files raises FileNotFoundError.

The resulting sprite uses a single sheet texture (so it follows the same fast GPU path as a hand-authored atlas: no per-frame upload at runtime) with frames_horizontal = N, frames_vertical = 1. The animation named name is registered with all N frames; play=True starts playback immediately.

All frames must have the same pixel dimensions; mismatched sizes raise ValueError.