Turtleyard

Write short scripts. Watch the turtle draw at once.

Turtleyard is a compact Pharo environment for turtle graphics. You write small scripts with move, turn, pen, color, repeat, and procedure commands. The turtle draws its path in a live window as the script runs. Export any drawing to a PNG file with one call.

Value

• Move and turn a turtle with readable commands.
• Lift and lower the pen without losing position.
• Set the pen to any color from a named palette.
• Set the pen width and choose a solid or dashed line.
• Repeat a block a fixed number of times.
• Define named procedures and call them by name.
• Expand L-system rules into turtle paths.
• Draw the path in a live Morphic window.
• Save any drawing to a PNG image file.

Architecture

Layer	Responsibility
TYTurtle	Tracks position, heading, pen state, and drawn segments.
TYTurtleSegment	Stores one line with its color, width, and style.
TYScriptLexer	Splits script text into tokens.
TYScriptParser	Builds a command tree from tokens.
TYScriptProgram	Runs commands, repeats, and procedures.
TYColorPalette	Maps color names to Pharo colors.
TYLSystem	Expands rules and interprets turtle symbols.
TYTurtleRenderer	Draws the path with colors, widths, and styles.
TYTurtleMorph	Shows the current path in a live window.
TYImageExporter	Renders a path to a PNG file.

The core package uses only Pharo and SUnit. Morphic and PNG support come from the Pharo image.

Setup

1. Install Pharo 13.1.
2. Open a Pharo playground.
3. Load the two packages.

CodeImporter evaluateFileNamed: 'src/Turtleyard-Core.st'.
CodeImporter evaluateFileNamed: 'tests/Turtleyard-Tests.st'.

Draw the square sample in a live window:

| turtle program |
turtle := TYTurtle new.
program := TYScriptProgram fromFile: 'examples/square.ty'.
program runLiveOn: turtle.
TYImageExporter exportTurtle: turtle to: 'output/square.png' extent: 640 @ 480.

Draw the colored spiral sample:

| turtle program |
turtle := TYTurtle new.
program := TYScriptProgram fromFile: 'examples/colors.ty'.
program runLiveOn: turtle.
TYImageExporter exportTurtle: turtle to: 'output/colors.png' extent: 640 @ 480.

Draw the Koch snowflake sample:

| turtle system |
turtle := TYTurtle new.
system := TYLSystem fromFile: 'examples/koch.tyls'.
system drawOn: turtle.
TYImageExporter exportTurtle: turtle to: 'output/koch.png' extent: 640 @ 480.

Run the whole demo from a terminal:

pharo --headless Pharo.image st scripts/run-demo.st

The exporter creates the parent directory for the output file.

Script language

Commands use one word and one number.

forward 80
right 90
pen up
pen down
color red
width 3
style dashed

• move aliases forward.
• back moves in reverse.
• left and right turn in degrees.
• pen up and pen down lift and lower the pen.
• color <name> sets the pen color.
• width <number> sets the pen width.
• style solid or style dashed sets the line style.
• # starts a comment to the end of the line.

Available colors:

black white gray grey red orange yellow green
blue purple pink brown cyan magenta

Repeat a block with square brackets:

repeat 4 [ forward 80 right 90 ]

Define a procedure with to and call it by name:

to square [ repeat 4 [ forward 80 right 90 ] ]
square

Procedure calls cannot recurse.

L-system rules

A fixture uses one line per setting:

axiom: F--F--F
iterations: 2
angle: 60
step: 4
rule F -> F+F--F+F

Symbols:

• F moves forward.
• + turns left.
• - turns right.
• [ saves the turtle state.
• ] restores the turtle state.
• Other symbols expand without drawing.

Sample output

The square fixture draws five segments. The first segment runs from 0@0 to 80@0. The demo writes output/square.png.

The colors fixture draws four squares with different pens. Each square uses a distinct color and width. The last square uses dashed lines. The demo writes output/colors.png.

The Koch fixture expands its axiom twice before drawing. The final string has 112 symbols and 48 forward moves. The demo writes output/koch.png.

Tests and CI

Run the SUnit suite with a Pharo 13 image:

pharo --headless Pharo.image st scripts/run-tests.st

The suite has 51 tests. It covers turtle path math, script parsing, L-system expansion, PNG export, and pen styles. All tests pass on Pharo 13.1.

GitHub Actions runs the same command on every push. It also runs the demo and checks the exported PNG files.

Limitations

• The language has no variables, arithmetic, or conditionals.
• The live window needs a graphical Pharo session.
• The live window does not edit scripts.
• Procedures cannot recurse.
• Dashed lines use a fixed dash pattern.

Roadmap

Complete

• Named colors, pen widths, and solid or dashed line styles.

Remaining

• Add a script editor with step controls as an independent release.
• Add variables and arithmetic as an independent release.
• Add a preset library of L-systems as an independent release.

License

MIT. See LICENSE.