Turtletoy API reference

Introduction

Turtletoy allows you to generate drawings with code inspired by Python's Turtle graphics API. Programming turtles is done with vanilla JavaScript.

Getting Started

To start a new drawing, click the Start Coding link and modify the example in the editor to the right.

In short, all global code is evaluated once, and after that, the walk function is called until it returns false.

Let's first look at the global code of the example:


const turtle = new Turtle();
turtle.penup();
turtle.goto(-50,-20);
turtle.pendown();

To draw lines, we first create a new instance of the Turtle class and then start giving it commands. In this example, the turtle is moved to position x: -50, y: -20 on the canvas. To prevent a line being drawn from its initial position x: 0, y: 0, penup() is called first. pendown() is then called to re-enable drawing lines when moving the turtle.

Next, we define what happens every time walk is called:


function walk(i) {
    turtle.forward(100);
    turtle.right(144);
    return i < 4;
}

In this example, the turtle will move forward by 100 pixels for every call, then turn right by 144 degrees.

The walk function will be called until it returns false. Argument i is zero the first time the function is called and will increase (+1) for each next call. The 5^th call, i will be 4, and i < 4 will return false. So, in this example, our drawing will be complete after five lines.

Turtle API

You can use the following methods to control a turtle:

Move and draw

forward(distance) | fd(distance): Move the turtle forward by the specified distance, in the direction the turtle is headed.
backward(distance) | bk(distance) | back(distance): Move the turtle backward by distance, opposite to the direction the turtle is headed. Do not change the turtle’s heading.
right(angle) | rt(angle): Turn turtle right by angle units. (Units are by default degrees but can be set via the degrees() and radians() functions.)
left(angle) | lt(angle): Turn turtle left by angle units. (Units are by default degrees but can be set via the degrees() and radians() functions.)
goto(x, y = undefined) | setpos(x, y = undefined) | setposition(x, y = undefined): If y is undefined, x must be a pair of coordinates [x ,y] (e.g. as returned by pos()).
Move turtle to an absolute position. If the pen is down, draw a line. Do not change the turtle’s orientation.
jump(x, y = undefined) | jmp(x, y = undefined): If y is undefined, x must be a pair of coordinates [x ,y] (e.g. as returned by pos()).
Move the turtle to an absolute position. Do not draw a line, and do not change the turtle’s orientation.
setx(x): Set the turtle’s first coordinate to x, leave second coordinate unchanged.
sety(y): Set the turtle’s second coordinate to y, leave first coordinate unchanged.
setheading(to_angle) | seth(to_angle): Set the orientation of the turtle to to_angle.
home(): Move turtle to the origin – coordinates [0 ,0] – and set its heading to its start-orientation.
circle(radius, extent = undefined, steps = undefined): Draw a circle with given radius. The center is radius units right of the turtle; extent – an angle – determines which part of the circle is drawn. If extent is not given, draw the entire circle. If extent is not a full circle, one endpoint of the arc is the current pen position. Draw the arc in clockwise direction if radius is positive, otherwise in counterclockwise direction. Finally, the direction of the turtle is changed by the amount of extent.
As the circle is approximated by an inscribed regular polygon, steps determines the number of steps to use. If not given, it will be calculated automatically.

Tell Turtle’s state

position() | pos(): Return the turtle’s current location [x ,y].
xcor() | x(): Return the turtle’s x coordinate.
ycor() | y(): Return the turtle’s y coordinate.
heading() | h(): Return the turtle’s current heading.
isdown(): Return true if pen is down, false if it’s up.

Setting and measurement

degrees(fullcircle = 360.0): Set angle measurement units, i.e. set the number of “degrees” for a full circle. The default value is 360 degrees.
radians(): Set the angle measurement units to radians. Equivalent to degrees(2 * Math.PI)
fullCircle(): Return the number of units of a full circle.
distance(x, y = undefined): Return the distance from the turtle to the point [x ,y].
towards(x, y = undefined): Return the angle between the line from the turtle to the point [x ,y] and the turtle’s heading.

Pen control

pendown() | pd() | down(): Pull the pen down – drawing when moving.
penup() | pu() | up(): Pull the pen up – no drawing when moving.

General

clone(): Creates a clone of the turtle.

Canvas

To adjust the pen opacity, use the method Canvas.setpenopacity(1). Valid values for this method range from -1 to 1. You can set this value once in the global scope at the top of your turtle.

When the pen opacity is set to a negative value, the turtle will render the drawing using a white pen on a black background, creating a negative image effect.

Adjustable Variables

Adjustable variables are specially formatted variable declarations in your Turtletoy script that can be modified via the UI. To make a variable adjustable, you add a comment directly after its declaration with specific parameters that define its adjustable nature.

Numeric Variables

For numeric variables, define the range and step:

const variableName = defaultValue; // min=<minValue> max=<maxValue> step=<stepValue> <(Option 1, Option 2, ...)> Optional descriptive text

minValue: The minimum value users can select.
maxValue: The maximum value users can select.
stepValue: The increment between values.
Named Options (Optional).
An optional text can follow stepValue to provide a description, shown on hover in the UI.

For example:

const grid = 11; // min=5, max=50, step=1

Note on Dropdowns:

When you use named options for adjustable variables, ensure that the number of names matches the number of steps calculated between the min and max values inclusive. This setup replaces the default slider with a dropdown, allowing users to choose from predefined options which can be more intuitive for specific configurations. For example:

const drawmode = 2; // min=0, max=2, step=1, (Gradient, Curl, Flow field)

The dropdown enhances the user interface by providing clear, descriptive choices, making it easier for users to understand the impact of their selections on the drawing output.

String Variables

To allow users to input text:

const guess = 'Hello world!'; // type=string, What's your guess?

Path Variables

For drawing paths that users can redefine:

const pathInput = `M57,61C-72,51 -23,-84 36,-67`; // type=path, Click here to redraw the path

Setting type=path adds a button in the UI; clicking it lets users draw a path.
The variable value will be the SVG path data of the line drawn.
The description after the comma instructs users on the UI action.

Best Practices

Descriptive Names: Use clear, descriptive names for variables.
Sensible Defaults: Choose defaults that provide a good starting point.
Appropriate Ranges and Steps: Set ranges and steps that allow meaningful adjustments.
Clear Descriptions: Provide helpful descriptions for adjustable variables, especially for complex adjustments or actions needed from users.

Adjustable variables empower creators and viewers to interactively explore the artistic possibilities of Turtletoy scripts, making the experience more engaging and customizable.

Frequently Asked Questions

Can I use AI to write my turtle?: Please see our note on AI and creative coding.
Can I draw lines outside the walk function?: Yes, you could choose to generate the entire drawing in global code. But, if you write complex turtles, this can take quite some time, resulting in a canvas that will initially stay blank. In that case, it is recommended to use the walk function to make it more responsive.
Is the canvas updated every time the walk function is called?: The canvas is updated after every 100 or so calls (~16ms), resulting in a — more or less — animated drawing of your turtle.
Why can I set the pen opacity only once?: Because we want the resulting drawing to be easy to plot with a plotter and by adding (artificial) restrictions we hope to stimulate creativity.