Struct Machine 

pub struct Machine { /* private fields */ }

A linked program and its persistent state. Clone creates an independent checkpoint.

Implementations

impl Machine

pub fn new(program: Program, limits: Limits) -> Result<Self, Diagnostic>

Initialize supplied modules once in dependency order, then the main module.

Errors

Rejects invalid initializers or resource limits without creating a machine.

pub fn with_registry( program: Program, limits: Limits, registry: NativeRegistry, ) -> Result<Self, Diagnostic>

Construct with explicitly registered pure host operations.

Errors

Returns initializer/type/resource diagnostics exactly as Self::new.

pub fn snapshot(&self) -> Snapshot

A read-only projection of the accepted state.

pub const fn execution_state(&self) -> (u64, bool)

Returns the current fixed tick and terminal lifecycle state without cloning entities, logs, traces, or component values.

pub fn program(&self) -> &Program

The immutable linked program that defines this machine.

pub fn limits(&self) -> &Limits

The resource limits applied to every accepted transaction.

pub fn tick(&mut self, dt: f64) -> Result<Snapshot, Diagnostic>

Run all systems in linked source order. A system visits its starting query in ascending entity-ID order. Spawns are visible to subsequent systems. New tuples run init immediately before their first frame. A despawn request takes effect after the current callback writes its bindings back; initialized tuples then run done before the entity is deleted.

Errors

Any error rolls back the complete tick, including logs and entity IDs.

pub fn finish(&mut self) -> Result<Snapshot, Diagnostic>

Complete initialized system memberships in system/entity/component order. Repeated calls return the same snapshot. No callback runs for an unvisited tuple.

Errors

A failed callback rolls back all cleanup and keeps the machine running.

pub fn invoke( &mut self, name: &str, arguments: Vec<Value>, ) -> Result<Value, Diagnostic>

Invoke a main or explicitly imported/exported function transactionally. This is the shared action entry for UI controls, tests, and agent adapters.

Errors

Rejects inaccessible/unknown names, invalid arguments or execution, and exhausted budgets. The previously accepted state remains unchanged.

pub fn invoke_component( &mut self, id: u64, component: &str, field: &str, arguments: Vec<Value>, ) -> Result<Value, Diagnostic>

Invoke the typed function stored in an exact component field. The host supplies no function identity; private callbacks retained by the program remain callable. Lookup, execution, logs and world edits commit together.

Errors

Rejects missing entity/component/field, non-callable fields, mismatched arguments and exhausted budgets, preserving the accepted state.

pub fn invoke_entity( &mut self, id: u64, name: &str, arguments: Vec<Value>, ) -> Result<Value, Diagnostic>

Dispatch a method on exactly one component. Multiple matching components are ambiguous and rejected; mutation and logs commit together on success.

Errors

Rejects missing/ambiguous methods, invalid arguments, conflicting component writes, and execution limits without changing accepted state.

pub fn upsert_components( &mut self, patches: &[(u64, Value)], ) -> Result<(), Diagnostic>

Atomically attach or replace validated components from an explicit host adapter. Existing entity identity and spawn source are preserved.

Errors

Rejects unknown entities, malformed records, and storage limit violations.

pub fn patch_components( &mut self, patches: &[(u64, Value)], ) -> Result<(), Diagnostic>

Atomically replace existing components from a host adapter (for example, a physics solver). Class fields and all storage limits are revalidated.

Errors

Rejects missing entities/components, malformed records, and storage limits; either the complete patch is accepted or none of it is applied.

pub fn transaction<T>( &mut self, operation: impl FnOnce(&mut Self) -> Result<T, Diagnostic>, ) -> Result<T, Diagnostic>

Roll back this machine when a composed operation fails.

Errors

Propagates the closure diagnostic without replacing this machine. The closure must include any adapter state in its own transaction; this method cannot undo external I/O, global Rust state, or effects on other objects.

Trait Implementations

impl Clone for Machine

fn clone(&self) -> Machine

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.