Turtle 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 New turtle link and modify the example in the editor to the right.

In short, all global code is evaluated once, then 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, then we 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, every call, the turtle will move forward by 100 pixels, 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 5 lines.

Below is a summary of all commands available for a Turtle.

FAQ

Can I draw lines outside the walk function?

Yes, you could choose to generate the entire drawing in global code. If you write complex turtles this can take quite some time, resulting in a canvas that will initially stay blank. To make it more responsive, it is recommended to use the walk function.

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.

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 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 turtle to an absolute position. Do not draw a line. 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 number of “degrees” for a full circle. Default value is 360 degrees.

radians()

Set the angle measurement units to radians. Equivalent to degrees(2 * Math.PI)

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.