Struct Vm 

pub struct Vm { /* private fields */ }

One command-dispatch table used to execute ACTION opcodes.

Implementations

impl Vm

pub fn new() -> Self

Creates an empty VM command table.

pub fn define_command<F>(&mut self, command: u16, handler: F)

where F: Fn(&mut VmScript, u16, u8) -> Result<(), VmError> + 'static,

Registers one command handler by its numeric action id.

pub fn define_simple_command<F>(&mut self, command: u16, handler: F)

where F: Fn(&mut VmScript) -> Result<(), VmError> + 'static,

Registers one zero-metadata command handler.

pub fn define_engine_structure<F>(&mut self, index: u8, factory: F)

where F: Fn(u8) -> VmEngineStructureValue + 'static,

Registers one engine-structure default factory by its numeric type index.

pub fn define_engine_structure_default( &mut self, index: u8, value: VmEngineStructureValue, )

Registers one fixed default engine-structure value by its numeric type index.

pub fn define_engine_structure_comparer<F>(&mut self, index: u8, comparer: F)

where F: Fn(u8, &VmEngineStructureValue, &VmEngineStructureValue) -> bool + 'static,

Registers one engine-structure equality hook by its numeric type index.

pub fn define_trace_hook<F>(&mut self, hook: F)

where F: Fn(&VmScript, &VmTraceEvent) + 'static,

Registers one instruction trace hook invoked before each opcode executes.

pub fn clear_trace_hook(&mut self)

Removes the currently registered instruction trace hook.

pub fn run(&self, script: &mut VmScript) -> Result<(), VmError>

Executes one script until it returns from the outermost frame.

Errors

Returns VmError if execution fails.

pub fn step(&self, script: &mut VmScript) -> Result<VmStepOutcome, VmError>

Executes exactly one instruction.

Errors

Returns VmError if decoding or execution fails.

pub fn run_until_offset( &self, script: &mut VmScript, offset: usize, options: VmRunOptions, ) -> Result<VmStepOutcome, VmError>

Continues execution until the script is about to execute the instruction at offset.

If the script reaches the requested offset, this returns VmStepOutcome::Running without executing that instruction.

Errors

Returns VmError if execution fails or exceeds the configured instruction budget.

pub fn step_over( &self, script: &mut VmScript, options: VmRunOptions, ) -> Result<VmStepOutcome, VmError>

Executes the current instruction, stepping over user-function calls.

For non-JSR instructions this behaves like Vm::step. For JSR, it runs until control returns to the caller, preserving a debugger-friendly “step over” behavior.

Errors

Returns VmError if execution fails or exceeds the configured instruction budget.

pub fn step_out( &self, script: &mut VmScript, options: VmRunOptions, ) -> Result<VmStepOutcome, VmError>

Continues execution until the current function returns to its caller.

If the script is currently at top level, this runs until the script halts or aborts.

Errors

Returns VmError if execution fails or exceeds the configured instruction budget.

pub fn run_until_line( &self, script: &mut VmScript, file_name: &str, line_number: usize, options: VmRunOptions, ) -> Result<VmStepOutcome, VmError>

Continues execution until the script is about to execute one instruction mapped to file_name:line_number in attached NDB metadata.

If the script reaches the requested line, this returns VmStepOutcome::Running without executing that instruction.

Errors

Returns VmError if the script has no matching debug mapping, execution fails, or the instruction budget is exceeded.

pub fn run_until_function( &self, script: &mut VmScript, name: &str, options: VmRunOptions, ) -> Result<VmStepOutcome, VmError>

Continues execution until the script is about to execute one instruction inside the named function from attached NDB metadata.

If the script reaches the requested function, this returns VmStepOutcome::Running without executing that instruction.

Errors

Returns VmError if the script has no matching debug mapping, execution fails, or the instruction budget is exceeded.

pub fn run_with_options( &self, script: &mut VmScript, options: VmRunOptions, ) -> Result<(), VmError>

Executes one script with explicit runtime controls until it returns from the outermost frame.

Errors

Returns VmError if execution fails or exceeds the configured instruction budget.

pub fn run_situation( &self, situation: &VmSituation, ) -> Result<VmScript, VmError>

Executes one previously captured NWScript action situation.

Errors

Returns VmError if execution fails.

pub fn run_situation_with_options( &self, situation: &VmSituation, options: VmRunOptions, ) -> Result<VmScript, VmError>

Executes one previously captured NWScript action situation with explicit runtime controls.

Errors

Returns VmError if execution fails.

pub fn run_bytes( &self, bytes: &[u8], label: impl Into<String>, ) -> Result<VmScript, VmError>

Decodes one script, runs it, and returns the finished runtime state.

Errors

Returns VmError if decoding or execution fails.

pub fn run_bytes_with_options( &self, bytes: &[u8], label: impl Into<String>, options: VmRunOptions, ) -> Result<VmScript, VmError>

Decodes one script, runs it with explicit runtime controls, and returns the finished runtime state.

Errors

Returns VmError if decoding or execution fails.

pub fn run_bytes_with_ndb( &self, bytes: &[u8], label: impl Into<String>, ndb: &Ndb, ) -> Result<VmScript, VmError>

Decodes one script, attaches one NDB table, runs it, and returns the finished runtime state.

This is the recommended path for compiled scripts that contain user-function calls, because the VM uses NDB metadata to recover callee stack shapes.

Errors

Returns VmError if decoding, metadata attachment, or execution fails.

pub fn run_bytes_with_ndb_and_options( &self, bytes: &[u8], label: impl Into<String>, ndb: &Ndb, options: VmRunOptions, ) -> Result<VmScript, VmError>

Decodes one script, attaches one NDB table, and runs it with explicit runtime controls.

Errors

Returns VmError if decoding, metadata attachment, or execution fails.

pub fn run_function_bytes( &self, bytes: &[u8], label: impl Into<String>, ndb: &Ndb, name: &str, args: &[VmValue], ) -> Result<VmScript, VmError>

Decodes one script, prepares a named direct function call, and runs it.

This bypasses the compiler-emitted loader and initializes globals automatically for main()-style entry loaders when needed.

Errors

Returns VmError if decoding fails, the function cannot be invoked directly, or execution fails.

pub fn run_function_bytes_with_options( &self, bytes: &[u8], label: impl Into<String>, ndb: &Ndb, name: &str, args: &[VmValue], options: VmRunOptions, ) -> Result<VmScript, VmError>

Decodes one script, prepares a named direct function call, and runs it with explicit runtime controls.

Errors

Returns VmError if decoding fails, the function cannot be invoked directly, execution fails, or the instruction budget is exceeded.

Trait Implementations

impl Debug for Vm

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Vm

fn default() -> Vm

Returns the “default value” for a type.