# Tag forward

#### A Starry turtleSpaces Logo Introduction Part One: Starfield

Traditional Logo had new users build a house as an introduction, but due to turtleSpaces’ 3D nature, starfields are much more impressive, so we’ll start there.

``` ```

Click and drag the window above to see all the stars!

Cool huh? First, we’re going to create this simple starfield that wraps around the camera position.

We’ll start by creating the procedure:

```TO stars
END
```

Then we’ll add in some setup stuff:

```TO stars

reset
hideturtle
penup

END
```

reset – resets the workspace to its default configuration
hideturtle – hides the turtle
penup – doesn’t draw lines. The turtle draws lines as it moves by default

setfillshade 12 – sets the fill shade to 12. Shades have a range of -15 (light) to +15 (dark) where 0 is normal

We don’t need to use the gradients, but the starfield looks so much better with them enabled!

So, now we’ll carry on and create our main loop:

```  repeat 1000 [
]
```

This will create 1000 stars, once we fill in the rest of it. Let’s fill in the loop and then go through each command:

```  repeat 1000 [
randomvectors
forward 500 + random 1000
up 90
randomfillcolor
setpencolor fillcolor
spot 1 + random 10
home
]
```

…and that’s it! Not a lot, is it? Let’s go through it step-by-step.

randomvectors – sets a random three-dimensional orientation for the turtle. This is the equivalent of going left random 360 up random 360 rollright random 360 but in an easier and faster method. Why vectors? Because vectors describe the turtle’s orientation in 3D space, as well as the orientation of all other objects in it. Why build-in a shortcut? Because we wan’t to be easy to use!

forward 500 + random 1000 – move forward 500 turtle-units PLUS 0-999 turtle-units. random returns a random value between 0 and one less than the given value, because 0 is one of the (in this case) possible 1000 choices. This gives our starfield depth while making sure the stars aren’t too close!

random is a function, it doesn’t do anything on its own. Try typing random 30 at the prompt and see, you’ll get:

I don’t know what to do with 10

for example. That value needs to be ‘passed’ to another function or command — its output needs to become someone else’s input, in this case +.

Then +‘s output is passed to forward, which then moves the desired number of turtle-units. This is a big part of how Logo works, and is why commands can be stacked on the same line — they gobble up all of the inputs, and once they do they are ‘complete’ and we know to move on.

up 90 – spots are created around the turtle on its z-plane and so we need to tilt the turtle up 90 degrees so that the stars are facing back towards our view point near the center of the space.

(Note that if you used the lower primitive instead of forward, you wouldn’t need to tilt the turtle up.)

(Note also that different shapes may be positioned in different orientations relative to the turtle. The best way to build things is to progressively build them through the REPL (the command-line interface), using the backtrack command to undo any mistakes.)

randomfillcolor – picks a random fillcolor (the color shapes are colored), a value between 1 and 15 that is NOT the current fillcolor. The alternate form of this is complex: make “oldfillcolor fillcolor dountil fillcolor != :oldfillcolor [setfillcolor 1 + random 15]randomfillcolor is nicer. But you could do it the hard way if you want!

setpencolor fillcolor – because we’re using gradients we need to make the pencolor the new fillcolor so that the stars don’t gradient to a different color. fillcolor is a function that returns the current fillcolor.

spot 1 + random 10 – create a spot graphical primitive between 1 and 10 turtle-units in diameter around the turtle. Remember, random 10 will return a value from 0 to 9. If you just did spot random 10 without adding the 1 you might get 0., which while not an error won’t create anything of substance (literally).

home – return the turtle to the home position, which by default is [0 0 0], the center of the space.

Finally, all of this ‘filling’ is a list, passed to repeat to execute. Logo uses lists for all sorts of things, as you’ll see as you progress in your journey through Logo!

Congratulations, you’ve reached the end of this first (ahem) turtorial! Next in part two, we’re going to make a moving star ‘warp’ effect.

Here’s the full commented listing:

```TO stars
;TO declares a procedure, in this case one called
;'stars'. Procedures can be simply called by name
;to execute them. So, at the prompt, you can
;type 'stars' (without quotes) to execute this
;procedure

;this is a very simple starfield generator and
;a good first project for turtleSpaces. All
;we're doing is randomly orienting the turtle,
;moving forward a random amount and creating
;a randomly-sized spot 1000 times.

;10 commands, one function. Dead simple!

;But first a little setup stuff...

reset
;reset the workspace

hideturtle
;hide the turtle

penup
;don't draw lines

;we could omit this but it looks much better this way:

;...and that's it for setup stuff!
;Now on to the main event:

repeat 1000 [
;this means 'do this 1000 times'.
;things between square brackets are lists.
;repeat is a command that takes the number
;of times it is supposed to execute the contents
;of a list, and that list itself. What follows
;is the contents of that list:

randomvectors
;give the turtle a random 3D orientation.
;you could do this yourself using a bunch
;of movement commands but we like making
;things easy!

forward 500 + random 1000
;move forward 500 turtle units
;plus 0-999 turtle units
;(random returns a value between
;0 and the number passed to it
;excluding that number)

;random is a function that does not
;'do' anything on its own. Try typing
;'random 30' at the prompt to see.
;It returns a random value, which is
;then passed to another function or
;a command. In this case, random's
;output is passed to the + function,
;which then adds 500 to it and then passes
;its output to the forward command

;this is a big part of how Logo works

up 90
;spots are created around the turtle
;on the z-plane, and so we need to tilt
;the turtle up

;try creating a spot eg 'spot 100'
;after the workspace has been reset
;to see how the spot is placed relative
;to the turtle

;different shapes may be places different
;ways relative to the turtle

randomfillcolorsp
;shapes use the fill color
;and randomfillcolor picks a random
;fill color. You can pick one arbitrarily
;using the setfillcolor command

setpencolor fillcolor
;need to set the pencolor to the fillcolor
;otherwise it would gradient to the default
;pencolor as well

spot 1 + random 10
;make a spot between 1
;and 10 turtle-units in diameter
;(remember, random 10 returns
;a value between 0 and 9)

home
;(where the turtle started)

]
;perform the above list 1000 times
;as you can see, lists can be spread out
;across many lines

;So, 14 commands, a fillcolor and a couple of
;randoms and that's it.

;Click and drag the mouse over the view window
;to rotate the camera and see all the stars!

END

```

#### Tutorial #1: Simple Tree

These procedures draw a simple tree in a classic Logo lined style, and a forest of these trees. First, let’s take a look at the tree procedure as a whole.

```TO tree :scale
slideleft 8.25 * :scale
forward 20 * :scale
repeat 4 [
slideleft (10 * (5 - repcount)) * :scale
left 30
slideright (12 * (5 - repcount)) * :scale
right 30
]
left 30
slideright 5 * :scale
right 60
slideright 5 * :scale
left 30
repeat 4 [
right 30
slideright (12 * repcount) * :scale
left 30
slideleft (10 * repcount) * :scale
]
back 20 * :scale
slideleft 8.25 * :scale
END```

Now let’s go through it a line at a time. The procedure starts out with the procedure declaration TO, then the name of the procedure tree, then a single parameter, :scale

`TO tree :scale`

Remember that the colon indicates that scale is a container – but parameters are only containers inside of their procedures. This is important.

Notice that there is a companion END at the end of the procedure. Every TO must have an END.

`slideleft 8.25 * :scale`

slideleft is a movement primitive, it tells the selected turtle to shift its position to its left the given number of turtle-units, which correspond to OpenGL units. In this case, the number of turtle units to shift left is 8.25 * the value of :scale, which is given as a parameter when tree is called.

`forward 20 * :scale`

forward is another movement primitive, it tells the selected turtle to move forward the given number of turtle-units.

`repeat 4 [`

repeat is a loop primitive. It takes two parameters, the number of times to repeat the instruction list, and the instruction list itself, which is bookended by an open square bracket and a closed square bracket. repeat executes the instruction list the specified number of times. The contents of the instruction list can be spread across multiple lines, as it is here, and which follow:

`slideleft (10 * (5 - repcount)) * :scale`

slideleft is similar to slideright. The rounded brackets tell turtleSpaces which part of the supplied expression to evaluate first. If there are brackets inside brackets, the innermost ‘nest’ is evaluated first. turtleSpaces resolves mathematical expressions using the PEMDAS (BEDMAS) ordering, but often some clarity is required. In the case of the line above, we want to ensure that repcount (the current iteration of the repeat loop) is subtracted from 5 before it is multiplied by 10, and all of that needs to be done before it is multiplied by :scale

turtleSpaces parses right to left. This means that it evaluates expressions in the right of the instruction first. What this means for the statement above is that without brackets, repcount * :scale would be evaluated first. Then 10 * 5. Then the result of repcount  * :scale would be subtracted from 10 * 5. This is not what we want! So we need brackets.

`left 30`

left rotates the turtle to its left the specified number of degrees, in this case 30.

`slideright (12 * (5 - repcount)) * :scale`

The slideright instruction is similar to the slideleft instruction above, except in this case we are going to slide a bit more right than we did left.

`right 30`

Similarly to left, right turns the turtle to the right the given number of degrees, also 30 in this case.

`]`

The closing bracket finishes the instruction list. All of this is collected and given to repeat, which then repeats the instructions the given number of times (4).

```left 30
slideright 5 * :scale
right 60
slideright 5 * :scale
left 30
repeat 4 [
right 30
slideright (12 * repcount) * :scale
left 30 slideleft (10 * repcount) * :scale
]```

The next four instructions draw the ‘peak’ of the tree, and the following repeat loop the opposite side of the tree.

```back 20 * :scale
slideleft 8.25 * :scale```

back is similar to forward, except the turtle backs up. slideleft you already know!

`END`

end finishes the procedure.

Once the procedure is entered, you can call it by typing tree and then a scale ‘factor’.

```tree 1

tree 0.5

tree 2```

0.5 makes a tree half as large as one, and 2 twice as large.

TIP: To make the turtle move smoothly, use the fluid primitive.

`fluid`

Let’s make another procedure that draws a whole forest!

```TO forest
reset
repeat 10 [
penup
home
slideleft -150 + random 300
forward -100 + random 150
randompencolor
pendown
tree (2 + random 8) / 10
]
END```

Again stepping through each instruction:

`TO forest`

This procedure declaration doesn’t take a parameter – all we need to know is inside it, and all it will take to call it is a single word: forest.

`reset`

reset causes the graphical workspace to return to its initial state, erasing any contents and moving all of the turtles to their home positions. It doesn’t erase any procedures but it does erase containers! Unlike other Logos (and like virtually every other programming language), in turtleSpaces all containers (variables) need to be declared by a procedure, they cannot exist on their own and are not otherwise saved in project files. While it seems like a good idea if they could be, it’s really not.

`repeat 10 [`

The following instructions will be repeated ten times. You can change that to whatever number you want. Or you could make it a parameter in the forest procedure definition, and then replace the number 10 with the container you specified there, such as :trees

`penup`

Turtles (except for Snappy the camera turtle) start with their pen down after a reset or when they are created. This means they draw lines whenever they move. You can stop them from drawing lines with the penup instruction.

`home`

home causes the turtle to move to its home position. In Myrtle’s case, her default position is [0 0 0], that is 0 horizontally (x), 0 vertically (y) and 0 in depth (z). All of these are ‘centered’ in their given axis (x y or z). With two-dimensional procedures and programs you don’t need to worry about depth (z). There are other primitives for positioning the turtle we will get into in another tutorial. But for now, we’ll stick with what we’ve learned so far.

`slideleft -150 + random 300`

random picks a random number between and including 0 and the number that is given to it, but not that number. So, random 300 will return a number between 0 and 299. Why? Because you might want 0 as a possible result. And you might want to pick from a range of however many numbers you specified (in this case 300). 300 numbers including 0 gives you a range from 0 to 299. I know it would be easier if it was a range from 0 to 300, but that would be 301 numbers in total, not 300!

We take the number chosen by random, and add it to -150. If the number is still negative, that means that the turtle will slide to the right rather than the left!

`forward -100 + random 150`

Similarly, if the result of -100 + random 150 is negative, the turtle will move backwards, not forward. All of the movement primitives behave the same way. A negative value will cause it to move in the opposite direction indicated by the primitive. For example, a negative angle will cause left to turn right.

`randompencolor`

This ‘shorthand’ instruction causes the turtle to pick a random pen color, a value between 1 and 15. You could do the same if you wrote:

`setpencolor 1 + random 15`

but randompencolor gets straight to the point. To see a list of the turtle’s default colors, type showcolors. The colors are based on the default colors in the low resolution mode of the Apple II! They’re historical (and I’m maybe a little hysterical).

`pendown`

Similarly to penup, pendown puts the turtle’s pen down, and causes it to draw again.

`tree (2 + random 8) / 10`

And now that we’re in a random position, we’re going to draw a tree (the first procedure) providing a random :scale value. random cannot generate parts of numbers, only whole numbers, so to get a fraction we need to divide (/) our random result by 10. So, after calculating, the parameter passed to tree will be a value between 0.2 and 0.9

`]`

And that closing square bracket signals the end of the instruction list provided to the repeat above.

`END`

That’s the END of the forest procedure and our first (ahem) turtorial (ba-dum).

Let’s give it a go:

Because it’s completely random, it may take a few tries to get a distribution that you like.

Finally, set the title of your creation using the settitle primitive:

`settitle "forest`

and then save it using the save primitive:

`save`

And now you can visit your forest again whenever you like.

You’ve entered your first Logo program. Well done!