simvx.core.script

ScriptManager: file-based class script loading for nodes.

Scripts are standard Python classes that extend the node’s type. ScriptManager imports the module, looks up the class by name, and swaps node.__class__ so the node gains the script’s methods (ready, process, etc.).

Script references use the path::ClassName format (e.g. "player.py::Player"). The class name is required: there is no guessing/searching.

Public API: ScriptManager.load(node, project_dir) # raises ScriptLoadError on failure ScriptManager.unload(node) ScriptManager.reload(node, project_dir) # bool convenience (logs failures) ScriptManager.load_tree(root, project_dir) # resilient: logs+skips bad nodes parse_script_ref(script) -> (path, class_name) ScriptLoadError # typed failure raised by load()

Module Contents

Classes

ScriptManager

Static manager for loading/unloading file-based class scripts on nodes.

Functions

parse_script_ref

Parse a script reference into (file_path, class_name).

Data

log
__all__

API

simvx.core.script.log

‘getLogger(…)’

simvx.core.script.__all__

[‘ScriptLoadError’, ‘ScriptManager’, ‘parse_script_ref’]

exception simvx.core.script.ScriptLoadError

Bases: Exception

Raised when a node’s script cannot be loaded.

Covers genuine failures: file not found, class not found, no Node subclass defined, ambiguous classes, and import/exec errors. Callers that load a single node (e.g. the editor’s “attach script” flow) should catch this to surface the error; ScriptManager.load_tree catches it per-node so one bad script never aborts loading the rest of the tree.

Initialization

Initialize self. See help(type(self)) for accurate signature.

class __cause__

class __context__

__delattr__()

__dir__()

__eq__()

__format__()

__ge__()

__getattribute__()

__getstate__()

__gt__()

__hash__()

__le__()

__lt__()

__ne__()

__new__()

__reduce__()

__reduce_ex__()

__repr__()

__setattr__()

__setstate__()

__sizeof__()

__str__()

__subclasshook__()

class __suppress_context__

class __traceback__

add_note()

class args

with_traceback()

simvx.core.script.parse_script_ref(script: str) → tuple[str, str | None]

Parse a script reference into (file_path, class_name).

"player.py::Player" → ("player.py", "Player") "player.py" (legacy, no ::)) → ("player.py", None)

class simvx.core.script.ScriptManager

Static manager for loading/unloading file-based class scripts on nodes.

classmethod load(node: simvx.core.node.Node, project_dir: str = '') → None

Load a file-based or embedded script onto node.

For file-backed scripts: parses node.script for path::ClassName, resolves the path relative to project_dir, imports the module, looks up the class by name, and swaps node.__class__.

For embedded scripts: registers source with EmbeddedScriptFinder, imports it, finds the class via AST, and applies the same class swap.

Returns None on success. Raises :class:ScriptLoadError on any genuine failure (file not found, class not found, no/ambiguous Node subclass, import error). A node with no script attached is a guarded no-op (returns None), not a misuse: callers may safely invoke load on scriptless nodes.

Use :meth:load_tree to load a whole tree resiliently (it catches and logs each per-node failure and continues).

classmethod unload(node: simvx.core.node.Node) → None

Restore the node’s original class, removing the script behavior.

classmethod reload(node: simvx.core.node.Node, project_dir: str = '') → bool

Reload a node’s script (re-import module, re-swap class).

Preserves Property values across the reload. Convenience bool contract: returns True on success, False if the node has no script or the reload failed (the underlying :class:ScriptLoadError is logged, not propagated, so a single failing reload never crashes a hot-reload loop).

classmethod load_tree(root: simvx.core.node.Node, project_dir: str = '') → list[simvx.core.node.Node]

Walk root’s tree and load file-based scripts on every node that has one.

Returns the list of nodes whose class was swapped so the caller can invoke on_ready() or other lifecycle methods.

classmethod invalidate(abs_path: str) → None

Remove a module from the cache and its registry entries.

classmethod clear_cache() → None

Clear the entire module cache and all script-originated registry entries.