openstranded_plugin_api/lib.rs
1//! # openstranded-plugin-api
2//!
3//! Plugin SDK for `OpenStranded` — the core types and traits that all
4//! WASM game plugins use to communicate with the engine and each other.
5//!
6//! This crate defines the **plugin contract** only. Internal data structures
7//! (`Registry`, `ServiceRegistry`) live in the engine crate.
8//!
9//! ## Core types
10//!
11//! - [`Value`]: dynamic type for cross-plugin arguments and return values
12//! - [`ServiceError`]: typed errors for Service API calls
13//! - [`Service`]: cross-plugin method call interface (trait)
14//! - [`RegistryEntry`]: a single file from content pack (data + filename)
15//! - [`GameAPI`]: host-side API surface provided to plugins
16//! - [`Contribution`]: declarative output from WASM plugin `build()` phase
17//! - [`ApiVersion`]: compile-time baked version for compatibility checks
18//!
19//! ## Feature flags
20//!
21//! - `parse` (default): enables [`parse_registry_data`] and [`parse_registry_list`]
22//! - `test-utils`: enables `MockGameAPI` for testing
23//!
24//! ## WASM entry points
25//!
26//! Every WASM plugin must export the following `#[no_mangle] extern "C"` functions:
27//!
28//! | Export | Required | Called during |
29//! |--------|----------|---------------|
30//! | `plugin_api_version() -> ApiVersion` | Yes | Load, before anything |
31//! | `plugin_build(ctx) -> Vec<Contribution>` | Yes | Registry phase |
32//! | `plugin_ready(api) -> bool` | No | Discovery phase |
33//! | `plugin_finish(api)` | No | Integration phase |
34
35mod value;
36mod error;
37mod service;
38mod registry;
39mod game_api;
40mod contributions;
41mod version;
42
43#[cfg(feature = "test-utils")]
44pub mod test_utils;
45
46// ── Re-exports ─────────────────────────────────────────────────────
47
48pub use value::Value;
49pub use error::ServiceError;
50pub use service::Service;
51pub use registry::RegistryEntry;
52#[cfg(feature = "parse")]
53pub use registry::{parse_registry_data, parse_registry_list};
54pub use game_api::{GameAPI, LogLevel};
55pub use contributions::{Contribution, SystemDecl, ResourceDecl};
56pub use version::{ApiVersion, VersionMismatch};