openstranded_common_wasmcontract/
game_api.rs

1use crate::{RegistryEntry, Service, ServiceError};
2
3/// Log severity level.
4#[derive(Clone, Copy, Debug, PartialEq, Eq)]
5pub enum LogLevel {
6    Debug,
7    Info,
8    Warn,
9    Error,
10}
11
12/// Host-side API surface provided to WASM plugins.
13///
14/// During the build/ready/finish lifecycle phases, the plugin receives
15/// a `&mut dyn GameAPI` to interact with the engine.
16///
17/// # Implementations
18///
19/// - **Host (engine):** real implementation backed by ECS + wasmtime
20/// - **Test:** `MockGameAPI` (in `openstranded-plugin-api` behind `test-utils` feature)
21///   for unit-testing plugins natively
22///
23/// # Example
24///
25/// ```rust
26/// use openstranded_common_wasmcontract::{GameAPI, RegistryEntry, Service, ServiceError, Value, LogLevel};
27///
28/// fn plugin_build(api: &mut dyn GameAPI) {
29///     let entries = api.registry_domain("items").unwrap();
30///     for entry in &entries {
31///         api.log(LogLevel::Info, &format!("Loaded {}", entry.filename));
32///     }
33/// }
34/// ```
35pub trait GameAPI {
36    // ── Registry ──────────────────────────────────────────────────
37
38    /// Get all file entries for a domain.
39    fn registry_domain(&self, name: &str) -> Result<Vec<RegistryEntry>, ServiceError>;
40
41    /// Get raw bytes of a specific file within a domain.
42    fn registry_file(&self, domain: &str, filename: &str) -> Result<Vec<u8>, ServiceError>;
43
44    // ── Services ─────────────────────────────────────────────────
45
46    /// Register a service under the given domain name.
47    fn register_service(
48        &mut self,
49        domain: &str,
50        service: Box<dyn Service>,
51    ) -> Result<(), ServiceError>;
52
53    /// Get a reference to a registered service.
54    fn get_service(&self, domain: &str) -> Result<&dyn Service, ServiceError>;
55
56    /// Check whether a service domain is registered.
57    fn has_service(&self, domain: &str) -> bool;
58
59    // ── Logging ──────────────────────────────────────────────────
60
61    /// Log a message at the given level.
62    fn log(&self, level: LogLevel, message: &str);
63}
openstranded_common_wasmcontract/game_api.rs

openstranded_common_wasmcontract/
game_api.rs
