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) ScriptManager.unload(node) ScriptManager.reload(node, project_dir) ScriptManager.load_tree(root, project_dir) parse_script_ref(script) -> (path, class_name)

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__

[‘ScriptManager’, ‘parse_script_ref’]

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 = '') → bool

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 True on success, False on error (logged, not raised).

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.

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 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.