diff --git a/turtle-lib-macroquad/src/builders.rs b/turtle-lib-macroquad/src/builders.rs index 308c2eb..b5c8039 100644 --- a/turtle-lib-macroquad/src/builders.rs +++ b/turtle-lib-macroquad/src/builders.rs @@ -12,6 +12,25 @@ pub trait WithCommands { /// Trait for forward/backward movement pub trait DirectionalMovement: WithCommands { + /// Moves the turtle forward by the specified distance. + /// + /// The turtle moves in the direction of its current heading. + /// If the pen is down, a line is drawn. + /// + /// # Examples + /// + /// ```no_run + /// # use turtle_lib_macroquad::*; + /// # + /// #[turtle_main("Forward Example")] + /// fn draw(turtle: &mut TurtlePlan) { + /// // Move forward 100 pixels + /// turtle.forward(100.0); + /// + /// // Chain movements + /// turtle.forward(50.0).right(90.0).forward(50.0); + /// } + /// ``` fn forward(&mut self, distance: T) -> &mut Self where T: Into, @@ -21,6 +40,25 @@ pub trait DirectionalMovement: WithCommands { self } + /// Moves the turtle backward by the specified distance. + /// + /// The turtle moves opposite to its current heading without changing + /// the heading direction. If the pen is down, a line is drawn. + /// + /// # Examples + /// + /// ```no_run + /// # use turtle_lib_macroquad::*; + /// # + /// #[turtle_main("Backward Example")] + /// fn draw(turtle: &mut TurtlePlan) { + /// // Move backward 100 pixels + /// turtle.backward(100.0); + /// + /// // Draw a line forward, then retrace backward + /// turtle.forward(100.0).backward(50.0); + /// } + /// ``` fn backward(&mut self, distance: T) -> &mut Self where T: Into, @@ -33,6 +71,24 @@ pub trait DirectionalMovement: WithCommands { /// Trait for turning operations pub trait Turnable: WithCommands { + /// Turns the turtle left (counter-clockwise) by the specified angle in degrees. + /// + /// Changes the turtle's heading without moving its position. + /// Does not draw anything. + /// + /// # Examples + /// + /// ```no_run + /// # use turtle_lib_macroquad::*; + /// # + /// #[turtle_main("Left Turn Example")] + /// fn draw(turtle: &mut TurtlePlan) { + /// // Draw a square using left turns + /// for _ in 0..4 { + /// turtle.forward(100.0).left(90.0); + /// } + /// } + /// ``` fn left(&mut self, angle: T) -> &mut Self where T: Into, @@ -42,6 +98,24 @@ pub trait Turnable: WithCommands { self } + /// Turns the turtle right (clockwise) by the specified angle in degrees. + /// + /// Changes the turtle's heading without moving its position. + /// Does not draw anything. + /// + /// # Examples + /// + /// ```no_run + /// # use turtle_lib_macroquad::*; + /// # + /// #[turtle_main("Right Turn Example")] + /// fn draw(turtle: &mut TurtlePlan) { + /// // Draw a triangle using right turns + /// for _ in 0..3 { + /// turtle.forward(100.0).right(120.0); + /// } + /// } + /// ``` fn right(&mut self, angle: T) -> &mut Self where T: Into, @@ -54,6 +128,35 @@ pub trait Turnable: WithCommands { /// Trait for curved movement (circles) pub trait CurvedMovement: WithCommands { + /// Draws a circular arc turning to the left (counter-clockwise). + /// + /// The turtle draws a circular arc with the specified radius, sweeping through + /// the given angle. The circle center is positioned to the left of the turtle. + /// + /// # Parameters + /// + /// - `radius`: Distance from turtle to circle center (in pixels) + /// - `angle`: Arc sweep angle in degrees (360° = full circle) + /// - `steps`: Number of line segments to approximate the arc (more = smoother) + /// + /// # Examples + /// + /// ```no_run + /// # use turtle_lib_macroquad::*; + /// # + /// #[turtle_main("Circle Left Example")] + /// fn draw(turtle: &mut TurtlePlan) { + /// // Draw a full circle + /// turtle.circle_left(50.0, 360.0, 36); + /// + /// // Filled circle + /// turtle.pen_up().go_to(vec2(100.0, 0.0)).pen_down(); + /// turtle.set_fill_color(RED) + /// .begin_fill() + /// .circle_left(50.0, 360.0, 72) + /// .end_fill(); + /// } + /// ``` fn circle_left(&mut self, radius: R, angle: A, steps: usize) -> &mut Self where R: Into, @@ -70,6 +173,37 @@ pub trait CurvedMovement: WithCommands { self } + /// Draws a circular arc turning to the right (clockwise). + /// + /// The turtle draws a circular arc with the specified radius, sweeping through + /// the given angle. The circle center is positioned to the right of the turtle. + /// + /// # Parameters + /// + /// - `radius`: Distance from turtle to circle center (in pixels) + /// - `angle`: Arc sweep angle in degrees (360° = full circle) + /// - `steps`: Number of line segments to approximate the arc (more = smoother) + /// + /// # Examples + /// + /// ```no_run + /// # use turtle_lib_macroquad::*; + /// # + /// #[turtle_main("Circle Right Example")] + /// fn draw(turtle: &mut TurtlePlan) { + /// // Draw an S-curve using both directions + /// turtle.circle_left(50.0, 180.0, 36) + /// .circle_right(50.0, 180.0, 36); + /// + /// // Yin-yang pattern uses circle_left and circle_right + /// turtle.set_fill_color(BLACK) + /// .begin_fill() + /// .circle_right(100.0, 180.0, 36) + /// .circle_right(50.0, 180.0, 36) + /// .circle_left(50.0, 180.0, 36) + /// .end_fill(); + /// } + /// ``` fn circle_right(&mut self, radius: R, angle: A, steps: usize) -> &mut Self where R: Into, @@ -94,6 +228,35 @@ pub struct TurtlePlan { } impl TurtlePlan { + /// Creates a new empty turtle command plan. + /// + /// This has to be used when not using the `turtle_main` macro. + /// + /// # Examples + /// + /// ```no_run + /// use turtle_lib_macroquad::*; + /// use macroquad::prelude::*; + /// + /// #[macroquad::main("Manual Setup")] + /// async fn main() { + /// let mut turtle = TurtlePlan::new(); + /// turtle.forward(100.0).right(90.0).forward(100.0); + /// + /// let mut app = TurtleApp::new().with_commands(turtle.build()); + /// + /// loop { + /// clear_background(WHITE); + /// app.update(); + /// app.render(); + /// + /// if is_key_pressed(KeyCode::Escape) || is_key_pressed(KeyCode::Q) { + /// break; + /// } + /// next_frame().await; + /// } + /// } + /// ``` #[must_use] pub fn new() -> Self { Self { @@ -101,86 +264,394 @@ impl TurtlePlan { } } - #[must_use] - pub fn with_capacity(capacity: usize) -> Self { - Self { - queue: CommandQueue::with_capacity(capacity), - } - } - - /// Set animation speed - /// - Values >= 999 = instant mode (no animation) - /// - Values < 999 = animated mode with specified pixels/second + /// Sets the animation speed for turtle movements. + /// + /// Speed controls how fast the turtle moves during animations: + /// - Values `>= 1000`: Instant mode - commands execute immediately without animation. + /// The bigger the number, the more segments are drawn per frame. + /// - Values `< 1000`: Animated mode - turtle moves at specified pixels per second + /// + /// You can dynamically switch between instant and animated modes during execution. + /// + /// # Examples + /// + /// ```no_run + /// # use turtle_lib_macroquad::*; + /// # + /// #[turtle_main("Speed Example")] + /// fn draw(turtle: &mut TurtlePlan) { + /// // Slow animation at 50 pixels/second + /// turtle.set_speed(50.0) + /// .forward(100.0); + /// + /// // Switch to instant mode + /// turtle.set_speed(1000.0) + /// .forward(100.0); // Executes immediately + /// } + /// ``` pub fn set_speed(&mut self, speed: impl Into) -> &mut Self { self.queue.push(TurtleCommand::SetSpeed(speed.into())); self } + /// Sets the pen color for drawing lines. + /// + /// The pen color affects all subsequent drawing operations (forward, backward, circles) + /// until changed again. Does not affect fill color. + /// + /// # Examples + /// + /// ```no_run + /// # use turtle_lib_macroquad::*; + /// # + /// #[turtle_main("Pen Color Example")] + /// fn draw(turtle: &mut TurtlePlan) { + /// // Draw with predefined colors + /// turtle.set_pen_color(RED) + /// .forward(100.0) + /// .set_pen_color(BLUE) + /// .right(90.0) + /// .forward(100.0); + /// } + /// ``` pub fn set_pen_color(&mut self, color: Color) -> &mut Self { self.queue.push(TurtleCommand::SetColor(color)); self } + /// Sets the pen width (thickness) for drawing lines. + /// + /// The width is measured in pixels. Default is typically 2.0. + /// + /// # Examples + /// + /// ```no_run + /// # use turtle_lib_macroquad::*; + /// # + /// #[turtle_main("Pen Width Example")] + /// fn draw(turtle: &mut TurtlePlan) { + /// // Thin line + /// turtle.set_pen_width(1.0) + /// .forward(100.0); + /// + /// // Thick line + /// turtle.set_pen_width(10.0) + /// .forward(100.0); + /// } + /// ``` pub fn set_pen_width(&mut self, width: Precision) -> &mut Self { self.queue.push(TurtleCommand::SetPenWidth(width)); self } + /// Sets the turtle's absolute heading direction in degrees. + /// + /// - `0°` points to the right (east) + /// - `90°` points up (north) + /// - `180°` points left (west) + /// - `270°` points down (south) + /// + /// # Examples + /// + /// ```no_run + /// # use turtle_lib_macroquad::*; + /// # + /// #[turtle_main("Heading Example")] + /// fn draw(turtle: &mut TurtlePlan) { + /// // Point upward + /// turtle.set_heading(90.0) + /// .forward(100.0); + /// + /// // Point left + /// turtle.set_heading(180.0) + /// .forward(100.0); + /// } + /// ``` pub fn set_heading(&mut self, heading: Precision) -> &mut Self { self.queue.push(TurtleCommand::SetHeading(heading)); self } + /// Lifts the pen up so the turtle can move without drawing. + /// + /// When filling shapes, `pen_up()` also closes the current contour, + /// allowing you to create multi-contour fills (e.g., shapes with holes). + /// + /// # Examples + /// + /// ```no_run + /// # use turtle_lib_macroquad::*; + /// # + /// #[turtle_main("Pen Up/Down Example")] + /// fn draw(turtle: &mut TurtlePlan) { + /// // Move without drawing + /// turtle.pen_up() + /// .forward(100.0) // No line drawn + /// .pen_down() + /// .forward(100.0); // Line drawn + /// + /// // Create a donut shape (outer circle with inner hole) + /// turtle.set_fill_color(BLUE) + /// .begin_fill() + /// .circle_left(100.0, 360.0, 72) // Outer circle + /// .pen_up() // Close first contour + /// .go_to(vec2(0.0, -30.0)) + /// .pen_down() // Start second contour + /// .circle_left(30.0, 360.0, 36) // Inner circle (becomes hole) + /// .end_fill(); + /// } + /// ``` pub fn pen_up(&mut self) -> &mut Self { self.queue.push(TurtleCommand::PenUp); self } + /// Lowers the pen so the turtle draws when moving. + /// + /// This is the default state. When filling shapes, `pen_down()` starts + /// a new contour after `pen_up()` was called. + /// + /// # Examples + /// + /// ```no_run + /// # use turtle_lib_macroquad::*; + /// # + /// #[turtle_main("Pen Down Example")] + /// fn draw(turtle: &mut TurtlePlan) { + /// turtle.pen_up() + /// .forward(50.0) // Move without drawing + /// .pen_down() // Start drawing + /// .forward(100.0); // Line appears + /// } + /// ``` pub fn pen_down(&mut self) -> &mut Self { self.queue.push(TurtleCommand::PenDown); self } + /// Hides the turtle cursor from view. + /// + /// The turtle will still execute commands and draw, but the cursor + /// (typically an arrow or triangle) won't be visible. + /// + /// # Examples + /// + /// ```no_run + /// # use turtle_lib_macroquad::*; + /// # + /// #[turtle_main("Hide Turtle Example")] + /// fn draw(turtle: &mut TurtlePlan) { + /// turtle.hide() // Turtle cursor invisible + /// .forward(100.0) + /// .right(90.0) + /// .forward(100.0); + /// } + /// ``` pub fn hide(&mut self) -> &mut Self { self.queue.push(TurtleCommand::HideTurtle); self } + /// Shows the turtle cursor. + /// + /// Makes the turtle cursor visible if it was previously hidden. + /// This is the default state. + /// + /// # Examples + /// + /// ```no_run + /// # use turtle_lib_macroquad::*; + /// # + /// #[turtle_main("Show Turtle Example")] + /// fn draw(turtle: &mut TurtlePlan) { + /// turtle.hide() + /// .forward(100.0) + /// .show() // Turtle becomes visible again + /// .forward(100.0); + /// } + /// ``` pub fn show(&mut self) -> &mut Self { self.queue.push(TurtleCommand::ShowTurtle); self } + /// Sets the turtle's shape using a `TurtleShape` object. + /// + /// For most use cases, prefer using `shape()` which accepts a `ShapeType` enum. + /// + /// # Examples + /// + /// ``` + /// # use turtle_lib_macroquad::*; + /// # + /// #[turtle_main("Shape Example")] + /// fn draw(turtle: &mut TurtlePlan) { + /// let custom_shape = ShapeType::Arrow.to_shape(); + /// turtle.set_shape(custom_shape); + /// } + /// ``` pub fn set_shape(&mut self, shape: TurtleShape) -> &mut Self { self.queue.push(TurtleCommand::SetShape(shape)); self } + /// Sets the turtle's visual appearance. + /// + /// Available shapes: `Arrow`, `Triangle`, `Square`, `Circle`. + /// + /// # Examples + /// + /// ```no_run + /// # use turtle_lib_macroquad::*; + /// # + /// #[turtle_main("Shape Example")] + /// fn draw(turtle: &mut TurtlePlan) { + /// // Use different shapes + /// turtle.shape(ShapeType::Arrow) + /// .forward(50.0) + /// .shape(ShapeType::Circle) + /// .forward(50.0); + /// } + /// ``` pub fn shape(&mut self, shape_type: ShapeType) -> &mut Self { self.set_shape(shape_type.to_shape()) } + /// Starts recording a shape to be filled. + /// + /// All turtle movements between `begin_fill()` and `end_fill()` define + /// the shape's outline. The shape is filled using the fill color when + /// `end_fill()` is called. + /// + /// Multiple contours can be created using `pen_up()` and `pen_down()`. + /// The `EvenOdd` fill rule automatically creates holes for inner contours. + /// + /// # Examples + /// + /// ```no_run + /// # use turtle_lib_macroquad::*; + /// # + /// #[turtle_main("Fill Example")] + /// fn draw(turtle: &mut TurtlePlan) { + /// // Fill a square + /// turtle.set_fill_color(BLUE) + /// .begin_fill(); + /// for _ in 0..4 { + /// turtle.forward(100.0).right(90.0); + /// } + /// turtle.end_fill(); + /// + /// // Fill a circle + /// turtle.pen_up().go_to(vec2(150.0, 0.0)).pen_down(); + /// turtle.set_fill_color(RED) + /// .begin_fill() + /// .circle_left(50.0, 360.0, 36) + /// .end_fill(); + /// } + /// ``` pub fn begin_fill(&mut self) -> &mut Self { self.queue.push(TurtleCommand::BeginFill); self } + /// Completes the fill operation started with `begin_fill()`. + /// + /// Closes the current shape and fills it with the fill color. + /// All contours recorded since `begin_fill()` are filled together. + /// + /// # Examples + /// + /// ```no_run + /// # use turtle_lib_macroquad::*; + /// # + /// #[turtle_main("End Fill Example")] + /// fn draw(turtle: &mut TurtlePlan) { + /// // Triangle with fill + /// turtle.set_fill_color(GREEN) + /// .begin_fill(); + /// for _ in 0..3 { + /// turtle.forward(100.0).right(120.0); + /// } + /// turtle.end_fill(); + /// } + /// ``` pub fn end_fill(&mut self) -> &mut Self { self.queue.push(TurtleCommand::EndFill); self } + /// Sets the color used to fill shapes. + /// + /// This affects all shapes filled with `begin_fill()`/`end_fill()`. + /// Independent from the pen color used for outlines. + /// + /// # Examples + /// + /// ```no_run + /// # use turtle_lib_macroquad::*; + /// # + /// #[turtle_main("Fill Color Example")] + /// fn draw(turtle: &mut TurtlePlan) { + /// // Yellow fill with blue outline + /// turtle.set_fill_color(YELLOW) + /// .set_pen_color(BLUE) + /// .begin_fill() + /// .circle_left(50.0, 360.0, 36) + /// .end_fill(); + /// } + /// ``` pub fn set_fill_color(&mut self, color: impl Into) -> &mut Self { self.queue .push(TurtleCommand::SetFillColor(Some(color.into()))); self } + /// Moves the turtle to an absolute position. + /// + /// The turtle moves in a straight line to the specified coordinates. + /// If the pen is down, a line is drawn. The turtle's heading is not changed. + /// + /// Coordinates are in screen space: + /// - `(0, 0)` is at the center + /// - Positive x goes right + /// - Positive y goes down + /// + /// # Examples + /// + /// ```no_run + /// # use turtle_lib_macroquad::*; + /// # + /// #[turtle_main("Goto Example")] + /// fn draw(turtle: &mut TurtlePlan) { + /// // Draw a triangle by connecting points + /// turtle.go_to(vec2(0.0, 0.0)); + /// turtle.go_to(vec2(100.0, 0.0)); + /// turtle.go_to(vec2(50.0, 86.6)); + /// turtle.go_to(vec2(0.0, 0.0)); + /// } + /// ``` pub fn go_to(&mut self, coord: impl Into) -> &mut Self { self.queue.push(TurtleCommand::Goto(coord.into())); self } + /// Consumes the `TurtlePlan` and returns the command queue. + /// + /// Use this to finalize the turtle commands and pass them to `TurtleApp`. + /// This method consumes `self`, so the plan cannot be used afterward. + /// + /// # Examples + /// + /// ``` + /// # use turtle_lib_macroquad::*; + /// # + /// let mut turtle = TurtlePlan::new(); + /// turtle.forward(100.0).right(90.0).forward(100.0); + /// + /// // Build and get the command queue + /// let commands = turtle.build(); + /// # assert!(!commands.is_empty()); + /// ``` #[must_use] pub fn build(self) -> CommandQueue { self.queue