Turtle Graphics

turtle.kbs is a module shipped with BASIC-256. It adds a turtle: an imaginary pen that you steer with instructions like go forward and turn right, rather than by working out coordinates. Drawing a square becomes four repetitions of one instruction instead of four sets of endpoints.

Pull it into a program with a single line:

include "turtle.kbs"

Every command it adds begins with tu_, so the turtle's vocabulary never collides with the language's own, with your program's, or with another module's (see why every name has a prefix). Because it is a module and not part of the language, these names only exist in programs that include the file.

Conventions

Angles are in degrees, measured clockwise from north, which is what turtle graphics has always used:


0	north / up
90	east / right
180	south / down
270	west / left

The language's own Sin and Cos take radians, but the turtle does not — if you are already holding an angle in radians, convert it with Degrees:

call tu_right(degrees(a))

The turtle starts in the middle of the graphics window, facing north, with its pen down. Nothing draws the turtle itself: it leaves a trail, it is not a cursor on screen.

Moving the turtle

Command	Effect
`call tu_forward(d)`	move d pixels along the current heading
`call tu_backward(d)`	move d pixels opposite the current heading
`call tu_goto(x, y)`	move to the point (x, y)
`call tu_home()`	move back to the middle of the graphics window
`call tu_reset()`	back to the start: centred, facing north, pen down

Each of these draws a line if the pen is down, and moves silently if it is up — except tu_reset, which never draws.

tu_backward reverses the turtle; it does not turn it round, so the heading is unchanged. tu_goto likewise carries the turtle to the new point without turning it to face that way. tu_home restores the position only, leaving the heading and the pen as they are; tu_reset is the one that puts everything back.

Turning

Command	Effect
`call tu_right(a)`	turn a degrees clockwise, without moving
`call tu_left(a)`	turn a degrees anticlockwise, without moving
`call tu_setheading(a)`	face a degrees clockwise from north

tu_right and tu_left are relative — they turn the turtle from wherever it is already pointing. tu_setheading is absolute, and ignores the previous heading entirely.

The pen

Command	Effect
`call tu_pendown()`	the turtle leaves a trail from here on
`call tu_penup()`	the turtle moves without drawing from here on

Only whether the pen draws lives in the module. What it draws with stays with the language's own statements, and they apply to the turtle's lines exactly as they do to anything else: Color sets the pen colour, PenWidth its width, and Clg clears the canvas.

Reading the turtle back

Function	Returns
`tu_x()`	the turtle's x position
`tu_y()`	the turtle's y position
`tu_getheading()`	the heading in degrees, 0 to just under 360
`tu_getpen()`	1 if the pen is down, 0 if it is up

These let a program do arithmetic against the turtle, mix turtle drawing with ordinary coordinate drawing, or put the turtle back where it found it. To drop a circle where the turtle is standing:

circle tu_x(), tu_y(), 5

They are also what makes branching figures possible: a routine that draws a branch can note the position and heading it started from, and restore them before the next branch begins.

Help

call tu_help() prints a summary of every command in the Text Output window.

Short aliases

Alias	Same as
`tu_fw(d)`	`tu_forward(d)`
`tu_bw(d)`	`tu_backward(d)`
`tu_r(a)`	`tu_right(a)`
`tu_l(a)`	`tu_left(a)`
`tu_pd()`	`tu_pendown()`
`tu_pu()`	`tu_penup()`

These are plain forwarders, so anything true of the long name is true of the short one. Note that they take those names away from your own program: a program that includes turtle.kbs cannot also use tu_r or tu_l as a variable.

Example

Twelve squares, each turned a little further round than the last:

include "turtle.kbs"

clg white
color blue

for n = 1 to 12
   for side = 1 to 4
      call tu_forward(140)
      call tu_right(90)
   next side
   call tu_right(30)
next n

draws
Turtle Graphics

The inner loop draws a square — forward and turn, four times, the turn being 360 / 4. The outer loop turns 30 degrees between squares, which is 360 / 12. No coordinate is worked out anywhere in the program.

A longer tour of the module, including a recursive tree, ships as Examples/Turtle/turtle_demo.kbs.

When the turtle is placed

The turtle is placed on the first tu_ command the program issues, not when the file is included. This matters because the starting point is the middle of the graphics window, and GraphSize is usually called after the include. Placing the turtle on first use means the two can come in either order and the turtle still starts in the middle of the canvas you actually draw on.

If you resize the graphics window after the turtle has already moved, call tu_reset() to re-centre it on the new size.

Notes

Screen y grows downward in BASIC-256, as it does for Line and every other graphics statement, so north is the direction in which y decreases. The module accounts for this; programs using the turtle do not have to.

The turtle's state is held in variables named tu_state_x, tu_state_y, tu_state_h, tu_state_pen and tu_state_ready. They are Global, so avoid those five names in a program that includes the module, and change them only through the commands above.

Availability

The bundled module library is part of the BASIC-256 v2.1 continuation project. turtle.kbs was added in BASIC-256 2.2. In 2.3.1 its commands were renamed from t_ to tu_ and tu_help was added; programs written for an earlier version need the new names.

Turtle Graphics​

Conventions​

Moving the turtle​

Turning​

The pen​

Reading the turtle back​

Help​

Short aliases​

Example​

When the turtle is placed​

Notes​

See Also​

Availability​