From dd3867968e3cbd48357d4c4707b1db872272a1e5 Mon Sep 17 00:00:00 2001 From: Scott Richmond Date: Sat, 20 Jul 2024 16:34:12 -0400 Subject: [PATCH] add description of turtle graphics protocol --- turtle-graphics.md | 63 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 turtle-graphics.md diff --git a/turtle-graphics.md b/turtle-graphics.md new file mode 100644 index 0000000..2c95748 --- /dev/null +++ b/turtle-graphics.md @@ -0,0 +1,63 @@ +# 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. +