wyrd/
lib.rs

1//! Engine-neutral signal-graph game logic for Wyrd.
2//!
3//! Author an immutable [`Weave`], bind it to dense ids with [`Runtime`], then
4//! sample host senses and settle it once per frame. Use [`core`], [`graph`],
5//! and [`runtime`] when an explicit layer namespace is clearer.
6//!
7//! The crate root re-exports the common authoring and runtime vocabulary. The
8//! layer modules provide the same contracts grouped by intent. Implementation
9//! modules stay private so downstream code cannot depend on bind tables or
10//! runtime storage details:
11//!
12//! ```compile_fail
13//! use wyrd::runtime_impl::Runtime;
14//! ```
15//!
16//! ```compile_fail
17//! use wyrd::authoring::WeaveBuilder;
18//! ```
19//!
20//! Start with the ordered, executable [`examples`], beginning at
21//! [`examples::tier_a::a01_hello_invert`].
22
23#![no_std]
24#![forbid(unsafe_code)]
25#![warn(missing_docs)]
26
27extern crate alloc;
28extern crate no_std_compat as std;
29
30/// Allocation types used by exported declarative authoring macros.
31///
32/// This is public only so macro expansions remain portable to `no_std + alloc`
33/// callers; it is not part of the supported hand-written API.
34#[doc(hidden)]
35pub mod __private {
36    pub use crate::std::string::String;
37    pub use crate::std::vec::Vec;
38}
39
40mod authoring;
41mod foundation;
42mod runtime_impl;
43
44pub mod examples;
45
46pub mod core {
47    //! Shared signal, id, port, and knot-catalog vocabulary.
48    //!
49    //! This layer exposes types and helpers only — no weave authoring, bind, or
50    //! settle. Pick exactly one compile-time numeric path (`signal-f32` or
51    //! `signal-i32`) before building graphs or runtimes.
52
53    pub use crate::foundation::signal_ops;
54    pub use crate::foundation::{
55        from_count, from_level, is_truthy, port_domain, port_slot, ports_of, CalcOp, CompareOp,
56        FlagPriority, HostTime, KnotId, KnotKind, NumericPath, PortDir, PortDomain, PortInfo,
57        PortSlot, Seed, Signal, SignalDomain, ThreadId, TimerMode, ONE, ZERO,
58    };
59}
60
61pub mod graph {
62    //! Weave authoring, validation, patterns, and serialization codecs.
63    //!
64    //! Author immutable [`Weave`] graphs with open string ids, validate structure
65    //! and budgets, then hand the weave to [`runtime::Runtime::bind`]. Optional
66    //! `serde-ron`, `serde-json`, and `schema` features add load/save and JSON
67    //! Schema tooling with validate-on-decode.
68
69    #[cfg(feature = "serde-json")]
70    pub use crate::authoring::{from_json, to_json, JsonCodecError};
71    #[cfg(feature = "serde-ron")]
72    pub use crate::authoring::{from_ron, to_ron, RonCodecError};
73    pub use crate::authoring::{
74        slot_of, validate, validate_report, Bool, BoolWire, Budget, BudgetWarning, BuildError,
75        ComposeError, Composer, Count, CountWire, InputPort, KnotDef, KnotHandle, Level, LevelWire,
76        NumericWireDomain, OutputPort, Pattern, PatternDef, PatternExportDef, PatternInstance,
77        PortRefDef, ThreadDef, ThresholdWires, ValidateReport, ValidationError, Weave,
78        WeaveBuilder, WeaveDef, Wire, WireDomain,
79    };
80    pub use crate::runtime_impl::{
81        EmitCommandManifest, RecipeManifest, SignalInManifest, SignalOutManifest,
82    };
83    /// JSON Schema traits and macros for recipe tooling.
84    ///
85    /// Available only with the opt-in `schema` feature, which also enables
86    /// `std` and `serde` while preserving default and no_std dependencies.
87    #[cfg(feature = "schema")]
88    pub use schemars::{schema_for, JsonSchema};
89}
90
91pub mod runtime {
92    //! Runtime binding, host integration, and output collection.
93    //!
94    //! Lifecycle: bind a validated weave, sample host senses each frame, settle
95    //! once with [`Runtime::loom`], apply [`Outbox`] effects, and optionally
96    //! snapshot or restore continuation state. The hot path uses dense handles
97    //! only — no engine types or string lookups after bind.
98
99    pub use crate::runtime_impl::{
100        append_commands, outbox_to_commands, tick_once, BindError, BindOpts, BindRestoreError,
101        CmdId, Emit, HandleError, Host, HostCommand, HostPathId, KnotHandle, NullHost, Outbox,
102        PortWriter, PresetError, Recipe, RecipeEndpoint, RecipeError, RecipeInstance,
103        RecipeResolveError, RestoreError, Runtime, RuntimePreset, RuntimePresetEntry, RuntimeState,
104        RuntimeStateEntry, RuntimeStateReport, Scenario, ScenarioError, ScriptedHost, SenseId,
105        SignalOutSample, RUNTIME_STATE_FORMAT_VERSION,
106    };
107}
108
109pub use foundation::signal_ops;
110pub use foundation::{
111    from_count, from_level, is_truthy, port_domain, port_slot, ports_of, CalcOp, CompareOp,
112    FlagPriority, HostTime, KnotId, KnotKind, NumericPath, PortDir, PortDomain, PortInfo, PortSlot,
113    Seed, Signal, SignalDomain, ThreadId, TimerMode, ONE, ZERO,
114};
115
116pub use authoring::{
117    slot_of, validate, validate_report, Bool, BoolWire, Budget, BudgetWarning, BuildError,
118    ComposeError, Composer, Count, CountWire, InputPort, KnotDef, Level, LevelWire,
119    NumericWireDomain, OutputPort, Pattern, PatternDef, PatternExportDef, PatternInstance,
120    PortRefDef, ThreadDef, ThresholdWires, ValidateReport, ValidationError, Weave, WeaveBuilder,
121    WeaveDef, Wire, WireDomain,
122};
123
124/// JSON Schema traits and macros for serializable graph and recipe types.
125/// Enable the opt-in `schema` feature before importing these exports.
126#[cfg(feature = "schema")]
127pub use schemars::{schema_for, JsonSchema};
128
129#[cfg(feature = "serde-ron")]
130pub use authoring::{from_ron, to_ron, RonCodecError};
131#[cfg(feature = "serde-ron")]
132pub use runtime_impl::{runtime_state_from_ron, runtime_state_to_ron, RuntimeStateRonCodecError};
133
134#[cfg(feature = "serde-json")]
135pub use authoring::{from_json, to_json, JsonCodecError};
136#[cfg(feature = "serde-json")]
137pub use runtime_impl::{
138    runtime_state_from_json, runtime_state_to_json, RuntimeStateJsonCodecError,
139};
140
141pub use runtime_impl::{
142    append_commands, outbox_to_commands, tick_once, BindError, BindOpts, BindRestoreError, CmdId,
143    Emit, EmitCommandManifest, HandleError, Host, HostCommand, HostPathId, NullHost, Outbox,
144    PortWriter, PresetError, Recipe, RecipeEndpoint, RecipeError, RecipeInstance, RecipeManifest,
145    RecipeResolveError, RestoreError, Runtime, RuntimePreset, RuntimePresetEntry, RuntimeState,
146    RuntimeStateEntry, RuntimeStateReport, Scenario, ScenarioError, ScriptedHost, SenseId,
147    SignalInManifest, SignalOutManifest, SignalOutSample, RUNTIME_STATE_FORMAT_VERSION,
148};
wyrd/lib.rs

wyrd/
lib.rs
