`simvx.core.nodes_2d.camera`¶

Camera2D – 2D camera with smoothing, zoom, bounds, and shake.

Module Contents¶

Classes¶

Camera2D

2D camera for scrolling games.

API¶

class simvx.core.nodes_2d.camera.Camera2D(**kwargs)[source]¶

Bases: simvx.core.nodes_2d.node2d.Node2D

2D camera for scrolling games.

Provides target following with smoothing, zoom, viewport bounds/limits, and screen shake effects. The active Camera2D’s offset is applied by the renderer to all 2D draw calls.

Initialization

zoom¶: ‘Property(…)’

smoothing¶: ‘Property(…)’

limit_left¶: ‘Property(…)’

limit_right¶: ‘Property(…)’

limit_top¶: ‘Property(…)’

limit_bottom¶: ‘Property(…)’

cull_mask¶: ‘Bitmask(…)’

gizmo_colour¶: ‘Colour(…)’

set_cull_mask_layer(index: int, enabled: bool = True) → None[source]¶: Enable or disable a specific cull mask layer (0-31).

is_cull_mask_layer_enabled(index: int) → bool[source]¶: Check if a specific cull mask layer is enabled (0-31).

property current: simvx.core.math.types.Vec2[source]¶

Current smoothed camera position in world space.

Reads the post-smoothing, post-limit-clamp position the renderer uses to translate 2D draws. Assignment teleports the camera (skips smoothing for that frame): equivalent to :meth:snap_to without rebinding to the target’s world_position.

on_enter_tree()[source]¶

on_exit_tree() → None[source]¶

Clear the tree’s current-camera reference if it points at us.

Without this, destroying the active Camera2D leaves a stale reference on the tree: the renderer keeps following the freed camera each frame, panning over to whatever world_position arrives via stale _current. Other Camera2D instances claim the slot back via their own on_enter_tree(); the only failure mode is “active camera was the last one in the scene”, which now correctly resets to None.

shake(intensity: float = 5.0, duration: float = 0.3)[source]¶: Start a screen shake effect.

snap_to(pos: simvx.core.math.types.Vec2 | None = None) → None[source]¶

Skip smoothing this frame.

If pos is given, snap there. If pos is None, snap to the current target’s world_position (or the camera’s own world_position if no target). Bounds limits and zoom are honoured; shake jitter continues uninterrupted.

on_update(dt: float)[source]¶

canvas_transform(screen_size: simvx.core.math.types.Vec2 | tuple[float, float], shake: simvx.core.math.types.Vec2 | tuple[float, float] | None = None) → tuple[float, float, float, float, float, float][source]¶

The single Camera2D screen mapping: world -> screen affine (a,b,c,d,tx,ty).

This is the one source of truth. The renderer bakes this exact matrix into the 2D vertex stream, world_to_screen/screen_to_world invert it, and every Family-B pass (lights, particles, tiles) routes through it, so hit-testing and rendering provably agree under zoom + pan + shake.

screen_size is the viewport size in pixels; shake defaults to the camera’s current per-frame jitter (_shake_offset). A point p maps to (a*p.x + c*p.y + tx, b*p.x + d*p.y + ty) (rotation-free: b == c == 0).

world_to_screen(world_pos: simvx.core.math.types.Vec2, screen_size: simvx.core.math.types.Vec2 | tuple[float, float] | None = None) → simvx.core.math.types.Vec2[source]¶

Convert a world position to screen coordinates (via :meth:canvas_transform).

screen_size defaults to the tree’s screen size.

screen_to_world(screen_pos: simvx.core.math.types.Vec2, screen_size: simvx.core.math.types.Vec2 | tuple[float, float] | None = None) → simvx.core.math.types.Vec2[source]¶

Convert screen coordinates to world position (inverse of :meth:canvas_transform).

screen_size defaults to the tree’s screen size.

get_gizmo_lines() → list[tuple[simvx.core.math.types.Vec2, simvx.core.math.types.Vec2]][source]¶: Return line segments for viewport bounds rectangle and crosshair at camera position.