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}