@genocode/core 0.3.0 → 0.5.0

package/reference/LANGUAGE.md

@@ -167,7 +167,7 @@ allowed as arguments to `print`.
 creature  gene  part  function  return  let  if  else  repeat  as  for  from  to  by  while
 branch  lay  reshape  symmetric  shape  colour  color  shine  sharpness  texture  background
 fill  dance  forward  back  move  pitch  yaw  roll  rotate  around  grow  mirror  in  step  log
-at  and  or  not  true  false  print  turtle  time  beat  music
+at  and  or  not  true  false  print  turtle  time  beat  music  variant
 ```
 
 Some words are only special in one place, and are ordinary names elsewhere:
@@ -176,7 +176,8 @@ Some words are only special in one place, and are ordinary names elsewhere:
 - the effect names `morph`, `zoom`, `spin`, `turn`, `reverse` and `flat` inside a `dance` block.
 
 **Built-in names**, such as the library functions, constants, colour names, shape names and pattern
-kinds, can't be used as names of genes, variables, parameters, parts or functions.
+kinds, and the words `gradient` and `spectrum`, can't be used as names of genes, variables, parameters,
+parts or functions.
 
 `colour` and `color` mean the same thing everywhere, including in `turtle.colour` / `turtle.color`.
 
@@ -303,6 +304,46 @@ part wing(reach, side) { … }
 - A part gene can only be called. It can't be stored in a variable, passed as an argument or
   compared.
 
+### 6.6 Variants
+
+A creature can keep other sets of gene values alongside its own: its **variants**. Together with
+the creature itself, they form a family of related creatures that share one program, such as the
+members of an evolved population.
+
+```
+creature Cobra
+
+gene hood  = 1.2 in 0.5..2  // how wide the hood spreads
+gene coils = 3   in 1..6 step 1
+gene skin  = hsv(120, 0.7, 0.8) in hsv(60, 0.3, 0.5)..hsv(180, 1, 1)
+
+grow hood
+repeat coils {
+  colour skin
+  forward 1
+  lay
+}
+
+variant Coiled { coils = 6; hood = 0.8 }
+
+variant Striker {
+  hood = 2
+  skin = hsv(70, 0.9, 1)  // bright, to warn others off
+}
+```
+
+- `variant Name { … }` sets genes by their **full names** ([6.3](#63-full-names)), one per line
+  (or separated by `;`): `petals = 9`, `whorl.petals = 9`, `background.hue = 200`, `seed = 42`.
+  Genes it doesn't mention keep the values written in their declarations.
+- Variants can only be at the top level of a creature file. Their names must be different from one
+  another; they don't clash with any other names.
+- Each value is a constant expression ([6.1](#61-declaring-genes)) that would be allowed as the
+  gene's own value: of the gene's kind, within its range, one of its options, or one of its parts.
+  A gene can be set at most once in a variant.
+- Variants don't change what the program does. They are used by the app wherever it wants a
+  group of related creatures ([section 19](#19-genetics)), for example as the loop a creature
+  morphs through.
+
 ## 7. Variables
 
 ```
@@ -564,7 +605,7 @@ opacity: 1 is solid and 0 is invisible.
 
 **Blending two colours** (in `mix`, `smoothmix`, gradients and morphing) blends saturation, value
 and alpha in a straight line, and hue the short way round the circle. Hues exactly 180 degrees
-apart blend in the increasing direction.
+apart blend in the increasing direction. Spectrums ([13.3](#133-gradients)) are the one exception.
 
 The named colours are:
 
@@ -610,6 +651,15 @@ repeat 20 as i {
   last stop it's the last stop's, and between two stops it's those two colours blended
   ([13.1](#131-colours)).
 
+**Spectrums.** `spectrum(…)` is written and sampled like `gradient(…)`, with one difference: between
+two stops, hue moves in a straight line from one number to the other, never across 0°. So
+`spectrum(blue, red)` passes through cyan, green and yellow (240° down to 0°), where
+`gradient(blue, red)` goes the short way, through magenta.
+
+```
+let flame = spectrum(hsv(60, 1, 1), hsv(0, 1, 1), hsv(280, 1, 0.5))   // yellow, red, then back through every hue to violet
+```
+
 ## 14. Textures
 
 Textures are generated from a recipe of a few values, so they can be genes and evolve with the
@@ -801,7 +851,7 @@ All angles are in degrees.
 
 ### 18.3 Colours
 
-`hsv(…)`, `rgb(…)`, `mix(a, b, t)`, `smoothmix(a, b, t)` and `gradient(…)`, plus the colour names in
+`hsv(…)`, `rgb(…)`, `mix(a, b, t)`, `smoothmix(a, b, t)`, `gradient(…)` and `spectrum(…)`, plus the colour names in
 [13.1](#131-colours) and the parts `.hue`, `.sat`, `.val` and `.alpha`.
 
 ### 18.4 Reading the turtle
@@ -910,14 +960,15 @@ Values aren't limited to either creature's range while morphing.
 
 A morph through several creatures (a loop) is a chain of these morphs between neighbours. When A
 and B share a program, a morph is smooth all the way; when their programs differ, the creature
-changes shape at the halfway point.
+changes shape at the halfway point. A creature with variants ([6.6](#66-variants)) has a loop of its
+own: the creature itself, then each variant in the order they're written.
 
 ### 19.4 Saving
 
 A creature that has been mutated, bred or morphed is saved as an ordinary creature file: its
 program, with each gene's new value written into the gene's line. Nothing else in the program
 changes, except that the file is laid out by the formatter, and a gene whose value hasn't changed
-keeps the text it was written with. The new values are written readably: stepped numbers exactly,
+keeps the text it was written with. Variants are kept as they are. The new values are written readably: stepped numbers exactly,
 other numbers to four significant figures, colours as `hsv(…)`, and choices by name, always within
 the gene's range. The automatic `seed` gene has no line of its own, so it isn't saved yet: a saved
 creature that uses `random` starts again from seed 0.
@@ -992,7 +1043,9 @@ dance_file    = "dance" NAME NL dance_body ;
 
 item          = gene | part | function | statement
               | "background" "{" bg_body "}"
-              | "dance" "{" dance_body "}" ;
+              | "dance" "{" dance_body "}"
+              | "variant" NAME "{" { gene_ref "=" expr NL } "}" ;
+gene_ref      = ( NAME | "background" | "dance" ) { "." NAME } ;
 
 gene          = "gene" NAME "=" expr [ gene_range ] NL ;
 gene_range    = "in" expr ".." expr [ "step" expr | "log" ]
@@ -1054,7 +1107,7 @@ primary       = NUMBER | HEX_COLOUR | STRING | "true" | "false"
               | "turtle" "." NAME | "time" | "beat" | "music" "." NAME
               | "(" expr ")"
               | "(" expr "," expr "," expr ")"
-              | "gradient" "(" stop "," stop { "," stop } ")" ;
+              | ( "gradient" | "spectrum" ) "(" stop "," stop { "," stop } ")" ;
 stop          = expr [ "at" expr ] ;
 args          = expr { "," expr } ;
 ```