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