Skip to main content

openstranded_plugin_api/
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` (behind `test-utils` feature) for unit-testing plugins natively
21///
22/// # Example
23///
24/// ```rust
25/// use openstranded_plugin_api::{GameAPI, RegistryEntry, Service, ServiceError, Value, LogLevel};
26///
27/// fn plugin_build(api: &mut dyn GameAPI) {
28///     let entries = api.registry_domain("items").unwrap();
29///     for entry in &entries {
30///         api.log(LogLevel::Info, &format!("Loaded {}", entry.filename));
31///     }
32/// }
33/// ```
34pub trait GameAPI {
35    // ── Registry ──────────────────────────────────────────────────
36
37    /// Get all file entries for a domain.
38    fn registry_domain(&self, name: &str) -> Result<Vec<RegistryEntry>, ServiceError>;
39
40    /// Get raw bytes of a specific file within a domain.
41    fn registry_file(&self, domain: &str, filename: &str) -> Result<Vec<u8>, ServiceError>;
42
43    // ── Services ─────────────────────────────────────────────────
44
45    /// Register a service under the given domain name.
46    fn register_service(
47        &mut self,
48        domain: &str,
49        service: Box<dyn Service>,
50    ) -> Result<(), ServiceError>;
51
52    /// Get a reference to a registered service.
53    fn get_service(&self, domain: &str) -> Result<&dyn Service, ServiceError>;
54
55    /// Check whether a service domain is registered.
56    fn has_service(&self, domain: &str) -> bool;
57
58    // ── Logging ──────────────────────────────────────────────────
59
60    /// Log a message at the given level.
61    fn log(&self, level: LogLevel, message: &str);
62}