**TurtleScript**
**Make Art with Math**
by Morgan McGuire at [Casual Effects](https://casual-effects.com)
[Click here](ide.html) to get started!
Anyone who can add numbers and read can make art with TurtleScript. I
created it for my children to design images, patterns, and animations.
It is a great way to learn programming and geometry.
You can create TurtleScript programs from our [online editor](ide.html)
or using any text editor on your computer. They run in a web browser
and you don't need to install anything on your computer.
When done, you can e-mail your `html` file to other people to see or
host it on a web page.
To see the program for any Turtle Graphics animation made by another person, select View
Source from the web browser menus while that file is loaded. Use this to learn
from examples.
"Turtle" graphics is the name for relative vector graphics in the
plane. It was popularized by the Logo programming language graphics
features created by Seymour Papert at MIT. The names of the commands
in this package are inspired by those from the Logo programming
language...which I first learned to program on in the 1980's.
Commands
==========================================================================
The TurtleScript commands are:
`fd`(_distance_)
: Move forward the given distance.
`bk`(_distance_)
: Move backward the given distance.
`rt`(_angle_)
: Turn right (clockwise) in place.
`rt`(_angle_, _radius_)
: Turn right (clockwise) in an arc of the given radius.
`lt`(_angle_)
: Turn left (counterclockwise) in place.
`lt`(_angle_, _radius_)
: Turn left (counterclockwise) in an arc of the given radius.
`arc`(_angle_, _radius_)
: Draw an arc around the turtle, without moving the turtle. The angle
is relative to the current heading.
`pu`()
: Pick the pen up to temporarily move without drawing.
`pd`()
: Put the pen down to resume drawing.
`setColor`(_color_)
: Set the pen color by name such as `RED` or CSS color string such as `"#FF0041"`.
`setColor`(_r_, _g_, _b_)
: Set the pen color based on three RGB values each between zero and one.
`setColor`(_r_, _g_, _b_, _a_)
: Set the pen color based on three RGB values and an opacity value,
each between zero and one.
`startFill`(_color_)
: Start drawing a filled region of the given color. Must end with
`endFill()`
`startFill`(_r_, _g_, _b_)
: Start drawing a filled region with color given by three RGB values,
each between zero and one.
`setColor`(_r_, _g_, _b_, _a_)
: Start drawing a region filled by three RGB values and an opacity value,
each between zero and one.
`endFill`()
: End drawing a filled region and actually fill it. If the pen is down,
then the outline will also be stroked.
`setPosition`(_x_, _y_)
: Sets the absolute position. If the pen is down, draws a line
to that position.
`setX`(_x_)
: Sets the absolute x-axis position. If the pen is down, draws a line
to that position.
`getX`()
: Returns the absolute x-axis position.
`setY`(_x_)
: Sets the absolute y-axis position. If the pen is down, draws a line
to that position.
`getY`()
: Returns the absolute y-axis position.
`setWidth`(_width_)
: Sets the pen width.
`setHeading`(_degrees_)
: Sets the current heading in degrees measured clockwise from the
upwards vertical axis. North = 0, East = 90, South = 180, West = 270.
`getHeading`()
: Returns the current heading in degrees measured clockwise from the
upwards vertical axis. North = 0, East = 90, South = 180, West = 270.
`setScale`(_s_)
: Scales all distances (but not _x_ and _y_
coordinates or pen width) by this factor.
Useful for reusing drawing commands for different
size objects. 1.0 is the default scale.
`getScale`()
: Returns the current drawing scale.
`setSpeed`(_speed_)
: Sets the number of commands executed before showing the
next frame of animation. Defaults to 1. Can be set to
`Infinity` to draw the entire image at once. Does not
affect `wait` times.
`clear`(_color_)
: Clears the screen to the specified color
`clear`(_r_, _g_, _b_)
: Clears the screen to the specified color
`wait`(_seconds_)
: Pauses drawing for approximately this many seconds. Useful
for creating animations. Not affected by `setSpeed`.
`repeat` (_count_) { ... }
: Repeat the commands between the curly braces the specified
number of times.
You can also use any JavaScript or [codeheart.js](https://casual-effects.com/codeheart/doc.xml) code,
such as [`randomReal()`](https://casual-effects.com/codeheart/doc.xml#randomReal) or [`floor(x)`](https://casual-effects.com/codeheart/doc.xml#floor).
Legacy Commands
------------------------------------------------------
These are provided for backwards compatibility with Logo:
* `setxy` = `setPosition`
* `setheading` = `setHeading`
Colors
==========================================================================
These color names are variables that can be used with `setColor` and
`startFill`:
Examples
==========================================================================
Local Editing
==========================================================================
In addition to using my online editor, you can create and edit TurtleScript animations directly
on your computer or through other web editors.
To do this, download `starter.html` or
create a new plain-text document with a filename ending in "`.html`". For example,
`turtle.html`. The first and last lines are always the same and must be:
~~~~~~~~~~~~~~~~~~~~~~~~
<script crossorigin="anonymous" src="https://casual-effects.com/codeheart/turtle/turtle.min.js?">-*- javascript -*-</script><script type="text/turtlescript">
</script>
~~~~~~~~~~~~~~~~~~~~~~~~
In between these lines, write TurtleScript commands. For example, to draw a
square, you could make your file into:
~~~~~~~~~~~~~~~~~~~~~~~~
<script crossorigin="anonymous" src="https://casual-effects.com/codeheart/turtle/turtle.min.js?">-*- javascript -*-</script><script type="text/turtlescript">
fd(100)
rt(90)
fd(100)
rt(90)
fd(100)
rt(90)
fd(100)
rt(90)
</script>
~~~~~~~~~~~~~~~~~~~~~~~~
Load your file in a web browser to see the result. Press the reload
button on the web browser after you change and save your program when
you change it.
If you own a computer and can work from your local hard drive, then
you can use the free [Atom](https://atom.io/) or
[Sublime](https://www.sublimetext.com/) text editor. In a pinch, you
could even use Notepad on Windows. Save your files to your hard drive
and double-click to run them in a web browser.
You can also work entirely on the web. This is good if you don't own
your computer, want to be able to program from anywhere, or use a
Chromebook or tablet that doesn't provide easy access to local
storage. In this case, I recommend using the
[Zed](https://chrome.google.com/webstore/detail/zed-code-editor/pfmjnmeipppmcebplngmhfkleiinphhp?hl=en)
app for Chrome to edit your files and hosting directly on
[Github](https://github.com/) with
[Github pages](https://pages.github.com/). All of these tools are
free.