From b40adb1685f5e4dd19b01081aea23b19a0e87f9f Mon Sep 17 00:00:00 2001 From: Mark Date: Fri, 29 Dec 2023 15:46:09 -0800 Subject: [PATCH] Documentation --- crates/content/src/engine.rs | 8 ++++++++ crates/content/src/gun.rs | 30 ++++++++++++++++++++++++++++++ crates/content/src/lib.rs | 13 +++++++++++++ crates/content/src/ship.rs | 26 ++++++++++++++++++++++++++ crates/content/src/system.rs | 21 ++++++++++++++++++++- 5 files changed, 97 insertions(+), 1 deletion(-) diff --git a/crates/content/src/engine.rs b/crates/content/src/engine.rs index 099e798..0f15d0c 100644 --- a/crates/content/src/engine.rs +++ b/crates/content/src/engine.rs @@ -17,10 +17,18 @@ pub(super) mod syntax { } } +/// Represents an (foward) engine outfit that may be attached to a ship. #[derive(Debug, Clone)] pub struct Engine { + /// The name of this outfit pub name: String, + + /// How much thrust this engine produces pub thrust: f32, + + /// The flare sprite this engine creates. + /// Its location and size is determined by a ship's + /// engine points. pub flare_sprite: String, } diff --git a/crates/content/src/gun.rs b/crates/content/src/gun.rs index 0ab382f..25c348e 100644 --- a/crates/content/src/gun.rs +++ b/crates/content/src/gun.rs @@ -27,24 +27,54 @@ pub(super) mod syntax { } } +/// Represents a gun outfit. #[derive(Debug, Clone)] pub struct Gun { + /// The name of this gun pub name: String, + + /// The projectile this gun produces pub projectile: Projectile, + + /// The accuracy of this gun. + /// Projectiles can be off center up to + /// `spread / 2` degrees in both directions. + /// + /// (Forming a "fire cone" of `spread` degrees) pub spread: Deg, + + /// Average delay between projectiles, in seconds. pub rate: f32, + + /// Random variation of projectile delay, in seconds. + /// Each shot waits (rate += rate_rng). pub rate_rng: f32, } +/// Represents a projectile that a [`Gun`] produces. #[derive(Debug, Clone)] pub struct Projectile { + /// The projectile sprite pub sprite: String, + + /// The average size of this projectile + /// (height in game units) pub size: f32, + /// Random size variation pub size_rng: f32, + + /// The speed of this projectile, in game units / second pub speed: f32, + /// Random speed variation pub speed_rng: f32, + + /// The lifespan of this projectile. + /// It will vanish if it lives this long without hitting anything. pub lifetime: f32, + /// Random lifetime variation pub lifetime_rng: f32, + + /// The damage this projectile does pub damage: f32, } diff --git a/crates/content/src/lib.rs b/crates/content/src/lib.rs index 1fcb4b1..808c181 100644 --- a/crates/content/src/lib.rs +++ b/crates/content/src/lib.rs @@ -1,3 +1,8 @@ +#![warn(missing_docs)] + +//! This subcrate is responsible for loading, parsing, validating game content, +//! which is usually stored in `./content`. + mod engine; mod gun; mod ship; @@ -39,9 +44,16 @@ trait Build { /// Represents generic game content, not connected to any game objects. #[derive(Debug)] pub struct Content { + /// Star systems pub systems: Vec, + + /// Ship bodies pub ships: Vec, + + /// Gun outfits pub guns: Vec, + + /// Engine outfits pub engines: Vec, } @@ -79,6 +91,7 @@ impl Content { return Ok(()); } + /// Load content from a directory. pub fn load_dir(path: &str) -> Result { let mut content = Self { systems: Vec::new(), diff --git a/crates/content/src/ship.rs b/crates/content/src/ship.rs index d6409d9..8b1114e 100644 --- a/crates/content/src/ship.rs +++ b/crates/content/src/ship.rs @@ -32,24 +32,50 @@ pub(super) mod syntax { // Processed data structs. // These are exported. +/// Represents a ship chassis. #[derive(Debug, Clone)] pub struct Ship { + /// This ship's name pub name: String, + + /// This ship's sprite pub sprite: String, + + /// The size of this ship. + /// Measured as unrotated height, + /// in terms of game units. pub size: f32, + + /// Engine points on this ship. + /// This is where engine flares are drawn. pub engines: Vec, + + /// Gun points on this ship. + /// A gun outfit can be mounted on each. pub guns: Vec, + + /// This ship's hull strength pub hull: f32, } +/// An engine point on a ship. +/// This is where flares are drawn. #[derive(Debug, Clone)] pub struct EnginePoint { + /// This engine point's position, in game units, + /// relative to the ship's center. pub pos: Point2, + + /// The size of the flare that should be drawn + /// at this point, measured as height in game units. pub size: f32, } +/// A gun point on a ship. #[derive(Debug, Clone)] pub struct GunPoint { + /// This gun point's position, in game units, + /// relative to the ship's center. pub pos: Point2, } diff --git a/crates/content/src/system.rs b/crates/content/src/system.rs index 5512771..c74be55 100644 --- a/crates/content/src/system.rs +++ b/crates/content/src/system.rs @@ -77,17 +77,36 @@ pub(super) mod syntax { // Processed data structs. // These are exported. +/// Represents a star system #[derive(Debug)] pub struct System { + /// This star system's name pub name: String, + + /// Objects in this system pub objects: Vec, } +/// Represents an orbiting body in a star system +/// (A star, planet, moon, satellite, etc) +/// These may be landable and may be decorative. +/// System objects to not interact with the physics engine. #[derive(Debug)] pub struct Object { + /// This object's sprite pub sprite: String, - pub position: Point3, + + /// This object's size. + /// Measured as height in game units. + /// This value is scaled for distance + /// (i.e, the z-value of position) pub size: f32, + + /// This object's position, in game coordinates, + /// relative to the system's center (0, 0). + pub position: Point3, + + /// This object's sprite's angle, in degrees. pub angle: Deg, }