1. Commands
StarLogoT primitives are classified into two types: commands and reporters.
Commands are primitives that tell agents what to do. Commands, e.g., forward, hatch, and back, tell the agents how to move, and what to do. Commands can stand alone or they may take some type of input. For example:forward 1 hatch [forward 1] back 1In these examples, the commands forward and back take a number input: namely, 1. A number input is either a number, or a Reporter that returns a number. Reporters are discussed in the next section.
The command hatch executes a commands input: namely, forward 1. A commands input is a list of one or more commands. The hatch command tells a turtle to reproduce by making a copy of itself. However, two turtles on the same patch look like one. Thus, the input forward 1 tells the newly hatched turtle to execute the command to move one step forward.
2. Reporters
Another example:
3. Input Types
There are hundreds of different commands and reporters in
StarLogoT, which are listed in the Quick Reference, and in this Manual's Primitives List. Each command and reporter requires certain types of inputs. Here is the list of different all the types of inputs
available in StarLogoT. This is a handy reference for when you come across a type of input that you haven't met before:
*breed-name: the name of a breed (e.g., wolves, sheep)
*color: either the name of a color (e.g., red), or its associated number (e.g., 15). On the name/number correspondence
of colors see the section Color, below.
*commands: a list of one or more commands.
*condition: This is an important type of input. A condition is an expression that evaluates to either true
or false. If it is true for an agent, that agent goes ahead and executes further inputs; if it is false, the agent doesn't
do anything else with it.
Another example is: *data: a list of numbers
*dx: this is the distance along the x-axis. dx is used in many contexts. If it
is being used by a turtle or patch command, it will be used to say how far something is from an agent.
If it is being used by an observer command, it will be used to say how far something is from the center
of the graphics window. It is normally used in conjunction with dy.
*dy: this is the distance along the y-axis. It is normally used in conjunction with dx.
*ID-Number: Every turtle has a unique ID number, also known as its 'WHO'. By clicking on the turtle, this number comes up in the command window.
These numbers are assigned as the turtles are created. For instance, if there are 100 turtles, they have ID-Numbers between 0 and 99. Any
of these are acceptable inputs for a command or reporter requiring an ID-Number. For example,
*index: this is used as an argument to array primitives. It determines what spot in the array is being accessed. It
ranges from 0, the first element, to length-1, the last element.
*item: usually found in conjuction with data inputs. An item is one the elements from the
data list.
*number: a number or a Reporter that returns a number.
*numeric-expression or numerical-expression: a Reporter that returns a number.
*patch-variable: any variable that has been declared as patches-own. See The Guide to Programming StarLogoT2001, for a detailed explanation of declaring variables.
*shape: shape stands for either the shape-name of a shape or its number; they can be used interchangeably.
*shape-name: when shapes are created, they are assigned specific names and numbers. The name can be used as an input
to the set-shape command.
*string: this is a literal string of text; either in quotes, or with quotes and vertical bars (which signify literal text). See the type command.
*thing: any input type.
*turtle-variable: any variable that has been declared as turtles-own. See The Guide to Programming StarLogoT2001, for a detailed explanation of declaring variables.
*turtle-or-patch-variable: any variable that has been declared as either turtles-own or patches-own. See The Guide to Programming StarLogoT2001, for a detailed explanation of declaring variables.
*value: this is used as an argument in array primitives to set elements. It is the value placed into an array at an index.
*variable: any variable that has been declared as turtles-own, patches-own, or as globals. See The Guide to Programming StarLogoT2001, for a detailed explanation of declaring variables.
*xcor: simply means x-coordinate.
*ycor: simply means y-coordinate.
4. Agent/Breed Specific Primitives
5. Parentheses & Brackets
Brackets [ ] must be used around lists of commands and data. They are sometimes required around numerical expressions. They are shown in the Primitives List whenever they are required.
Parentheses ( ) are used around conditions and to clarify order of operations. When in doubt, put them in.
6. Spaces
7. Dashes
8. Suffixes
The suffix '-at' takes the inputs dx dy For a turtle or patch, this is the x and y coordinates in relation to it as if it were the center of the coordinate system. Thus for a turtle at (5,5), count-turtles-at 2 1 would count the turtles at (7,6). The observer always goes from (0,0) - the actual center of the StarLogoT screen - so for the observer, (x,y) and (dx,dy) are identical.
The suffix '-here' reports an ID-number of a turtle.
The suffix '-of' takes an ID-number. For example: The suffix '-with' always takes a condition as an input, as in
9. Comments
10. Commas
11. Colors
12. Typographic Conventions
Each entry in the Primitives List is tagged with at least one of the following icons.
In the StarLogoT Quick Reference, (in the primitive definition windows) the letters T, P, and O indicate
whether the primitive is a turtle, patch or observer primitive.
Reporters are primitives that output information. However, instead of telling some agent to execte a command, reporters
return a value. Thus, reporters are often used as inputs for commands. For example:
color
reports the color of the turtle.
Thus, the code:
if (color = white) [fd 20]
asks each turtle what color it is. If the color primitive reports back 'white', then the condition is satisfied, and the turtle executes
the commands and moves forward twenty steps.
random number
is a reporter that takes the input number and returns another number. Thus,
random 10
returns a value between 0 and 9. The value returned by this reporter can be used as an input to a command. So, in the code
forward (random 10)
the command forward calls the reporter random. The reporter takes the number input 10, and reports back a
random number (for example, 4). The command forward then uses this number as its input. And the turtle moves forward
4 steps. Note that each turtles evaluates (random 10) independently.
For example:
histogram-BREED-with condition patch-or-turtle-variable
executes the
histogram command for a given turtle's variable only if the condition, such as color = red
is true; otherwise that
turtle's variable is not histogrammed.if (condition) [commands]
If the condition, such as xcor > 10
is true, then the commands, for example, rt 90 fd 1 are executed. That is, if (xcor > 10) [rt 90 fd 1]
So, if a turtle satisfies
the condition of having an x-coordinate greater than 10, it executes the commands to turn right 90 degrees and move forward one.setc-of 45 red
and
if (who = 45) [setcolor red]
both set the color of the turtle with ID = 45 to red
Some commands and reporters use a syntax that requires placing a specific agent-variable, or breed-name into the body of the
primitive. For example:
create-BREED number
This command uses the value of the number input to create new agents of the specified breed. So,
create-wolves 10
creates ten new turtles of the "wolves" breed.
This syntax is used in many cases, and only requires that you replace the text: BREED
with the appropriate breed name.
if ((random 100) > (decay-percent * 100)) [decay]
All primitives, variables, operators, numbers, etc. must have spaces between them. The only exceptions are brackets and parentheses. Similarly, names for procedures and variables must NOT have spaces. Hence the liberal use of dashes to create compound words with no spaces.
The conventions are as follows: Generally there is no dash after 'set', but there is a dash before the next word, as in setcolor-at and setplot-xrange. Use dashes after most other verbs or prefixes, such as 'ask-', 'count-', 'max-of-', 'sum-of-', 'auto-', 'save-', 'scale-', 'who-', etc. Use dashes before the suffixes '-at', '-with', '-of', and '-here'. Watch for non-standard cases, such as setscreen-size-x, setplot-pencolor, vs. setplotwindow-name, set-random-seed-a. Invent variable-names as long as you like, to help you remember what they are, e.g. wolf-number, temp-speed, empty-fish-boats.
setc-of 84 green
sets the color of turtle number 84 to green.
sum-of-turtles-with [color = green]
Put semicolons in front of text that you don't want executed as code.
Repeat 36 [rt 10 fd 4] ;turtles make a polygon
You can put in more than one semicolon to make the comment stand out. Generally, the more comments the better.
Commas synchronize the parallel operations of turtles. Without commas, each turtle runs at its own speed, and some can get ahead of others. A comma means, "wait till all the turtles (or patches, as the case may be) have finished before you continue".
Colors can be specified by a number or by certain names. Each color ranges over ten integer values, with the named color being the brightest shade in the middle. For example, reds go from 10 to 19, and "red" reports 15. You can find them on the toolbar. The names are: black = 0, grey = 5, white = 9, red = 15, orange = 25, brown = 35, yellow = 45, green = 55, lime = 65, turquoise = 75, cyan = 85, sky = 95, blue = 105, violet = 115, magenta = 125, pink = 135. Numbers greater than 140 "wrap" (using modulo 140).
: This primitive can be called by a patch agent.
: This primitive can be called by a turtle agent.
: This primitive can be called by the observer.