# robotkarol — Robot Karol worlds and block programs for teaching material

Version 3.6 (2026-08-23) — Anselm Wagner <anselm.wagner@posteo.de>

The `robotkarol` package draws worlds and Blockly-style block programs in the
visual style of the German teaching environment *Robot Karol Online*
(https://karol.arrrg.de/), for use in worksheets, exams, and slides.
Colours and proportions were measured from the original interface and
rebuilt with TikZ; no artwork is copied.

## Features

* `karolwelt` environment: full 2-D worlds rendered either as a 3-D
  oblique view (with room frame, brick stacks, markers, walls, and the
  Karol avatar) or as a 2-D top view matching the original interface.
* `\karolzeile`: compact string notation for one-row worlds
  (`\karolzeile{> Z 2 {2M} M Q}`), drawn with the very same building
  blocks as `karolwelt` — a one-row world is visually a `karolwelt` with
  `laenge=1`, only the input is shorter. Plus helpers for before/after
  pairs, empty grids, and legends.
* `karolbloecke` environment and block commands (`\bbefehl`,
  `\bwiederholemal`, `\bwenndannsonst`, …) reproducing the Blockly
  editor: exact colours, flat design, condition plugs, number pills,
  ghost blocks and empty sockets for cloze exercises.
* Inline blocks (`\ibefehl`, `\iwenndann`, `\iwiederholemal`, …) set a
  single block into running text: the block's text baseline sits exactly
  on the surrounding baseline, the label takes the surrounding font size,
  and the notches are shallower so the block's height stays close to the
  line height. Blocks that would span several lines in a stack appear
  inline with their header only.
* Two figures, switched with `\karolfigur{karol}` (default) or
  `\karolfigur{emma}` (long hair and a flower).
* The fonts of the online interface: labels in Noto Sans, program text in
  Hack (falling back to DejaVu Sans Mono when Hack is not installed).
  Load the package as `\usepackage[schrift=dokument]{robotkarol}` to use
  the document's own `\sffamily`/`\ttfamily` instead — that also avoids
  loading `fontspec`.
* `karolcode` environment for syntax-highlighted Karol source text and
  helpers for structograms (via `struktex`).
* All colours and dimensions adjustable through `\karolsetup`.

## Requirements

LuaLaTeX (the package warns if `\directlua` is missing), expl3, TikZ,
listings, struktex, graphicx, and — unless loaded with
`schrift=dokument` — fontspec and the Noto Sans fonts (both in TeX Live).

## Installation

Put `robotkarol.sty` where LaTeX finds it, e.g.

    TEXMFHOME/tex/latex/robotkarol/robotkarol.sty

and refresh the file database (`mktexlsr`) if your distribution needs it.
`robotkarol.cwl` is a command list for TeXstudio's auto-completion and
belongs in that editor's `completion/user` directory; it is not needed to
typeset documents.

## Files

| File | Purpose |
|---|---|
| `robotkarol.sty` | the package |
| `robotkarol-doc.tex`, `robotkarol-doc.pdf` | manual (German, English abstract) |
| `robotkarol-beispiel.tex`, `robotkarol-beispiel.pdf` | example document |
| `robotkarol-cheatsheet.md` | quick reference |
| `robotkarol.cwl` | TeXstudio auto-completion |

## Documentation

See `robotkarol-doc.pdf` (German, with an English abstract). A quick start:

```latex
\usepackage{robotkarol}
...
\begin{karolwelt}[breite=5, laenge=3]
  \karol[x=1, y=2, richtung=osten]
  \ziegel[x=2, y=2, anzahl=4]
  \marke[x=5, y=2]
\end{karolwelt}

Karol checks \iwenndann{IstZiegel} and repeats \iwiederholemal{5}.
```

## License

LaTeX Project Public License, version 1.3c or later
(https://www.latex-project.org/lppl.txt). This work has the LPPL
maintenance status `maintained`; the current maintainer is Anselm Wagner.

Copyright (C) 2026 Anselm Wagner <anselm.wagner@posteo.de>
