diff --git a/Orbital/src/game/world/change/mod.rs b/Orbital/src/game/world/change/mod.rs index d5443a23..c3f3a5a1 100644 --- a/Orbital/src/game/world/change/mod.rs +++ b/Orbital/src/game/world/change/mod.rs @@ -12,7 +12,7 @@ use crate::{ variant::Variant, }; -use super::{Identifier, ModelUlid}; +use super::Identifier; pub mod mode; pub use mode::*; @@ -20,59 +20,77 @@ pub use mode::*; pub mod camera; pub use camera::*; -/// A [WorldChange] is a _proposed change to the [World]_. +/// A [WorldChange] is a _proposed change_ to the [World]. +/// Basically, whenever we need to interact with the [World], it is through +/// a [WorldChange]. /// /// [World]: super::World pub enum WorldChange { - /// Queues an [Element] to be spawned. - /// The given [Element] must be [Boxed](Box)! + /// Spawns (== adds) an [Element] to the [World]. + /// + /// ⚠️ The given [Element] must be [Boxed](Box) as it's a `dyn Trait`! + /// + /// [World]: super::World SpawnElement(Box), - /// Queues one or many [Element(s)](Element) to be despawned. - /// Use an [Identifier] to select what to despawn! - DespawnElement(Identifier), - /// Queues a [Model] to be spawned. + /// Despawns (== removes) one or many [Element]s from the [World]. /// - /// Same as [WorldChange::SpawnModel], but without needing to supply - /// an [ElementUlid]. - /// The [ElementUlid] of the current [Element] will be used. + /// If the identifier is used by multiple [Element]s, **all** will be + /// despawned. + /// + /// [World]: super::World + DespawnElement(Identifier), + /// Spawns (== add) a [Model] into the [World]. /// /// [Model]: crate::resources::realizations::Model + /// [World]: super::World SpawnModel(ModelDescriptor), - /// Queues a [Model] to be despawned. - /// Use a [ModelUlid] to specify which is being despawned. - /// - /// TODO: Update docs + /// Despawns (== removes) a [Model] from the [World]. /// /// [Model]: crate::resources::realizations::Model + /// [World]: super::World DespawnModel(String), - /// Sends a message to one or many [Elements](Element). - /// The message must be a [HashMap]. + /// Sends a `Message` to one or many [Element]s. + /// + /// The message must be a [HashMap] and can encode most + /// information. Make sure to _"share information, not references"_! + /// + /// # Rejection + /// Will be rejected if an [Element] with the specified _Identifier_ was + /// not found. + /// SendMessage(Identifier, HashMap), - /// Spawns a [Camera] with a given [CameraDescriptor]. - /// If the chosen `identifier` of the [Camera] is already taken, this change - /// will be rejected. + /// Spawns a [Camera] into the [World]. + /// + /// # Rejection + /// Will be rejected if a [Camera]/[CameraDescriptor] with the specified + /// _Identifier_ already exists. /// /// [Camera]: crate::resources::realizations::Camera + /// [World]: super::World SpawnCamera(CameraDescriptor), - /// Similar to [Self::SpawnCamera], but also makes the new [Camera] active. + /// Does the same as [WorldChange::SpawnCamera], but also makes the new + /// [Camera] become active. /// /// [Camera]: crate::resources::realizations::Camera SpawnCameraAndMakeActive(CameraDescriptor), - /// Despawns a [Camera] given a `identifier` ([String]). + /// Despawns a [Camera] given a _Identifier_. /// - /// If a [Camera] with the given `identifier` exists, it will be removed. - /// If a [Camera] with the given `identifier` does not exist, nothing will happen. + /// # Rejection + /// If a [Camera] with the given _identifier_ does not exist, the change + /// will be rejected. /// - /// If the active [Camera] is removed, a [Default] [Camera] will be spawned - /// automatically on the next cycle. + /// # Active [Camera] removal + /// If the **active** [Camera] is removed, a [Default] [Camera] will be + /// spawned automatically on the next cycle. /// /// [Camera]: crate::resources::realizations::Camera DespawnCamera(String), /// Changes the active [Camera] to a [Camera] with the - /// given `identifier` ([String]). + /// given _identifier_. /// - /// If a [Camera] with the given `identifier` does **not** exist, - /// the active [Camera] **will not be changed**. + /// # Rejection + /// If a [Camera] with the given _identifier_ does **not** exist, + /// the change will be rejected. /// /// [Camera]: crate::resources::realizations::Camera ChangeActiveCamera(String), @@ -81,6 +99,8 @@ pub enum WorldChange { /// If a [Camera] exists with the specified [CameraDescriptor::identifier], /// any property that is set to `Some(...)` will be applied, and if the /// [Camera] is active, will trigger a [Buffer] update. + /// + /// # Rejection /// If a [Camera] does not exists with the [CameraDescriptor::identifier], /// this world change will be rejected and a warning will be printed to /// console. @@ -88,13 +108,21 @@ pub enum WorldChange { /// [Camera]: crate::resources::realizations::Camera /// [Buffer]: wgpu::Buffer UpdateCamera(CameraChange), - /// Any [AppChange]s that need to be processed need to use this variant! + /// Passes on _any_ [AppChange]s that need to be processed + /// by the [AppRuntime]. + /// + /// [AppRuntime]: crate::app::AppRuntime AppChange(AppChange), - /// Spawns a light into existence. + /// Spawns a [Light] into the [World]. + /// + /// [Light]: crate::resources::realizations::Light + /// [World]: super::World SpawnLight(LightDescriptor), - ChangeWorldEnvironment { - skybox_material: MaterialDescriptor, - }, + /// Changes the _World Environment_ for the [World]. + /// This is mainly changing the _SkyBox_ and _IBL_. + /// + /// [World]: super::World + ChangeWorldEnvironment { skybox_material: MaterialDescriptor }, /// Cleans the entire [World]. /// Meaning, that any [Element]s, and their associated resources like /// [Model]s, will be despawned and @@ -119,6 +147,12 @@ pub enum WorldChange { /// [World]: crate::game::world::World /// [Model]: crate::resources::realizations::Model CleanWorld, + /// Enqueues a [Loader] of any kind to the [World]. + /// The [World] will eventually start executing the [Loader] in the + /// background and once done, process any [WorldChange]s proposed by it. + /// + /// [World]: super::World + /// [Loader]: crate::loader::Loader EnqueueLoader(Box), }