GenoCode reference

Every statement, function, input and constant in GenoCode, one entry each: how it's written, what its parameters are, what it gives back, and an example. The language explains how GenoCode works as a whole and is the definition when the two differ; each entry here links to the part of it that goes deeper.

How to read an entry

Each entry has some of these:

• Syntax: how it's written. Words in the syntax that aren't GenoCode's own words, such as distance in forward distance, stand for values you write in; Parameters says what each one is. { … } stands for a block of statements. When there are several lines, each is one way to write it.
• Parameters: each value it takes, with its type and meaning. Types are the ones in Values and types: number, bool, vector, colour, gradient, shape, pattern, pattern kind, scheme, finish, way of mixing, list and picture. Any means a value of any type.
• Returns: what a function gives back.
• Used in: where it's allowed. Creature code means a creature's top level and its parts. Functions, background blocks, dance blocks and pattern code each allow less, as listed.
• Remarks: rules and details worth knowing.
• Example: code you can paste into a creature. Longer examples are whole files.

A whole number parameter is rounded to the nearest whole number, with halves rounded up. Angles are always in degrees.

Contents

1. Files: creature, breed, variant
2. Genes, variables, parts and functions: gene, let, assignment, part, function, return
3. Control flow: if, repeat, for, while
4. The turtle: forward, back, move, pitch, yaw, roll, rotate, grow, mirror, branch, symmetric, reshape
5. Shapes and material: shape, lay, colour, shine, sharpness, texture, wear
6. Backgrounds: background, fill
7. Dance styles: dance, morph, zoom, spin, turn, reverse, flat, triggers and bursts
8. Pattern code: pattern blocks and files, picture, value, x, y, r and a
9. Debugging: print
10. Number functions: abs, sign, floor, ceil, round, frac, min, max, clamp, wrap, bounce, sqrt, exp, ln, log10, sin, cos, tan, asin, acos, atan, atan2, degrees, radians, wave, bump, mix, smoothmix, mandel
11. Vector and list functions: vec, length, normalize, dot, cross
12. Colours and gradients: hsv, rgb, gradient, spectrum
13. Noise and randomness: noise, fbm, random
14. Texture functions: pattern, mixed
15. Picture functions: clouds, blur, zoom_blur, stretch, power
16. Inputs: time, beat, music, turtle
17. Constants: numbers, axes, colour names, shapes, pattern kinds, schemes, finishes, ways of mixing, none
18. Values and operators: literals, operators, parts of values

1. Files

creature

Starts a creature file. It must be the file's first line.

creature Name

Remarks

• After the header come, in any order: top-level statements, genes, parts, functions, variants, at most one background block, at most one dance block and any number of pattern blocks.
• Comment lines directly below the header are the creature's description, which the app shows.
• The top-level statements run from the top each time the creature is built.
• Other files start with background Name, dance Name or pattern Name instead; see their entries.

Example

creature Snowball
// One white ball.

shape ball
lay

See also: Files

breed

Says whether the app may mutate and breed the creature.

breed off
breed on

Used in: a creature's top level, at most once.

Remarks

• breed off is for creatures whose children wouldn't keep their look. The app then won't mutate or breed them, but they can still be morphed and danced.
• breed on is the default, so it's never needed.

Example

creature Clock
breed off

See also: Genetics

variant

Keeps another set of gene values alongside the creature's own.

variant Name { gene = value; … }

Used in: a creature's top level.

Remarks

• Each setting is on its own line, or separated by ;. A gene can be set at most once in a variant.
• A variant only lists the genes it changes. Every other gene keeps the value on its own gene line, and follows that line if you change it later. In the example below, Wide doesn't mention coils, so it has 3 coils, like the creature itself.
• A creature that uses random has a hidden gene, seed, which picks its random numbers. It has no gene line, but a variant can still set it: in the example, seed = 42 gives Wide its own wiggle, while Coiled keeps the creature's seed, 0.
• Variants don't change what the program does. The app uses them where it wants a family of related creatures: a creature's morph loops through itself and then each variant in order.

Example

creature Cobra

gene hood  = 1.2 in 0.5..2
gene coils = 3   in 1..6 step 1

grow hood
repeat coils {
  yaw random(-20, 20)  // each coil bends a random way
  forward 1
  lay
}

variant Coiled { coils = 6; hood = 0.8 }

variant Wide {
  hood = 2
  seed = 42  // bends its coils other ways
}

See also: gene, Variants

2. Genes, variables, parts and functions

gene

Declares a value the app may change when it mutates, breeds and morphs the creature.

gene name = value in min..max
gene name = value in min..max step size
gene name = value in min..max log
gene name = true
gene name = value from [option, option, …]

Used in: a file's top level, or directly inside a part, function, background, dance or pattern body. Not inside if, loops, branch, symmetric, lay { } or reshape { }.

Remarks

• log makes mutation and morphing work by ratios, for sizes and speeds. min must be above 0, and log can't be used with step.
• A bool gene has no range: gene spiky = true.
• A colour gene's hue is a circle. hsv(0, …)..hsv(360, …) allows every hue. When the first hue is bigger, the range runs up through red: in the example, warm goes from 300 (magenta) through 0 (red) to 40 (orange) (Colour genes).
• A gene whose options are part names is a part gene: calling it calls the part it names. In the example, limb(2) calls leg(2) or fin(2), whichever limb holds. Every part in the list must take the same number of parameters (Part genes).
• The value, range and options must be constant: literals, built-in constants and maths on them. Other genes, variables, random, noise, time and music aren't constant.
• A gene has one value for the whole creature, even if declared in a part that runs many times.
• Genes can't be assigned to.
• A // comment at the end of the line is the gene's description, shown by the app.
• A gene's full name is prefixed by where it's declared. In the example, bend is declared in part leg, so its full name is leg.bend. Genes in a background, a dance or a pattern start with background., dance. or the pattern's name.

Example

creature Critter

gene petals = 7    in 3..16 step 1  // how many limbs
gene size   = 1    in 0.1..10 log
gene skin   = hsv(120, 0.6, 0.9) in hsv(60, 0.3, 0.5)..hsv(180, 1, 1)
gene warm   = hsv(20, 0.8, 1) in hsv(300, 0.5, 0.5)..hsv(40, 1, 1)
gene spiky  = true
gene body   = cone from [ball, cone, tube]
gene limb   = leg  from [leg, fin]

grow size
shape body
colour skin
lay
repeat petals as i {
  branch {
    roll 360 * i / petals
    pitch 90
    limb(2)
  }
}

part leg(reach) {
  gene bend = 30 in 0..90  // how far the legs bend
  colour warm
  pitch bend
  forward reach
  lay
}

part fin(reach) {
  if spiky {
    shape cone
  }
  colour warm
  forward reach
  lay { grow (1, 0.2, 2) }
}

See also: variant, Genes, Genetics

let

Creates a variable.

let name = value

Used in: everywhere statements are allowed.

Remarks

• The variable lasts until the end of the block it's created in. Creating the same name twice in one block is an error; an inner block may create a name that hides an outer one.
• A top-level let makes a global. Parts can read and change globals; functions can only read them. A global can't be used before its let has run.

Example

let size = 1
repeat 5 {
  grow size
  lay
  size *= 0.8
}

See also: assignment, Variables

assignment

Changes a variable's value.

name = value
name += value
name -= value
name *= value
name /= value

Used in: everywhere except dance blocks.

Remarks

• a += b is a = a + b, and so on, with the same rules as the operators. list += [x] adds an item to the end of a list, as sizes += [i + 1] does in the example.
• Genes, loop variables, side and globals inside a function can't be assigned to.

Example

let reach = 3
reach *= 0.5  // now 1.5

let sizes = []
repeat 4 as i {
  sizes += [i + 1]  // now [1, 2, 3, 4]
}

See also: let

part

Defines a piece of creature: code that moves the turtle and lays shapes. Calling it runs that code.

part name(parameter, parameter, …) { … }
part name { … }
name(argument, argument, …)
name

Used in: definitions at a creature's top level. Calls in creature code.

Remarks

• A part with no parameters can be defined and called without brackets, as tail is in the example.
• A part may move the turtle, lay shapes, call parts and functions, and change globals. It doesn't restore the turtle afterwards: put the call in a branch for that, as the example does for leg.
• return with no value leaves a part early. In the example, leg draws nothing when reach is 0 or less.
• Parts can be used before they're defined, and can call themselves up to 200 calls deep.
• Genes declared in a part have the part's name in front: leg.reach.

Example

part leg(reach, bend) {
  if reach <= 0 {
    return
  }
  forward reach
  pitch bend
  lay
}

part tail {
  back 2
  lay
}

symmetric x {
  branch {
    yaw 90
    leg(2, 30)
  }
}
tail

See also: function, Parts and functions

function

Defines a calculation that gives back a value.

function name(parameter, parameter, …) { … }
name(argument, argument, …)

Returns: the value of the return that ends it.

Used in: definitions at a creature's top level. Calls anywhere an expression is allowed in creature code.

Remarks

• A function must end by returning a value with return value.
• It may read the turtle, globals and genes and call other functions. It must not move or change the turtle, lay shapes, call parts or change globals.
• Arguments are copies: changing a parameter doesn't change the caller's variable.

Example

function taper(i, n) {
  return 1 - i / n * 0.8
}

repeat 6 as i {
  branch {
    grow taper(i, 6)
    lay
  }
  forward 1
}

See also: part, return

return

Leaves a function with its value, or leaves a part early.

return value
return

Used in: functions (with a value) and parts (without one).

Example

function half(x) {
  return x / 2
}

See also: function, part

3. Control flow

if

Runs a block only when a condition is true.

if condition { … }
if condition { … } else { … }
if condition { … } else if condition { … } else { … }

Used in: everywhere except dance blocks.

Remarks

• Any number of else if blocks may follow, and one else at the end.

Example

gene petals = 7 in 3..16 step 1

if petals > 10 {
  shape ball
} else if petals > 5 {
  shape cone
} else {
  shape cube
}

See also: operators, Control flow

repeat

Runs a block a number of times.

repeat count { … }
repeat count as i { … }

Used in: creature code, functions and pattern code.

Example

repeat 8 as i {
  branch {
    roll 45 * i
    forward 2
    lay
  }
}

See also: for, while

for

Runs a block for each value of a counter, from one number to another.

for v from start to end { … }
for v from start to end by step { … }

Used in: creature code, functions and pattern code.

Remarks

• start, end and step are read once, when the loop starts.
• With a positive step the loop runs while v ≤ end. With a negative one it counts down, while v ≥ end: the second loop in the example gives size the values 1, 0.75, 0.5 and 0.25.

Example

for a from 0 to 315 by 45 {
  branch {
    yaw a
    forward 3
    lay
  }
}

for size from 1 to 0.25 by -0.25 {
  branch {
    grow size
    lay
  }
  forward 1
}

See also: repeat, while

while

Runs a block again and again for as long as a condition is true.

while condition { … }

Used in: creature code, functions and pattern code.

Remarks

• There's no break: something in the block must make the condition false. A loop that never ends is stopped by the build's step limit, with a warning (Building a creature).

Example

let size = 1
while size > 0.1 {
  grow 0.7
  forward 1
  lay
  size *= 0.7
}

See also: repeat, for

4. The turtle

The turtle starts at (0, 0, 0), heading along z (towards the viewer), with up along y and its side along x, size (1, 1, 1). The turtle explains its state in full.

Inside reshape and lay { } (lay), the commands in this section change the shape transform instead of the turtle.

forward

Moves the turtle along its heading.

forward distance

Used in: creature code, reshape { } and lay { }.

Example

repeat 5 {
  lay
  forward 1
}

See also: back, move, Moving

back

Moves the turtle backwards along its heading. back d is forward -d.

back distance

Used in: creature code, reshape { } and lay { }.

Example

back 2
lay

See also: forward

move

Moves the turtle sideways, up and forward at once, without turning it.

move offset

Used in: creature code, reshape { } and lay { }.

Example

move (1, 2, 0)   // one to the side, two up
lay

See also: forward

pitch

Tips the turtle's nose down or up, turning about its side axis.

pitch angle

Used in: creature code, reshape { } and lay { }.

Remarks

• When the turtle is mirrored, every turn is the mirror image of what it would be unmirrored, so mirrored halves match.

Example

pitch -90   // now heading up
forward 3
lay

See also: yaw, roll, rotate, Turning

yaw

Turns the turtle left or right, about its up axis.

yaw angle

Used in: creature code, reshape { } and lay { }.

Example

yaw 90
forward 2
lay

See also: pitch, roll

roll

Rolls the turtle about its heading, like a plane rolling.

roll angle

Used in: creature code, reshape { } and lay { }.

Example

repeat 6 as i {
  branch {
    roll 60 * i
    pitch 90
    forward 2
    lay
  }
}

See also: pitch, yaw

rotate

Turns the turtle about any axis of its own.

rotate angle around axis

Used in: creature code, reshape { } and lay { }.

Remarks

• rotate a around (1, 0, 0) is the same as pitch a, rotate a around (0, 1, 0) as yaw a and rotate a around (0, 0, 1) as roll a.

Example

rotate 45 around (1, 1, 0)
lay

See also: pitch, yaw, roll

grow

Changes the turtle's size. Everything after it moves further and lays bigger shapes.

grow factor
grow factors

Used in: creature code, reshape { } and lay { }.

Remarks

• Sizes multiply: grow 2 twice makes the turtle 4 times its size.
• Each size stays with its own axis when the turtle turns.

Example

grow 2
lay
lay { grow (1, 0.2, 3) }   // a flat slab, this shape only

See also: mirror, Growing and mirroring

mirror

Reverses one of the turtle's axes, so everything after it is a mirror image.

mirror x
mirror y
mirror z

Used in: creature code, reshape { } and lay { }.

Remarks

• mirror x is the same as grow (-1, 1, 1). It flips turtle.mirrored.
• symmetric is the usual way to draw two mirrored halves.

Example

mirror x
yaw 30      // turns the other way now
forward 2
lay

See also: symmetric, grow

branch

Runs a block, then puts the turtle back exactly as it was.

branch { … }

Used in: creature code.

Remarks

• Everything about the turtle is saved and restored: position, direction, size, mirroring, shape transform, shape, colour, shine, sharpness, texture and wear.
• Variables changed inside aren't restored.

Example

repeat 5 as i {
  branch {
    yaw 72 * i
    forward 3
    lay
  }
}

See also: symmetric, Branches

symmetric

Runs a block twice: once as it is, and once mirrored. Each run is in its own branch.

symmetric x { … }
symmetric y { … }
symmetric z { … }

Used in: creature code.

Remarks

• Inside the block, the read-only variable side is 1 on the first run and -1 on the mirrored run. In the example it makes one side red and the other blue.
• symmetric x { … } is branch { … } followed by branch { mirror x; … }.

Example

symmetric x {
  colour mix(blue, red, side * 0.5 + 0.5)
  yaw 90
  forward 2
  lay
}

See also: mirror, branch, Symmetry

reshape

Changes the shape transform: an extra move, turn and stretch applied to every shape laid after it, without moving the turtle.

reshape { … }

Used in: creature code.

Remarks

• Inside the block, forward, back, move, pitch, yaw, roll, rotate, grow and mirror act on the shape transform, using its own axes and sizes. let, assignment and if are allowed too; nothing else is.
• It lasts until it's changed again or the enclosing branch ends.
• To change just one shape, use lay { … } (lay).

Example

reshape { grow (1, 0.3, 4) }
lay
forward 2
lay   // both shapes long and flat

See also: lay, The shape transform

5. Shapes and material

shape

Chooses the shape that later lays lay.

shape s

Used in: creature code.

Remarks

• The turtle starts with ball.
• The checker warns about a shape with no lay after it, which usually belongs before the lay it was meant for.

Example

shape cone
lay

See also: lay, Shapes

lay

Lays the current shape where the turtle is, in its current colour and material.

lay
lay { … }

Used in: creature code.

Remarks

• The shape fits a 1 × 1 × 1 box centred on the turtle, scaled by the turtle's size. Its length axis, where it has one, is the heading.
• lay { … } changes the shape transform for this one shape only. Inside the block the same commands are allowed as in reshape.
• Each shape keeps the colour, shine, sharpness, texture and wear it was laid with.
• A build stops with a warning after 50,000 shapes.

Example

shape tube
lay { grow (0.3, 0.3, 4) }   // a long thin tube

See also: shape, reshape

colour

Sets the colour of the shapes laid after it. color is the same word.

colour c
color c

Used in: creature code.

Remarks

• The turtle starts white.
• A gradient isn't a colour: sample it at a position, as colour skin(0.3) does in the example (gradient).
• Alpha below 1 makes shapes see-through, like the last ball in the example.

Example

let skin = gradient(green, yellow)

colour hsv(30, 0.8, 1)
lay
forward 1
colour skin(0.3)
lay
forward 1
colour hsv(200, 1, 1, 0.4)
lay

See also: hsv, Colours

shine

Sets how strong the highlights are on the shapes laid after it.

shine amount

Used in: creature code.

Example

shine 0.8
sharpness 0.9
lay

See also: sharpness, Material

sharpness

Sets how small and tight the highlights are on the shapes laid after it.

sharpness amount

Used in: creature code.

Example

shine 1
sharpness 0.2
lay

See also: shine

texture

Sets the texture of the shapes laid after it.

texture p

Used in: creature code.

Remarks

• The turtle starts with none.
• A textured shape shows the texture's colours with a fifth of its own colour mixed in. wear says how much of the texture shows.

Example

texture pattern(marble, 200, 7, dusk, pearl)
lay
texture none

See also: pattern, wear, Textures

wear

Sets how much of their texture the shapes laid after it show.

wear amount

Used in: creature code.

Remarks

• A gene for wear lets a creature fade its texture in and out as it morphs, dances and breeds.

Example

gene coat = 0.6 in 0..1

texture pattern(cells, 40, 3)
wear coat
lay

See also: texture

6. Backgrounds

background

Gives the creature the background it's shown against. A background file holds the same contents on its own.

background { … }
background Name

Used in: a creature's top level, at most once. background Name starts a background file.

Remarks

• The block may hold genes, let, assignment, if and exactly one fill, which comes last. It may use the library, time, beat and music.
• It's self-contained: it can't lay shapes or use the creature's genes, variables, parts or functions. It may use the creature's own pattern kinds.
• Its genes' full names start with background..
• Without one, the app shows its own default background.

Example

background {
  gene hue   = 260 in 0..360
  gene pulse = 30  in 0..90  // how far the colours shift with the bass

  fill pattern(aurora, hue + pulse * music.bass, 12)
}

See also: fill, Backgrounds

fill

Says what the background shows.

fill p

Used in: background blocks and files, as the last statement, exactly once.

Example

background {
  fill gradient(black, hsv(230, 0.8, 0.3))
}

See also: background

7. Dance styles

dance

Gives the creature its own dance style: how music moves the creature as a whole. A dance file holds the same contents on its own.

dance { … }
dance Name

Used in: a creature's top level, at most once. dance Name starts a dance file.

Remarks

• The block holds genes, lets and at most one line for each effect: morph, zoom, spin, turn, reverse and flat. An effect without a line is off.
• The block runs again at every moment of the dance, so inputs and settings can be expressions of time, beat, music and the block's genes and variables.
• Each effect's line starts with its name; the words after it can come in any order. Settings left out take their defaults.
• It's self-contained: it can't use the creature's genes or variables. Its genes' full names start with dance..
• The app may switch to another style while the creature dances.

Example

dance {
  gene drive = 1.1 in 0.3..3  // how fast the music pushes the morph

  morph follows music.mid speed drive settle 2
  zoom follows music.level amount 0.5 settle 15
  spin follows music.bass_hit from 45 to 170 smooth 0.4
  turn on music.mid changes by 1
}

See also: Dance styles

morph

Moves the creature along its morph loop (itself and its variants) at a speed the input sets. It coasts to a stop when the input is quiet.

morph follows x speed s settle t

Used in: dance blocks and files.

Example

dance {
  morph follows clamp(music.mid * 1.5 - 0.2, 0, 1) speed 1.5
}

See also: reverse, dance

zoom

Brings the creature towards the viewer as the input rises; it drifts back when the input falls.

zoom follows x amount a settle t

Used in: dance blocks and files.

Example

dance {
  zoom follows music.level amount 0.3
}

See also: dance

spin

Spins the creature about its spin axis, faster or slower with the input.

spin follows x from slowest to fastest smooth t

Used in: dance blocks and files.

Remarks

• With a turn line, the input is read each time the axis turns; without one, all the time.

Example

dance {
  spin follows music.bass_hit from 20 to 200 smooth 0.2
  turn on music.mid changes by 1
}

See also: turn

turn

Gives the spin a new, random axis each time the input triggers.

turn on x changes by d
turn on x drops by d
turn on x rises by d

Used in: dance blocks and files.

Remarks

• While flat is on, turn only counts drops, whatever its line says.
• See triggers and bursts.

Example

dance {
  turn on music.high drops by 0.6
}

See also: spin

reverse

Reverses the direction of the morph each time the input triggers.

reverse on x drops by d
reverse on x drops by d on n off m

Used in: dance blocks and files.

Example

dance {
  morph follows music.mid
  reverse on music.bass drops by 1 on 4 off 4
}

See also: morph, triggers and bursts

flat

Turns the creature face-on and spins it flat, in bursts, then back to tumbling in 3D.

flat on x drops by d
flat on x drops by d on n off m

Used in: dance blocks and files.

Remarks

• Each trigger while flat reverses the flat spin.

Example

dance {
  spin follows music.bass
  flat on music.level drops by 0.86 on 24 off 48
}

See also: spin, triggers and bursts

triggers and bursts

The words that say when turn, reverse and flat act.

on x changes by d
on x drops by d
on x rises by d
on n off m

See also: Dance styles

8. Pattern code

pattern blocks and files

Makes a new pattern kind, written in GenoCode, that pattern colours like a built-in one.

pattern Name { … }
pattern Name

Used in: a creature's top level, any number of times. pattern Name starts a pattern file.

Remarks

• The code runs once for each picture drawn, and ends with value p, where p is a picture. Its numbers run from 0 (dark) to 1 (light); values outside are cut off.
• It may hold genes, let, assignment, if, repeat, for, while and value, and use the library and the picture functions. It can't use the turtle, shapes, time, beat, music, or the creature's genes, variables, parts or functions.
• random draws from the recipe's seed, so each seed gives a different picture of the same kind, and always the same one.
• Its genes' full names start with its name: Ripples.rings.

Example

pattern Ripples
// Rings that wobble.

gene rings  = 8   in 2..20
gene wobble = 0.3 in 0..1

let turn = random(0, 360)
let lumps = clouds(5, 3)
value picture {
  let ripple = sin(r * rings * 180 + turn + lumps(x, y) * wobble * 360)
  value ripple * 0.5 + 0.5
}

See also: Your own patterns

picture

Makes a picture by running a block once for every pixel.

picture { … }

Returns: a picture.

Used in: pattern code, outside other picture { } blocks.

Remarks

• Inside the block, x, y, r and a say where the pixel is, and the block ends with value v, the pixel's number.
• A picture named on its own inside the block is its value at this pixel, as lumps is in the example. p(x, y) reads it at another point.
• random and the picture functions can't be used inside. Draw random settings before the block, as the example does with turn and lumps.
• Reading any picture p(x, y) blends the four nearest pixels. Outside −1..1 the picture is folded back, as in a mirror: in the example, lumps(x * 2, y) reads past the edges.

Example

pattern Rings

let turn = random(0, 1)
let lumps = clouds(4, 2)
value picture {
  let rings = wave(r * 4 + turn) * 0.5 + 0.5
  value rings * 0.6 + (lumps + lumps(x * 2, y)) * 0.2
}

See also: value, clouds

value

Ends pattern code, giving its picture, or a picture { } block, giving the pixel's number.

value v

Used in: pattern code, as the last statement.

Example

pattern Soft

value blur(clouds(), 12)

See also: picture

x, y, r and a

Where the pixel is, inside picture { }.

Used in: picture { } blocks. Elsewhere they're ordinary names.

Example

pattern Fan

value picture {
  value wave(a / 30) * 0.5 + 0.5
}

9. Debugging

print

Writes values to the app's console, to see what a program is doing.

print(value, value, …)

Used in: creature code and functions.

Remarks

• Strings are only allowed in print.

Example

print("size is", turtle.size)

10. Number functions

All of these can be used in gene declarations, since they give the same result every time.

abs

abs(x)

Returns: number. x without its sign: abs(-3) is 3.

sign

sign(x)

Returns: number. −1 if x is negative, 0 if it's 0, 1 if it's positive.

Example

yaw 30 * sign(turtle.position.x)

floor

floor(x)

Returns: number. x rounded down: floor(2.7) is 2, floor(-2.2) is −3.

See also: ceil, round

ceil

ceil(x)

Returns: number. x rounded up: ceil(2.2) is 3, ceil(-2.7) is −2.

See also: floor, round

round

round(x)

Returns: number. The nearest whole number, halves rounded up: round(2.5) is 3, round(-2.5) is −2.

See also: floor, ceil

frac

frac(x)

Returns: number. x minus its whole part, keeping the sign: frac(1.25) is 0.25 and frac(-1.25) is −0.25.

min

min(a, b)

Returns: number. The smaller of the two.

See also: max, clamp

max

max(a, b)

Returns: number. The larger of the two.

Example

grow max(0.2, 1 - turtle.position.y / 10)

See also: min, clamp

clamp

clamp(x, lo, hi)

Returns: number. lo if x is below it, hi if x is above it, otherwise x.

Example

let loud = clamp(music.level * 2, 0, 1)

See also: wrap, bounce

wrap

wrap(x, lo, hi)

Returns: number. x wrapped round into the range, as on a clock: wrap(370, 0, 360) is 10. hi itself wraps to lo.

Example

colour hsv(wrap(200 + time * 30, 0, 360), 0.8, 1)

See also: bounce, clamp

bounce

bounce(x, lo, hi)

Returns: number. x folded back and forth between lo and hi: as x rises steadily, the result climbs to hi, falls back to lo, climbs again, and so on. bounce(12, 0, 10) is 8.

Example

forward bounce(time, 0, 3)
lay

See also: wrap, wave

sqrt

sqrt(x)

Returns: number. The square root. A negative x gives "not a number", and shapes placed with it are left out with a warning.

exp

exp(x)

Returns: number. e (2.71828…) to the power x.

See also: ln

ln

ln(x)

Returns: number. The natural logarithm, so ln(exp(x)) is x.

See also: exp, log10

log10

log10(x)

Returns: number. The base-10 logarithm: log10(1000) is 3.

sin

sin(angle)

Returns: number from −1 to 1. The sine: sin(90) is 1.

Example

repeat 36 as i {
  branch {
    move (i * 0.5, 2 * sin(i * 20), 0)
    lay
  }
}

See also: cos, wave

cos

cos(angle)

Returns: number from −1 to 1. The cosine: cos(0) is 1.

See also: sin

tan

tan(angle)

Returns: number. The tangent: tan(45) is 1.

asin

asin(x)

Returns: number, in degrees from −90 to 90. The angle whose sine is x.

acos

acos(x)

Returns: number, in degrees from 0 to 180. The angle whose cosine is x.

atan

atan(x)

Returns: number, in degrees from −90 to 90. The angle whose tangent is x.

See also: atan2

atan2

atan2(y, x)

Returns: number, in degrees from −180 to 180. The angle of the point (x, y) from the x axis, correct in every quarter: atan2(1, -1) is 135.

Example

let p = turtle.position
yaw atan2(p.y, p.x)

degrees

degrees(r)

Returns: number. The same angle in degrees: degrees(pi) is 180.

See also: radians

radians

radians(d)

Returns: number. The same angle in radians: radians(180) is pi.

See also: degrees

wave

wave(t)

Returns: number from −1 to 1. sin(t × 360): 0, 1, 0, −1 and 0 again as t goes from 0 to 1, and repeating after that.

Example

yaw 20 * wave(time / 4)   // sways once every 4 seconds

See also: bump, sin

bump

bump(t)

Returns: number. sin(t × 180): rises from 0 to 1 and back to 0 as t goes from 0 to 1. Good for things that are thickest in the middle.

Example

repeat 10 as i {
  branch {
    grow 0.3 + bump(i / 9)
    lay
  }
  forward 1
}

See also: wave

mix

mix(a, b, t)

Returns: the same type as a. (1 − t)·a + t·b.

Remarks

• For numbers and vectors t isn't clamped, so t = 2 goes past b. For colours it's clamped to 0–1.
• Colours blend saturation, value and alpha in a straight line and hue the short way round.

Example

colour mix(red, yellow, 0.25)

See also: smoothmix, gradient

smoothmix

smoothmix(a, b, t)

Returns: the same type as a. Like mix, but it eases in and out: it moves slowly near a and b and fastest in the middle. It's mix(a, b, (1 − cos(180 × t)) / 2).

mandel

mandel(x, y)

Returns: number from 0 to 1. How quickly the point x + iy escapes the Mandelbrot set: the number of steps of z → z² + c before z grows past 2, up to 64, divided by 64. 1 means it never escaped.

Example

repeat 40 as i {
  branch {
    move (i * 0.25, 0, 0)
    grow 0.2 + mandel(i / 20 - 1.5, 0.3)
    lay
  }
}

11. Vector and list functions

vec

vec(x, y, z)

Returns: vector. The same as writing (x, y, z).

length

length(v)
length(l)

Returns: number. A vector's length, or how many items a list has.

Example

let far = length(turtle.position)
let points = [1, 2, 3]
repeat length(points) as i {
  forward points[i]
  lay
}

normalize

normalize(v)

Returns: vector. v scaled to length 1, pointing the same way. The zero vector stays zero.

dot

dot(a, b)

Returns: number. a.x·b.x + a.y·b.y + a.z·b.z. For two vectors of length 1 it's the cosine of the angle between them: 1 when they point the same way, 0 at right angles.

Example

let facing_up = dot(turtle.heading, y_axis)

cross

cross(a, b)

Returns: vector. The cross product: at right angles to both a and b.

12. Colours and gradients

hsv

hsv(h, s, v)
hsv(h, s, v, a)

Returns: colour.

Example

colour hsv(200, 0.8, 1)
colour hsv(0, 1, 1, 0.5)   // see-through red

See also: rgb, colour names, Colours

rgb

rgb(r, g, b)
rgb(r, g, b, a)

Returns: colour, kept as hue, saturation, value and alpha like every colour.

Example

colour rgb(1, 0.5, 0)   // orange, the same as #ff8000

See also: hsv

gradient

Makes a colour that changes along a line from 0 to 1.

gradient(stop, stop, …)
gradient(colour at position, …)
skin(t)

Returns: gradient. To get a colour out of it, write a position in brackets after it, as if calling it: skin(0.5).

Remarks

• Stops without a position: the first is at 0, the last at 1, and the others are spread evenly between their neighbours that have positions. In the example, yellow lands at 0.6, halfway between red at 0.2 and white at 1.
• Two stops at the same position make a sharp edge, as in flag.
• Between stops colours blend as in mix, hue the short way round.
• A gradient can be a fill, as in the example's background, but colour needs a sampled colour.

Example

let skin = gradient(black, red at 0.2, yellow, white at 1)
repeat 20 as i {
  colour skin(i / 19)
  forward 1
  lay
}

let flag = gradient(blue, blue at 0.5, white at 0.5, white)
colour flag(0.7)  // white: past the edge
lay

background {
  fill gradient(black, hsv(230, 0.8, 0.3))
}

See also: spectrum, Gradients

spectrum

Like gradient, but hue moves in a straight line between stops, through every hue in between, instead of the short way round.

spectrum(stop, stop, …)

Returns: gradient, sampled the same way.

Remarks

• spectrum(blue, red) goes from 240° down to 0°, through cyan, green and yellow; gradient(blue, red) goes through magenta.

Example

let rainbow = spectrum(hsv(0, 1, 1), hsv(300, 1, 1))
repeat 12 as i {
  colour rainbow(i / 11)
  forward 1
  lay
}

13. Noise and randomness

noise

Smooth noise: a number that wanders gently up and down as its input changes.

noise(x)
noise(v)

Returns: number from −1 to 1.

Remarks

• The same input always gives the same result, so creatures built with it still morph smoothly.
• noise(x) is noise((x, 0, 0)). Inputs close together give close results; about 1 apart they are unrelated.
• It isn't constant, so it can't be used in gene declarations.

Example

repeat 30 as i {
  pitch 15 * noise(i * 0.3)
  yaw 15 * noise(i * 0.3 + 100)
  forward 0.5
  lay
}

See also: fbm, random, Noise and randomness

fbm

Fractal noise: noise with finer detail on top.

fbm(x)
fbm(v)

Returns: number from −1 to 1. Five layers of noise, each at twice the detail and half the strength of the last.

Example

grow 1 + 0.3 * fbm(turtle.position)
lay

random

A random number between two others.

random(lo, hi)

Returns: number, from lo up to but not including hi.

Remarks

• Random numbers are the same every build. They come from a sequence started by the creature's seed gene, which a creature gets automatically when it uses random. Mutating the creature can change its seed.
• In pattern code the sequence starts from the recipe's seed instead, and no seed gene is made.
• Unlike noise, random numbers don't blend while morphing. Use noise for variation that should change smoothly.
• It isn't constant, so it can't be used in gene declarations.

Example

repeat 10 {
  branch {
    move (random(-3, 3), random(-3, 3), 0)
    grow random(0.3, 1)
    lay
  }
}

See also: noise

14. Texture functions

pattern

Makes a texture from a short recipe.

pattern(kind, hue, seed)
pattern(kind, hue, seed, scheme)
pattern(kind, hue, seed, scheme, finish)

Returns: pattern.

Remarks

• The same recipe always gives the same picture.
• Hue, scheme and finish only recolour the picture, so they can follow time and music smoothly. A new kind or seed draws a new picture, which takes a moment.
• All the arguments can be genes, so textures evolve with the creature. A pattern itself can't be a gene.

Example

gene coat_hue  = 200 in 0..360
gene coat_kind = marble from [marble, cells, aurora]

texture pattern(coat_kind, coat_hue, 7, dusk, pearl)
lay

See also: mixed, texture, fill, Textures

mixed

Mixes a second pattern kind into a pattern.

mixed(p, way, kind, amount)

Returns: pattern.

Remarks

• The second pattern takes its layout from p's seed, and the colours are always p's.
• A pattern holds at most one second pattern: mixing a mixed pattern replaces it.
• Mixing none gives none.

Example

texture mixed(pattern(cells, 40, 3), warp, vortex, 0.6)
lay

See also: pattern

15. Picture functions

These make and change pictures. They can only be used in pattern code, outside picture { }. Elsewhere their names are free: a creature may call a variable stretch.

clouds

Random cloudy noise, the usual start of a pattern.

clouds()
clouds(layers, grid)

Returns: picture, from 0 to 1. Each layer is twice as fine and half as strong as the last.

Remarks

• It takes its numbers from the random sequence, so each seed of the recipe gives different clouds.

Example

pattern Fog

value clouds(4, 2)

See also: blur, How they work

blur

Blurs a picture.

blur(p, width)
blur(p, across, down)

Returns: picture.

Example

pattern Streaks

value blur(clouds(), 40, 2)

zoom_blur

Streaks a picture outwards from the middle.

zoom_blur(p, s)

Returns: picture.

Example

pattern Rush

value zoom_blur(clouds(), 0.5)

stretch

Stretches a picture so it uses the whole range from dark to light.

stretch(p)

Returns: picture whose darkest point is 0 and lightest is 1.

Example

pattern Bright

value stretch(blur(clouds(), 30))

power

Raises every value of a picture to a power, to darken or lighten its middle tones.

power(p, e)

Returns: picture.

Example

pattern Dark

value power(clouds(), 3)

16. Inputs

Read-only values from outside the program. They can be used anywhere except pattern code.

time

time

Type: number. Seconds since the creature started being shown, from 0 upwards. It keeps running when no music is playing.

Remarks

• A creature that reads time, beat or music (outside its background and dance blocks) is rebuilt every frame. In still pictures, such as thumbnails, all three are 0.

Example

roll 45 * time   // turns 45 degrees a second
lay

See also: Time and music

beat

beat

Type: number from 0 to 1. Where the music is within the current beat: 0 on the beat, rising towards 1 just before the next. 0 when no music is playing.

Example

grow 1 + 0.2 * bump(beat)
lay

music

music.part

Type: number from 0 to 1, whatever the volume. All are 0 when no music is playing.

Example

gene flap = 30 in 0..70  // how hard the wings beat with the bass

symmetric x {
  roll 10 + flap * music.bass
  yaw 90
  forward 2
  lay
}

turtle

Reads the turtle's current state.

turtle.part

Used in: creature code and functions.

Remarks

• They describe the turtle, not the shape transform.

Example

while turtle.position.y < 5 {
  pitch -10
  forward 1
  lay
}

See also: Reading the turtle

17. Constants

Built-in names for fixed values. None of them can be used as the name of a gene, variable, parameter, part or function.

number constants

Example

repeat 50 as i {
  branch {
    yaw i * 360 / golden   // spreads them like seeds in a sunflower
    forward sqrt(i) * 0.5
    lay
  }
}

axis vectors

colour names

shapes

Every shape fits a 1 × 1 × 1 box centred on the turtle. The number is the one shape picks with a number.

pattern kinds

The first argument of pattern, and the third of mixed: sunburst, vortex, plasma, cells, kaleidoscope, interference, starburst, marble, lightning, aurora and bloom. Each is also written in GenoCode, in the patterns folder, as an example to read. A creature's own pattern blocks add more.

schemes

The colours of a pattern.

finishes

The surface of a pattern.

ways of mixing

How mixed adds a second pattern.

none

No texture. texture none lays plain shapes again; mixing none gives none.

18. Values and operators

literals

Comments are // to the end of the line, or /* … */.

operators

From the loosest to the tightest:

See also: Operators, Vector arithmetic

parts of values

Parts are read-only: to change one, make a new value.

Example

let c = turtle.colour
colour hsv(c.hue + 30, c.sat, c.val)