"""SimVX Core: Backend-agnostic node system and game engine.
This package provides the core game engine: node hierarchy, scene tree,
collision detection, signals, coroutines, and serialization.
Rendering is handled by the Vulkan backend package (simvx.graphics).
Examples:
from simvx.core import Node, Camera3D
from simvx.graphics import App
class MyGame(Node):
def on_ready(self):
self.add_child(Camera3D())
App(width=800, height=600).run(MyGame())
"""
import importlib.metadata as _meta
try:
__version__: str = _meta.version("SimVX-Core")
except _meta.PackageNotFoundError:
__version__ = "0.1.0-dev"
# Asset path resolution
# Node system
# Easing module: `from simvx.core import easing; easing.ease_in_quad(...)`
from . import easing
# Animation system
from .animation.blend_space import BlendSpace1D, BlendSpace2D
from .animation.player import AnimationPlayer
from .animation.skeletal import BoneTrack, SkeletalAnimationClip
from .animation.sprite import AnimatedSprite2D, Sprite2D
from .animation.state_machine import AnimationState, AnimationTree, Transition
from .animation.track import AnimationClip, AnimationEvent, Track
from .animation.tween import Tween, TweenChain, tween
from .asset_resolver import resolve_asset_path
# Asynchronous asset loading
from .assets import AssetServer, BatchHandle, Handle
# Enhanced tween from animation module (replaces old tween)
# Atlas / sprite sheet
from .atlas import AtlasTexture, SpriteSheet, TextureAtlas, pack_atlas
# Audio system
from .audio import (
AudioStream,
AudioStreamPlayer,
AudioStreamPlayer2D,
AudioStreamPlayer3D,
)
# Audio backend
from .audio_backend import MiniaudioBackend, NullAudioBackend, make_backend
# Audio bus system
from .audio_bus import AudioBus, AudioBusLayout
# Audio effects (typed bus-effect classes; wired on native + web backends)
from .audio_effect import (
AudioEffect,
BandPassFilter,
CompressorEffect,
DelayEffect,
EQBand,
GainEffect,
HighPassFilter,
LowPassFilter,
NotchFilter,
ParametricEQ,
ReverbEffect,
SoftClipEffect,
)
# Audio listener scene nodes: placed in the tree and tracked like Camera2D/3D
from .audio_listener import AudioListener2D, AudioListener3D
# Audio synthesis: oscillators, envelopes, AudioSynth
from .audio_synth import (
ADSR,
AudioSynth,
Exponential,
Filter,
HighPass,
Linear,
LowPass,
Oscillator,
PinkNoise,
WhiteNoise,
)
from .clipboard import Clipboard
# Clustered lighting (Forward+)
from .clustered_lighting import ClusterConfig, ClusterGrid, LightCluster, assign_lights
from .collision import (
BoxShape,
CapsuleShape,
CollisionShape,
CollisionWorld,
ConvexShape,
RayHit,
ShapeCastResult,
SpatialHashGrid,
SphereShape,
)
# Unified configuration
from .config import AppConfig, EditorSection, GeneralConfig, IDESection
from .coroutines import next_frame, parallel, punch_position, punch_rotation, wait, wait_signal, wait_until
# Constructive Solid Geometry
from .csg import CSGBox3D, CSGCombiner3D, CSGCylinder3D, CSGOperation, CSGShape3D, CSGSphere3D, csg_combine
# Debug system
from .debug import Debug, DebugNode
# Decal projection
from .decal import Decal3D
from .decorators import (
on_draw,
on_enter_tree,
on_exit_tree,
on_input,
on_physics_process,
on_picked,
on_process,
on_ready,
on_unhandled_input,
)
# Canonical submodule imports (previously aggregated in simvx.core.engine,
# which was a back-compat re-export shim now removed).
from .descriptors import (
Child,
Children,
Collision,
Coroutine,
CoroutineHandle,
Notification,
OnReady,
ProcessMode,
Property,
)
# Document model
from .document import BufferRegistry, Document
from .events import InputEvent, TreeInputEvent
# Export / build system
from .export import ExportError, ExportMode, ExportPreset, ProjectExporter, bundle_project
# File state mixin (shared editor/IDE signals)
from .file_state import FileStateMixin
# Fog volumes
from .fog_volume import FogMaterial, FogVolume3D, FogVolumeShape
# Gesture recognition
from .gesture import GestureRecognizer
from .gizmo import Gizmo, GizmoAxis, GizmoMode
from .gpu_particles import GPUParticles2D, GPUParticles3D
from .graphics.material import Material
from .graphics.mesh import Mesh
from .graphics.shader import Shader
# Hot reload
from .hot_reload import HotReloadManager
# i18n / localization
from .i18n import TranslationServer, tr
# Input Action Map system
from .input.enums import JoyAxis, JoyButton, Key, MouseButton, MouseCaptureMode, key_to_name, name_to_keys
from .input.events import InputBinding, InputEventKey, InputEventMouse
from .input.map import InputMap
from .input.state import Input
# 2D lighting system
from .light2d import DirectionalLight2D, Light2D, LightOccluder2D, PointLight2D
# Math utilities
# Extended math types
from .math import (
AABB,
Basis,
Curve,
Curve2D,
Curve3D,
Quat,
Rect2,
Transform2D,
Transform3D,
Vec2,
Vec3,
clamp,
cross,
dot,
identity,
length,
look_at,
mix,
normalize,
orthographic,
perspective,
quat_to_mat4,
rotate,
scale,
slerp,
translate,
)
from .math.matrices import mat4_from_trs, mat4_to_bytes
from .math.raycast import ray_intersect_sphere, screen_to_ray
# 2D mesh rendering
from .mesh_instance_2d import Mesh2D, MeshInstance2D
# Mesh LOD system
from .mesh_lod import LODLevel, MeshLOD, generate_lods
# Navigation / Pathfinding
from .navigation import AStar2D, AStarGrid2D, NavigationAgent2D, PathFollower2D
# 3D Navigation
from .navigation3d import (
NavigationAgent3D,
NavigationMesh3D,
NavigationObstacle3D,
NavigationRegion3D,
NavigationServer3D,
)
from .node import Node, Timer
from .nodes_2d.camera import Camera2D
from .nodes_2d.canvas import (
CanvasLayer,
CanvasModulate,
ParallaxBackground,
ParallaxLayer,
)
from .nodes_2d.marker import Marker2D
from .nodes_2d.ninepatch import NinePatchRect, PatchRect
from .nodes_2d.node2d import Node2D
from .nodes_2d.path import Path2D, PathFollow2D
from .nodes_2d.remote_transform import RemoteTransform2D
from .nodes_2d.shapes import Line2D, Polygon2D
from .nodes_2d.spring_follow import SpringFollow2D
from .nodes_2d.text import Text2D
from .nodes_2d.trail import Trail2D
from .nodes_2d.ysort import YSortContainer
from .nodes_3d.camera import Camera3D, OrbitCamera3D
from .nodes_3d.chase_camera import ChaseCamera
from .nodes_3d.lights import DirectionalLight3D, Light3D, PointLight3D, SpotLight3D
from .nodes_3d.marker import Marker3D
from .nodes_3d.mesh import MeshInstance3D
from .nodes_3d.multimesh import MultiMesh, MultiMeshInstance3D
from .nodes_3d.node3d import Node3D
from .nodes_3d.path import Path3D, PathFollow3D
from .nodes_3d.remote_transform import RemoteTransform3D
from .nodes_3d.spring_arm import SpringArm3D
from .nodes_3d.sprite import AnimatedSprite3D, Sprite3D
from .nodes_3d.text import Text3D
# Noise generation
from .noise import FastNoiseLite, FractalType, NoiseType
from .particles import ParticleEmitter
# Physics engine
from .physics import (
BodyMode,
Contact,
HingeJoint3D,
Joint2D,
Joint3D,
KinematicBody2D,
KinematicBody3D,
PhysicsMaterial,
PhysicsServer,
PinJoint2D,
PinJoint3D,
RayCast2D,
RayCast3D,
RigidBody2D,
RigidBody3D,
StaticBody2D,
StaticBody3D,
)
from .physics_nodes import (
Area2D,
Area3D,
CharacterBody2D,
CharacterBody3D,
CollisionShape2D,
CollisionShape3D,
ShapeCast2D,
ShapeCast3D,
)
# Project configuration
from .project import ProjectSettings, find_project, load_project, save_project
# UI system
from .properties import Bitmask, Colour, FilePath, Multiline, NodePath
from .reflection_probe import ReflectionProbe3D
# Package-resource handle
from .resource import Resource
# Save data persistence
from .save_manager import SAVE_FORMAT_VERSION, SaveManager
# Scene management
# scene_io (SceneFile/SceneModule/load_scene/emit_scene) is authoring/tooling and
# pulls in `parso`. Import it LAZILY (see __getattr__ below) so `import simvx.core`
# (the game-runtime and web-export path) does not eagerly load parso. The names
# stay in __all__ and resolve on first access.
from .scene_tree import SceneTree
# Script manager
from .script import ScriptLoadError, ScriptManager, parse_script_ref
from .script_embed import EmbeddedScriptFinder
# Scripted demo playback
from .scripted_demo import Assert, Click, DemoRunner, Do, MoveTo, Narrate, PressKey, TypeText, Wait
from .selection import Selection
# Process management
from .py_console import PyConsoleNode
from .shell_node import ShellNode
# Editor infrastructure
from .shortcuts import ShortcutManager
from .signals import Connection, Signal
from .skeleton import PROFILE_HUMANOID, Bone, Skeleton, SkeletonProfile
from .skeleton2d import (
Bone2D,
Skeleton2D,
SkeletonModification2D,
SkeletonModification2DCCDIK,
SkeletonModification2DTwoBoneIK,
)
# Procedural geometry
from .surface_tool import (
ImmediateGeometry3D,
PrimitiveType,
SurfaceTool,
create_box,
create_capsule,
create_cylinder,
create_plane,
create_sphere,
)
# Testing API (headless scene runner, input simulation, diagnostics)
from .testing.diagnostics import FrameTimer, NodeCounter, scene_describe, scene_diff, ui_describe
from .testing.input_sim import InputSimulator
from .testing.recorder import RecordedEvent, ScriptRecorder
from .testing.scene_runner import SceneRunner
# TileMap system
from .tilemap import TileData, TileMap, TileMapLayer, TileSet
from .ui import (
AnchorPreset,
AppTheme,
AutocompletePopup,
Button,
CheckBox,
CodeEditorPanel,
CodeTextEdit,
ColourPicker,
ColumnSizing,
CompletionItem,
CompletionItemKind,
ConsoleWidget,
Container,
Control,
DimBackdrop,
DockContainer,
DockPanel,
DragData,
DrawCall,
DrawLog,
DropDown,
FileBrowserPanel,
FileDialog,
FocusMode,
FormLayout,
GraphConnection,
GraphEdit,
GraphNode,
GraphPort,
GridContainer,
HBoxContainer,
Label,
MarginContainer,
MenuBar,
MenuItem,
ModalBackdrop,
MultiLineTextEdit,
OutputPanel,
Panel,
PopupMenu,
ProgressBar,
RadioButton,
RichTextLabel,
ScrollContainer,
SizeFlags,
SizingMode,
Slider,
SpinBox,
SplitContainer,
StyledSpan,
SyntaxTheme,
TabContainer,
TerminalEmulator,
TextEdit,
TextMarker,
Theme,
ThemeColour,
ThemeSize,
Toolbar,
ToolbarButton,
TooltipManager,
TreeItem,
TreeView,
UIInputEvent,
UITestHarness,
VBoxContainer,
VirtualScrollContainer,
parse_ansi,
set_theme,
strip_ansi,
)
from .undo import (
AddChildCommand,
BatchCommand,
CallableCommand,
PropertyCommand,
RemoveChildCommand,
ReparentCommand,
UndoStack,
)
# Viewport & Display system
from .viewport import DisplaySettings, StretchAspect, StretchMode, SubViewport, ViewportContainer, VSyncMode, WindowMode
from .world_environment import Environment, PostProcessEffect, WorldEnvironment
__all__ = [
# Version
"__version__",
# Asset resolution
"resolve_asset_path",
# Nodes
"Node",
"Node2D",
"Node3D",
"CharacterBody2D",
"CharacterBody3D",
"CollisionShape2D",
"CollisionShape3D",
"Area2D",
"Area3D",
"ShapeCast2D",
"ShapeCast3D",
# Path nodes
"Path2D",
"PathFollow2D",
"Path3D",
"PathFollow3D",
# Remote transform
"RemoteTransform2D",
"RemoteTransform3D",
"SpringFollow2D",
# Markers
"Marker2D",
"Marker3D",
# NinePatch
"NinePatchRect",
"PatchRect",
# 2D rendering nodes
"CanvasLayer",
"ParallaxBackground",
"ParallaxLayer",
"CanvasModulate",
"YSortContainer",
"Line2D",
"Polygon2D",
"Trail2D",
"Mesh2D",
"MeshInstance2D",
"Camera2D",
"Camera3D",
"ChaseCamera",
"OrbitCamera3D",
"MeshInstance3D",
"MultiMesh",
"MultiMeshInstance3D",
"Light3D",
"DirectionalLight3D",
"PointLight3D",
"SpotLight3D",
"ReflectionProbe3D",
"Decal3D",
"Text2D",
"Text3D",
"Sprite3D",
"AnimatedSprite3D",
"SpringArm3D",
"Timer",
# Signals/Properties/Enums
"Property",
# Typed Property subclasses
"Colour",
"FilePath",
"Multiline",
"Bitmask",
"NodePath",
"Signal",
"Connection",
"Child",
"OnReady",
"InputEvent",
"TreeInputEvent",
# Lifecycle hook decorators
"on_ready",
"on_process",
"on_physics_process",
"on_input",
"on_unhandled_input",
"on_enter_tree",
"on_exit_tree",
"on_draw",
"on_picked",
"Collision",
"ProcessMode",
"Notification",
# Input/Scene
"Input",
"SceneFile",
"SceneModule",
"SceneTree",
"emit_scene",
"load_scene",
# Input Action Map
"Key",
"MouseButton",
"JoyButton",
"JoyAxis",
"MouseCaptureMode",
"InputBinding",
"InputMap",
"InputEventKey",
"InputEventMouse",
"key_to_name",
"name_to_keys",
# Coroutines
"CoroutineHandle",
"tween",
"parallel",
"wait",
"wait_until",
"wait_signal",
"next_frame",
"punch_position",
"punch_rotation",
# Easing module (prefer `from simvx.core import easing; easing.ease_in_quad(...)`)
"easing",
# Math helpers
"mat4_from_trs",
"mat4_to_bytes",
"screen_to_ray",
"ray_intersect_sphere",
# Save data persistence
"SaveManager",
"SAVE_FORMAT_VERSION",
# Resources
"Resource",
# Audio
"AudioStream",
"AudioStreamPlayer",
"AudioStreamPlayer2D",
"AudioStreamPlayer3D",
"AudioListener2D",
"AudioListener3D",
# Animation system
"Tween",
"TweenChain",
"Sprite2D",
"AnimatedSprite2D",
"Track",
"AnimationClip",
"AnimationPlayer",
"AnimationState",
"Transition",
"AnimationTree",
"AnimationEvent",
"BlendSpace1D",
"BlendSpace2D",
# UI system
"Control",
"Container",
"HBoxContainer",
"VBoxContainer",
"MarginContainer",
"GridContainer",
"Label",
"Button",
"Panel",
"TextEdit",
"Slider",
"ProgressBar",
"CheckBox",
"SpinBox",
"DropDown",
"RadioButton",
"FormLayout",
"ScrollContainer",
"SplitContainer",
"TabContainer",
"TreeItem",
"TreeView",
"MenuItem",
"PopupMenu",
"MenuBar",
"ModalBackdrop",
"DimBackdrop",
"Theme",
"AppTheme",
"SyntaxTheme",
"ThemeColour",
"ThemeSize",
"set_theme",
"Colour",
"UIInputEvent",
"FileBrowserPanel",
"FileDialog",
"ColourPicker",
"MultiLineTextEdit",
"Toolbar",
"ToolbarButton",
"TooltipManager",
"DockPanel",
"DockContainer",
"CodeTextEdit",
"TextMarker",
"StyledSpan",
"parse_ansi",
"strip_ansi",
"RichTextLabel",
"OutputPanel",
"ConsoleWidget",
"TerminalEmulator",
# Testing (UI)
"UITestHarness",
"DrawLog",
"DrawCall",
# Testing (scene / game)
"SceneRunner",
"InputSimulator",
"scene_diff",
"scene_describe",
"ui_describe",
"NodeCounter",
"FrameTimer",
"ScriptRecorder",
"RecordedEvent",
# Scripted demo
"DemoRunner",
"MoveTo",
"Click",
"TypeText",
"PressKey",
"Wait",
"Assert",
"Do",
"Narrate",
# Particles
"ParticleEmitter",
"GPUParticles2D",
"GPUParticles3D",
# Skeletal animation (3D)
"Skeleton",
"Bone",
"SkeletonProfile",
"PROFILE_HUMANOID",
"BoneTrack",
"SkeletalAnimationClip",
# Skeletal animation (2D)
"Bone2D",
"Skeleton2D",
"SkeletonModification2D",
"SkeletonModification2DCCDIK",
"SkeletonModification2DTwoBoneIK",
# Constructive Solid Geometry
"CSGOperation",
"CSGShape3D",
"CSGBox3D",
"CSGSphere3D",
"CSGCylinder3D",
"CSGCombiner3D",
"csg_combine",
# Graphics
"Mesh",
"Material",
"Shader",
# Collision system
"CollisionShape",
"SphereShape",
"BoxShape",
"ConvexShape",
"CapsuleShape",
"SpatialHashGrid",
"RayHit",
"ShapeCastResult",
"CollisionWorld",
# Clustered lighting (Forward+)
"ClusterConfig",
"ClusterGrid",
"LightCluster",
"assign_lights",
# 3D Navigation
"NavigationMesh3D",
"NavigationRegion3D",
"NavigationAgent3D",
"NavigationServer3D",
"NavigationObstacle3D",
# Math utilities
"identity",
"perspective",
"look_at",
"translate",
"rotate",
"scale",
"orthographic",
"quat_to_mat4",
# Vector/Quat types
"Vec2",
"Vec3",
"Quat",
# Math functions
"normalize",
"length",
"dot",
"cross",
"mix",
"clamp",
"slerp",
# TileMap system
"TileData",
"TileSet",
"TileMapLayer",
"TileMap",
# Viewport & Display
"StretchMode",
"StretchAspect",
"VSyncMode",
"WindowMode",
"DisplaySettings",
"SubViewport",
"ViewportContainer",
"WorldEnvironment",
"Environment",
"PostProcessEffect",
# Extended math types
"Rect2",
"AABB",
"Transform2D",
"Transform3D",
"Basis",
"Curve",
"Curve2D",
"Curve3D",
# Noise generation
"FastNoiseLite",
"NoiseType",
"FractalType",
# 2D lighting
"Light2D",
"PointLight2D",
"DirectionalLight2D",
"LightOccluder2D",
# Gesture recognition
"GestureRecognizer",
# Debug system
"Debug",
"DebugNode",
# Process management
"PyConsoleNode",
"ShellNode",
# Document model
"Document",
"BufferRegistry",
# Export / build system
"ExportMode",
"ExportPreset",
"ProjectExporter",
"bundle_project",
"ExportError",
# File state mixin
"FileStateMixin",
# Editor infrastructure
"ShortcutManager",
"UndoStack",
"PropertyCommand",
"CallableCommand",
"BatchCommand",
"AddChildCommand",
"RemoveChildCommand",
"ReparentCommand",
"Gizmo",
"GizmoMode",
"GizmoAxis",
"Selection",
"Clipboard",
# Navigation / Pathfinding
"AStar2D",
"AStarGrid2D",
"NavigationAgent2D",
"PathFollower2D",
# Hot reload
"HotReloadManager",
# Script manager
"ScriptLoadError",
"ScriptManager",
"parse_script_ref",
# Project configuration
"ProjectSettings",
"load_project",
"save_project",
"find_project",
# Asynchronous asset loading
"AssetServer",
"Handle",
"BatchHandle",
# Audio backend
"MiniaudioBackend",
"NullAudioBackend",
"make_backend",
# Audio bus system
"AudioBus",
"AudioBusLayout",
# Audio effects
"AudioEffect",
"GainEffect",
"LowPassFilter",
"HighPassFilter",
"BandPassFilter",
"NotchFilter",
"DelayEffect",
"ReverbEffect",
"EQBand",
"ParametricEQ",
"SoftClipEffect",
"CompressorEffect",
# Audio synthesis
"AudioSynth",
"Oscillator",
"WhiteNoise",
"PinkNoise",
"ADSR",
"Linear",
"Exponential",
"Filter",
"LowPass",
"HighPass",
# i18n / localization
"TranslationServer",
"tr",
# Physics engine
"PhysicsMaterial",
"BodyMode",
"Contact",
"PhysicsServer",
"RigidBody2D",
"RigidBody3D",
"StaticBody2D",
"StaticBody3D",
"KinematicBody2D",
"KinematicBody3D",
"Joint2D",
"Joint3D",
"PinJoint2D",
"PinJoint3D",
"HingeJoint3D",
"RayCast2D",
"RayCast3D",
# Unified configuration
"AppConfig",
"GeneralConfig",
"EditorSection",
"IDESection",
# Atlas / sprite sheet
"AtlasTexture",
"TextureAtlas",
"SpriteSheet",
"pack_atlas",
# Script embedding
"EmbeddedScriptFinder",
# Fog volumes
"FogVolume3D",
"FogVolumeShape",
"FogMaterial",
# Mesh LOD system
"LODLevel",
"MeshLOD",
"generate_lods",
# Procedural geometry
"SurfaceTool",
"PrimitiveType",
"ImmediateGeometry3D",
"create_box",
"create_sphere",
"create_cylinder",
"create_plane",
"create_capsule",
# Code editor
"CodeEditorPanel",
"AutocompletePopup",
"CompletionItem",
"CompletionItemKind",
# UI extras
"AnchorPreset",
"DragData",
"FocusMode",
"GraphConnection",
"GraphEdit",
"GraphNode",
"GraphPort",
"SizeFlags",
"SizingMode",
"ColumnSizing",
"VirtualScrollContainer",
]
# Lazily-resolved scene_io names: kept out of the eager import chain so a bare
# `import simvx.core` (game runtime / web export via Pyodide) never imports parso.
# They remain in __all__ and resolve on first attribute access (PEP 562).
_LAZY_SCENE_IO = {"SceneFile", "SceneModule", "emit_scene", "load_scene"}
[docs]
def __getattr__(name: str):
if name in _LAZY_SCENE_IO:
from . import scene_io
return getattr(scene_io, name)
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
[docs]
def __dir__() -> list[str]:
return sorted(set(globals()) | _LAZY_SCENE_IO)