Struct Game

Source

pub struct Game {
    pub layout: MemoryLayoutImpl<DllGameMemory>,
    pub memory: Arc<DllGameMemory>,
    pub base_slot: <DllGameMemory as GameMemory>::Slot,
    /* private fields */
}

Expand description

An SM64 API that uses a traditional frame advance / save state model.

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

§Example

use wafel_api::Game;

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

let power_on = game.save_state();

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

game.load_state(&power_on);
assert_eq!(game.frame(), 0);

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

game.advance_n(500);
assert_eq!(
    game.read("gCurrLevelNum"),
    game.constant("LEVEL_CASTLE_GROUNDS")
);

Fields§

§layout: MemoryLayoutImpl<DllGameMemory>§memory: Arc<DllGameMemory>§base_slot: <DllGameMemory as GameMemory>::Slot

Implementations§

Source §

impl Game

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 Game, 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 Game, this is UB.
The DLL can easily execute arbitrary code.

Source

pub fn pid(&self) -> u32

Return the PID of the running process.

This may be used to allow external processes to access this Game instance’s memory, e.g. using RemoteDll.

Source

pub fn base_address(&self) -> usize

Return the base address of the libsm64 DLL in memory.

This may be used to allow external processes to access this Game instance’s memory, e.g. using RemoteDll.

Source

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

Read a value from memory.

See the crate documentation for the path syntax.

§Panics

Panics if the path fails to compile or reading from memory fails.

Source

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

Read a value from memory.

See the crate documentation for the path syntax.

Returns an error if the path fails to compile or reading from memory fails.

Source

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

Read a null terminated string from memory at the given address.

§Panics

Panics if reading from memory fails.

Source

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

Read a null terminated string from memory at the given address.

Returns an error if reading from memory fails.

Source

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

Find the address of a path.

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 or reading from memory fails.

Source

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

Find the address of a path.

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 or reading from memory fails.

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, path: &str, value: Value)

Write a value to memory.

See the crate documentation for the path syntax.

§Panics

Panics if the data path fails to compile or the write fails.

Source

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

Write a value to memory.

See the crate documentation for the path syntax.

Returns an error if the data path fails to compile or the write fails.

Source

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

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

§Panics

Panics if the write fails.

Source

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

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

Returns an error if the write fails.

Source

pub fn frame(&self) -> u32

Get the frame of the current game state.

Source

pub fn advance(&mut self)

Advance a single frame.

Source

pub fn advance_n(&mut self, num_frames: u32)

Advance multiple frames.

Source

pub fn save_state(&self) -> SaveState

Create a save state using the current game state.

Source

pub fn load_state(&mut self, state: &SaveState)

Load a save state.

§Panics

Panics if the save state was produced by a different Game instance.

Source

pub fn try_load_state(&mut self, state: &SaveState) -> Result<(), Error>

Load a save state.

Returns an error if the save state was produced by a different Game instance.

Source

pub fn rerecords(&self) -> u32

Return the number of times that a save state has been loaded.

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