cougr_core/
lib.rs

1#![no_std]
2#![doc = r#"
3Cougr is a monolithic-on-the-outside ECS framework for Soroban-compatible applications.
4
5The public API is intentionally split into:
6
7- root re-exports for the onboarding path
8- `app` for the default gameplay runtime surface
9- `auth` for beta account and session flows
10- `privacy` for stable and experimental privacy surfaces
11- `ops` for stable operational standards
12- `accounts` for account abstraction and session flows
13- `zk::stable` for stable privacy primitives
14- `zk::experimental` for fast-moving proof-verification APIs
15
16# Golden Path
17
18```rust
19use cougr_core::{ComponentTrait, Position, SimpleWorld};
20use soroban_sdk::Env;
21
22let env = Env::default();
23let mut world = SimpleWorld::new(&env);
24let entity = world.spawn_entity();
25world.set_typed(&env, entity, &Position::new(1, 2));
26
27let pos: Position = world.get_typed(&env, entity).unwrap();
28assert_eq!(pos.x, 1);
29```
30
31# Stability
32
33- ECS runtime and storage: Stable
34- `app`: Stable
35- `standards`: Stable
36- Accounts: Beta
37- `zk::stable`: Stable
38- `zk::experimental`: Experimental
39"#]
40
41extern crate alloc;
42
43// Global allocator for WASM
44#[global_allocator]
45static ALLOC: wee_alloc::WeeAlloc = wee_alloc::WeeAlloc::INIT;
46
47// Macros must be declared before modules that use them
48#[macro_use]
49pub mod macros;
50
51// Public product domains
52pub mod accounts;
53pub mod archetype_world;
54mod change_tracker;
55pub mod commands;
56pub mod component;
57#[cfg(feature = "debug")]
58#[doc(hidden)]
59pub mod debug;
60pub mod ecs;
61pub mod error;
62pub mod event;
63mod hooks;
64mod incremental;
65mod observers;
66pub mod plugin;
67pub mod query;
68pub mod resource;
69pub mod scheduler;
70pub mod simple_world;
71pub mod standards;
72mod system;
73pub mod zk;
74
75// Root-level golden path re-exports.
76pub use archetype_world::{ArchetypeQuery, ArchetypeQueryBuilder, ArchetypeWorld};
77pub use commands::CommandQueue;
78pub use component::{Component, ComponentId, ComponentStorage, ComponentTrait, Position};
79pub use ecs::{RuntimeWorld, RuntimeWorldMut, WorldBackend};
80pub use error::{CougrError, CougrResult};
81pub use event::{Event, EventReader, EventWriter};
82pub use plugin::{GameApp, Plugin, PluginGroup};
83pub use query::{QueryStorage, SimpleQuery, SimpleQueryBuilder};
84pub use resource::Resource;
85pub use resource::ResourceTrait;
86pub use scheduler::{ScheduleError, ScheduleStage, SimpleScheduler, SystemConfig, SystemGroup};
87pub use simple_world::SimpleWorld;
88
89/// Default gameplay runtime surface for new Cougr projects.
90pub mod app {
91    pub use super::{
92        CommandQueue, GameApp, Plugin, PluginGroup, Resource, ResourceTrait, RuntimeWorld,
93        RuntimeWorldMut, ScheduleError, ScheduleStage, SimpleQuery, SimpleQueryBuilder,
94        SimpleScheduler, SimpleWorld, SystemConfig, SystemGroup,
95    };
96    pub use crate::system::{
97        context_system, named_app_system, named_context_system, named_system, world_system,
98        AppSystem, SimpleSystem, SystemContext, SystemSpec,
99    };
100}
101
102/// Beta account and session surface.
103///
104/// This namespace mirrors [`accounts`] but makes its product role explicit.
105pub mod auth {
106    pub use super::accounts::*;
107}
108
109/// Privacy surface split by maturity tier.
110///
111/// New code should prefer [`privacy::stable`] for defended contracts and only
112/// opt into [`privacy::experimental`] knowingly.
113pub mod privacy {
114    pub use super::zk::{
115        experimental, stable, G1Point, G2Point, Groth16Proof, Scalar, VerificationKey, ZKError,
116    };
117}
118
119/// Stable operational and contract standards.
120///
121/// This namespace mirrors [`standards`] while making the adoption boundary
122/// clearer for application code.
123pub mod ops {
124    pub use super::standards::*;
125}
126
127/// Common ECS imports for the default onboarding path.
128pub mod prelude {
129    pub use super::simple_world::EntityId;
130    pub use super::{
131        ArchetypeWorld, CommandQueue, Component, ComponentStorage, ComponentTrait, GameApp,
132        PluginGroup, Position, QueryStorage, Resource, RuntimeWorld, RuntimeWorldMut, SimpleQuery,
133        SimpleQueryBuilder, SimpleWorld, WorldBackend,
134    };
135    pub use crate::system::SystemContext;
136}
137
138/// Advanced runtime primitives that remain supported but are not part of the
139/// smallest onboarding surface.
140pub mod runtime {
141    pub use super::observers::ComponentEvent;
142    pub use super::{
143        archetype_world::{ArchetypeQueryCache, ArchetypeQueryState},
144        change_tracker::{ChangeTracker, TrackedWorld},
145        hooks::{HookRegistry, HookedWorld},
146        incremental::{StorageWorld, WorldMetadata},
147        observers::{ObservedWorld, ObserverRegistry},
148        query::{SimpleQueryCache, SimpleQueryState},
149        resource::Resource,
150        system::{
151            context_system, named_app_system, named_context_system, named_system, world_system,
152            AppSystem, SimpleSystem, SystemContext, SystemSpec,
153        },
154        Event, EventReader, EventWriter, Plugin, PluginGroup, QueryStorage, RuntimeWorld,
155        RuntimeWorldMut, ScheduleError, ScheduleStage, SimpleQuery, SimpleQueryBuilder,
156        SimpleScheduler, SystemConfig, WorldBackend,
157    };
158}
cougr_core/lib.rs

cougr_core/
lib.rs
