turtle/AGENTS.md

Turtle Graphics Library - AI Agent Instructions

Project Overview

Rust workspace with turtle graphics implementations. Primary focus: turtle-lib - lightweight library using Macroquad + Lyon for GPU-accelerated rendering with multi-turtle support and optional threading.

Workspace Structure

turtlers/
├── turtle-lib/        # MAIN LIBRARY - Macroquad + Lyon (focus here)
│   └── examples/      # 30 examples including threading patterns
└── turtle-lib-macros/ # Proc macro for turtle_main

Architecture (turtle-lib)

Core Design Pattern: Turtle Entities + Persistent Animation Controllers

• Builder API (TurtlePlan) accumulates commands into immutable CommandQueue
• TurtleWorld maintains persistent Vec<Turtle> (world.turtles), each encapsulating state and a TweenController
• TweenController manages command execution, queue consumption, and animation interpolation per turtle
• Lyon Tessellation converts all primitives to GPU meshes
• Multi-Turtle support: Create multiple turtles with add_turtle() or threading channels

Key Architectural Decision: Turtle Entity Encapsulation

Each turtle in TurtleWorld is represented by a Turtle struct (state.rs) storing its own turtle_id, TurtleParams, fill state, tessellated drawing commands, SVG log, and an embedded TweenController.

• turtle_id is stored directly on Turtle (and passed to TweenController::update for logging and side effects); TweenController itself manages animation state without needing turtle identity.
• Rendering (drawing.rs) iterates through world.turtles sequentially, directly accessing each turtle's tween_controller.current_tween(), commands, and filling.

Key Files

src/
├── lib.rs              - TurtleApp, multi-turtle API, channel integration
├── builders.rs         - Fluent API traits (forward/right/circle/reset/etc)
├── commands.rs         - TurtleCommand enum (Move/Turn/Circle/Reset/etc)
├── execution.rs        - Command execution (immediate) + state updates
├── tweening.rs         - Animation + tween interpolation (TweenController per Turtle)
├── drawing.rs          - Lyon mesh rendering with Macroquad
├── state.rs            - Turtle, TurtleParams, TurtleWorld (persistent state)
├── tessellation.rs     - Lyon integration (polygons/strokes/fills/arcs)
├── circle_geometry.rs  - Arc/circle math helpers
└── commands_channel.rs - Async channels for threading patterns

Critical Concepts

1. Consolidated Move Commands:

• Move(distance) - negative = backward (no separate Backward)
• Turn(angle) - positive = right, negative = left (degrees)
• Circle{radius, angle, steps, direction} - unified left/right via CircleDirection
• Reset - clears drawings, animations, fill state; resets params to defaults

2. Fill System (Multi-Contour with Holes):

• FillState tracks Vec<Vec<Coordinate>> (multiple closed contours)
• pen_up() closes current contour, pen_down() opens new one
• Lyon's EvenOdd fill rule auto-detects holes (inner contours with opposite winding)
• Example: Donut = outer circle (pen_down) → pen_up → inner circle → end_fill

3. Animation Modes:

• Speed >= 1000: Instant mode (no tweening, executes with max(1, speed - 1000) draw calls per frame)
• Speed < 1000: Animated mode (tweens with CubicInOut easing, duration based on distance/speed)
• Dynamic switching via SetSpeed command mid-animation

4. Multi-Turtle Architecture:

• Each turtle in world.turtles owns its persistent TweenController
• Rendering directly inspects each turtle's active tween via turtle.tween_controller.current_tween() during sequential traversal of world.turtles
• Supports concurrent animation of multiple turtles
• Threading channels: create_turtle_channel(buffer_size) returns TurtleCommandSender, with the receiver managed internally by TurtleApp

5. Threading Pattern (for interactive apps like Hangman):

• create_turtle_channel(buffer_size) returns TurtleCommandSender (clonable, Send)
• Spawn game logic on thread, send CommandQueue batches via channel
• Main render loop calls app.process_commands() before update() to drain channels
• Example: hangman_threaded.rs spawns stdin reader, sends drawing commands when player guesses

Developer Workflows

Building & Testing

# Main library
cargo build --package turtle-lib
cargo test --package turtle-lib
cargo clippy --package turtle-lib -- -Wclippy::pedantic \
  -Aclippy::cast_precision_loss -Aclippy::cast_sign_loss -Aclippy::cast_possible_truncation

# Run examples
cargo run --package turtle-lib --example hello_turtle
cargo run --package turtle-lib --example yinyang
cargo run --package turtle-lib --example hangman_threaded

Code Quality Standards

• Clippy pedantic enabled (graphics math casts allowed)
• Examples must build warning-free
• Use #[must_use] on builder methods
• Builder methods return &mut Self (never owned Self) for chaining

Project-Specific Patterns

1. Single Turtle (Default)

#[turtle_main("Simple")]
fn draw(turtle: &mut TurtlePlan) {
    turtle.forward(100.0).right(90.0);
}

2. Multi-Turtle Direct Setup

let mut app = TurtleApp::new();
let t0_id = app.add_turtle();  // Default setup
let t1_id = app.add_turtle();

app.append_commands(t0_id, turtle1_plan.build());
app.append_commands(t1_id, turtle2_plan.build());

3. Threading Pattern (Hangman Example)

let mut app = TurtleApp::new();
let turtle_tx = app.create_turtle_channel(100);

// Spawn game thread
let tx = turtle_tx.clone();
std::thread::spawn(move || {
    loop {
        let letter = get_input();  // Blocks
        let mut plan = create_turtle_plan();
        plan.forward(50.0);
        tx.send(plan.build()).ok();
    }
});

// Main loop
loop {
    clear_background(WHITE);
    app.process_commands();  // ← Drains channel
    app.update();
    app.render();
    next_frame().await;
}

4. Multi-Contour Fills (Donut)

turtle.set_fill_color(BLUE)
      .begin_fill()
      .circle_left(100.0, 360.0, 72);   // Outer
      
turtle.pen_up()
      .go_to(vec2(0.0, -30.0))
      .pen_down()
      .circle_left(30.0, 360.0, 36);    // Inner (hole)

turtle.end_fill();  // EvenOdd creates hole

5. Reset Turtle

turtle.forward(100.0)
      .reset()              // Clears drawings, resets to defaults
      .forward(50.0);       // Fresh start

Common Tasks

Adding New Turtle Command

1. Add variant to TurtleCommand enum in commands.rs
2. Implement builder method in builders.rs (always return &mut Self)
3. Add execution in execution.rs (for immediate state changes) or tweening.rs (for animated state)
4. If animated, implement in calculate_target_state() in tweening.rs
5. Update drawing/tessellation if needed

Adding an Example

• Use turtle_main macro for simplicity
• Import only use turtle_lib::*; (all exports included)
• For threading: use create_turtle_channel() + process_commands()
• Place in turtle-lib/examples/ and update README examples

Debugging Animation Issues

RUST_LOG=turtle_lib=debug cargo run --example yinyang

• Check tweening.rs for state transitions
• Verify command_creates_drawing() includes your command type
• Circle direction: Left = counter-clockwise, Right = clockwise

Critical Implementation Details

TurtleCommand::Reset Behavior

• Clears Turtle::commands (all drawings)
• Clears Turtle::filling (ongoing fill operations)
• Resets TurtleParams to defaults (position 0,0, heading 0, pen down, etc.)
• Preserves turtle_id after reset
• Called via execute_command() in both instant and animated modes

Turtle Entity and State Encapsulation

• Each Turtle struct owns its turtle_id, visual params, filling state, tessellated commands, svg_log, and tween_controller
• TweenController is responsible purely for command queue management and interpolation, decoupled from turtle identity
• Rendering iterates sequentially over world.turtles, accessing each turtle's commands, active tween (turtle.tween_controller.current_tween()), and live fill preview in place

Lyon Tessellation

• All drawing → tessellate_arc/stroke/circle/multi_contour → MeshData → Macroquad Mesh
• Circle direction affects angle stepping: Left subtracts, Right adds
• Start angle for circles: geom.start_angle_from_center.to_degrees() (NOT rotation)
• EvenOdd fill rule: holes detected by contour winding (no explicit flag needed)

Dependencies & Integration

Main Dependencies

• macroquad = "0.4" - Window/rendering framework
• lyon = "1.0" - Tessellation (fills, strokes, circles)
• tween = "2.2.0" - Animation easing (CubicInOut)
• tracing = "0.1" - Optional logging (zero cost when unused)
• crossbeam = "0.8" - Threading pattern support (channels)

What NOT to Do

• Don't assume TweenController stores turtle_id or look up active tweens globally by ID (rendering iterates world.turtles and inspects turtle.tween_controller directly)
• Don't add use macroquad::prelude::* without explicit need (causes unused imports)
• Don't manually triangulate—always use Lyon tessellate_* functions
• Don't separate Forward/Backward—use negative Move values
• Don't call reset() expecting to preserve drawing state—it clears everything

Response Style

• Be concise, actionable, focused on code
• Reference specific files/lines when helpful
• Use examples from examples/ directory
• No generic advice; focus on THIS project's patterns