`simvx.core.physics_nodes`¶

Physics/collision nodes: CharacterBody, CollisionShape, Area, ShapeCast (2D and 3D).

Module Contents¶

Classes¶

`CharacterBody2D`	2D node with velocity, movement, and collision response.
`CollisionShape2D`	2D collision shape: circle (default) or axis-aligned rectangle.
`Area2D`	2D trigger zone that detects overlapping bodies and areas.
`CharacterBody3D`	3D node with velocity, movement, and collision response.
`CollisionShape3D`	Sphere, axis-aligned box, or Y-axis capsule collision shape.
`Area3D`	3D trigger zone that detects overlapping bodies and areas.

Data¶

log

API¶

simvx.core.physics_nodes.log¶: ‘getLogger(…)’

class simvx.core.physics_nodes.CharacterBody2D(collision=None, **kwargs)[source]¶

Bases: simvx.core.physics_nodes._CharacterBodyBase, simvx.core.nodes_2d.node2d.Node2D

2D node with velocity, movement, and collision response.

Uses CollisionShape2D children for circle or rectangle collision. Screen coordinates: Y-down, so floor normal defaults to (0, -1).

Initialization

collision_layer¶: ‘Bitmask(…)’

collision_mask¶: ‘Bitmask(…)’

max_slides¶: ‘Property(…)’

max_substeps¶: ‘Property(…)’

move_and_slide(dt: float = 1.0)[source]¶

Apply velocity with collision response. Resolves overlaps and slides along surfaces.

Sub-stepping prevents tunneling at high velocities by splitting movement into ceil(disp / col_radius) iterations, capped at max_substeps. The cap protects frame rate at the risk of tunneling for extreme velocities; raise it for fast bullets/projectiles.

get_overlapping(group: str = None, body_type: type = None) → list[simvx.core.physics_nodes.CharacterBody2D][source]¶: Find all CharacterBody2D nodes whose collision overlaps ours.

is_on_floor() → bool¶

is_on_wall() → bool¶

is_on_ceiling() → bool¶

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_draw(renderer) → 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.physics_nodes.CollisionShape2D(**kwargs)[source]¶

Bases: simvx.core.physics_nodes._CollisionShapeBase, simvx.core.nodes_2d.node2d.Node2D

2D collision shape: circle (default) or axis-aligned rectangle.

Circle mode (default): set radius. Rectangle mode: set extents to a Vec2(half_width, half_height). When extents is non-zero the shape is treated as an AABB and radius is ignored for overlap tests.

Initialization

radius¶: ‘Property(…)’

extents¶: ‘Property(…)’

gizmo_colour¶: ‘Colour(…)’

property is_rect: bool[source]¶: True when extents are non-zero (rectangle mode).

overlaps(other: simvx.core.physics_nodes.CollisionShape2D) → bool[source]¶: Test overlap with another CollisionShape2D (circle or rect).

overlaps_point(point: tuple[float, float] | numpy.ndarray) → bool[source]¶: Test if a point is inside this shape.

get_penetration(other: simvx.core.physics_nodes.CollisionShape2D) → tuple[simvx.core.math.types.Vec2, float] | None[source]¶: Return (normal, depth) to push self out of other, or None.

get_gizmo_lines() → list[tuple[simvx.core.math.types.Vec2, simvx.core.math.types.Vec2]][source]¶: Return wireframe line segments for the collision shape in world space.

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_draw(renderer) → 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.physics_nodes.Area2D(**kwargs)[source]¶

Bases: simvx.core.physics_nodes._AreaBase, simvx.core.nodes_2d.node2d.Node2D

2D trigger zone that detects overlapping bodies and areas.

Add CollisionShape2D children to define the detection region. Emits body_entered/body_exited when CharacterBody2D nodes overlap, and area_entered/area_exited for other Area2D nodes.

Initialization

collision_layer¶: ‘Bitmask(…)’

collision_mask¶: ‘Bitmask(…)’

monitoring¶: ‘Property(…)’

gizmo_colour¶: ‘Colour(…)’

get_gizmo_lines() → list[tuple[simvx.core.math.types.Vec2, simvx.core.math.types.Vec2]][source]¶: Return gizmo lines from child collision shapes, or a default diamond if none.

on_physics_process(dt: float)[source]¶

property overlapping_bodies: list¶

property overlapping_areas: list¶

has_overlapping_bodies() → bool¶

has_overlapping_areas() → bool¶

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_draw(renderer) → 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.physics_nodes.CharacterBody3D(collision=None, **kwargs)[source]¶

Bases: simvx.core.physics_nodes._CharacterBodyBase, simvx.core.nodes_3d.node3d.Node3D

3D node with velocity, movement, and collision response.

Uses CollisionShape3D children: sphere, box, or capsule. Y-up convention: floor normal defaults to (0, 1, 0). Collision response routes through :meth:CollisionShape3D.get_penetration, so all shape pairings the shape node supports work transparently here.

Initialization

collision_layer¶: ‘Bitmask(…)’

collision_mask¶: ‘Bitmask(…)’

max_slides¶: ‘Property(…)’

move_and_slide(dt: float = 1.0)[source]¶: Apply velocity with collision response. Resolves overlaps and slides along surfaces.

get_overlapping(group: str = None, body_type: type = None) → list[simvx.core.physics_nodes.CharacterBody3D][source]¶

is_on_floor() → bool¶

is_on_wall() → bool¶

is_on_ceiling() → bool¶

position¶: ‘_SpatialVecProperty(…)’

rotation¶: ‘Property(…)’

scale¶: ‘_SpatialVecProperty(…)’

render_layer¶: ‘Property(…)’

property rotation_degrees: simvx.core.math.types.Vec3¶

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

property world_rotation: simvx.core.math.types.Quat¶

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

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

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

property up: simvx.core.math.types.Vec3¶

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

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

rotate(axis: tuple[float, float, float] | numpy.ndarray, angle: float)¶

rotate_x(angle: float)¶

rotate_y(angle: float)¶

rotate_z(angle: float)¶

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

face_along(forward: tuple[float, float, float] | numpy.ndarray, up: tuple[float, float, float] | numpy.ndarray | None = None) → None¶

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

is_on_render_layer(index: int) → bool¶

wrap_bounds(bounds: tuple[float, float, float] | numpy.ndarray, margin: float = 1.0)¶

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_draw(renderer) → 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.physics_nodes.CollisionShape3D(**kwargs)[source]¶

Bases: simvx.core.physics_nodes._CollisionShapeBase, simvx.core.nodes_3d.node3d.Node3D

Sphere, axis-aligned box, or Y-axis capsule collision shape.

Set :attr:kind to pick the shape. "sphere" uses :attr:radius, "box" uses :attr:extents (Vec3 of half-widths in X/Y/Z), and "capsule" is a Y-axis capsule with :attr:radius + :attr:height (total height including hemispherical caps; height >= 2 * radius for a meaningful cylinder section). Mirrors the 2D pattern but uses an explicit kind enum because three shape variants don’t auto-detect cleanly the way 2D’s circle/rect does.

Initialization

kind¶: ‘Property(…)’

radius¶: ‘Property(…)’

extents¶: ‘Property(…)’

height¶: ‘Property(…)’

pickable¶: ‘Property(…)’

gizmo_colour¶: ‘Colour(…)’

overlaps(other: simvx.core.physics_nodes.CollisionShape3D) → bool[source]¶

overlaps_point(point: tuple[float, float, float] | numpy.ndarray) → bool[source]¶

get_penetration(other: simvx.core.physics_nodes.CollisionShape3D) → tuple[simvx.core.math.types.Vec3, float] | None[source]¶

Return (normal, depth) to push self out of other, or None.

Sphere-sphere, sphere-box, and box-box are analytic. Capsule pairings approximate via the closest-points-on-segment reduction described in

Meth:: overlaps: accurate for vertical capsules (the common stand-up character collider) and good enough for sliding response on near-axis cases. A future GJK+EPA pass can replace this for full general capsule contact resolution.

get_gizmo_lines() → list[tuple[simvx.core.math.types.Vec3, simvx.core.math.types.Vec3]][source]¶: Return wireframe line segments for the collision shape.

position¶: ‘_SpatialVecProperty(…)’

rotation¶: ‘Property(…)’

scale¶: ‘_SpatialVecProperty(…)’

render_layer¶: ‘Property(…)’

property rotation_degrees: simvx.core.math.types.Vec3¶

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

property world_rotation: simvx.core.math.types.Quat¶

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

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

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

property up: simvx.core.math.types.Vec3¶

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

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

rotate(axis: tuple[float, float, float] | numpy.ndarray, angle: float)¶

rotate_x(angle: float)¶

rotate_y(angle: float)¶

rotate_z(angle: float)¶

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

face_along(forward: tuple[float, float, float] | numpy.ndarray, up: tuple[float, float, float] | numpy.ndarray | None = None) → None¶

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

is_on_render_layer(index: int) → bool¶

wrap_bounds(bounds: tuple[float, float, float] | numpy.ndarray, margin: float = 1.0)¶

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_draw(renderer) → 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.physics_nodes.Area3D(**kwargs)[source]¶

Bases: simvx.core.physics_nodes._AreaBase, simvx.core.nodes_3d.node3d.Node3D

3D trigger zone that detects overlapping bodies and areas.

Add CollisionShape3D children to define the detection region. Emits body_entered/body_exited when CharacterBody3D nodes overlap, and area_entered/area_exited for other Area3D nodes.

Initialization

collision_layer¶: ‘Bitmask(…)’

collision_mask¶: ‘Bitmask(…)’

monitoring¶: ‘Property(…)’

gizmo_colour¶: ‘Colour(…)’

get_gizmo_lines() → list[tuple[simvx.core.math.types.Vec3, simvx.core.math.types.Vec3]][source]¶: Return gizmo lines from child collision shapes, or a small axis cross if none.