Skip to main content

sim_logic/
lib.rs

1//! A code-first application and logic layer for Sim;Engine.
2//!
3//! Sim;Logic owns the ordinary application loop around an ECS world: staged
4//! systems, bounded structural spawn/insert/remove/despawn commands, typed input, fixed-step time,
5//! application-owned resources, World replacement, application-requested exit,
6//! and extraction into Sim;Engine scenes.
7//!
8//! # Where to start
9//!
10//! Use [`prelude`] for application setup, then [`app::Application`] to register
11//! World factories and Systems. [`headless::HeadlessRunner`] advances the same
12//! runtime without a window or GPU. See the [usage guides](https://github.com/lexawhatt/Sim-Logic/tree/master/DOCUMENTATION)
13//! for a complete headless program and desktop examples.
14//!
15//! # Optional features
16//!
17//! - `desktop` (default): window hosting and the Sim;Engine GPU bridge.
18//! - `fonts`: CPU font loading, shaping and rasterization through Engine.
19//! - `headless-text`: managed CPU text preparation, including `fonts`.
20//! - `text`: retained GPU text, including `headless-text` but not window hosting.
21//! - `audio`: single-source device output through Rodio.
22//! - `easter-eggs`: the bundled Ferris image helper.
23//!
24//! Disable default features for the core headless runtime. Systems execute
25//! sequentially; only one World is active. Domain models, gameplay, layout and
26//! collision response remain application code, not renderer state.
27
28#![warn(missing_docs)]
29
30#[path = "application/app.rs"]
31pub mod app;
32#[path = "assets/mod.rs"]
33pub mod assets;
34#[cfg(feature = "audio")]
35pub mod audio;
36#[path = "logic/collision.rs"]
37pub mod collision;
38#[path = "ecs/commands.rs"]
39pub mod commands;
40#[path = "ecs/component.rs"]
41mod component;
42#[cfg(feature = "desktop")]
43#[path = "platform/desktop.rs"]
44pub mod desktop;
45#[cfg(feature = "easter-eggs")]
46#[path = "rendering/easter_eggs/mod.rs"]
47pub mod easter_eggs;
48#[path = "ecs/events.rs"]
49pub mod events;
50/// Engine's CPU-only font loading, shaping and reusable layout primitives.
51/// Enable `fonts` without default features to use these without a GPU or window.
52#[cfg(feature = "fonts")]
53pub mod fonts {
54    pub use sim_engine::{
55        FontBudget, FontBudgetResource, FontError, FontFace, LogicalPixels, PhysicalPerLogical,
56        RasterizedGlyph, ShapedGlyph, ShapedLine, ShapedLineError, TextDirection, TextLayoutBudget,
57        TextShapingSession, TextStyle,
58    };
59}
60#[path = "rendering/extraction.rs"]
61mod extraction;
62#[path = "application/headless.rs"]
63pub mod headless;
64
65#[path = "ecs/identity.rs"]
66pub mod identity;
67#[path = "application/input.rs"]
68pub mod input;
69#[path = "logic/motion.rs"]
70pub mod motion;
71#[path = "ecs/query.rs"]
72pub mod query;
73#[path = "rendering/render.rs"]
74pub mod render;
75#[path = "application/resources.rs"]
76pub mod resources;
77#[path = "rendering/screen.rs"]
78pub mod screen;
79#[path = "ecs/system.rs"]
80pub mod system;
81#[cfg(feature = "headless-text")]
82pub mod text;
83#[path = "rendering/three_d/mod.rs"]
84pub mod three_d;
85#[path = "application/time.rs"]
86pub mod time;
87#[path = "application/transition.rs"]
88pub mod transition;
89pub mod ui;
90#[path = "rendering/visual.rs"]
91pub mod visual;
92#[path = "application/window.rs"]
93pub mod window;
94#[path = "ecs/world.rs"]
95pub mod world;
96
97/// Exact ECS foundation used by Sim;Logic.
98///
99/// Re-exporting the crate lets downstream `Component` and `Resource` derive
100/// macros resolve their generated Bevy paths with only a `sim-logic`
101/// dependency.
102pub use bevy_ecs;
103// CPU configuration values required by public Logic APIs. Downstream users
104// must not need a second renderer dependency just to construct an argument.
105pub use component::{ComponentApprovalError, ComponentTuple, LifecycleHook};
106#[cfg(feature = "easter-eggs")]
107pub use easter_eggs::{CrabDrawError, draw_crab};
108#[cfg(feature = "headless-text")]
109pub use extraction::ResolvedScreenText;
110pub use extraction::{
111    ExtractedFrame, ExtractionError, ResolvedCircle, ResolvedLine, ResolvedRectangle,
112    ResolvedScreenImage, ResolvedScreenPrimitive, ResolvedScreenRectangle, ScreenDraw,
113    ScreenExtractionUpdates,
114};
115pub use sim_engine::{
116    Layer, SceneBudget, SceneBudgetResource, SceneError, Stroke, StrokeCap2d, StrokeDashPattern2d,
117    StrokeJoin2d, StrokeMarker2d, StrokeMarkerAnchor2d, StrokeStyle2d, StrokeStyleError,
118    StrokeWidthMode2d,
119};
120
121/// Convenience result for application code and fallible Systems that combine
122/// unrelated owned error types with `?`.
123///
124/// Sim;Logic operations continue to return their concrete error types, and
125/// fallible Systems may return any `Display + 'static` error without using
126/// this alias. The boxed error is not required to be `Send` or `Sync`;
127/// applications needing those bounds or a concrete error enum should define
128/// their own result type.
129pub type LogicResult<T = ()> = std::result::Result<T, Box<dyn std::error::Error>>;
130
131/// Commonly used Sim;Logic and ECS types.
132pub mod prelude {
133    pub use crate::bevy_ecs;
134    #[cfg(feature = "desktop")]
135    pub use crate::desktop::FrameCacheBudget;
136    #[cfg(all(feature = "desktop", feature = "text"))]
137    pub use crate::desktop::{DesktopTextError, DesktopTextUpdates};
138    pub use bevy_ecs::prelude::{Bundle, Component, Res, ResMut, Resource, With, Without};
139    #[cfg(feature = "desktop")]
140    pub use sim_engine::RendererPresentMode;
141    pub use sim_engine::{
142        AmbientLight3d, Camera2d, Camera2dError, Camera3d, Color, DirectionalLight3d, Fog3d,
143        Lighting3d, LogicalPixels, LogicalScreenPosition, LogicalScreenVector, LogicalViewport,
144        Mesh3dAttributes, Rotation3d, SurfaceLighting3d, SurfaceSidedness3d, SurfaceStyle3d,
145        TextureAddressMode3d, TextureUvTransform3d, Transform3d, Vec2, Vec3, WireframeStyle3d,
146        WorldLength,
147    };
148
149    pub use crate::ComponentTuple;
150    pub use crate::LogicResult;
151    #[cfg(feature = "headless-text")]
152    pub use crate::ResolvedScreenText;
153    pub use crate::app::{AppConfig, Application};
154    pub use crate::assets::{ImageAsset, ImageAssetError, ImageAssetId, ImageAssetLimits};
155    pub use crate::collision::{
156        CircleCollider2d, CircleColliderError, CircleOverlapEntities, RectangleCollider2d,
157        RectangleColliderError, RectangleOverlapEntities,
158    };
159    pub use crate::commands::{CommandEnqueueError, LogicCommands as Commands};
160    #[cfg(feature = "desktop")]
161    pub use crate::desktop::{
162        DesktopConfig, DesktopExitReason, DesktopGpuTimingSample, DesktopGpuTimings,
163        DesktopImageError, DesktopPointerError, DesktopRunError, DesktopRunReport,
164        DesktopScreenError, DesktopScreenMode, DesktopScreenUpdates, DesktopThreeDError,
165        DesktopThreeDUpdates,
166    };
167    pub use crate::events::{EventReader, EventSendError, EventWriter, WorldEvent};
168    pub use crate::headless::{
169        BeginFrameRejection, CandidateFailure, FrameFailure, FrameOutcome, FrameRequest,
170        FrameTransition, HeadlessRunner, LifecycleEvent, LifecycleRecord, LogicFrameReport,
171        RunnerBuildError, TransitionRequestFailure,
172    };
173    pub use crate::identity::{
174        LogicEntity, LogicEntityRef, TransitionIntentToken, WorldFactoryId, WorldGeneration,
175    };
176    pub use crate::input::{
177        Action, ActionEdge, ButtonState, DigitalAxis2d, DuplicateMouseBinding, FixedInput,
178        FrameInput, FrameInputEvent, InputCancellationReason, InputCollectionError, InputControl,
179        InputEvent, MouseButton, PhysicalKeyCode, PointerCapture, PointerCaptureStatus,
180        PointerSample, PointerSampleError, PointerScrollEvent, RelativePointerMotion,
181        RelativePointerMotionError, ScrollDelta, ScrollDeltaError, ScrollUnit,
182    };
183    pub use crate::motion::{
184        CameraFollowTarget2d, CameraFollowTarget2dError, DigitalMovement2d, DigitalMovement2dError,
185        LinearAcceleration2d, LinearAcceleration2dError, LinearVelocity2d, LinearVelocity2dError,
186    };
187    pub use crate::query::{Query, QueryEntityError, QuerySingleError, Single};
188    pub use crate::render::{
189        FrameLimits, FrameViewport, PresentationBudgetRejection, PresentationBudgetResource,
190        PresentationBudgetStage, PresentationFeedback, RenderLimits,
191    };
192    pub use crate::resources::{AppRes, AppResMut, ApplicationResourceError};
193    pub use crate::screen::{
194        ImageFilter, ImageRegion, ImageVisualError, ScreenCircleVisual, ScreenClip,
195        ScreenImageVisual, ScreenLineVisual, ScreenPolylineError, ScreenPolylineVisual,
196        ScreenRectangleVisual, ScreenVisualError,
197    };
198    pub use crate::system::{Stage, SystemRunFailure, SystemSetupError};
199    #[cfg(feature = "headless-text")]
200    pub use crate::text::{
201        ScreenTextVisual, TextAlignment, TextAtlasLimits, TextError, TextFont, TextLimits,
202        TextMetrics, TextPreparationSession, TextRunLimits, TextSettings,
203    };
204    pub use crate::three_d::{
205        CuboidVisual3d, CuboidVisualError, MeshAsset3d, MeshVisual3d, MeshVisualError,
206        ResolvedCuboid3d, ResolvedMesh3d, TextureAsset3d, TextureVisual3d, TextureVisualError,
207        ThreeDExtractionError, ThreeDLimitResource, ThreeDRenderLimits, ThreeDSnapshot,
208        ThreeDSurfacePolicy, View3d, View3dError,
209    };
210    pub use crate::time::{DroppedFixedTime, FixedFramePlan, FixedTime, FrameTime, TimeConfig};
211    pub use crate::transition::WorldReplacementOnPress;
212    pub use crate::ui::{
213        FocusCommand, FocusError, FocusOutcome, KeyboardFocus, PointerButton,
214        PointerButtonCancellation, PointerButtonEvent, PointerButtonOutcome,
215    };
216    pub use crate::visual::{
217        ActiveCamera2d, CircleVisual, LineVisual, RectangleVisual, Transform2d, VisualValueError,
218        WorldBackground,
219    };
220    pub use crate::window::{
221        CursorShape, FullscreenMonitor, WindowControls, WindowMode, WindowModeFailure,
222        WindowModeStatus,
223    };
224    pub use crate::world::{WorldBuildError, WorldBuilder};
225    #[cfg(feature = "easter-eggs")]
226    pub use crate::{CrabDrawError, draw_crab};
227    pub use crate::{
228        ExtractedFrame, ExtractionError, ResolvedCircle, ResolvedLine, ResolvedRectangle,
229        ResolvedScreenImage, ResolvedScreenPrimitive, ResolvedScreenRectangle, ScreenDraw,
230        ScreenExtractionUpdates,
231    };
232    pub use crate::{
233        Layer, SceneBudget, SceneBudgetResource, SceneError, Stroke, StrokeCap2d,
234        StrokeDashPattern2d, StrokeJoin2d, StrokeMarker2d, StrokeMarkerAnchor2d, StrokeStyle2d,
235        StrokeStyleError, StrokeWidthMode2d,
236    };
237}