turtles


ambient

Takes:   none

Returns:   list

Returns the turtle’s ambient light values, if the turtle is acting as a light. See setambient

show ambient


animate

Takes:   milliseconds (number) OR movement (word) | frames (list)

Returns:   Animates the calling turtle, either by cycling through a series of models (frames) every x milliseconds regardless of movement, or by cycling through a series of models (frames) during each step of a fluid movement based on a particular command, such as forward. For example, animate 100 [model1 model2 model3] would cycle the turtle through the three given models every 100ms, regardless of if it is moving or not, while animate “forward [model1 model2 model3] will only animate the turtle when it moves forward and ONLY if fluid is also enabled. noanimate disables ALL animations applied to the current turtle. Specifying an empty list of frames will also turn a specific animation type off (but leave it at the last model frame animated).

animate 1000 [myrtle shelly]


arrowcolor

Takes:   none

Returns:   color

Returns the color of the arrow that indicates the turtle’s direction. See setarrowcolor, showarrow, hidearrow

show arrowcolor


arrowdistance

Takes:   none

Returns:   distance

Returns the distance of the turtle’s directional arrow from the turtle. See setarrowdistance, showarrow, hidearrow

show arrowdistance


arrowsize

Takes:   none

Returns:   size

Returns the size of the directional arrow. See setarrowsize, showarrow, hidearrow

show arrowsize


backtrack bt

Takes:   none

Returns:   none

Backtrack deletes the last entry in the current turtle’s track, that is, it undoes the last movement the current turtle made, the last turtle-specific setting that was changed (such as setpencolor) or the last object the turtle created.

backtrack


balecount

Takes:   bale (word)

Returns:   number

Returns a count of the current active members in a bale.

show balecount "bale


baleindex

Takes:   none

Returns:   number

Returns the bale ‘index number’ of the calling bale turtle. If called by a non-bale turtle returns 0. See balename, balemembers, newbale

show baleindex


balemembers

Takes:   bale (word)

Returns:   list

Returns a list of all active bale members by index eg [1 2 5 7]

show balemembers "bale


balename

Takes:   none

Returns:   name (word)

Returns the name of the bale the calling turtle belongs to.

show balename


bales

Takes:   none

Returns:   list

Returns a list of the currently defined bales. See newbale

show bales


balesync

Takes:   bale (word)

Returns:   none

Enables ‘syncing’ of the bale, that is, the bale’s graphical state is updated simultaneously once all bale members have executed an iteration of the bale’s code. This is the default state of a new bale. See nobalesync, which disables this, and balesyncp which returns true if the bale is syncing (what are you syncing?)

balesync "mybale


bounds

Takes:   none

Returns:   list

Returns the current boundaries of the turtle’s fence and wrap areas, set with setbounds. See fence, wrap, window.

show bounds


cam

Takes:   none

Returns:   none

Returns the current camera (view) turtle.

cam:forward 20


clearhatchqueue

Takes:   none

Returns:   none

Clears the calling turtle’s hatch queue. Any queued hatch requests are cleared. See hatch, hatchrate

clearhatchqueue


cloneturtle

Takes:   sourceturtle (word) | destinationturtle (word)

Returns:   none

Clones a turtle.

cloneturtle "myrtle "max


copydef

Takes:   sourceprocedure (word) | procedurecopy (word)

Returns:   none

Copies a procedure inside a turtle to a procedure with the provided name

copydef "procedure "procedurecopy


copyproc

Takes:   procedure (word) | target (word)

Returns:   none

Copies a procedure from the calling turtle to the target turtle

copyproc "procedure "turtle


depopulate

Takes:   number | bale

Returns:   none

Removes the specified number of turtles to the given bale name, based on the lowest-numbered turtles first. See populate, newbale, startbale

depopulate 10 "bale


diffuse

Takes:   none

Returns:   list

Returns a list of the diffuse light values, if the turtle is a light. See setdiffuse

show diffuse


drain

Takes:   none

Returns:   none

Empties the calling turtle’s message queue.

drain


elevationsnap

Takes:   none

Returns:   none

Causes the calling turtle to ‘snap’ to the center of the current elevation ‘sector’ determined by the terrainresolution. See noelevationsnap, setterrainresolution, elevationsnapp

elevationsnap


fluid

Takes:   none

Returns:   none

Turns on ‘fluid’ mode, which causes the turtle to move incrementally. See nofluid

fluid


fluidangle

Takes:   none

Returns:   number

Returns the fluid angle. See setfluidangle

show fluidangle


fluidinterval

Takes:   none

Returns:   number

Returns the number of milliseconds fluid waits between steps and angle movements. See setfluidinterval

show fluidinterval


fluidstep

Takes:   none

Returns:   number

Returns the fluid step value. See setfluidstep

show fluidstep


follow fo

Takes:   turtle (word)

Returns:   none

Causes the calling turtle to ‘follow’ the specified turtle. Can only be set if the turtle is the view (camera) turtle.

follow myrtle


following

Takes:   none

Returns:   turtle (word)

Returns the name of the turtle followed by the calling turtle, if any.

show following


hatch

Takes:   list

Returns:   none

Hatch creates a new turtle that contains a copy of the calling turtle’s global (variable) containers at the calling turtle’s position and orientation and then executes the requests specified in the provided list in a new thread. It is automatically given an incremental name based on the name of the turtle that called hatch. Once all the given requests have been executed the hatchling dies and its turtle track is deleted. hatchlimit and hatchrate moderate the creation of hatchlings, the first the total number that can be ‘alive’ at one time (default 100) and the second the number that can be created each second. If you wish to save its turtle track, you will need to use merge. Finally, hatch calls updatestate if norender or notrackrender is on, to ensure it is hatched in the right place. See merge

hatch [right random 360 forward 100]
make "duck 5 hatch [inc "duck show :duck] wait 20 show :duck
6
5


hatchlimit

Takes:   none

Returns:   number

Returns the current hatch limit of the calling turtle. See sethatchlimit, hatch

show hatchlimit


hatchrate

Takes:   none

Returns:   number

Returns the current hatch rate of the calling turtle. See sethatchrate, hatch

show hatchrate


hatchlingname

Takes:   workerid (number)

Returns:   turtlename (word)

Returns the name of the hatchling controlled by the given worker IF that worker was created with a hatchling.

show hatchlingname 17


hatchlings

Takes:   none

Returns:   none

Returns a list of hatchlings belonging to the selected turtle.

show myrtle:hatchlings


hatchlingworker

Takes:   turtlename (word)

Returns:   workerid (number)

Returns the id number of the worker created with the specified hatchling, if the name supplied is that of a hatchling.

show hatchlingworker "hatchling123
12


hideall

Takes:   none

Returns:   none

Hides all turtles. See showall

hideall


hideturtle ht

Takes:   none

Returns:   none

Hides the turtle’s model. Show it again with showturtle

hideturtle


libby

Takes:   none

Returns:   “libby

Libby is the library turtle. She stores procedures to be used by any other turtle. She does not execute procedures herself. The libby primitive simply returns “libby, to avoid having to put the ” on the front of her name when addressing her. See myrtle, snappy

setturtle libby


light

Takes:   none

Returns:   number

Returns the light status of the calling turtle, either 0 (not a light), 1 (spot light) or 2 (point light). See setlight

show light


listen

Takes:   none

Returns:   message (list)

Returns the message on the top of the messsage queue, which is a list containing two items: the name of the turtle that sent the message, and the message itself (which can be a number, word or list). If there are no messages in the queue, listen will block until there is a message to retrieve.

show listen


listenp

Takes:   none

Returns:   boolean

Returns true if there is a message waiting for the calling turtle. See listen, tell

show listenp


lockelevation

Takes:   none

Returns:   none

Locks the calling turtle to the elevation of the terrain at the turtle’s current xy position. See nolockelevation, elevationsnap

lockelevation


lockelevationmode

Takes:   none

Returns:   list

Returns the current value(s) used by setlockelevationmode, which determins its behavior. See setlockelevationmode

show lockelevationmode


markerwidth

Takes:   none

Returns:   turtle-units (number)

Returns the width of the current marker in turtle-units.

show markerwidth
2


mimic

Takes:   target (word)

Returns:   none

locks the calling turtle’s orientation to that of the target turtle. nomimic turns it off

mimic "snappy


mimicking

Takes:   none

Returns:   turtle (word)

Returns the name of the turtle the calling turtle is mimicking, if any.

show mimicking


models

Takes:   none

Returns:   list

Returns a list of the currently defined models.

show models
[myrtle turtle]


myrtle

Takes:   none

Returns:   “myrtle

Myrtle is the turtle you see when you start up turtleSpaces, and she is the first turtle selected. Her name simply returns “myrtle, so a quote is unneeded when you invoke setturtle myrtle. See snappy, libby

setturtle myrtle


nameturtle

Takes:   name (word)

Returns:   none

Creates a new turtle, but unlike newturtle does not switch to it on creation.

nameturtle "fred


newbale

Takes:   name (word)

Returns:   none

Creates a new ‘bale’, or group of turtles. Turtles in bales execute code in two stages: first, each turtle executes the init procedure defined inside of the bale (output can be used to pass parameters to the main procedure), and then second they execute the main procedure defined inside of the bale repeatedly until stopped or suspended. Each turtle in the bale executes consecutively, using a single worker, ensuring they remain synchronised, and reducing load on the host computer.

Bales can also contain triggers and other procedures that can be called from init or main. die causes the calling bale turtle to be removed from the bale and cease existing. The name of a bale turtle is a combination of its numerical index inside the bale, and the name of the bale itself, eg bale12. newbale is declared in the workspace similarly to newturtle. You start a bale using startbale.

Global containers are shared between bale members, and so containers specific to individual bale members need to be declared private or local (local variables only exist for the specific iteration of the bale code execution).

See startbale, stopbale, pausebale, resumebale, balename, baleindex, balemembers, populate, depopulate, balep, baleactivep, balepausedp, baleindexp

newbale "bale


newturtle newtu

Takes:   name (word)

Returns:   none

Creates a new turtle with the given name. The turtle is hidden by default, and is hidden when reset is called.

newturtle "daisy


noanimate

Takes:   none

Returns:   none

Disables the calling turtle’s animations, if any. See animate

noanimate


nobalesync

Takes:   bale (word)

Returns:   none

Disables bale syncing, which causes all graphical bale updates to happen at the end of an iteration of collective execution. See balesync

nobalesync "mybale


noelevationsnap

Takes:   none

Returns:   none

Causes the calling turtle to NOT ‘snap’ to the center of the current elevation ‘sector’ determined by the terrainresolution. See elevationsnap, setterrainresolution

noelevationsnap


nofluid

Takes:   mone

Returns:   none

Disables fluid mode on the calling turtle.

nofluid


nofollow nfo

Takes:   none

Returns:   none

Disables follow mode in the calling turtle.

nofollow


nolockelevation

Takes:   none

Returns:   none

Unlocks the calling turtle from the elevation of the terrain at the turtle’s current xy position. See lockelevation, elevationsnap

nolockelevation


pausebale

Takes:   bale (word)

Returns:   none

Pauses the execution of the specified bale. See resumebale, stopbale, startbale

pausebale "bale


popturtle popt

Takes:   none

Returns:   none

‘Pops’ a turtle state off of the stack and restores the turtle to it. See pushturtle

popturtle


populate

Takes:   number | bale or [bale param1 param2…]

Returns:   none

Adds the specified number of turtles to the given bale name. If a list is provided for the bale name, the provided parameters are passed to the init procedure within the bale by each new bale member. See depopulate, newbale, startbale

populate 10 "bale


procs

Takes:   none

Returns:   list

Returns a list of the calling turtle’s currently defined procedures.

show procs


pushturtle pusht

Takes:   none

Returns:   none

‘Pushes’ the state of the turtle on to a stack (position, pen color, etc.) popturtle pulls the state back off of the stack again. Imagine drawing a tree with randomly extending branches. You can construct it by pushing the turtle’s state at each junction, then popping the turtle to return to it, then the previous one, etc.

pushturtle


query

Takes:   turtle (word) | query (list)

Returns:   result

Allows you to query another turtle’s internal state. See in

show query "snappy [position]


release

Takes:   none

Returns:   none

Erases all turtles except for Myrtle, Snappy and Libby, and any turtles that have defined procedures.

release


renameturtle

Takes:   oldname | newname

Returns:   none

Renames a turtle.

renameturtle "fred "doug


resetturtle

Takes:   none

Returns:   none

Resets the calling turtle, which initializes it similarly to reset, but only the calling turtle.

resetturtle


resumebale

Takes:   bale (word)

Returns:   none

Resumes the bale of the given name. See suspendbale, stopbale, startbale

resumebale "bale


resumebalemember

Takes:   bale (word) | member (number)

Returns:   Resumes the execution of the specified bale member. See suspendbalemember

resumebalemember “bale 12


saveturtle

Takes:   filename

Returns:   none

Saves the calling turtle’s procedures to a file.

saveturtle


setambient

Takes:   RGBA (list)

Returns:   none

Sets the ambient light values (red, green, blue, and opacity) of the calling turtle, if the turtle is acting as a light. See ambient

setambient [50 50 50 100]


setarrowdistance

Takes:   distance (number)

Returns:   none

Sets the distance the turtle’s directional arrow is from the turtle’s position. See showarrow, hidearrow

setarrowdistance 10


setarrowsize

Takes:   size (number)

Returns:   none

Sets the size of the turtle’s directional arrow. See showarrow, hidearrow


setdiffuse

Takes:   RGBA

Returns:   none

Sets the diffuse light RGBA values of the calling turtle, if that turtle is acting as a light. See diffuse

setdiffuse [50 50 50 100]


setfluidangle

Takes:   angle (number)

Returns:   none

Sets the angular increments by which the turtle turns when fluid mode is on. See fluid

setfluidangle 5


setfluidinterval

Takes:   number

Returns:   none

Sets the number of milliseconds fluid waits between steps and angle movements. See fluidinterval

show setfluidinterval


setfluidstep

Takes:   steps (number)

Returns:   none

Sets the step increments by which the turtle moves when fluid mode is on. See fluid

setfluidstep 1


sethatchlimit

Takes:   number

Returns:   none

Sets the total number of hatchlings allowed to exist belonging to the calling turtle at any one time. Additional hatch requests are queued until existing hatchlings cease execution. The default hatchlimit is 100. See hatchlimit, clearhatchqueue.

sethatchlimit 20


sethatchrate

Takes:   number

Returns:   none

Sets the number of hatchlings that can be hatched every second. See hatchrate

sethatchrate 100


setlight

Takes:   number

Returns:   none

Sets the light status of the calling turtle to either 0 (not a light), 1 (spot light) or 2 (point light). See light

setlight 1


setlockelevationmode

Takes:   [point] OR [sphere <diameter>] OR [voxel [x1 y1 z1][x2 y2 z2]]

Returns:   none

Sets the method used by lockelevation. Point simply alters the elevation when the turtle’s position strays into a new sector. Sphere alters the position if any of the area of a sphere of the specified diameter surrounding the turtle’s position enters a new sector. Voxel does similarly with the area of the voxel offset from the turtle’s position, as such the first list values need to be negative in order to include the turtle position within that area. See lockelevationmode

setlockelevationmode [sphere 5]
setlockelevationmode [voxel [-10 -10 -10][10 10 10]]


setmodel

Takes:   modelname (word) OR [list of instructions]

Returns:   none

Sets the turtle model to the specified model name or constructs a temporary model using the given list of instructions. Note that you cannot execute a procedure inside of a setmodel list, and you should use tags and newmodel to construct a model in that way. See newmodel, setmodelscale Built-in models: myrtle, turtle, spaceship, astronaut, plane, invisible

setmodel "plane


setmodelscale

Takes:   ratio (number)

Returns:   none

Scales the turtle’s model based on the given ratio.

setmodelscale 2


setpremodel

Takes:   instructions [list]

Returns:   none

Allows you to insert directional and movement instructions between the end of the turtle track and the start of the model. Mostly used to alter the orientation of the model, for example to point the turtle upwards when orbiting a point, rather than pointing at the point, as in the startup animation, or to rotate the model without affecting its logical orientation. Note that premodel obeys modelscale, and so premodel instructions are multiplied by the modelscale value if set.

setpremodel [up 90]


setspecular

Takes:   RGBA (list)

Returns:   none

Sets the specular RGBA values of the calling turtle, if the turtle is acting as a light. See specular

setspecular [50 50 50 100]


setspeed sspd

Takes:   microseconds (mumber)

Returns:   none

Sets the number of microseconds the turtle sleeps between executing each instruction, an instruction being a fully formed statement, such as print position, or right sum 20 30. The default is 500 (half of a millisecond). Note that if you set this to a low value, or 0, you may use a large percentage of your host computer’s available CPU time, and may cause issues with your operating system’s overall performance! See speed

setspeed 200


setspotcutoff

Takes:   number

Returns:   none

Sets the spot light cutoff value of the calling turtle, if that turtle is a light. See spotcutoff

setspotcutoff 1


setspotexp

Takes:   number

Returns:   none

Sets the spot light exponent value of the calling turtle, if that turtle is a light. See spotexp

setspotexp 0


setstate

Takes:   state (list)

Returns:   none

Sets the turtle’s state. See state

setstate snappy:state


setturtle tu

Takes:   turtlename (word)

Returns:   none

Sets the turtle to execute as to the provided turtlename. Shortcut is tu

setturtle myrtle
tu snappy


showall

Takes:   none

Returns:   none

Shows all turtles. See hideall

showall


showarrow

Takes:   none

Returns:   none

Shows the directional arrow, which indicates the direction the turtle is facing. See hidearrow, setarrowsize, setarrowdistance

showarrow


showturtle st

Takes:   none

Returns:   Causes the turtle to display if hidden.

showturtle


sinceactive

Takes:   turtlename

Returns:   milliseconds

Returns the number of milliseconds since the turtle added to its track, by moving, creating an object or changing a turtle parameter such as the pen color.

print myrtle:sinceactive


snappy

Takes:   none

Returns:   “snappy

Snappy is the default ‘view’ turtle, one of the three turtles created when a space is initialized, and the first turtle from whose perspective you see when you start up turtleSpaces. While other turtles (except for Libby) can both create things and be seen out from, Snappy can only move and be used as a view turtle, and cannot create items in his ‘turtle track’ (eg create lines or shapes). See myrtle, libby

setview snappy


specular

Takes:   none

Returns:   none

Returns the specular RGBA values of the calling turtle, if that turtle is acting as a light. See setspecular

show specular


speed

Takes:   none

Returns:   microseconds (number)

Returns the current speed value, the number of microseconds the turtle ‘sleeps’ between the execution of each instruction. The default speed value is 500 microseconds, or half a millisecond. See setspeed

show speed


spotcutoff

Takes:   none

Returns:   number

Returns the spot cutoff value of the calling turtle, if that turtle is a light. See setspotcutoff

show spotcutoff


spotexp

Takes:   none

Returns:   number

Returns the spot exponent value of the calling turtle, if that turtle is a light. See setspotexp

show spotexp


state

Takes:   none

Returns:   list

Returns a list containing the entire turtle state. See setstate

show state


startbale

Takes:   bale (word) or [bale param1 param2] | initialnumber or [initialnumber workers]

Returns:   none

Starts a bale executing if not already executing and creates the given initialnumber of bale turtles, passing the optional parameters to the init procedure inside the bale if provided. If the number of balemembers is provided as a list, the second parameter in that list is the number of workers to distribute the turtles across (which can be used for performance tuning.) Note that a bale can be started with 0 members, which does not automatically cause a bale to cease operating, it just doesn’t execute any code unless it has at least one active member. It can only be fully stopped by calling stopbale. See newbale, stopbale, pausebale, resumebale

startbale "bale 20
startbale [bale param1 param2] 10


stopbale

Takes:   bale (word)

Returns:   none

Stops the bale of the given name. See startbale, pausebale, newbale

stopbale "bale


stopbalemember

Takes:   bale (word) | index (number)

Returns:   none

Stops the bale member of the given index in the given bale. Similar to as if the bale member called die. See startbale, suspendbalemember, resumebalemember

stopbalemember "bale 12


suspendbalemember

Takes:   bale (word) | member (number)

Returns:   none

Suspends the bale member, preventing it from executing. See resumebalemember

suspendbalemember "bale 12


swapcolors

Takes:   none

Returns:   none

Exchanges the current pen and fill colors and shades.

swapcolors


tandem

Takes:   target (word) or [target boolx booly boolz] (list)

Returns:   none

keeps calling turtle in the same relative position (based on the orientation) of the target turtle as when tandem was called (for example, if the target moves, or rotates). If the calling turtle changes position using FD, etc., its relative position for the purposes of tandem is updated. If tandem’s arguments are provided as a list, the tandeming turtle only updates if the target turtle moves on the specified axes. tandem does not update the orientation of the calling turtle, only its position. notandem turns it off

tandem "myrtle


tandeming

Takes:   none

Returns:   turtle (word)

Returns the name of the turtle the calling turtle is tandeming, if any. See tandem

show tandeming


target

Takes:   turtle (word)

Returns:   none

Causes the calling turtle to face the specified target turtle. A turtle may only target one turtle at a time. notarget turns it off. See notarget

target "myrtle


targeting

Takes:   none

Returns:   turtle (word)

Returns the name of the turtle the calling turtle is targeting, if any. See target

show targeting


tell

Takes:   turtle (word) or turtles (list) | message (number, word or list)

Returns:   none

Sends a message to the target turtle containing the provided number, word or list. See listen

tell snappy "hello


turtle

Takes:   none

Returns:   turtlename (word)

Returns the current turtle. See setturtle

show turtle
myrtle


turtles

Takes:   none

Returns:   turtlenames (list)

Lists the currently defined turtles.

show turtles
[myrtle libby snappy]


updatestate

Takes:   none

Returns:   none

Updates the state of the calling turtle. Only useful if the turtle’s rendering is currently disabled, either by notrackrender or norender. In a no-render state, the turtle’s position and orientation information is otherwise not updated unless updatestate is called (as these are updated by the processing of the ‘turtle track’).

updatestate


viewturtle

Takes:   none

Returns:   word

Returns the current view turtle

show viewturtle
"snappy


window

Takes:   none

Returns:   none

Sets ‘window’ mode, in which the turtle is unrestricted and can leave the area defined by bounds. See fence, wrap

window


wrap

Takes:   none

Returns:   none

Sets the turtle in wrap mode, which means if the turtle reaches the edge of the area defined by setbounds, it wraps to the opposite side of that area. See window, fence.

wrap