simvx.core.project

Project configuration: simvx.toml files.

Schema-driven TOML file describing a SimVX game’s display, physics, input, audio, rendering, export, and editor settings. Uses stdlib tomllib for reading and a small hand-rolled writer for round-tripping.

Public API: from simvx.core.project import ProjectSettings, load_project, save_project

settings = load_project("simvx.toml")
settings.name = "My Game"
save_project(settings, "simvx.toml")

Module Contents

Classes

ProjectSettings

TOML-based project configuration.

Functions

input_bindings_from_toml	An [input] entry’s source list, read by the spelling the rebind file shares.
input_bindings_to_toml	An action’s sources as the plain data an [input] entry holds.
load_project	Load project settings from a simvx.toml file.
save_project	Save project settings to a simvx.toml file.
find_project	Search up the directory tree for simvx.toml.

Data

log
__all__
TOML_FILENAME

API

simvx.core.project.log

‘getLogger(…)’

simvx.core.project.__all__

[‘ProjectSettings’, ‘ValidationError’, ‘load_project’, ‘save_project’, ‘find_project’, ‘input_bindin…

simvx.core.project.TOML_FILENAME

‘simvx.toml’

simvx.core.project.input_bindings_from_toml(action: str, entries: list[Any]) → list[simvx.core.input.actions.Source]

An [input] entry’s source list, read by the spelling the rebind file shares.

See :mod:simvx.core.input.spelling for the forms: a key’s name or a combo, a control’s type:name, a table with held and exact, {low, high}, {up, down, left, right}, and {name = ...}.

simvx.core.project.input_bindings_to_toml(sources: list[simvx.core.input.actions.Source]) → list[Any]

An action’s sources as the plain data an [input] entry holds.

exception simvx.core.project.ValidationError

Bases: ValueError

Raised when simvx.toml contains invalid values.

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()

class simvx.core.project.ProjectSettings(data: dict[str, Any] | None = None)

TOML-based project configuration.

Sections are stored as plain dicts for simplicity and easy serialization. Top-level fields (name, main) are direct attributes. Any table the class does not model is kept in extras and written back out unchanged.

Initialization

__slots__

(‘name’, ‘main’, ‘display’, ‘input’, ‘physics’, ‘audio’, ‘rendering’, ‘export_web’, ‘export_desktop’…

to_dict() → dict[str, Any]

Serialize to a nested dict matching TOML structure.

validate() → None

Validate all settings. Raises ValidationError on invalid values.

property project_dir: str

Directory containing the project file ("." if unset).

resolve_path(relative: str) → str

Resolve a project-relative path to an absolute path.

apply_input() → None

Make the project’s [input] entries the project layer of every tree’s map.

The layer sits over the engine’s own entries and under every tree’s contexts and the player’s rebinds, and it is read live, so a change applied here reaches trees that already exist: that is what makes the editor’s input-map dialog reach the game it is hosting. The entries may name each other in any order, and a set that cannot resolve is refused, naming the problem.

simvx.core.project.load_project(path: str | pathlib.Path) → simvx.core.project.ProjectSettings

Load project settings from a simvx.toml file.

Raises: FileNotFoundError: If the file does not exist. tomllib.TOMLDecodeError: If the file is not valid TOML. ValidationError: If values fail schema validation.

simvx.core.project.save_project(settings: simvx.core.project.ProjectSettings, path: str | pathlib.Path | None = None) → None

Save project settings to a simvx.toml file.

Args: settings: ProjectSettings to save. path: Output file path. If None, uses settings.project_path.

simvx.core.project.find_project(start_dir: str | pathlib.Path | None = None) → pathlib.Path | None

Search up the directory tree for simvx.toml.

Args: start_dir: Directory to start searching from. Defaults to cwd.

Returns: Path to simvx.toml if found, None otherwise.