# robotkarol.sty v3.6 — Cheatsheet

Robot-Karol-Welten als Schrägbild und Blockprogramme in der Optik von
**Robot Karol Online** (<https://karol.arrrg.de/>) für die Reihe
**„Karol-Gesellenstück"** (Kl. 8, LB 1 Algorithmen).
Kompilierung mit **LuaLaTeX**, expl3 durchgehend. Lädt tikz, listings,
struktex, graphicx.

**Neu in v3.0:** `\karolzeile` zeichnet im selben Design wie die
`karolwelt`-Umgebung (→ §2), und Blöcke lassen sich als Inline-Blöcke in
den Fließtext setzen (→ §4).

---

## 1. Weltnotation

Ein Zeichen = ein Feld. **Leerzeichen im Weltstring werden ignoriert**
(zur Lesbarkeit erlaubt: `> Z . M Q`).

| Zeichen | Bedeutung |
|---|---|
| `>` `<` | Karol, Blick nach rechts / links |
| `^` | Karol, vom Betrachter abgewandt (Pfeil-Badge nach hinten) |
| `v` | Karol, dem Betrachter zugewandt (Pfeil-Badge nach vorn) |
| `.` | leeres Feld |
| `Z` | 1 Ziegel |
| `1` … `9` | Ziegelstapel der angegebenen Höhe |
| `M` | Marke (flache gelbe Platte) |
| `Q` | Quader / Wand |
| `{…}` | **mehrere Objekte auf EINEM Feld**, von unten nach oben |

Unbekannte Zeichen erzeugen eine Warnung und werden ignoriert.

### Gruppen `{…}` — das Neue in v2.0

```latex
{M>}    % Karol steht auf einer Marke
{2M}    % Marke liegt auf einem 2er-Stapel
{3>}    % Karol steht auf einem 3er-Stapel
{2M>}   % Karol auf Marke auf 2er-Stapel
```

Reihenfolge = Baureihenfolge von unten nach oben, wie im echten Karol.

---

## 2. Welten zeichnen

```latex
\karolzeile{>....Q}
\karolzeile[skalierung=0.8, nummern=false]{.MMMM{M>}.}
\karolzeile[hervorheben={2,4}]{..Z.Z>}      % Felder 2 und 4 markieren
\karolzeile[titel={\textbf{Soll}}, hinweis={Karol trägt 3 Ziegel.}]{>...}

\karolgitter{8}                            % leeres Gitter zum Eintragen

\karolpaar{>....Q}{....>Q}                 % vorher → nachher
\karolpaar[skalierung=0.95][titel={\textbf{Soll}}]{>Z.Z.Z}{..Z.Z>}
%          └ beide Bilder ┘└ nur „nachher" ┘
```

**Schlüssel** (für `\karolzeile`, `\karolgitter`, beide Optionen von
`\karolpaar`): `skalierung` (Faktor, Vorgabe 1), `nummern` (true/false),
`titel` (über dem Bild), `hinweis` (kursiv darunter),
`hervorheben` (Komma-Liste von Feldnummern), `rahmen` (true/false,
Vorgabe **false**), `hoehe` (Raumhöhe des Rahmens in Ziegellagen,
Vorgabe 3).

Die **Feldnummern stehen vor der vordersten Gitterkante** (blau, klein).
Im Schrägbild würde eine Nummer auf dem Feld von jedem Ziegelstapel
verdeckt; so bleibt die Zuordnung Zahl ↔ Feld immer lesbar.

**`hervorheben`** zeichnet einen **magentafarbenen** Rahmen knapp
außerhalb des Feldes und färbt dessen Nummer mit — rot wäre neben den
reinroten Ziegelkanten nicht zu erkennen. Farbe: `hervorfarbe`.

### Design ab v3.0

`\karolzeile` benutzt dieselben Zeichenbausteine wie die
`karolwelt`-Umgebung: gleiche Projektion, blaues Bodengitter, flache
dunkelrote Ziegel mit leuchtenden Lagenkanten, Markenplatte mit
Diagonalkreuz, grauer Quader, derselbe Avatar. **Eine Zeilen-Welt ist
optisch eine `karolwelt` mit `laenge=1`** — nur die Eingabe ist kürzer.
Den Raumrahmen (gestrichelte Wände, oberer Rahmen) zeichnet sie auf
Wunsch mit `rahmen`; für eine einzelne Reihe ist er meist zu wuchtig.

Die Marke ist — wie in der `karolwelt` — eine flache Platte ohne
Bauhöhe: `{M>}` setzt Karol auf die Marke, ohne ihn anzuheben.

### Figur wählen (v3.5)

```latex
\karolfigur{karol}    % Vorgabe: die schlichtere Figur
\karolfigur{emma}     % langes Haar, Blume in der Hand
\karolsetup{figur=emma}   % gleichwertig
```

Wirkt auf `\karolzeile` **und** `karolwelt`; in einer Gruppe gesetzt gilt
es nur dort. Emma ist aus derselben Figur gebaut wie Karol (Nachbau, keine
Kopie); ihre Farben `karolEmmaShirt`, `karolEmmaHaar`, `karolEmmaBluete`,
`karolEmmaStiel` lassen sich per `\colorlet` ändern.

### Schriften (v3.6)

Vorgabe sind die Schriften der Online-Oberfläche: Beschriftungen in
**Noto Sans**, Programmtext (`karolcode`, `\kb`, `\kw`) in **Hack**.
Dafür lädt das Paket `fontspec`. Noto Sans liegt in TeX Live, Hack nicht
— fehlt es im System, nimmt das Paket **DejaVu Sans Mono** (Hacks
Vorläufer) und schreibt das in die `.log`.

```latex
\usepackage[schrift=dokument]{robotkarol}   % \sffamily/\ttfamily wie bis v3.5
\karolsetup{schrift=karol}                  % zurück zur Karol-Schrift
\karolsetup{textschrift={\fontspec{Fira Sans}}}
\karolsetup{codeschrift={\ttfamily}}
\karolschrift \karolcodeschrift             % Umschalter für eigenen Text
```

- `schrift=dokument` ist **Paketoption**: nur so bleibt `fontspec`
  ungeladen. Zur Laufzeit umschalten geht trotzdem — aber `schrift=karol`
  ist dann wirkungslos (mit Warnung), die Schriften fehlen ja.
- `titel` und `hinweis` einer Welt bleiben absichtlich in der
  Dokumentschrift — sie sind Text, keine Beschriftung der Zeichnung.
- Mit `schrift=dokument` ist die Ausgabe pixelgleich zu v3.5 (geprüft).

### Volle Welten: `karolwelt`

```latex
\begin{karolwelt}[breite=5, laenge=4, hoehe=6, ansicht=3d]
	\karol[x=1, y=4, richtung=osten]
	\ziegel[x=2, y=3, anzahl=2, bisx=4]   % Bereich x=2..4
	\marke[x=5, y=1, farbe=cyan!60]
	\quader[x=4, y=2, bisy=3]             % \wand = Synonym
\end{karolwelt}
```

Koordinaten wie in Karol Online: `x` = Spalte von links, **`y` = Zeile
von hinten** (y=1 in 2D oben, in 3D hinten). `ansicht=2d` gibt die
Draufsicht. `richtung`: `osten`/`westen`/`norden`/`sueden` (Synonyme
`rechts`/`links`/`hinten`/`vorn`).

```latex
\karollegende                               % umbruchfähige Standardlegende
\karollegendenitem{{2M}}{Marke auf Stapel}  % eigener Legendeneintrag
```

---

## 3. Blockprogramme (Blockly-Stil)

```latex
\begin{karolbloecke}                        % optional: [skalierung=0.9]
	\bwiederholesolange{NichtIstWand}{%
		\bwenndann{IstZiegel}{%
			\bbefehl{Aufheben}}
		\bbefehl{Schritt}}
\end{karolbloecke}
```

| Kommando | Block |
|---|---|
| `\bbefehl[1]{Schritt}` | violetter Anweisungsblock; optionale Zahl als Pille |
| `\bwiederholemal{5}{…}` | Zählschleife (grün), Zahl als Pille |
| `\bwiederholesolange{Bed}{…}` | kopfgesteuerte Schleife (grün) |
| `\bwiederholeimmer{…}` | Endlosschleife |
| `\bwenndann{Bed}{…}` | einseitige Verzweigung (grün) |
| `\bwenndannsonst{Bed}{…}{…}` | zweiseitige Verzweigung mit sonst-Balken |
| `\bbedingung{IstZiegel}` | stahlblaues Rundrechteck mit **linkem Stecker**, auch inline |
| `\bist{Norden}` | Himmelsrichtung als **Auswahlmenü** (helle Pille + Dreieck) |
| `\bnichtist{Norden}` | dasselbe verneint (`NichtIst`) |
| `\bbedingung{}` bzw. `\bwiederholesolange{}{…}` | **weißer Leersockel** (Lücke) |
| `\bluecke[7em]` | gestrichelter Geisterblock für Lückenaufgaben |
| `\bkommentar{Text}` | Kommentarblock (khaki) mit `//`-Präfix, Karol-Platzhalterstil |
| `\baufruf[1]{TueEtwas}` | Aufruf einer eigenen Anweisung (rot); Name in einer **Auswahlpille mit Dreieck** |
| `\banweisung{TueEtwas}{…}` | Definition einer eigenen Anweisung (roter C-Block) |
| `\bhauptprogramm` | Hauptprogramm-Hut (graubraun, ohne obere Kerbe) |

- Innerhalb der `{…}`-Rümpfe Blöcke einfach untereinander schreiben;
  `%` am Zeilenende wie üblich gegen Leerzeichen.
- Verschachtelung beliebig tief (Schleife in Schleife, wenn in solange …).
- Für Blöcke im Fließtext → §4.

### Himmelsrichtungen (v3.1)

```latex
\bist{Norden}                    % eigenständiges Bedingungsplättchen
\bwenndann{\bist{Norden}}{…}     % als Bedingung eines Kontrollblocks
\bwiederholesolange{\bnichtist{Osten}}{…}
```

`\bist` / `\bnichtist` erkennen selbst, wo sie stehen: **allein** bauen
sie das ganze Plättchen, **innerhalb eines Blocks** nur dessen
Beschriftung — sonst säße ein Plättchen im Plättchen. Richtungen sind
freier Text (`Norden`, `Süden`, `Osten`, `Westen`).

Das **Auswahldreieck** hat die volle Blockfarbe auf der `!40!white`-Pille;
Seitenlänge 0.325 × Pillenhöhe, Spitze auf der Textgrundlinie (alles aus
der Oberfläche gesampelt). Denselben Menüpfeil trägt `\baufruf` — dort
wird die aufzurufende Anweisung ausgewählt; `\banweisung` (die
Definition) zeigt den Namen ohne Dreieck.

### Farben

Voreinstellung = **exakt aus der Karol-Online-Oberfläche gesampelt**
(systematische 91/165-Palette, Pillen als `blockfarbe!40` mit schwarzer
Schrift). Jeder Block trägt einen 3D-Anschliff wie im Original: jede
nach **oben oder links** zeigende Kante ist aufgehellt
(`blockfarbe!70!white`), jede nach **unten oder rechts** zeigende
abgedunkelt (`blockfarbe!80!black`), 0.045 em stark. Die Striche liegen
vollständig innerhalb des Blocks, sodass Blöcke exakt ineinander passen
und sich nicht überlagern. Das ist der leichte 3D-Anschliff des
Originals — und vor allem sorgt es dafür, dass
**gleichfarbige Blöcke voneinander abgesetzt** sind: ein grüner
`wenn`-Block in einer grünen Schleife wäre sonst nicht zu erkennen.
Beschriftungen sind wie im Original **normal** gesetzt, nicht fett.

| Schlüssel | Voreinstellung | betrifft |
|---|---|---|
| `befehlfarbe` | RGB 116,91,165 (violett) | `\bbefehl` |
| `schleifenfarbe` | RGB 91,165,91 (grün) | wiederhole-Blöcke |
| `verzweigungfarbe` | RGB 91,165,91 (grün) | wenn/dann |
| `bedingungfarbe` | RGB 91,128,165 (stahlblau) | `\bbedingung` |
| `anweisungfarbe` | RGB 165,91,98 (rot) | `\baufruf`, `\banweisung` |
| `kommentarfarbe` | RGB 165,150,91 (khaki) | `\bkommentar` |
| `hutfarbe` | RGB 130,123,117 | `\bhauptprogramm` |

**Ziegel wie im Original:** flacher dunkelroter Körper (RGB 150,8,8),
jede Lage auf allen Sichtflächen leuchtend rot (255,0,0) umrandet — die
Stapelhöhe ist seitlich abzählbar.

Weltfarben (wirken auf `\karolzeile` **und** `karolwelt`, die dieselben
Bausteine zeichnen):

| Schlüssel | Voreinstellung | betrifft |
|---|---|---|
| `feldbreite` | 8.4 mm | Kantenlänge eines Feldes |
| `ziegelfarbe` | reines Rot | Lagenkante; Körper = `!59!black` |
| `ziegelkoerperfarbe` | RGB 150,8,8 | nur die Ziegelflächen |
| `ziegelkantenfarbe` | RGB 255,0,0 | nur die Lagenkanten |
| `markenfarbe` | RGB 250,205,60 | Markenplatte |
| `quaderfarbe` | RGB 128,128,128 | Quader / Wand |
| `bodenfarbe`, `gitterfarbe` | RGB 45,45,215 | Bodengitter (Synonyme) |
| `hervorfarbe` | RGB 226,0,122 | `hervorheben` |

---

## 4. Inline-Blöcke im Fließtext (v3.0)

Die `\i…`-Kommandos setzen **genau einen Block in die laufende Zeile**:

```latex
Mit \iwenndann{IstZiegel} prüft Karol, ob ein Ziegel vor ihm liegt;
\iwiederholemal{5} wiederholt fünfmal, \ibefehl{Schritt} geht weiter.
```

- Die **Textgrundlinie des Blocks liegt exakt auf der Grundlinie des
  umgebenden Textes**, die Beschriftung übernimmt dessen **Schriftgröße**
  (im Stapel bleibt es bei `\footnotesize`).
- Kerbe, Nase und Innenabstände sind inline flacher, damit die Blockhöhe
  der Zeilenhöhe nahekommt.
- **Mehrzeilige Blöcke gibt es inline nicht.** Schleifen, Verzweigungen
  und eigene Anweisungen erscheinen nur mit ihrem Kopf —
  `\iwenndann{IstZiegel}` ergibt den Block „wenn ⟨IstZiegel⟩ dann". Für
  echte Rümpfe bleibt `karolbloecke` zuständig.

| Inline | entspricht im Stapel |
|---|---|
| `\ibefehl[3]{Schritt}` | `\bbefehl[3]{Schritt}` |
| `\iaufruf[2]{Treppe}` | `\baufruf[2]{Treppe}` |
| `\ianweisung{Treppe}` | Kopf von `\banweisung` |
| `\ikommentar{Text}` | `\bkommentar{Text}` |
| `\ihauptprogramm` | `\bhauptprogramm` |
| `\iwiederholemal{5}` | Kopf von `\bwiederholemal` |
| `\iwiederholesolange{Bed}` | Kopf von `\bwiederholesolange` |
| `\iwiederholeimmer` | Kopf von `\bwiederholeimmer` |
| `\iwenndann{Bed}` | Kopf von `\bwenndann` |
| `\isonst` | sonst-Balken von `\bwenndannsonst` |
| `\ibedingung{Bed}` | `\bbedingung{Bed}` |
| `\iist{Norden}` | `\bist{Norden}` |
| `\inichtist{Norden}` | `\bnichtist{Norden}` |
| `\iluecke[4em]` | `\bluecke[7em]` |

Die `\b…`-Kommandos **erkennen den Fließtext selbst** und setzen dort
ebenfalls inline; die `\i…`-Fassungen ersparen nur die leeren
Rumpf-Argumente und erzwingen den Modus auch im Stapel.

> **Stolperstein:** Inline-Blöcke sind breite, unzerbrechliche Kästen. In
> schmalen Spalten kann TeX sie nicht immer umbrechen — dann hilft
> `\sloppy` oder eine höhere `\tolerance` für den Absatz.

---

## 5. Unverändert aus v1.0

- `karolcode`-Umgebung (listings) mit `\kb{…}` / `\kw{…}`
- struktex-Wrapper, `\leeranweisung`, `\stklucke[Breite]`

---

## 6. Migration

Alte Weltstrings kompilieren unverändert weiter. Zu beachten:

1. **`{M>}`-Gruppen nutzen**, wo Karol auf Marke/Ziegel steht — die
   Kursiv-Hinweise („Karol steht auf der Marke") entfallen dann:
   - AB 5, B2 nachher: `.MMMM>.` → `.MMMM{M>}.`
   - AB 5, G2 nachher: `......>.` → `......{M>}.`
   - Lehrkraft-Dokument: W1.3, W2.4, W3.x analog prüfen.
2. Stapelziffern `2`/`3` rendern jetzt **echte Ziegelstapel**
   (vorher Ziffer im Quadrat) — Bildhöhen ändern sich leicht.
3. `\karollegende` ist jetzt umbruchfähiger Fließtext statt tabular —
   in `center`-Umgebungen wie bisher verwendbar.
4. Neu verfügbar: `hervorheben`, Stapel `4`–`9`, `\karolsetup`,
   gesamtes Blockmodul.

### v3.5 → v3.6

Blockbeschriftungen und Programmtext stehen jetzt in Noto Sans bzw.
Hack; **Blöcke werden dadurch etwas breiter und höher**, Umbrüche können
sich verschieben. Wer das alte Bild braucht:
`\usepackage[schrift=dokument]{robotkarol}`.

Vorgegeben ist wieder die Figur `karol`; wer Emma aus v3.5 behalten
will, schreibt `\karolfigur{emma}` in die Präambel.

### v3.0 → v3.1

Nur eine sichtbare Änderung: **`\baufruf` zeigt den Namen jetzt in einer
Auswahlpille mit Dreieck** statt als blanken Text — so wie in Robot Karol
Online. Alle anderen Blöcke sind unverändert.

### v2.x → v3.0

Alle Kommandos und Schlüssel bleiben gültig; **die Bilder sehen anders
aus**:

1. `\karolzeile` zeichnet im `karolwelt`-Design (steilere Projektion,
   blaues Gitter, Karol-Online-Farben). Die Bilder werden **höher und
   etwas breiter** — Layouts mit knappem Platz prüfen.
2. Feldnummern stehen jetzt **unter** dem Gitter statt auf der
   Kachel-Stirnfläche.
3. `hervorheben` ist **magenta** statt rot (`hervorfarbe` stellt es um).
4. Die Marke hebt Karol nicht mehr an (flache Platte wie in der
   `karolwelt`).
5. `\karollegende` ist kleiner skaliert (0.42) und bricht um.
6. `ziegelfarbe` setzt jetzt die leuchtende **Lagenkante** und leitet den
   Körper daraus ab (59 %). `ziegelkoerperfarbe` / `ziegelkantenfarbe`
   steuern beide Flächen weiterhin einzeln — **nach** `ziegelfarbe`
   setzen.
7. Der Name `\karolwelt` gehört seit v3.0 der **Umgebung**; die
   Zeilen-Welt heißt `\karolzeile`.

---

## 7. Interna / Stolpersteine (expl3)

- pgf schaltet im Bildkontext auf `\nullfont`: **Boxen immer VOR dem
  `tikzpicture` füllen**, nie darin (sonst leere Box ohne Fehler).
- Aus demselben Grund ist **`em`/`ex` in Pfadkoordinaten innerhalb des
  Bildes = 0pt** — em-Maße vor dem Bild in dim-Register auslagern
  (degenerierte Pfade + rounded corners erzeugen sonst Mini-Bogen-Artefakte).
- fp-Variablen in pgfmath-Koordinaten stets mit `\fp_use:N`.
- eTeX-Dim-Ausdrücke kennen kein `-(…)` — `0pt-(…)` schreiben.
- Ziffern sind in expl3-CS-Namen unzulässig (`\l__x_bm2_dim` zerfällt).
- Blockstapelung: `\baselineskip=0`, `\lineskiplimit=\maxdimen`;
  Bounding-Box ohne Nase, damit die Nase in die Kerbe des Folgeblocks ragt.
  Inline dagegen zählt die Nase mit (Zeilenabstand).
- `rounded corners` **überläuft**, wenn ein Segment kürzer als zwei
  Eckradien ist → pgf zeichnet einen entarteten Bogen, der als Spitze
  heraussticht. Fällt nur bei gestrichenen Pfaden auf (`\bluecke`),
  nicht bei `fill`+`draw=none`. Deshalb: an Kerbe und Nase
  `sharp corners`, nur die Außenecken runden. Der Modus muss **vor**
  der betroffenen Koordinate stehen.
