cougr-core 1.0.0

Cougr - A Soroban-compatible ECS framework for on-chain gaming on Stellar
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158

#![no_std]
#![doc = r#"
Cougr is a monolithic-on-the-outside ECS framework for Soroban-compatible applications.

The public API is intentionally split into:

- root re-exports for the onboarding path
- `app` for the default gameplay runtime surface
- `auth` for beta account and session flows
- `privacy` for stable and experimental privacy surfaces
- `ops` for stable operational standards
- `accounts` for account abstraction and session flows
- `zk::stable` for stable privacy primitives
- `zk::experimental` for fast-moving proof-verification APIs

# Golden Path

```rust
use cougr_core::{ComponentTrait, Position, SimpleWorld};
use soroban_sdk::Env;

let env = Env::default();
let mut world = SimpleWorld::new(&env);
let entity = world.spawn_entity();
world.set_typed(&env, entity, &Position::new(1, 2));

let pos: Position = world.get_typed(&env, entity).unwrap();
assert_eq!(pos.x, 1);
```

# Stability

- ECS runtime and storage: Stable
- `app`: Stable
- `standards`: Stable
- Accounts: Beta
- `zk::stable`: Stable
- `zk::experimental`: Experimental
"#]

extern crate alloc;

// Global allocator for WASM
#[global_allocator]
static ALLOC: wee_alloc::WeeAlloc = wee_alloc::WeeAlloc::INIT;

// Macros must be declared before modules that use them
#[macro_use]
pub mod macros;

// Public product domains
pub mod accounts;
pub mod archetype_world;
mod change_tracker;
pub mod commands;
pub mod component;
#[cfg(feature = "debug")]
#[doc(hidden)]
pub mod debug;
pub mod ecs;
pub mod error;
pub mod event;
mod hooks;
mod incremental;
mod observers;
pub mod plugin;
pub mod query;
pub mod resource;
pub mod scheduler;
pub mod simple_world;
pub mod standards;
mod system;
pub mod zk;

// Root-level golden path re-exports.
pub use archetype_world::{ArchetypeQuery, ArchetypeQueryBuilder, ArchetypeWorld};
pub use commands::CommandQueue;
pub use component::{Component, ComponentId, ComponentStorage, ComponentTrait, Position};
pub use ecs::{RuntimeWorld, RuntimeWorldMut, WorldBackend};
pub use error::{CougrError, CougrResult};
pub use event::{Event, EventReader, EventWriter};
pub use plugin::{GameApp, Plugin, PluginGroup};
pub use query::{QueryStorage, SimpleQuery, SimpleQueryBuilder};
pub use resource::Resource;
pub use resource::ResourceTrait;
pub use scheduler::{ScheduleError, ScheduleStage, SimpleScheduler, SystemConfig, SystemGroup};
pub use simple_world::SimpleWorld;

/// Default gameplay runtime surface for new Cougr projects.
pub mod app {
    pub use super::{
        CommandQueue, GameApp, Plugin, PluginGroup, Resource, ResourceTrait, RuntimeWorld,
        RuntimeWorldMut, ScheduleError, ScheduleStage, SimpleQuery, SimpleQueryBuilder,
        SimpleScheduler, SimpleWorld, SystemConfig, SystemGroup,
    };
    pub use crate::system::{
        context_system, named_app_system, named_context_system, named_system, world_system,
        AppSystem, SimpleSystem, SystemContext, SystemSpec,
    };
}

/// Beta account and session surface.
///
/// This namespace mirrors [`accounts`] but makes its product role explicit.
pub mod auth {
    pub use super::accounts::*;
}

/// Privacy surface split by maturity tier.
///
/// New code should prefer [`privacy::stable`] for defended contracts and only
/// opt into [`privacy::experimental`] knowingly.
pub mod privacy {
    pub use super::zk::{
        experimental, stable, G1Point, G2Point, Groth16Proof, Scalar, VerificationKey, ZKError,
    };
}

/// Stable operational and contract standards.
///
/// This namespace mirrors [`standards`] while making the adoption boundary
/// clearer for application code.
pub mod ops {
    pub use super::standards::*;
}

/// Common ECS imports for the default onboarding path.
pub mod prelude {
    pub use super::simple_world::EntityId;
    pub use super::{
        ArchetypeWorld, CommandQueue, Component, ComponentStorage, ComponentTrait, GameApp,
        PluginGroup, Position, QueryStorage, Resource, RuntimeWorld, RuntimeWorldMut, SimpleQuery,
        SimpleQueryBuilder, SimpleWorld, WorldBackend,
    };
    pub use crate::system::SystemContext;
}

/// Advanced runtime primitives that remain supported but are not part of the
/// smallest onboarding surface.
pub mod runtime {
    pub use super::observers::ComponentEvent;
    pub use super::{
        archetype_world::{ArchetypeQueryCache, ArchetypeQueryState},
        change_tracker::{ChangeTracker, TrackedWorld},
        hooks::{HookRegistry, HookedWorld},
        incremental::{StorageWorld, WorldMetadata},
        observers::{ObservedWorld, ObserverRegistry},
        query::{SimpleQueryCache, SimpleQueryState},
        resource::Resource,
        system::{
            context_system, named_app_system, named_context_system, named_system, world_system,
            AppSystem, SimpleSystem, SystemContext, SystemSpec,
        },
        Event, EventReader, EventWriter, Plugin, PluginGroup, QueryStorage, RuntimeWorld,
        RuntimeWorldMut, ScheduleError, ScheduleStage, SimpleQuery, SimpleQueryBuilder,
        SimpleScheduler, SystemConfig, WorldBackend,
    };
}