ludus/turtle-graphics.md
2024-07-20 16:34:12 -04:00

3.6 KiB

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.