Command List

Here are a list of commands that affect logic structures.

Observer

ask-breed [list of commands]

Parameters:
[list of commands] List of turtle commands A list of turtle commands to run

Description:
Asks all turtles of breed frogs to run [list of commands]. The observer will wait for all of the turtles to finish before continuing.

Examples:
ask-frogs [fd 1 rt 90] will make all turtles of breed frogs move forward one step and then turn 90 degrees to the right.

Related Commands:
ask-breed-with ask-list-of-turtles ask-patch-at ask-patches ask-turtle ask-turtles ask-turtles-with
Turtle, Observer, Patch

ask-list-of-turtles [list of turtle who numbers] [list of commands]

Parameters:
[list of turtle who numbers] List A list of turtle who numbers to ask
[list of commands] List of turtle commands A list of commands to ask these turtles to run

Description:
Turtles whose who numbers (ID numbers) are in [list of turtle who numbers] run [list of commands]. The caller of this command waits for it to finish before continuing. If some invalid whonumbers make up [list of turtle who numbers], they are ignored.

Asking a list of turtles to do something is a moderately expensive operation since StarLogo creates a thread for each turtle. Try to group commands that you would have put into separate ask-list-of-turtles into the same one to minimize thread creation overhead.

Examples:
ask-list-of-turtles [4 6 10 14] [fd 1] makes 4 turtles (those with who numbers 4, 6, 10, and 14) move forward one step.

Related Commands:
ask-breed ask-patch-at ask-patches ask-turtle ask-turtles ask-turtles-with
Turtle, Observer, Patch

ask-patch-at [list of commands]

Parameters:
[list of commands] List of patch commands A list of commands for the patch to run

Description:
This command asks the patch which is xcor units in the x direction and ycor units in the y direction away from the caller to run the [list of commands]. The caller of this command will wait for the patch to finish before moving on. The observer is considered to be located at (0, 0).

Examples:
ask-patch-at 5 6 [setpc red] makes the patch 5 units to the right and 6 units up from the caller turn red.

ask-patch-at -3 -8 [setpc blue] makes the patch 3 units to the left and 8 units down from the caller turn blue.

Related Commands:
ask-breed ask-list-of-turtles ask-patches ask-patches-with ask-turtle ask-turtles ask-turtles-with
Observer

ask-patches [list of commands]

Parameters:
[list of commands] List of patch commands A list of commands for the patches to run

Description:
This observer command asks all of the patches to run the [list of commands]. The observer will wait for the patches to finish before moving on.

Asking the patches to do something is a moderately expensive operation since StarLogo creates a thread for each patch. Try to group commands that you would have put into separate ask-patches into the same one to minimize thread creation overhead.

Examples:
ask-patches [setpc red] colors all of the patches red.

Related Commands:
ask-breed ask-list-of-turtles ask-patch-at ask-turtle ask-turtles ask-turtles-with setbg
Turtle, Observer, Patch

ask-turtle who number [list of commands]

Parameters:
who number Integer The who number of a turtle
[list of commands] List of turtle commands A list of commands for the turtle to run

Description:
This command asks the turtle with who number number to run the [list of commands]. The caller will wait for the turtle to finish before moving on.

Examples:
ask-turtle 5 [fd 1] makes the turtle with who number 5 move forward 1 step.

Related Commands:
ask-breed ask-list-of-turtles ask-patch-at ask-patches ask-turtles ask-turtles-with
Observer

ask-turtles [list of commands]

Parameters:
[list of commands] List of turtle commands A list of commands for the turtles to run

Description:
Asks all turtles to run the [list of commands]. The observer will wait for all of the turtles to finish before continuing.

Asking all of the turtles to do something is a moderately expensive operation since StarLogo creates a thread for each turtle. Try to group commands that you would have put into separate ask-turtles into the same one to minimize thread creation overhead.

Examples:
ask-turtles [fd 1] will make all of the turtles move forward 1 step.

Related Commands:
ask-breed ask-list-of-turtles ask-patch-at ask-patches ask-turtle ask-turtles-with
Observer

ask-turtles-with [condition] [list of commands]

Parameters:
[condition] List of turtle commands An expression that returns a true or false value
[list of commands] List of turtle commands A list of commands for the turtles to run

Description:
This observer command asks turtles satisfying [condition] to run the [list of commands].
Asking many turtles to do something is a moderately expensive operation since StarLogo creates a thread for each turtle. Try to group commands that you would have put into separate ask-turtles-with into the same one to minimize thread creation overhead.

Examples:
ask-turtles-with [color = red] [fd 1] tells all red turtles to move forward one step.

Related Commands:
ask-breed ask-list-of-turtles ask-patch-at ask-patches ask-turtle ask-turtles
Turtle, Observer, Patch

case variable [ anything1 [list-of-commands1] anything2 [list-of-commands2] ]

Parameters:
variable Variable variable to check
[ anything1 [list-of-commands1] List of commands value to match and commands to run
anything2 [list-of-commands2] ] List of commands value to match and commands to run

Description:
Checks if the first argument variable is equal to any of the anythings in the list. If it is equal, the corresponding [list of commands] is executed and control skips to the end of the case statement. A case statement can often be used in place of nested ifelse statements. If nothing matches, no [lists of commands] are executed and control skips to the end of the case statement. You can use true as one of your anythings as a default case.

Examples:
case energy
[
1 [setc blue]
2 [setc yellow]
3 [setc red]
true [setc white]
]

This command will set the turtle's color to blue if energy is 1, yellow if energy is 2, red if energy is 3 and white in any other case.

Notes:
The first input can be an expression as well as a variable.


Turtle

die

Description:
Turtles die, meaning that they stop running all code and disappear forever.

Examples:
if pc = red [die] makes the turtle die if the patch it is on is red.

Related Commands:
kill
Turtle, Observer, Patch

dolist [:loop-variable list] [commands to run]

Parameters:
[:loop-variable list] List of commands On each iteration, :loop-variable is assigned to each element of the list
[commands to run] List of commands Commands to run once for each element of the list

Description:
This command loops over each element of the list, and runs [commands to run] for each one. During each run of [commands to run], the element of the list is bound to loop-variable.

Examples:
dolist [:i [2 4 -1]] [fd :i] loops over the list [1 2 3]. There are three iterations of this loop; in the first, we run fd 2, in the second fd 4 and the third fd -1.

Related Commands:
dotimes
Turtle, Observer, Patch

dotimes [:loop-variable #times] [commands to run]

Parameters:
[:loop-variable #times] List of commands On each iteration, :loop-variable is assigned to each number from 1 to #times
[commands to run] List of commands Commands to run once for each number from 1 to #times

Description:
This command loops over each integer number from 1 to #times, and runs [commands to run] for each one. During each run of [commands to run], the current number is bound to :loop-variable.

Examples:
dotimes [:foo 4] [show :foo] loops 4 times, each time assigning :foo to 1, 2, 3, and then 4. The commands that are run print the value of :foo to the command center.

Related Commands:
dolist
Turtle, Observer, Patch

every number [list of commands]

Parameters:
number Number number of seconds to wait between each iteration
[list of commands] List of commands list of commands to run each iteration

Description:
every is just like loop, in that it runs its [list of commands] forever, but it waits number seconds between each iteration. Number can be a decimal as well as an integer.
every is usually used in a non-forever button to run something over and over again with a pause in between.

Examples:
every 2 [fd 1 rt 90] would make all the turtles move forward one step, turn right 90 degrees, and then wait 2 seconds over and over again.


Turtle, Observer, Patch

grab number [list of commands]

Parameters:
number Number
[list of commands] List

Description:
Have turtles number execute [list of commands].

Examples:
grab one-of-turtles-here [setc red setc-of partner blue] This turns the caller red and the grabbed turtle blue. If there are no other turtles on the caller's patch, the [list of commands] does not get executed and no turtles change color.

Notes:
Caller instructs turtles with who number(s) number(s) to execute [list of commands]. The who number of the turtles being grabbed are stored in partner, if there is one, or partners, if there are many. A turtle cannot grab itself.

Grab is only useful for guaranteeing that a turtle you want to talk to is not being talked to by anyone else and cannot talk to anyone else while being grabbed. Note, while one turtle is grabbing another, neither may be grabbed by a third turtle.

Related Commands:
grabbed? partner partners
Turtle

grabbed?

Description:
Returns true if the turtle is currently grabbed by another turtle, otherwise false.

Examples:
if grabbed? [fd 1] Makes all grabbed turtles move forward 1 step.

Related Commands:
grab partner partners
Turtle

hatch [list of commands]

Parameters:
[list of commands] List of commands

Description:
Make an exact copy of a turtle, including turtles-own variables and state variables. The [list of commands] is then run on the cloned turtle.

Examples:
hatch [setc blue fd 1] has the caller make a duplicate of itself, and then the duplicate sets its color to blue and moves foward 1.

Related Commands:
sprout
Turtle, Observer, Patch

if condition [list of commands]

Parameters:
condition Boolean Condition that evaluates to either true or false
[list of commands] List of commands List of commands to execute of $arg1 is true

Description:
Do [list of commands] if and only if condition reports true.

Examples:
if color = black [fd 5 rt 90] makes every black turtle move forward 5 steps and then turn right.

Related Commands:
ifelse
Turtle, Observer, Patch

ifelse condition [list of commands1] [list of commands2]

Parameters:
condition Boolean Condition that evalutes to either true or false
[list of commands1] List of commands Runs if $arg1 is true
[list of commands2] List of commands Runs of $arg2 is false

Description:
Do [list of commands1] if condition reports true, otherwise do [list of commands2].

Examples:
ifelse color = black [fd 2] [bk 2] would make black turtles move forward 2 steps and all other turtles move back 2 steps.

Related Commands:
if
Turtle, Observer, Patch

ignore expression

Parameters:
expression Anything Expression to evalute for side effects

Description:
Ignores the return value of the expression immediately following it. More useful than it looks, ignore can be used to execute a procedure for its side effects.

Examples:
to compute-and-print-square :x
let [:ans :x * :x]
show :x
output :x

ignore compute-and-print-square 4 shows 16 in the command center, but does nothing with the return value from compute-and-print-square.


Turtle, Observer, Patch

item number [list]

Parameters:
number Number
[list] List

Description:
Returns the element of [list] at the number'th position.

Examples:
item 2 [4 6 8] returns 6.

Notes:
Indexing starts from 1.

Related Commands:
position remove remove-element setitem
Turtle, Observer, Patch

kill number

Parameters:
number Number

Description:
Kills turtle with who number equal to number.

Examples:
kill 2 kills the turtle with a who number equal to 2.

Related Commands:
die
Turtle, Observer, Patch

loop [list of commands]

Parameters:
[list of commands] List of commands the list of commands that will be run forever

Description:
Do [list of commands] forever.

Examples:
loop [fd 4 rt 45] makes turtles repeatedly move forward 4 steps and turn right 45 degrees.

Related Commands:
output repeat stop
Turtle, Observer, Patch

output something

Parameters:
something Anything the value to be returned

Description:
Exits the current procedure and returns something.

Examples:
output "hello" exits the current procedure and returns the string "hello".

Related Commands:
end loop stop to
Turtle, Observer, Patch

reset-timer (resett)

Description:
Resets the timer.

Examples:
If you want to time how long a process takes, do this:
reset-timer fd 1000 show timer

Related Commands:
timer
Observer

startup

Description:
This is a special procedure name. Anything within the startup procedure will be executed each time the project is opened.

Examples:
to startup
clear-turtles ;save the patches
crt 100
ask-turtles [setc blue]
end

This process of clearing the turtles, and creating 100 new blue ones will occur everytime the project is opened.

Related Commands:
end to
Turtle, Observer, Patch

stop

Description:
Exits the current procedure immediately.

Examples:
to check-patch-color
if pc-ahead = red [rt 90 stop]
if pc-ahead = green [lt 90 stop]
fd 1
end

This procedure will cause turtles to turn right and then exit the procedure if the the patch ahead is red, turn left and exit the procedure if the patch ahead is green, and only move forward one if the patch ahead was not green or red.

Notes:
Note: stop does not stop any callers of the procedure, only the procedure itself.

Related Commands:
end loop output to
Turtle, Observer, Patch

stopall

Description:
Tells everything to stop running, including procedures, buttons, monitors, and command centers.

Related Commands:
stopbuttonname
Observer

switch-scheduler

Description:
Toggles back and forth between fixed order scheduling and randomized scheduling.

Related Commands:
get-scheduler-random-seed scheduler set-scheduler-random-seed
Turtle, Observer, Patch

timer

Description:
Reports the current value of the timer in seconds (since the last call to reset-timer).

Each thread of execution has its own timer. A thread of execution is started for each turtle when a turtle button is pressed, or code is entered in the turtle command center. A thread of execution is started for the observer if an observer button is pressed, or code is entered in the observer command center. When turtles, patches or observer are asked to do something (e.g. using ask-turtles, ask-patches or ask-observer), a new timer is created and used for that list-to-run.

Examples:
If you want to time how long it takes for a turtle to move 1000 steps, do this: reset-timer fd 1000 show timer.

Related Commands:
reset-timer
Turtle, Observer, Patch

to-delimited-string [list of commands]

Parameters:
[list of commands] List of commands

Description:
Takes a list of instructions (variables, reporters, strings) and separates them with commas and then concatenates them, returning the concatenated string.

Notes:
This function is helpful in outputting to a spreadsheet program.

Related Commands:
to-list to-string
Turtle, Observer, Patch

to-list [list of commands]

Parameters:
[list of commands] List of commands Commands to execute whose return values will form the list

Description:
Runs then commands in [list of commands] and makes a new list from each command's return value.

Examples:
globals [foo]

set foo 45
to-list [1 2 + 4 foo] returns the list [1 6 45].

Related Commands:
list make-list pick sentence sublist to-delimited-string to-string
Turtle, Observer, Patch

to-string [list of commands]

Parameters:
[list of commands] List of commands Commands to execute whose return values will form the string

Description:
Takes a list of instructions (variables, reporters, strings), executes them, and concatenates their return values, returning the concatenated string.

Related Commands:
to-delimited-string to-list
Turtle, Observer, Patch

wait seconds

Parameters:
seconds Number A number of seconds. Decimals are allowed.

Description:
Caller waits seconds seconds before continuing.

This command is per-thread - meaning if you have two buttons that each call wait, they will not wait for one another.

Examples:
to crawl
fd 1
wait 2.1
end

crawl

The turtles go forward 1 step and then wait for 2.1 seconds.

Related Commands:
wait-until
Turtle, Observer, Patch

wait-until [condition]

Parameters:
[condition] List of commands A predicate that is run over and over again until it is true.

Description:
The caller waits until the [condition] is true. This command is used to make a button or procedure stop until some other event in your model occurs.

Examples:
wait-until [game-over = true] makes the caller wait until the game is over.

Related Commands:
wait