wde/
lib.rs

1//! WaterDropEngine - A modular game engine.
2//!
3//! # Overview
4//! WaterDropEngine is a modular game engine built on top of Bevy's ECS. It provides a collection of plugins and tools.
5//! The engine is composed of several modules, organized from low-level to high-level:
6//! - High-Level:
7//!    - [`wde_terrain`](wde_terrain): A plugin for generating and rendering procedural terrain.
8//!    - [`wde_terrain_editor`](wde_terrain_editor): A plugin for editing terrain in-game.
9//!    - [`wde_terrain_grid`](wde_terrain_grid): A plugin for managing terrain grids and LOD.
10//!    - [`wde_terrain_navigation`](wde_terrain_navigation): A plugin for pathfinding and navigation on terrain.
11//! - Render:
12//!    - [`wde_pbr`](wde_pbr): A plugin for physically based rendering (PBR) materials and lighting.
13//!    - [`wde_camera`](wde_camera): A plugin for managing cameras and viewports.
14//!    - [`wde_camera_controller`](wde_camera_controller): A plugin for controlling cameras with various input methods.
15//!    - [`wde_gltf`](wde_gltf): A plugin for loading and rendering glTF 3D models.
16//!    - [`wde_animation`](wde_animation): A plugin for animating rigid parts of models (e.g. colonist walk cycles).
17//!    - [`wde_gizmos`](wde_gizmos): A plugin for rendering debug gizmos and visualizations.
18//! - Core:
19//!    - [`wde_renderer`](wde_renderer): A plugin for rendering 3D graphics using the `wgpu` graphics API.
20//!    - [`wde_scene`](wde_scene): A plugin for managing scenes, entities, and components.
21//!    - [`wde_editor`](wde_editor): A plugin for creating in-game editors and tools.
22//! - Wrappers:
23//!    - [`wde_wgpu`](wde_wgpu): A wrapper around the `wgpu` graphics API for rendering. It is superseeded by [`wde_renderer`](wde_renderer).
24//!    - [`wde_physics`](wde_physics): A wrapper around the `rapier` physics engine for 3D physics simulation.
25//!    - [`wde_logger`](wde_logger): A wrapper around the `tracing` library for logging and diagnostics.
26//!    - [`wde_egui`](wde_egui): A wrapper around the `egui` library for creating user interfaces. It is superseeded by [`wde_editor`](wde_editor).
27//!
28//! # Getting Started
29//! To get started with WaterDropEngine, add the `wde` crate to your `Cargo.toml`:
30//! ```toml
31//! [dependencies]
32//! wde = "0.1"
33//! ```
34//! Then, in your main Rust file, you can use the default plugins to set up a basic application:
35//! ```rust
36//! app.add_plugins(WdeDefaultPlugins);
37//! ```
38//!
39//! To modify and configure individual plugins, use:
40//! ```rust
41//! app.add_plugins(WdeDefaultPlugins.set(LogPlugin {
42//!     level: LogLevel::DEBUG,
43//!     ..Default::default()
44//! }));
45//! ```
46//!
47//! # Features
48//! WaterDropEngine is designed to be modular and extensible. You can enable or disable features! using Cargo features. For example, to enable the `pbr` feature for physically based rendering, add the following to your `Cargo.toml`:
49//! ```toml
50//! [dependencies]
51//! wde = { version = "0.1", features = ["pbr"] }
52//! ```
53
54use bevy::{
55    app::{ScheduleRunnerPlugin, TaskPoolThreadAssignmentPolicy, plugin_group},
56    diagnostic::FrameCountPlugin,
57    input::InputPlugin,
58    prelude::*,
59    time::TimePlugin
60};
61
62#[cfg(all(feature = "gizmos", feature = "editor"))]
63mod debug;
64
65/// Custom Bevy plugins for WaterDropEngine default plugins.
66#[derive(Default)]
67pub struct CustomBevyPlugins;
68impl Plugin for CustomBevyPlugins {
69    fn build(&self, app: &mut App) {
70        app.add_plugins((
71            TaskPoolPlugin {
72                task_pool_options: TaskPoolOptions {
73                    min_total_threads: 1,
74                    max_total_threads: usize::MAX,
75
76                    // Use 1 core for IO
77                    io: TaskPoolThreadAssignmentPolicy {
78                        min_threads: 1,
79                        max_threads: 2,
80                        percent: 0.25,
81                        on_thread_spawn: None,
82                        on_thread_destroy: None
83                    },
84
85                    // Use 1 core for async compute
86                    async_compute: TaskPoolThreadAssignmentPolicy {
87                        min_threads: 1,
88                        max_threads: 2,
89                        percent: 0.25,
90                        on_thread_spawn: None,
91                        on_thread_destroy: None
92                    },
93
94                    // Use all remaining cores for compute (at least 1)
95                    compute: TaskPoolThreadAssignmentPolicy {
96                        min_threads: 1,
97                        max_threads: usize::MAX,
98                        percent: 1.0, // This 1.0 here means "whatever is left over"
99                        on_thread_spawn: None,
100                        on_thread_destroy: None
101                    }
102                }
103            },
104            FrameCountPlugin,
105            TimePlugin,
106            ScheduleRunnerPlugin::default(),
107            bevy::prelude::AssetPlugin {
108                mode: AssetMode::Unprocessed,
109                file_path: "res".to_string(),
110                ..Default::default()
111            },
112            InputPlugin,
113            TransformPlugin
114        ));
115    }
116}
117
118/// Custom WaterDropEngine plugins. Set it in [`WdeDefaultPlugins`] to configure the window:
119/// ```rust
120/// app.add_plugins(WdeDefaultPlugins.set(CustomWdePlugins {
121///     window_title: "My Game".into(),
122///     ..Default::default()
123/// }));
124/// ```
125pub struct CustomWdePlugins {
126    /// Title shown in the window's title bar.
127    pub window_title: String,
128    /// Initial size (width, height) of the window, in logical pixels.
129    pub window_resolution: (u32, u32),
130    /// Icon shown in the OS taskbar/title bar. See
131    /// [`WindowIcon::from_bytes`](wde_renderer::prelude::WindowIcon::from_bytes).
132    pub window_icon: Option<wde_renderer::prelude::WindowIcon>
133}
134impl Default for CustomWdePlugins {
135    fn default() -> Self {
136        let render = wde_renderer::RenderPlugin::default();
137        Self {
138            window_title: render.window_title,
139            window_resolution: render.window_resolution,
140            window_icon: render.window_icon
141        }
142    }
143}
144impl Plugin for CustomWdePlugins {
145    fn build(&self, app: &mut App) {
146        app.add_plugins((
147            wde_logger::LogPlugin::default().auto_level(),
148            wde_renderer::RenderPlugin {
149                window_title: self.window_title.clone(),
150                window_resolution: self.window_resolution,
151                window_icon: self.window_icon.clone()
152            },
153            wde_gltf::GltfPlugin,
154            wde_animation::AnimationPlugin,
155            wde_camera::CameraPlugin,
156            wde_camera_controller::CameraControllerPlugin,
157            wde_physics::PhysicsPlugin,
158            wde_terrain::TerrainPlugin,
159            wde_terrain_grid::TerrainGridPlugin,
160            wde_terrain_editor::TerrainEditorPlugin,
161            wde_terrain_navigation::TerrainNavigationPlugin,
162            wde_pbr_outline::PbrOutlinePlugin
163        ));
164
165        #[cfg(feature = "gizmos")]
166        app.add_plugins(wde_gizmos::GizmosPlugin);
167        #[cfg(feature = "pbr")]
168        app.add_plugins(wde_pbr::PbrPlugin);
169        #[cfg(feature = "editor")]
170        app.add_plugins(wde_editor::EditorPlugin);
171        #[cfg(all(feature = "gizmos", feature = "editor"))]
172        app.add_plugins(debug::PhysicsDebugPlugin);
173
174        // Always add the scene plugin last
175        app.add_plugins(wde_scene::ScenePlugin);
176    }
177}
178
179plugin_group! {
180    /// Default plugins for WaterDropEngine.
181    pub struct WdeDefaultPlugins {
182        :CustomBevyPlugins,
183        :CustomWdePlugins,
184    }
185}
186
187/// The prelude module of WaterDropEngine.
188/// Import this to get access to the most commonly used types and traits.
189#[doc(hidden)]
190pub mod prelude {
191    // Default plugins
192    pub use crate::WdeDefaultPlugins;
193
194    // Core modules
195    pub use wde_animation::prelude::*;
196    pub use wde_camera::prelude::*;
197    pub use wde_camera_controller::prelude::*;
198    pub use wde_gltf::prelude::*;
199    pub use wde_logger::prelude::*;
200    pub use wde_pbr_outline::prelude::*;
201    pub use wde_physics::prelude::*;
202    pub use wde_renderer::prelude::*;
203    pub use wde_scene::prelude::*;
204    pub use wde_terrain::prelude::*;
205    pub use wde_terrain_grid::prelude::*;
206    pub use wde_terrain_navigation::prelude::*;
207
208    // Optional feature modules
209    #[cfg(all(feature = "gizmos", feature = "editor"))]
210    pub use crate::debug::PhysicsDebugSettings;
211    #[cfg(feature = "editor")]
212    pub use wde_editor::prelude::*;
213    #[cfg(feature = "gizmos")]
214    pub use wde_gizmos::prelude::*;
215    #[cfg(feature = "pbr")]
216    pub use wde_pbr::prelude::*;
217}
218
219// Re-export the modules for external use
220pub use wde_animation;
221pub use wde_camera;
222pub use wde_camera_controller;
223pub use wde_gltf;
224pub use wde_logger;
225pub use wde_pbr_outline;
226pub use wde_physics;
227pub use wde_renderer;
228pub use wde_scene;
229pub use wde_terrain;
230pub use wde_terrain_editor;
231pub use wde_terrain_grid;
232pub use wde_terrain_navigation;
233
234#[cfg(feature = "editor")]
235pub use wde_editor;
236#[cfg(feature = "gizmos")]
237pub use wde_gizmos;
238#[cfg(feature = "pbr")]
239pub use wde_pbr;
wde/lib.rs

wde/
lib.rs
