TurtleLab guide

For students and teachers. TurtleLab works in Chrome, with a mouse or a touchscreen.

Your first minute

Tap a round button on the left to open a palette of blocks. Try the green turtle. Tapping a block there only shows a grey preview of what it would do, then the turtle comes back. To really draw, drag the block out.
Drag a block out onto the page. Drag a second block just under the first. You will see a ring where it will snap.
Tap any block to run its whole stack. The turtle moves and draws.
Tap a number on a block to change it, then press Enter.

To use the Run button, open the Flow palette and drag out a start block, then snap your blocks under it. Run begins at the start block. If there is no start block, Run uses the top stack on the page.

Try a sample

Not sure what to build? The samples page has programs to open, from a plain square up to a turtle that wanders by chance. Each one runs by itself, so you can watch it draw, and has a sticky note that explains it. Change the blocks and see what happens. Nothing you change is saved unless you press Save, and the blocks you saved before are never touched.

Want a path to follow? TurtleLab Lessons has five steps, from drawing your initials to a piece of art of your own, each starting from a sample.

The palettes

Palette	What is in it
Turtle	clean (wipe the paper and send the turtle home), forward, back, left, right, arc, set xy, set heading, and blocks that tell you x, y and heading
Pen	pen up and down, pen size, set color, fill screen, start and end fill, and blocks that tell you the pen size and color
Math	plus, minus, times, divide, % (the remainder), parentheses, random, one of, less than, greater than, equals, and, or, not and print
Flow	start, when paper clicked with mouseX and mouseY under it, when key pressed, every, repeat, forever, if, if with an else, wait, speed and stop. The Flow list is long, so scroll it to see the blocks at the bottom.
Boxes	four boxes you can store numbers in, as variables: a store in block and a block that gives the number back, for each box, and ask, which asks a question and puts the number you type in box1
My Blocks	the to block for making blocks of your own, and the blocks you make
Notes	a sticky note, for explaining what your program does, the write block, which writes words on the drawing, and the set font and set curve blocks that style the words

Make your own blocks

When you keep building the same thing, make it a block. Open My Blocks and drag out the to block. Tap the first box and type a name, like square. Put the blocks you want under it. That is what your block does.

Your new block shows up in My Blocks, ready to use. Drag it under a Start block, and when the program gets there, the blocks under to run.

Want it to work for different sizes? Tap the dashed input box and type a name, like size. Your block now has a place to type a number, and a size block appears in My Blocks. Plug it in wherever the number belongs, like the one in forward. A block can have two inputs.

A block can even use itself, which is how a spiral or a tree gets drawn. Give it a way to stop, like an if, or it will keep going until TurtleLab stops it for you. A stop block inside one of your blocks only leaves that block.

Change a name and every use of the block changes with it. Delete the to block and the blocks that use it will say they cannot find it. Undo brings it back.

Saving your work

TurtleLab keeps your blocks for you. If you refresh the page, they are still here when it comes back. That copy stays in this browser, on this computer, and nowhere else.

Save (the arrow button, or Ctrl+S) downloads a picture of your drawing. Your blocks are tucked inside it. It is a normal PNG, so you can put it in a document or share it like any other picture.
PDF (the button with PDF on it) downloads a PDF: your blocks, laid out the way they are on your screen, and your drawing, with a grid of x and y numbers on it and the turtle where it stopped so you can see which way it is facing. A small program has the blocks above the drawing on one page. A bigger one puts the blocks down the left side, or on page 1 with the drawing on page 2, so the writing is big enough to read. Along the top of page 1 are the four numbers from the badge (blocks, complexity, elegance and efficiency), and the last page has the reasons for each, which makes the work easier to mark. If your program has not been run since you last changed it, the PDF button runs it first (quickly, and stopping it after 5 seconds if it never ends) so the efficiency is on the page and the drawing comes from your blocks. The picture with your blocks inside is attached to it, and that picture is just the drawing, with no turtle and no grid.
Other ways to save. Right-click the Save button (or press and hold it, on a touchscreen) for a list: a JPEG, a PNG with no blocks inside, an SVG (lines that stay sharp at any size), an SVG for a cutter or plotter, files for an embroidery machine, your blocks as Python, or your blocks as a plain text file.
Open (the folder button), or dragging a saved picture or a PDF onto the page, brings your blocks back, and the drawing too. A PDF has to be one that TurtleLab saved. Undo takes you back to the blocks you had before.
New (the page with a plus) starts over with no blocks and clean paper. If you press it by mistake, Undo brings your blocks back.

On a shared computer, press New when you are finished, so the next person does not start with your blocks.

Only your blocks, and the words on any notes or write blocks you typed, are saved inside the picture. It has no name, no date and nothing about the computer you used. Read your notes before you share a picture, because anyone who opens it can read them.

Stitching it on an embroidery machine

Right-click Save and choose Embroidery: PES for a Brother machine, or Embroidery: DST for most other machines. A Brother machine can read DST too. Run your program first, so the turtle has drawn something.

The machine stitches along every line the pen drew, about 3 millimeters at a time, and follows curves closely. TurtleLab makes the design 90 millimeters across its longer side (about 3.5 inches), which fits a 4 inch hoop, and puts it in the middle. All the lines of one color are stitched together, then the machine stops so you can change the thread, so every color is one more thread to change.

The thickness of the pen is not copied. A line is always one row of stitches.
A filled shape is stitched round its edge only. Covering a whole area takes a different stitch.
Lines you draw with the pen up are not stitched. The needle hops across them.
One or two colors work best, and a few long lines work better than thousands of tiny ones. The three samples for an embroidery machine on the Samples page are a good start.
Stitch a new design on a scrap of cloth first.

See your blocks as Python

Press the Python button (the three arrows, like the prompt in Python) and a small box shows your blocks written as Python. It uses the turtle module that comes with Python, so you can press Copy, paste it into IDLE or Thonny, and run it. It is also written to work in EduBlocks (edublocks.org). The box changes as you build, so you can watch the Python appear one block at a time.

Blocks you make become def functions, your inputs become parameters, boxes become variables, the ask block becomes a small ask function that uses Python's input, a when paper clicked becomes a function on_click(x, y) that Python's turtle calls with onscreenclick (EduBlocks has no way to click, so there it does nothing), a when key pressed becomes a function such as on_key_up() that the turtle calls with onkeypress, an every becomes a function that sets up its own next time with ontimer, and notes become comments. A write block becomes a comment too, because Python's turtle has no way to draw TurtleLab's letters. The two do not match everywhere. Python's turtle counts angles from the east and turns the other way, so a few lines look different from the blocks, such as setheading(90 - 30). The Python is meant for reading and learning. Press the button again to hide the box.

Write Logo, the language the turtle was made for

The Logo button (the letters fd) opens a box with your blocks written as Logo. Unlike the Python box, you can type in this one. Change the Logo, or write a program from scratch, and press Run Logo (or Ctrl+Enter) to draw it on the same paper. Your blocks are never changed, so once you type, the blocks and the Logo no longer match. What you type is not saved, so press Copy if you want to keep it. Follow my blocks throws your changes away and shows the blocks again. Short words writes fd, rt and pu instead of forward, right and penup. Both ways work when you type. Open in real Logo opens your program in JSLogo, a real Logo kept on this same site, in a new tab, where it runs at once. TurtleLab's Logo is a little different, so the program is translated for it first (arcs become short steps, colors become color words, and anything JSLogo has no way to do is left out, with a note). It is handy for showing a class how the same program looks in real Logo.

For this	Write this
Move	forward 100 or fd 100, back (bk), left (lt), right (rt), setxy 50 -20, setheading 90 (seth), home, arc 90 50
Pen	penup (pu), pendown (pd), setpensize 5, setpencolor [255 0 0] (setpc), setpc "red, setscreencolor [0 0 80], clearscreen (cs), startfill, endfill
Repeat and decide	repeat 4 [ forward 100 right 90 ], forever [ ... ], if :size > 10 [ ... ], ifelse :n % 2 = 0 [ ... ] [ ... ], stop, wait 60
Remember a number	make "size 50, then :size. You can have four. They are the four boxes.
Blocks of your own	to square :size, then the commands, then end. Use it by writing square 100.
Numbers	+ - / %* (% is the remainder), < > =, brackets, (random 1 6), xcor ycor heading, print :size. write \|Go Cougars\| 60 writes words, ask \|How many sides?\| asks for a number and puts it in box1, onclick [ ... ] on a line of its own runs its commands each time the paper is clicked (with mousex and mousey for where), setfont "fancy picks the font for them, and setcurve 120 bends them.

Some things are a little different from other Logos. Colors run from 0 to 255. arc moves the turtle along the curve, the way the arc block does. wait counts 60ths of a second. Real Logo has more (and, or, not, lists, and blocks that give back an answer) that TurtleLab Logo does not have yet, and it says so if you try. A mistake tells you the line it is on and selects it.

Things to know

The paper is 700 wide and 560 tall. The middle is 0, 0. The turtle starts there, facing up. Turning right makes the heading go up: 90 is right, 180 is down, 270 is left.
Colors are red, green and blue, each from 0 to 255. Black is 0, 0, 0. White is 255, 255, 255. A gray has the same number three times.
Boxes hold a number, and there are four of them. Use store in box1 to put a number in, and the box1 block to use it. Every time you run a program the boxes start at 0.
Math blocks read left to right, like a sum on paper. Put one block inside another to say what is worked out first.
and, or and not (in the Math palette) put yes or no blocks together, so an if can ask two things at once. Their holes are pointed like the one in if, so only a less than, greater than, equals, and, or or not block fits. and is yes only when both are yes, or is yes when at least one is, and not turns a yes into a no. For example, a click is inside a box when mouseX is more than the left edge and less than the right edge. If the first half of an and is already no, or the first half of an or is already yes, the second half is not worked out at all, as in Python.
print shows its number in the Output box at the top right.
when paper clicked (in the Flow palette) is a block you put blocks under, like start, but Run does not start from it. Press Run, and when the program has run its last block it keeps listening: every time you click the paper, the blocks under when paper clicked run, and mouseX and mouseY (the two round blocks right under it in the Flow palette) hold where you clicked, in the same x and y that set xy uses. A small ring opens where you click, so you can see the click was heard. Sliding the paper with the mouse is not a click, and nor is a click on a block or on the gray round the paper. A program with only a when paper clicked on the page listens as soon as you press Run. Press Stop when you are done. When the PDF button runs your program for you, nobody clicks, so it just finishes.
when key pressed (in the Flow palette) is the same kind of block for the keyboard. Tap the box on it and choose a key: the four arrows, space, enter, a letter or a digit. Every time you press that key while your program is running, the blocks under it run. Hold the key down and it keeps running, like typing. Use one for each key you want to listen for. Typing in the Logo box, a sticky note or the ask box is typing, not a key press, and neither is a key held down with Ctrl or Cmd. In a frame on a page, click the paper once first, so the frame has the keyboard. Press Stop when you are done.
every (in the Flow palette) runs the blocks under it again and again, this many tenths of a second apart: 10 is one second, 2 is five times a second, and the fastest is 0.5. It starts when the last block under start has run, and goes on until you press Stop. A tick waits for the block that is running to finish, so a tick never runs on top of a click or a key press, and a slow tick is never run twice at once. Blocks take time to run at the slow speeds, so a game puts speed set to 4 (instant) near the top of start.
ask (in the Boxes palette) stops the program and asks its question in a box at the top of the page. Type a number and press Enter, and the number goes into box1. Tap the words on the block to change the question. A word that is not a number is asked about again, and Cancel, Escape or Stop ends the program. When the PDF button runs your program for you, nobody is there to answer, so it uses 0 and says so.
wait counts tenths of a second, so 10 is one second.
Stop always works, even in a forever loop.
Sticky notes are for explaining what you are doing, to yourself and to anyone who reads your program. Drag one out of the Notes palette and tap it to write. A note never changes how your program runs, and it does not snap to other blocks, so put it wherever it helps.
write (in the Notes palette) writes words on the drawing in a single line. It uses the pen's color and thickness and starts where the turtle is. Tap the words on the block to change them, up to 40 letters. size is how tall a capital letter is. The tops of the letters point the way the turtle faces, so the turtle facing up writes ordinary words, and if you turn it right 90 the words run down the page (left 90 and they run up). Watch the turtle trace each letter, lifting the pen to move between strokes, at the speed your program has (all at once at speed 4). The turtle does not end up anywhere new, and it writes even with the pen up. It is good for names and labels, and a single line is just what an embroidery machine wants. It does not turn into Python.
set font (in the Notes palette) chooses the font for every write block after it, the way set color chooses a color. Tap the font on the block to open a list of seven (script, fancy, sans, bold, serif, blocky and pixel), each shown in its own letters. Script, fancy, sans, blocky and pixel are the thinnest. Fancy, bold and serif use more lines, so they look best bigger. Blocky is wide, with square, cut off corners like a robot sign, so its words take more room. Pixel is made of square pixels like a video game, drawn as the outline of the pixels, so a thick pen or a small size fills the letters in. clean puts it back to script.
set curve (in the Notes palette) bends the words the write blocks after it write, by this many degrees over the whole word. A positive number arches like a rainbow, a negative number is a bowl like a smile, 360 goes all the way round a circle, and 0 is straight. Bent words are centered on the turtle: stand at the top of the arch, or the bottom of the bowl, and write. clean puts it back to straight. The Samples page has a badge with words curved round it, ready to stitch.

Handy moves

To do this	Do this
Delete a block	Drag it to the left side, where the trash can is, or lay it on top of the can. The whole column turns red and a shark pops out. Let go and it eats the block and the blocks under it. Now and then it burps a bubble afterward. Undo brings them back, and the shark spits them out again.
Pull a block out of a stack	Drag it. Everything under it comes too.
Copy a stack	Shift and drag it. On a touchscreen, press and hold a block, then tap Copy stack.
See what a block does	Press and hold it (or right-click it) for a tip
Keep your work	Save (Ctrl+S). Open it again, or drag the picture onto the page.
Start over	New. Undo brings your blocks back.
Undo and redo	The arrow buttons, or Ctrl+Z and Ctrl+Y (Cmd+Z on a Mac)
Zoom the blocks	The two size buttons, or hold Ctrl and scroll, or pinch with two fingers
Slide the blocks around	Drag empty space, or scroll
Move or turn the turtle	Drag its shell to move it, or its head to turn it (not while a program is running). It squirms while you hold it.
See what the pen is doing	The turtle's shell is the color of the pen. When the pen is up the turtle hovers, with a shadow and a paler shell, as if the pen were lifted off the paper. (The turtle in a PDF is always the plain green one.)
Pick a color	The color box on set color and fill screen shows the color of the block's three numbers, and its hex, like #FF8000, under the name of the block. Press it to open the color picker. Choose a color, or type one as a hex color, as numbers, or in binary: red, green and blue are each a number from 0 to 255, which is 2 hex digits or 8 bits, and the picker shows all of them at once. Change one and the others follow. The block keeps its three numbers, so you can still type them yourself, and Undo puts back the color the block had before you opened the picker. If another block is plugged into one of the numbers (a variable, say, or random) the box says N/A, because then it is not one color until the program runs.
Blocks, complexity, elegance and efficiency	The badge in the bottom right corner counts your blocks and gives three numbers from 0.0 to 1.0. Complexity is how many of the big ideas your program uses: variables count the most (store a number in a box, then use that box in another block, and a box that changes every time round a loop is worth even more), then loops (repeat and forever), conditionals (if and if else), blocks you make yourself with to, and user input: an ask block whose answer you use, and a when paper clicked with blocks under it (reading mouseX and mouseY there is worth a little more). Elegance is how neatly it is put together: blocks that are copied and pasted (the same blocks again and again, where a repeat or a block of your own would do), a number typed over and over, and blocks that never run all take it down. Efficiency is about a run, so it says run it until your program has run: drawing over the same line twice, a lot of walking with the pen up, hundreds of tiny lines where an arc would do, and a huge number of steps all take it down. Press the badge to see the reasons for each number and one thing to try next. When something you build makes complexity or elegance go up, a plus number floats up from it. The numbers only look at the blocks on the page and at the run, and they are not saved anywhere, or in a picture. The one place they go is the PDF you save yourself: the numbers are along the top of page 1 and the reasons are on the last page.
The shark's score	The shark keeps score. A sticker on the trash can goes up one for each stack of blocks you throw in and each fish or boat it eats, and down one each time the harpoon from the fishing boat hits the can. When it gets to zero the sticker comes off. Poke the can (click its body) as many times as its score, or once if it has no score, and a fish or the boat comes by. A bubble counts the pokes still to go, and the count starts again if you stop for more than a second or so. The score is not saved: it starts again each time the page opens. If your computer is set to show less motion, poking does nothing.
Turtle moods	While a wait block waits for more than a second the turtle yawns, with a Zzz floating up, and when a program finishes it waves a flipper. Stop it part way and there is no wave. Work earns treats. When you have been building and running your program for a while, the turtle might dance or blow happy bubbles, or a fish might swim all the way across the window, or a fishing boat might sail in and try to harpoon the shark. The harpoon only clangs off the can, and the shark snaps back. Click the fish or the boat and the shark swims out of the can, eats it, swims home and burps. Putting blocks in, changing a number or rearranging blocks counts, and so does running a program you have changed. Moving a stack around, deleting blocks and pressing Run again on the same blocks do not. Leave it alone for about five seconds and the color of the turtle's shell slowly gets lighter and deeper again, as if it were breathing. After about half a minute it starts to amuse itself: it might scratch its head, yawn, blow bubbles, or do what turtles do (sometimes twice), and the shark might doze off and dream of turtle soup, or be sick and bring up everything it has eaten, which lands all round the can and fades away. Change the grid or the paper and something silly happens right then: the turtle dances, yawns or blows bubbles, the shark dozes off or is sick, or a fish or a boat comes by. The bubbles and the Zzz float right off the top of the window, and the other thing falls right off the bottom. Touch anything and it stops.
See your whole drawing	The eye button hides the blocks. Press it again to bring them back.
Zoom so everything fits	The Fit button (four corners round a square). It zooms the paper until everything the turtle drew is on it, even lines that ran off the edge, and zooms and slides the blocks until all of them are in the window (a long program gets small, so you can see all of it at once). Press Fit a second time and the paper goes back to normal and your blocks go back to normal size, with the top of your code in the window, so you can read it and slide down to the rest. The house button also goes back to how it started, and pressing Run starts again from the normal view. The PDF button zooms the paper to fit the whole drawing in the PDF, and leaves your blocks as they are.
Read x and y off the paper	The grid button (a square with lines) shows a grid with numbers along the axes: the same x and y you type into set xy. It follows the zoom, and it is not in a saved picture. (A PDF always has the grid on its drawing.) Press it again and the paper changes: whiteboard, graph paper, chalkboard, blueprint, and then the blank screen comes back.
Other grids and papers	A plain press of the grid button always gives the squares with x and y numbers, going through the papers one by one. Right-click it (or press and hold it on a touch screen) for a list instead, where you can choose a different grid and a paper yourself. Under Grid you can pick squares without numbers, dots, circles and angles (the rings show how far from the middle, the number you give forward, and the numbers around the edge are headings, the ones in set heading: 0 is up and 90 is to the right). Under Paper you can pick white, a whiteboard, graph paper, a chalkboard or a blueprint. The whiteboard and the chalkboard look hand drawn: every line wobbles a little, as if someone drew it with a marker or a stick of chalk, and chalk is grainy and skips. Wipe marks and chalk dust are on the board, the turtle stays on the end of its line, and the grid wobbles with the drawing. Each time you choose one of them the wobble and the dirt are different, so no two boards look quite the same. The paper is only how your screen looks, and the grid changes its colors to show up on it. Saved pictures and PDFs always have plain white paper and straight lines, and TurtleLab does not remember your choice after you close the page.
Fill the whole screen	The full screen button (two arrows pointing apart) hides the browser's bars so your blocks and drawing fill the screen. Press it again, or press Esc, to come back. On an iPad, if that button is missing or does not work, tap Share, then Add to Home Screen, and open TurtleLab from the new icon: it opens with no bars. An iPhone cannot go full screen.
Save a different kind of file	Right-click Save, or press and hold it
Watch it draw slowly	Put a speed block (in Flow) under Start. 1 is slow, 2 is medium, 3 is fast and 4 draws it all at once. You can use it again further down to change the speed partway through.

When something goes wrong

If a block has a problem, the program stops, the block gets a red outline, and a message under the drawing says what happened. For example, an if block (or an if with an else) with nothing plugged into it will ask for a yes or no block, like a less than block.

About TurtleLab and privacy.