Struct Timeline

Source

pub struct Timeline { /* private fields */ }

Expand description

An SM64 API that allows reads and writes to arbitrary frames without frame advance or save states.

See crate level docs for more details on which API to use.

§Example

use wafel_api::Timeline;

let mut timeline = unsafe { Timeline::new("libsm64/sm64_us.dll") };

assert_eq!(
    timeline.read(1500, "gCurrLevelNum"),
    timeline.constant("LEVEL_BOWSER_1")
);

for frame in 0..1000 {
    if frame % 2 == 1 {
        timeline.write(
            frame,
            "gControllerPads[0].button",
            timeline.constant("START_BUTTON"),
        );
    }
}

assert_eq!(
    timeline.read(1500, "gCurrLevelNum"),
    timeline.constant("LEVEL_CASTLE_GROUNDS")
);

Implementations§

Source §

impl Timeline

Source

pub unsafe fn new(dll_path: &str) -> Self

Load a libsm64 DLL.

§Panics

Panics if the DLL fails to open, probably because the file doesn’t exist or the DLL isn’t a proper libsm64 DLL.

§Safety

This method is inherently unsafe:

If the DLL image is modified (either on disk before load or in memory) from anywhere except this Timeline, this is UB.
The DLL can easily execute arbitrary code.

Source

pub unsafe fn try_new(dll_path: &str) -> Result<Self, Error>

Load a libsm64 DLL.

Returns an error if the DLL fails to open, probably because the file doesn’t exist or the DLL isn’t a proper libsm64 DLL.

§Safety

This method is inherently unsafe:

If the DLL image is modified (either on disk before load or in memory) from anywhere except this Timeline, this is UB.
The DLL can easily execute arbitrary code.

Source

pub fn set_hotspot(&mut self, name: &str, frame: u32)

Set a hotspot with a given name.

A hotspot is a hint to the algorithm that scrolling should be smooth near the given frame.

balance_distribution must also be called frequently to maintain this.

Source

pub fn delete_hotspot(&mut self, name: &str)

Delete a hotspot with the given name, if it exists.

Source

pub fn balance_distribution(&mut self, max_run_time_seconds: f32)

Perform housekeeping to improve scrolling near hotspots.

Source

pub fn read(&self, frame: u32, path: &str) -> Value

Read a value from memory on the given frame.

See the crate documentation for the path syntax.

§Panics

Panics if:

The path fails to compile
Reading from memory fails
A write on a previous frame failed

Source

pub fn try_read(&self, frame: u32, path: &str) -> Result<Value, Error>

Read a value from memory on the given frame.

See the crate documentation for the path syntax.

Returns an error if:

The path fails to compile
Reading from memory fails
A write on a previous frame failed

Source

pub fn read_string_at(&self, frame: u32, address: Address) -> Vec<u8>

Read a null terminated string from memory on the given frame.

§Panics

Panics if:

Reading from memory fails
A write on a previous frame failed

Source

pub fn try_read_string_at( &self, frame: u32, address: Address, ) -> Result<Vec<u8>, Error>

Read a null terminated string from memory on the given frame.

Returns an error if:

Reading from memory fails
A write on a previous frame failed

Source

pub fn address(&self, frame: u32, path: &str) -> Option<Address>

Find the address of a path on the given frame.

This method returns None if ? is used in the path and the expression before ? evaluates to a null pointer.

See the crate documentation for the path syntax.

§Panics

Panics if:

The path fails to compile
Reading from memory fails
A write on a previous frame failed

Source

pub fn try_address( &self, frame: u32, path: &str, ) -> Result<Option<Address>, Error>

Find the address of a path on the given frame.

This method returns None if ? is used in the path and the expression before ? evaluates to a null pointer.

See the crate documentation for the path syntax.

Returns an error if:

The path fails to compile
Reading from memory fails
A write on a previous frame failed

Source

pub fn address_to_symbol(&self, address: Address) -> Option<String>

Return the name of the global variable at the given address.

Returns None if no global variable is at the address.

Source

pub fn data_type(&self, path: &str) -> DataType

Return a simplified description of the type of the given variable.

See the crate documentation for the path syntax.

§Panics

Panics if the path fails to compile or type resolution fails.

Source

pub fn try_data_type(&self, path: &str) -> Result<DataType, Error>

Return a simplified description of the type of the given variable.

See the crate documentation for the path syntax.

§Panics

Panics if the path fails to compile or type resolution fails.

Source

pub fn write(&mut self, frame: u32, path: &str, value: Value)

Write a value on the given frame.

See the crate documentation for the path syntax.

§Panics

Panics if the data path fails to compile. Note that this method does not panic if there is a write error, e.g. null pointer dereference. Instead, write errors will be returned if read is called on a frame later than or equal to frame.

Source

pub fn try_write( &mut self, frame: u32, path: &str, value: Value, ) -> Result<(), Error>

Write a value on the given frame.

See the crate documentation for the path syntax.

Returns an error if the data path fails to compile. Note that this method does not return an error if there is a write error, e.g. null pointer dereference. Instead, write errors will be returned if read is called on a frame later than or equal to frame.

Source

pub fn set_input(&mut self, frame: u32, input: Input)

Set the game’s controller input for the given frame using Input.

§Panics

Panics if path compilation fails.

Source

pub fn try_set_input(&mut self, frame: u32, input: Input) -> Result<(), Error>

Set the game’s controller input for the given frame using Input.

Returns an error if path compilation fails.

Source

pub fn reset(&mut self, frame: u32, path: &str)

Clear all previous calls to write with the given frame and path.

The path string must match the one passed to write exactly. If it is different, then this method will do nothing.

§Panics

Panics if the data path fails to compile.

Source

pub fn try_reset(&mut self, frame: u32, path: &str) -> Result<(), Error>

Clear all previous calls to write with the given frame and path.

The path string must match the one passed to write exactly. If it is different, then this method will do nothing.

Returns an error if the data path fails to compile.

Source

pub fn reset_all(&mut self)

Clear all previous calls to write.

Source

pub fn insert_frame(&mut self, frame: u32)

Shift all edits to the right, starting at the given frame.

Source

pub fn delete_frame(&mut self, frame: u32)

Delete edits at the given frame, shifting all later edits to the left.

Source

pub fn dbg_data_cache_size(&self) -> usize

Return the size of the data cache in bytes.

Source

pub fn dbg_cached_frames(&self) -> Vec<u32>

Return a list of the frames that are currently loaded by the algorithm.

Source

pub fn constant(&self, name: &str) -> Value

Return the value of the macro constant or enum variant with the given name.

§Panics

Panics if the constant doesn’t exist. Unless the name has a typo, it is likely that either Wafel is out of date or it is just a limitation of how Wafel obtains constants from the source.

Source

pub fn try_constant(&self, name: &str) -> Result<Value, Error>

Return the value of the macro constant or enum variant with the given name.

Returns an error if the constant doesn’t exist. Unless the name has a typo, it is likely that either Wafel is out of date or it is just a limitation of how Wafel obtains constants from the source.

Source