# movement and vectors

##### anchor

**movement and vectors**

none

list

Returns the location of the current anchor. The anchor is the ‘pivot point’ of the orbit commands and pullin / pullout.

`show anchor`

##### around

**movement and vectors**

position (list) | vector (list) | length (number) | radius (number)

turtles (list)

Returns a list of turtles within the cylinder created by the given parameters, in the direction indicated by the vector away from the position with the given length and radius. Useful for collision detection. See also inside, encroaching.

`snappy:show without turtle around position forwarddir 200 20`

`[myrtle]`

##### back bk

**movement and vectors**

turtlesteps (number)

none

Moves the current turtle back the specified number of turtle steps.

`back 20`

##### caught

**movement and vectors**

none

number

Returns a value if the calling turtle passes a fence or wrap threshold. caught returns 1 if the turtle hits / passes the X1 threshold provided to wrap / fence, 2 if X2, 3 if Y1, 4 if Y2, 5 if Z1, 6 if Z2. clearcaught resets it to 0.

`show caught`

##### clearfrag

**movement and vectors**

none

none

Clears the current list of frag points. See frag

`clearfrag`

##### direction

**movement and vectors**

position (list)

vectors (list)

Returns a list of vectors that would point the calling turtle at the supplied list of co-ordinates.

`show direction myrtle:position snappy:position`

`[[0 1 0] [0 0 1] [1 0 0]]`

`snappy:setvectors direction myrtle:position`

##### distance

**movement and vectors**

position (list) | position (list)

distance (number)

Returns the distance from the first given set of co-ordinates to the second given set of co-ordinates.

`show distance myrtle:position snappy:position`

`show distance [0 0 0] [100 100 100]`

##### divergence

**movement and vectors**

[vector1 vector2] (list) | [vector3 vector4] (list)

degrees (number)

Divergence returns the degrees of difference (divergence) between vector1 and vector3 in a clockwise direction, that direction established using vector2 and vector4, which need to be the axis you would be pivoting on to measure that difference. So if you’re measuring the degrees of difference between two forward vectors in terms of left and right, the second vector needs to be the up vector. If you were measuring the difference in terms of up and down, you would give the right vector. Divergence is extremely useful for ball games.

`show divergence {item 1 myrtle:vectors item 3 myrtle:vectors} {item 1 snappy:vectors item 3 myrtle:vectors}`

`90`

##### down dn

**movement and vectors**

degrees (number)

none

Tilts the calling turtle’s nose down by the given number of degrees. See up

`down 45`

##### drift

**movement and vectors**

steps vector

Causes the selected turtle to ‘drift’ the specified number of steps in the direction specified by vector. You can use drift to simulate momentum or gravity, particularly in concert with workers. See forwarddir

drift 10 forwarddir

`forward 10 make "forward forwarddir newworker [repeat 5 [drift 1 :forward]]`

##### dropanchor

**movement and vectors**

none

none

Sets the selected turtle’s orbit anchor point to its current position. See setanchor

`repeat 10 [penup forward 60 dropanchor pullout 50 pendown repeat 36 [orbitleft 10]]`

##### encroaching

**movement and vectors**

position (list) | vectors (list) | [left right forward backward above below] (list)

turtles (list)

Returns a list of turtles encroaching within the ‘box’ specified by the third list input. This is a more sophisticated version of inside, which allows for a box of any orientation, based on the provided vectors. See around, inside

`show encroaching position vectors [10 10 10 10 10]`

##### extrapolate

**movement and vectors**

position (list) | vector (list) | distance (number)

list

Returns a list of target co-ordinates based on the starting position, a vector and the distance in turtle-units along that vector.

`show extrapolate position forwarddir 5`

##### facingp

**movement and vectors**

booleans

co-ordinates (list) | degrees (number)

boolean

`returns true if a vector from the calling turtle to the supplied co-ordinates diverges less than the supplied number of degrees from the calling turtle's forward vector. See divergence`

`reset`

`snappy:show facingp myrtle:position 10`

`true`

`myrtle:show facingp snappy:position 10`

`false`

##### fence

**movement and vectors**

none

none

Causes the calling turtle to halt if it reaches the screen boundaries set by setbounds. See setbounds, bounds, window, wrap, caught

`fence`

##### fixate fix

**movement and vectors**

position

none

Both sets the anchor point and points the selected turtle at it. Compare with setanchor, which does not change the orientation of the selected turtle.

`snappy:fixate myrtle:position`

`fixate [0 0 0]`

`points Snappy (the camera turtle) at Myrtle.`

##### forward fd

**movement and vectors**

turtle-spaces (number)

none

Moves the turtle forward the given number of turtle steps. Draws a line if the pen is down. See pendown, back

`forward 20`

##### forwarddir

**movement and vectors**

none

vector (list)

Returns the calling turtle’s forward vector.

`show forwarddir`

##### heading hd

**movement and vectors**

none

degrees

Returns the heading (x-axis) of the selected turtle in degrees. Heading is an accumulated, relative value that cannot be used in isolation to accurately reproduce an orientation when the turtle moves in three dimensions – for that, use orientation / setorientation. See pitch and roll

`print heading`

##### home

**movement and vectors**

none

none

Returns the currently selected turtle to the home position.

`home`

##### inside

**movement and vectors**

[[x1 y1 z1] [x2 y2 z2]]

list

Returns a list of turtles inside the area denoted by the provided sets of co-ordinates.

`show inside [[-100 -100 -100] [100 100 100]`

`[myrtle]`

##### jump

**movement and vectors**

steps (number)

none

Moves the turtle forward the given number of turtle steps without drawing, regardless of the pen state.

`jump 20`

##### left lt

**movement and vectors**

degrees

none

Turns the selected turtle to the left the specified number of degrees. See right

`left 90`

`lt 45`

##### leftarc larc

**movement and vectors**

degrees | radius

none

Creates an arc forward and to the left from the turtle’s position, placing the turtle at its end. See rightarc

`leftarc 90 40`

##### location

**movement and vectors**

co-ordinates (list)

list

Returns a list of isRight, isAbove, isAhead where a value of 1 indicates the target co-ordinates are in those areas relative to the turtle’s forward view, 0 indicates that the co-ordinates are on the same plane as the calling turtle as appropriate, and -1 indicates the co-ordinates are in the opposite region (eg a -1 for isRight indicates it is to the left of the turtle’s forward vector / view).

`snappy:show location myrtle:position`

`[0 0 1]`

`myrtle:show location snappy:position`

`[0 1 0]`

##### lower lo

**movement and vectors**

turtle-units

none

‘Lowers’ the turtle (moves back along its up vector). Same as doing ‘down 90 forward turtle-units up 90’. For example, Myrtle in her home position when turtleSpaces is started will move away from the Snappy camera turtle if you lower her. See raise

`lower 100`

##### modelhome

**movement and vectors**

none

none

modelhome sets the turtle to the position and vectors set by setmodelorigin. These two primitives are only useful inside of model definitions, they are relative to the position and vectors of the turtle prior to the drawing of the model (its absolute vectors and position). See setmodelorigin, newmodel

`modelhome`

`### `

`modelp`

`environment`

`word`

`boolean`

`Returns true if there is a model with the name of the provided word.`

`show modelp "turtle`

`true`

##### move

**movement and vectors**

vector (list) | distance (number)

none

Moves the turtle the specified distance in turtle units in the direction of the given vector, allowing for arbitrary movement. If the pen is down, the turtle draws a line.

`move forwarddir 20`

##### near

**movement and vectors**

position (list) | radius (number)

list

Returns a list of all the turtles within the specified radius of turtle-units from the specified position. See nearme

`show near [0 0 0] 10`

##### nearme

**movement and vectors**

distance (number)

turtles (list)

Returns a list of turtles within the specified distance of the calling turtle, except the calling turtle itself. See near, nearp

`show nearme 200`

##### nostealth

**movement and vectors**

none

none

Causes calling turtle to appear in lists generated by near. See stealth

`nostealth`

##### notether

**movement and vectors**

none

none

Untethers the selected turtle from the orbit anchor point. When the turtle is untethered, the anchor point moves relative to it.

`notether`

##### orbitdistance

**movement and vectors**

none

turtle-units (number)

Returns the distance between a turtle and its anchor point. See setanchor, dropanchor

`show orbitdistance`

##### orbitdown odn

**movement and vectors**

degrees (number)

none

Orbits down from (beneath) the turtle around its anchor point the specified number of degrees. Note that the turtle goes to its destination directly regardless of the status of fluid, and if the pen is down a line will be drawn between the start and destination with no intermediary points. See setanchor, dropanchor

`orbitdown 90`

##### orbitleft olt

**movement and vectors**

degrees (number)

none

Orbits the turtle left around its anchor point the specified number of degrees. Note that the turtle goes to its destination directly regardless of the status of fluid, and if the pen is down a line will be drawn between the start and destination with no intermediary points. See setanchor, dropanchor

`orbitleft 90`

##### orbitright ort

**movement and vectors**

degrees (number)

none

Orbits the turtle right around its anchor point the specified number of degrees. Note that the turtle goes to its destination directly regardless of the status of fluid, and if the pen is down a line will be drawn between the start and destination with no intermediary points. See setanchor, dropanchor

##### orbitup oup

**movement and vectors**

degrees (number)

none

Orbits up from (above) the turtle around its anchor point the specified number of degrees. Note that the turtle goes to its destination directly regardless of the status of fluid, and if the pen is down a line will be drawn between the start and destination with no intermediary points. See setanchor, dropanchor

`orbitup 90`

##### orbitvector

**movement and vectors**

vector (list) | degrees (number)

none

Orbits the specified number of degrees around the turtle’s anchor point using the specified vector. To orbit in the opposite direction, specify a negative number of degrees. Note that the turtle goes to its destination directly regardless of the status of fluid, and if the pen is down a line will be drawn between the start and destination with no intermediary points. See setanchor, dropanchor

`orbitvector updir 10`

##### orientation

**movement and vectors**

none

list

Returns the current orientation, in the order specified by orientationorder. So if orientation order is set to “phr, then the first value returned by orientation will be pitch, the second heading and the third roll. See orientationorder

`show orientation`

##### orientationorder

**movement and vectors**

none

word

Returns the current order heading, pitch and roll are processed when setorientation, setheading, setpitch or setroll is used.

`show orientationorder`

`"hpr`

##### origin

**movement and vectors**

none

list

Returns the current origin co-ordinates. See setorigin, home

`show origin`

`[0 0 0]`

##### originvectors

**movement and vectors**

none

list

Returns the current origin vectors. See setoriginvectors, origin, home

`show originvectors`

##### pitch pt

**movement and vectors**

none

pitch (number)

Returns the pitch (attitude) of the current turtle

`print pitch`

##### pos

**movement and vectors**

none

[x y] (list)

Returns the x and y co-ordinates of the turtle. For all three dimensions, use position

`show pos`

##### position

**movement and vectors**

none

[x y z] (list)

Returns the co-ordinates of the turtle. For just the first two dimensions, use pos

`show position`

##### pullin pui

**movement and vectors**

turtle-spaces (number)

none

Pulls the calling turtle toward its anchor point the specified number of turtle-spaces. Stops if it reaches its anchor point.

`pullin 40`

##### pullout puo

**movement and vectors**

turtle-spaces (number)

none

Pulls the calling turtle out away from its anchor point the specified number of turtle-spaces.

`dropanchor repeat 20 [penup pullout 10 pendown repeat 36 [orbitleft 10]]`

##### raise ra

**movement and vectors**

turtle-units (number)

none

Raises (elevates) the currently selected turtle by the specified number of turtle-units. Draws a line if the pen is down. See lower

`raise 20`

##### randomvectors [randvec]

**movement and vectors**

none

none

Orients the currently selected turtle randomly in three dimensions. This does NOT alter the current pitch, heading or roll values.

`pendown repeat 10 [randomvectors fd 100 home]`

##### right rt

**movement and vectors**

degrees

none

Turns the selected turtle the specified number of degrees to the right. If the specified number of degrees is negative, turns it to the left. See left

`right 90`

##### rightarc rarc

**movement and vectors**

degrees | radius

none

Creates an arc forward and to the right from the turtle’s position, placing the turtle at its end. See leftarc

`rightarc 90 40`

##### rightdir

**movement and vectors**

none

vector

Returns the right vector of the selected turtle.

`show rightdir`

##### roll ro

**movement and vectors**

none

number

Returns the current roll value. See setroll

`show roll`

##### rollleft rl

**movement and vectors**

degrees (number)

none

Rolls the currently selected turtle to the left by the provided number of degrees.

`rollleft 90`

##### rollright rr

**movement and vectors**

degrees (number)

none

Rolls the currently selected turtle to the right by the provided number of degrees.

`rollright 45`

##### setanchor

**movement and vectors**

position

none

Sets the selected turtle’s orbit anchor to the specified three-dimensional position. Compare with fixate.

`setanchor [0 0 0]`

##### setbounds sbds

**movement and vectors**

x1 y1 x2 y2 (list) OR [[x1 y1 z1][x2 y2 z2]] (list of lists)

none

Sets the boundary used by wrap and fence

`setbounds [-100 -100 100 100]`

`setbounds [[-100 -100 -100][100 100 100]`

##### setheading seth shd

**movement and vectors**

degrees (number)

none

Sets the turtle’s heading (left-right) and updates its orientation appropriately. Be aware that while setheading will alter the value of heading for the purposes of orientation, setorientation may not restore the expected turtle orientation if setheading is used in isolation. If you intend to use setorientation to restore a turtle’s orientation, you should use setorientation to change aspects of a turtle’s orientation also. See orientation

`setheading 90`

##### setmodelorigin

**movement and vectors**

none

none

setmodelorigin sets the current position and vectors of the turtle drawing the turtle model. These are restored using modelhome. Since the turtle model is redrawn every time the turtle moves, these values are automatically updated and used based on the turtle’s current position. See modelhome, newmodel

`setmodelorigin`

##### setorbitdistance

**movement and vectors**

turtle-units (number)

none

Sets the currently selected turtle’s distance from its anchor point.

`setorbitdistance 100`

##### setorientation

**movement and vectors**

vectors (list)

none

First unwinds the current orientation in the reverse of orientationorder, then changes the calling turtle’s orientation in the order specified by orientationorder, so that if orientationorder is “PHR then the first orientation changed is pitch, then heading, then the roll. Due to the nature of 3D movements, setorientation can only be used to restore orientations that are the result of relatively simple transforms (that is, series of orientation changing commands such as rollright or down). To restore complex orientations, use both setorientation and setvectors. See setvectors

`setorientation [0 90 0]`

##### setorientationorder

**movement and vectors**

order (word)

none

Sets the order in which heading, pitch and roll are processed after using setheading, setpitch or setroll. The required word is a three letter combination made up of h, for heading, p, for pitch, and r, for roll. See orientationorder

`setorientationorder "hpr`

`setorientationorder "rhp`

##### setorigin

**movement and vectors**

[x y z] (list)

none

Sets the turtle’s origin, the location it goes when it goes home. See origin, home

`setorigin [50 50 50]`

##### setoriginvectors

**movement and vectors**

vectors (list)

none

Sets the turtle’s origin vectors, the orientation the turtle ends up in when it goes home. See originvectors, vectors, home

`setoriginvectors vectors`

##### setpitch setp spi

**movement and vectors**

degrees (number)

none

Sets the turtle’s pitch (up-down) and updates its orientation appropriately. Be aware that while setpitch will alter the value of pitch for the purposes of orientation, setorientation may not restore the expected turtle orientation if setpitch is used in isolation. If you intend to use setorientation to restore a turtle’s orientation, you should use setorientation to change aspects of a turtle’s orientation also. See orientation

`setpitch 180`

##### setpos spo

**movement and vectors**

[x y] (list)

none

Sets the x and y co-ordinates of the calling turtle’s position. If the pen is down, a line is drawn between the turtle’s old position and new position. Does not affect z. Exists for compatibility with two-dimensional logos.

`setpos [20 30]`

##### setposition spn

**movement and vectors**

[x y z] (list)

none

Sets the turtle’s co-ordinates. If the pen is down, a line is drawn between the turtle’s old position and its new position.

`pendown repeat 100 [setposition {-200 + random 400 -200 + random 400 -200 + random 400}]`

##### setroll setr sro

**movement and vectors**

degrees (number)

none

Sets the turtle’s roll (rollleft-rollright) and updates its orientation appropriately. Be aware that while setroll will alter the value of roll for the purposes of orientation, setorientation may not restore the expected turtle orientation if setroll is used in isolation. If you intend to use setorientation to restore a turtle’s orientation, you should use setorientation to change aspects of a turtle’s orientation also. See orientation

`setroll 90`

##### setvectors

**movement and vectors**

[[forwarddir] [updir] [rightdir]] (list of lists)

none

Sets the current turtle’s orientation using vectors.

`setvectors [1 -1 0] [1 1 1] [0 0 0]`

##### setx

**movement and vectors**

number

none

Sets the turtle’s x position.

`setx 100`

##### setxy

**movement and vectors**

x (number) | y (number)

none

Sets the turtle’s x and y co-ordinates. This is here for compatibility. As opposed to setpos, which takes the two co-ordinates as a list. See setpos

`setxy 10 20`

##### sety

**movement and vectors**

number

none

Sets the turtle’s y position.

`sety 20`

##### setz

**movement and vectors**

number

none

Sets the turtle’s z position.

`setz 50`

##### showme

**movement and vectors**

turtle

none

Causes the calling turtle to position itself in the default view turtle position over the specified turtle. Usually called by the current view (camera) turtle.

`showme "myrtle`

##### slideleft sl

**movement and vectors**

turtle-steps

none

‘Slides’ the turtle to the left the given number of turtle-steps.

`slideleft 20`

##### slideright sr

**movement and vectors**

turtle-steps

none

‘Slides’ the turtle to the right the given number of turtle-steps.

`slideright 30`

##### spin

**movement and vectors**

[vectors] (list) | degrees

Spins the turtle around the given vector by the given number of degrees in a clockwise direction from behind the vector such that SPIN FORWARDDIR 90 would be the same as ROLLRIGHT 90. Does not affect pitch, heading or roll.

spin forwarddir 90

##### stealth

**movement and vectors**

none

none

Causes the calling turtle not to appear in lists returned by near. See nostealth

`stealth`

##### tether

**movement and vectors**

none

none

Tethers the selected turtle to the orbit anchor point. If the turtle moves, the anchor point remains unchanged. See setanchor, notether

`tether`

##### towards

**movement and vectors**

[x y] (list)

heading (number)

Returns a heading that would make the turtle face toward the provided co-ordinates. towards assumes the target co-ordinate is on the same Z plane as the turtle. towards is a legacy Apple Logo primitive that is useful in turtleSpaces for compatibility and two-dimensional applications. See heading

`setheading towards [30 40]`

##### up

**movement and vectors**

degrees

none

Angles the ‘nose’ of the turtle up the specified number of degrees. If looking down at the turtle from above (the default view), up 90 will cause the turtle to point straight up towards you.

`up 90`

##### updir

**movement and vectors**

none

vector (list)

Returns the calling turtle’s current up vector. See rightdir, forwarddir

`show updir`

##### unproject

**movement and vectors**

position (list)

[x-percent y-percent (list)

Returns the 2D position of the object as a percentage of the window / screen. For example, if the turtle appears to be in the dead center of the screen, unproject will return 50% across and 50% down. Note: If the co-ordinate is not in the view of the camera, unproject will return spurious results!

`unproject myrtle:position`

##### vectors

**movement and vectors**

none

[forwarddir updir rightdir]

Returns the orientation vectors of the turtle as a list. This is the most reliable method of storing and restoring the orientation of a turtle, as opposed to the orientation function, which returns relative heading / pitch / roll values.

`print vectors`

##### xcor xpos

**movement and vectors**

none

xpos (number)

Returns the current x co-ordinate of the turtle.

`show xpos`

##### ycor ypos

**movement and vectors**

none

ypos (number)

Returns the current y co-ordinate of the turtle.

`show ypos`

##### zcor zpos

**movement and vectors**

none

zpos (number)

Returns the current z co-ordinate of the turtle.

`show zpos`

##### zeroheading

**movement and vectors**

none

none

Zeroes the turtle’s heading value. This does not modify the turtle’s orientation. Further changes will modify heading as appropriate. This primitive allows you to establish a new base heading value to work forward from. See heading

`zeroheading`

##### zeroorientation

**movement and vectors**

none

none

Zeroes the turtle’s orientation values (pitch, heading, roll). This does not modify the turtle’s actual orientation. Further changes will modify orientation values as appropriate. This primitive allows you to establish new base orientation values to work forward from. See orientation

`zeroorientation`

##### zeropitch

**movement and vectors**

none

none

Zeroes the turtle’s pitch value. This does not modify the turtle’s orientation. Further changes will modify pitch as appropriate. This primitive allows you to establish a new base pitch value to work forward from. See pitch

`zeropitch`

##### zeroroll

**movement and vectors**

none

none

Zeroes the turtle’s roll value. This does not modify the turtle’s orientation. Further changes will modify roll as appropriate. This primitive allows you to establish a new base roll value to work forward from. See roll

`zeroroll`

##### zoom

**movement and vectors**

none

number

Returns the turtle’s ‘zoom’ value, which is relevant to its display when it is a view turtle. 100 (as in 100%) is the default value. See setzoom

`show zoom`