# Turtle Graphics protocol

name: "turtle-graphics"

version: 0.1.0

### Description
Turtle graphics describe the movements and drawing behaviours of screen, robot, and print "turtles."
* `proto`: `["turtle-graphics", "{version number}"]`
* `data`: an array of arrays; each array represents a turtle command; the first element of a command array is the verb; any subsequent items are the arguments to the verbs.
* Valid arguments are numbers, strings, and booleans.
* Depending on what we end up doing, we may add arrays of these, representing tuples or lists, and/or objects with string keys whose text are well-formed keywords in Ludus. For now, however, arguments must be atomic values.
* E.g., `["forward", 100]`
* Each turtle has its own stream.
* At current, this protocol describes the behaviour of turtle-like objects, all of which "live" in the same "world"; there is not yet a provision for multiple canvases/worlds. That said, an additional field for "world" in at the top level may well be added in the future to allow for multiple worlds to unfold at the same time.

### Verbs and arguments
* `forward`, steps: number
  - Moves the turtle forward by the number of steps/pixels.
* `back`, steps: number
  - Moves the turtle backwards by the number of steps/pixels.
* `right`, turns: number
  - Turns the turtle right by the number of turns. (1 turn = 360 degrees.)
* `left`, turns: number
  - Turns the turtle to the left by the number of turns. (1 turn = 360 degrees.)
* `penup`, no arguments
  - "Lifts" the turtle's pen, keeping it from drawing.
* `pendown`, no arguments
  - "Lowers" the turtle's pen, starting it drawing a path.
* `pencolor`, red: number, green: number, blue: number, alpha: number, OR: color: string
  - Sets the turtle's pen's color to the specified RGBA color.
* `pendwidth`, width: number
  - Sets the width of the turtle's pen, in pixels (or some other metric).
* `home`, no arguments
  - Sends the turtle back to its starting point, with a heading of 0.
* `goto`, x: number, y: number
  - Sends the turtle to the specified Cartesian coordinates, where the origin is the turtle's starting position.
* `setheading`, heading: number
  - Sets the turtle's heading. 0 is the turtle's starting heading, with increasing numbers turning to the right.
* `show`, no arguments
  - Shows the turtle.
* `hide`, no arguments
  - Hides the turtle.
* `clear`, no arguments
  - Erases any paths drawn and sets the background color to the default.
* `background`, red: number, green: number, blue: number, alpha: number
  - Sets the background color to the specified RGBA color, OR: color: string

These last two feel a little weird to me, since the background color is more the property of the **world** the turtle is in, not the turtle itself. Worlds with multiple turtles will be set up so that _any_ turtle will be able to change the background, and erase all paths.

That said, since we don't yet have a world abstraction/entity, then there's no other place to put them. This will likely be shifted around in later versions of the protocol.

### Other considerations
**Not all turtles will know how to do all these things.**
The idea is that this single abstraction will talk to all the turtle-like things we eventually use.
That means that some turtles won't be able to do all the things; that's fine! 
They just won't do things they can't do; but warnings should go to `stderr`.

**Errors are not passed back to Ludus.** 
These are fire-off commands.
Errors should be _reported_ to `stderr` or equivalent.
But Ludus sending things to its output streams should only cause Ludus panics when there's an issue in Ludus.