Trait GameAPI 

pub trait GameAPI {
    // Required methods
    fn registry_domain(
        &self,
        name: &str,
    ) -> Result<Vec<RegistryEntry>, ServiceError>;
    fn registry_file(
        &self,
        domain: &str,
        filename: &str,
    ) -> Result<Vec<u8>, ServiceError>;
    fn read_content_file(&self, path: &str) -> Result<Vec<u8>, ServiceError>;
    fn register_service(
        &mut self,
        domain: &str,
        service: Box<dyn Service>,
    ) -> Result<(), ServiceError>;
    fn get_service(&self, domain: &str) -> Result<&dyn Service, ServiceError>;
    fn call_service(
        &self,
        domain: &str,
        method: &str,
        args: &[Value],
    ) -> Result<Value, ServiceError>;
    fn has_service(&self, domain: &str) -> bool;
    fn get_component(
        &self,
        entity: u64,
        type_name: &str,
    ) -> Result<Vec<u8>, ServiceError>;
    fn set_component(
        &mut self,
        entity: u64,
        type_name: &str,
        data: &[u8],
    ) -> Result<(), ServiceError>;
    fn query_entities(
        &self,
        component_name: &str,
    ) -> Result<Vec<u64>, ServiceError>;
    fn spawn_entity(&mut self, archetype: &str) -> Result<u64, ServiceError>;
    fn despawn_entity(&mut self, entity: u64) -> Result<(), ServiceError>;
    fn read_config(&self, key: &str) -> Result<Value, ServiceError>;
    fn read_keybinds(&self) -> Result<Value, ServiceError>;
    fn register_save_data(
        &mut self,
        domain: &str,
        data: Vec<u8>,
    ) -> Result<(), ServiceError>;
    fn load_save_data(
        &self,
        domain: &str,
    ) -> Result<Option<Vec<u8>>, ServiceError>;
    fn emit_event(&self, name: &str, data: &Value) -> Result<(), ServiceError>;
    fn log(&self, level: LogLevel, message: &str);
}

Host-side API surface provided to WASM plugins.

During the build/ready/finish lifecycle phases, the plugin receives a &mut dyn GameAPI to interact with the engine.

Implementations

• Host (engine): [GameAPIHost] — real implementation backed by ECS, Registry, ServiceRegistry.
• Test: MockGameAPI (in openstranded-plugin-api behind test-utils feature) for unit-testing plugins natively.

Object safety

This trait is not object-safe due to get_service() returning &dyn Service. In practice, callers use &mut dyn GameAPI or concrete types. WASM plugins access the API through host import functions, not through this trait.

Required Methods

fn registry_domain( &self, name: &str, ) -> Result<Vec<RegistryEntry>, ServiceError>

Get all file entries for a domain.

fn registry_file( &self, domain: &str, filename: &str, ) -> Result<Vec<u8>, ServiceError>

Get raw bytes of a specific file within a domain.

fn read_content_file(&self, path: &str) -> Result<Vec<u8>, ServiceError>

Read any file from the active Content Pack by relative path.

Useful for loading assets (.glb, .png, .wav) that are not in the Registry but are referenced by path.

fn register_service( &mut self, domain: &str, service: Box<dyn Service>, ) -> Result<(), ServiceError>

Register a service under the given domain name.

fn get_service(&self, domain: &str) -> Result<&dyn Service, ServiceError>

Get a reference to a registered service (native use only).

fn call_service( &self, domain: &str, method: &str, args: &[Value], ) -> Result<Value, ServiceError>

Call a method on another plugin’s service (WASM-friendly).

This is the primary way for WASM plugins to communicate. The call is serialized, sent to the host, and dispatched to the target plugin.

fn has_service(&self, domain: &str) -> bool

Check whether a service domain is registered.

fn get_component( &self, entity: u64, type_name: &str, ) -> Result<Vec<u8>, ServiceError>

Read a component from an entity as raw serialised bytes.

fn set_component( &mut self, entity: u64, type_name: &str, data: &[u8], ) -> Result<(), ServiceError>

Buffer a component write. Applied atomically at the flush point.

fn query_entities(&self, component_name: &str) -> Result<Vec<u64>, ServiceError>

Find all entities that have a component with the given type name.

fn spawn_entity(&mut self, archetype: &str) -> Result<u64, ServiceError>

Buffer a spawn request. Returns the new entity ID after flush.

fn despawn_entity(&mut self, entity: u64) -> Result<(), ServiceError>

Buffer a despawn request.

fn read_config(&self, key: &str) -> Result<Value, ServiceError>

Read an engine config value by dotted key path.

Examples: "audio.master_volume", "window.width". Returns Null if the key does not exist (not an error).

fn read_keybinds(&self) -> Result<Value, ServiceError>

Read the full keybinds table as a Map<String, String>.

fn register_save_data( &mut self, domain: &str, data: Vec<u8>, ) -> Result<(), ServiceError>

Register a named blob of save data for the current save slot.

Called in response to a "save" event. The engine collects all domains and writes them to disk.

fn load_save_data(&self, domain: &str) -> Result<Option<Vec<u8>>, ServiceError>

Load a previously saved data blob by domain name.

Returns None if no data was saved under this domain.

fn emit_event(&self, name: &str, data: &Value) -> Result<(), ServiceError>

Emit a named event with attached data.

The event is broadcast to all registered handlers:

• WASM plugins with a matching on_event export are called
• Lua hooks registered via core_api.on() are triggered

fn log(&self, level: LogLevel, message: &str)

Log a message at the given level.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors