75 lines
4.3 KiB
Markdown
75 lines
4.3 KiB
Markdown
# 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.
|
|
* `penwidth`, 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.
|
|
* `loadstate`, x: number, y: number, heading: number, pendown: boolean, width: number, color: string OR r: number, g: number, b: number, a: number
|
|
- Loads a turtle state.
|
|
* `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.
|
|
|
|
**Colors aren't always RGBA.**
|
|
For pen-and-paper turtles, we don't have RGBA colors.
|
|
Colors should also be specifiable with strings corresponding to CSS basic colors: black, silver, gray, white, maroon, red, purple, fuchsia, green, lime, olive, yellow, navy, blue, teal, and aqua.
|
|
|
|
**Turtles should maybe communicate states.**
|
|
Ludus should have access to turtle states.
|
|
This is important for push/pop situations that we use for L-systems.
|
|
There are two ways to do this: Ludus does its own bookkeeping for turtle states, or it has a way to get the state from a turtle.
|
|
|