# PrimaSTEM Simulator: guide for AI assistants

Also available as https://simulator.primastem.com/ai (HTML page) and https://simulator.primastem.com/ai.txt (plain text).

## 1. What this is

https://simulator.primastem.com is a browser copy of the PrimaSTEM control board and its drawing robot (a ladybug with a marker). A program is a set of tiles placed into the board's cells; the robot executes them on a square field and draws its path. The whole scene (program, settings, robot start pose, optional maze) fits into a share link, and `&run` makes the program start by itself after the page opens. The page is a JavaScript app, so you cannot "use" it by reading it; you build the link from the rules below.

### How to answer a user

1. Translate the task into board tiles (sections 3 and 4).
2. Pick a robot start pose that keeps the whole figure on the field (section 5).
3. Give the user one complete link that ends with `&run`. It opens the simulator, loads the program and starts it about 4 seconds later.
4. In plain words, say what the program does and where the tiles sit ("top row: Function x10; function row: Forward 100, Right 36"), so the user can rebuild it on a real board. The user can press the round Start button to run it again.

Copy the structure of a worked example (section 6) and change only what you need. Every example link there was opened and checked in a browser.

### Before you answer: self-check (mandatory)

- [ ] **Rows.** `top=` lists at most 6 pairs, `fn=` at most 5, separated by commas. Each pair is `command` or `command.value` (one dot, no spaces). Use `top=`/`fn=`, not the old `p=`.
- [ ] **Pairs.** One command plus at most one value; no number next to `cfun` or `crnd`; a number and a repeat never share a pair.
- [ ] **Trace.** Go through the program step by step and write down the (x, y) of every corner. Every point must stay within 60 ... (N*150 - 60) mm, i.e. 60 ... 840 on the default 6x6 field.
- [ ] **Same pose.** The `&r=x-y-h` in the link is exactly the start pose you described and traced.
- [ ] **Codes.** Every value is a 4-character code: `n`/`r`/`a`/`s`/`m`/`d`/`e` plus 3 digits (`n045`, `r007`), or `sqrt`/`rrnd`.

## 2. Link grammar

```
https://simulator.primastem.com/#top=<pairs>&fn=<pairs>&s=<8 chars>&r=<x>-<y>-<heading>[&m=<maze>][&sh=<shape>][&lang=<xx>]&run
```

Everything after `#` is a fragment; parameters may come in any order. No URL-encoding is needed: all characters are `a-z 0-9 . , - & = #`.

| Param | Value | Meaning |
|---|---|---|
| `top` | up to 6 pairs, separated by `,` | The top row (the main program), pairs 1-6 from the left. |
| `fn` | up to 5 pairs, separated by `,` | The function row (a subroutine), pairs 1-5. Leave `fn` out when the program has no Function tile. |
| `s` | 8 characters, read by position | View settings (table below). If omitted: light theme, marker on, grid ON, speed x1, field 6x6, flat view. |
| `r` | `x-y-heading` | Robot start: centre in mm and heading in degrees. Use integers, heading 0-359. **Always include it**: without `r` the robot starts in a random cell. |
| `m` | digit pairs `cr` | Optional maze (section 6.8). Turns the grid and maze mode on. |
| `sh` | `square triangle star house circle spiral` | Optional "Repeat the shape" task: turns the grid off and challenge on, shows that target contour and puts the robot on its start (the task sets the start, so `r` is ignored). A run that draws the contour within 15 mm gets the win card. A maze (`m`) wins if both are given. |
| `lang` | `en fr es it nl de sv nb pl ru uk da ca pt fi tr ja he ar` | Optional UI language. Without it the page follows the visitor's saved choice or browser language. |
| `run` | `&run` or `&run=N` | Start the program automatically, N seconds (default 1, at most 3600) after the 3-second splash. Needs at least one non-empty pair in the top row. |
| `embed` | `&embed=play` or `&embed=full` | Only for a link placed in an `<iframe>` on another site. `play` shows the board and field run-only (Start replays from the start pose, nothing can be edited); `full` shows the whole simulator, editable, starting from the link's scene. Leave it out of links the user opens directly. |

### Pairs

The board has a top row of 6 pairs and a function row of 5 pairs; each pair holds a command tile and, optionally, one value tile. In the link a pair is written as

- `cfor` (a command alone), or
- `cfor.n400` (the command, a dot, the value). Write the command first; `n400.cfor` is read the same way.

Pairs are separated by commas and fill the row from the left: `top=cfor.n400,crig,cfor.n300` is Forward 400 in pair 1, Right in pair 2, Forward 300 in pair 3; pairs 4-6 stay empty. Nothing needs counting: write only the pairs you use. Examples:

- Forward 400, then Right: `#top=cfor.n400,crig`
- Function x8, which runs Forward 120, Right 45: `#top=cfun.r008&fn=cfor.n120,crig.n045`

Two commas in a row (`cfor,,crig`) leave an empty pair in between, which the robot skips; you never need that. More than 6 pairs in `top` (or 5 in `fn`) do not fit on the board and are ignored. A pair with more than two codes, two commands, or a value without a command is an error pair (red LED, skipped), as on the real board.

The older 22-field `p=` form still works (section 9). If a link has both, `p=` wins and `top`/`fn` are ignored.

### The 8 characters of `s`

| # | Char | Values | Meaning |
|---|---|---|---|
| 1 | theme | `l` light, `d` dark, `w` white (print) | Look only. |
| 2 | marker | `1` pen down, `0` pen up | Must be `1` to draw. |
| 3 | grid | `1` on, `0` off | Grid on = map/maze look with cell lines. Off = plain sheet for drawings. Does not change how commands move. |
| 4 | speed | `1` `2` `4` `8` | Speed multiplier. `1` is the real robot's pace. |
| 5 | age | `4` (ages 4-6), `7` (ages 7-10) | Which tiles the tray offers. Use `7` when the program has numbers or arithmetic. |
| 6 | field | `4`-`9` | Field is N x N cells of 150 mm. Default 6. |
| 7 | map opacity | `0` `1` `2` | Background map 100/66/33 %. Use `0`. |
| 8 | view | `2` flat, `3` 3D tilt | Use `2` unless the user wants the 3D look. |

Every character is read by its position, so write all 8. An invalid character leaves that setting at its default.

Ready-made values:
- drawing a figure: `s=l1047602` (light, marker on, grid off, x4, ages 7-10, 6x6, flat)
- cell-to-cell / maze task: `s=l1144602` (grid on, x4, ages 4-6)

## 3. Tile codes

| Code | Tile | Pairs with |
|---|---|---|
| `cfor` | Forward (move, mm) | nothing, a repeat, a number or arithmetic |
| `cbac` | Back (move backwards, mm) | same as Forward |
| `clef` | Left (turn counter-clockwise, degrees) | same as Forward |
| `crig` | Right (turn clockwise, degrees) | same as Forward |
| `cwat` | Pause (seconds) | same as Forward |
| `cfun` | Function: run the 5 function-row pairs | nothing or a repeat. A number/arithmetic is an ERROR |
| `crnd` | Random move: one cell (150 mm) forward, back, or turn 90 then forward | nothing or a repeat. A number/arithmetic is an ERROR |
| `r002`-`r999` | Repeat N times (`r002`-`r006` are the dotted tiles) | one command |
| `rrnd` | Dice repeat: random 1-6 times each run | one command |
| `n001`-`n999` | Number: sets the command's amount | Forward, Back, Left, Right, Pause |
| `a001`-`a999` | Arithmetic: add N to the command's saved amount | same as a number |
| `s001`-`s999` | Arithmetic: subtract N | same |
| `m001`-`m999` | Arithmetic: multiply by N | same |
| `d001`-`d999` | Arithmetic: divide by N | same |
| `e001`-`e999` | Arithmetic: raise to the power N | same |
| `sqrt` | Arithmetic: square root | same |

Values are always 3 digits with leading zeros: 45 is `n045`, 7 repeats is `r007`. An unknown code becomes a red error cell.

## 4. Program rules

- **A pair = one command + at most one value.** The value is ONE of: a repeat, a number, an arithmetic tile. A command alone is fine. Anything else is an error pair (red LED, skipped): two commands, two values, a value without a command.
- **You cannot put a number and a repeat in the same pair.** "Forward 100, four times" is not one pair. Use the function row: top row `cfun.r004`, function row `cfor.n100`.
- **Function or Random move + number/arithmetic = error.** Function + repeat is correct and is how loops are made.
- **Order.** The top row runs left to right, pairs 1-6; empty pairs are skipped. `cfun` runs the function-row pairs 1-5 left to right, then returns to the top row. So the top row holds at most 6 steps and the function row at most 5.
- **Repeats inside the function row work** (`cfor.r003` there is fine), which gives a loop inside a loop.
- **A `cfun` inside the function row recurses forever** (the robot never stops until Start is pressed). Avoid it in `&run` links unless the user wants an endless pattern.
- **Units.** Forward/Back: millimetres. Left/Right: degrees. Pause: seconds. Numbers 1-999 only.
- **Defaults when a command has no value:** Forward 150 mm, Back 150 mm, Left 90, Right 90, Pause 1 s. 150 mm is exactly one grid cell.
- **Saved amounts.** Each command remembers its last amount separately (Forward and Back are separate, Left and Right are separate). A number replaces the saved amount; arithmetic changes it (`cfor.a030` = forward 30 mm more than last time); a command alone reuses it. Example: `cfor.n100`, then `cfor` alone moves 100 again.
- **Negative amounts reverse direction** (`clef` whose amount went below 0 turns right). Division by 0 and the square root of a negative leave the amount unchanged.
- **Saved amounts survive between runs** in the same page (only the board's power button resets them). A link always starts from the defaults, but when the user presses Start again, arithmetic continues from where the last run ended. Put a number on the first use of any command you change with arithmetic, so a second run repeats the first.
- **More than 6 steps:** the top row holds only 6 pairs. Put the repeated part in the function row (up to 5 pairs) and call it from the top row with `cfun` (plus a repeat to loop it). The top row then has room for the steps around the loop (see the house, 6.9).
- **Numbers above 999:** split them. Forward 1200 = `cfor.n600` then `cfor` (reuses 600).
- **Angles that are not integers:** set a big amount and divide it. `crig.n360` (one full spin) then `crig.d007` (turns 51.43 and keeps 51.43 as the saved amount); after that `crig` alone turns 360/7. See the heptagon example.

Timing at x1: 150 mm takes 1.75 s, a 90 turn about 0.8 s, plus a 0.14 s beat after every pair and before each function call. Speed x2/x4/x8 divides all of it. The robot speaks only when a person presses Start at x1; the `&run` start is always silent.

## 5. Geometry

- **Field:** N x N cells of 150 mm, so 900 x 900 mm at the default 6x6. Origin (0,0) is the top-left corner; x grows to the right, y grows DOWN. The cell in column c, row r (both from 0) has its centre at (150c + 75, 150r + 75). On screen the columns are labelled A, B, C... from the left and the rows 1, 2, 3... from the top, so cell "B3" is c = 1, r = 2, centre (225, 375).
- **Heading:** 0 = up (towards y = 0), 90 = right, 180 = down, 270 = left. Right turns are clockwise on screen and add to the heading; left turns subtract.
- **A move of d mm** from (x, y) with heading h ends at (x + d*sin h, y - d*cos h).
- **The robot is a 120 mm disc.** Its centre (the pen) cannot leave the band [60, 900 - 60] = [60, 840] on a 6x6 field. A move that would cross it stops at the edge and the program continues, so the figure comes out distorted. Keep every corner of the path inside [100, 800] to be safe.
- **Planning recipe:** (1) choose the side length; (2) trace from an arbitrary start, e.g. (0, 0) heading 0, and note the min/max x and y; (3) shift the start so the figure's box is centred on the field (centre 450, 450 on 6x6): start = (0,0) + (450 - (minx+maxx)/2, 450 - (miny+maxy)/2); (4) trace again from that start and check every corner is within [60, 840].
- **Before you answer, trace the path** (start pose, every move and turn) and check the min/max of x and y. Pseudocode:

```
x, y, h = start
for each step: if move d: x += d*sin(h deg); y -= d*cos(h deg); track min/max
               if turn a: h += a   (right +, left -)
```

- **Regular polygon with n sides of length s, turning right by 360/n:** circumradius R = s / (2 sin(180/n)), apothem a = s / (2 tan(180/n)). Starting with heading 90 (moving right), the polygon lies below its first side. To centre it at (cx, cy), start at (cx - s/2, cy - a) with heading 90. It closes when n x turn is a multiple of 360. Fits a 6x6 field when 2R is under about 700 mm.
- **Field size and speed:** a bigger figure needs a bigger field (`s` char 6: up to 9, i.e. 1350 mm). For drawings recommend speed x4 (`s` char 4 = `4`): at x1 a 36-step circle takes over half a minute. Use x1 only when the user wants the real robot's pace.
- **Drawing settings:** marker on (`1`), grid off (`0`). Grid on is for cell-by-cell tasks.

## 6. Worked examples

All on a 6x6 field. Each link was opened in a browser, ran to the end and stayed on the field.

### 6.1 Square (side 300 mm)

Top row: Function x4. Function row: Forward 300, Right (default 90). Start (300, 600), heading 0; the square spans x 300-600, y 300-600.

https://simulator.primastem.com/#top=cfun.r004&fn=cfor.n300,crig&s=l1047602&r=300-600-0&run

For ages 4-6 (no numbers): `cfor` alone gives 150 mm sides, `crig` alone 90.

### 6.2 Equilateral triangle (side 400 mm)

Function x3: Forward 400, Right 120. Start (250, 623), heading 30, so the base is horizontal.

https://simulator.primastem.com/#top=cfun.r003&fn=cfor.n400,crig.n120&s=l1047602&r=250-623-30&run

### 6.3 Decagon (side 100 mm)

Function x10: Forward 100, Right 36. R = 161.8, apothem 153.9; start (400, 296), heading 90 centres it at (450, 450).

https://simulator.primastem.com/#top=cfun.r010&fn=cfor.n100,crig.n036&s=l1047602&r=400-296-90&run

### 6.4 Five-point star

Function x5: Forward 400, Right 144 (5 x 144 = 720, two full turns, so it closes). Start (250, 405), heading 90; the star spans x 250-650, y 260-640.

https://simulator.primastem.com/#top=cfun.r005&fn=cfor.n400,crig.n144&s=l1047602&r=250-405-90&run

### 6.5 Circle (36-gon)

Function x36: Forward 25, Right 10. Radius about 143 mm; start (438, 307), heading 90 centres it at (450, 450).

https://simulator.primastem.com/#top=cfun.r036&fn=cfor.n025,crig.n010&s=l1047602&r=438-307-90&run

### 6.6 Square spiral (arithmetic)

Top row: Forward 30, then Function x20. Function row: Right (90), Forward +30. Each pass the side grows by 30 mm (60, 90, ... 630). Start (450, 465), heading 0; the spiral spans x 150-750, y 135-765. The first pair `cfor.n030` resets Forward, so pressing Start again draws the same spiral.

https://simulator.primastem.com/#top=cfor.n030,cfun.r020&fn=crig,cfor.a030&s=l1047602&r=450-465-0&run

### 6.7 Heptagon (turn of 360/7, not an integer)

Top row: Right 360 (one spin), Right ÷7 (turns 51.43 and saves it), Function x7. Function row: Forward 200, Right (reuses 51.43). Start (350, 232), heading 39: after the spin and the 51.43 turn the robot faces right (90.4).

https://simulator.primastem.com/#top=crig.n360,crig.d007,cfun.r007&fn=cfor.n200,crig&s=l1047602&r=350-232-39&run

### 6.8 Drive to a cell (maze, grid on)

The maze param `m` lists cells as two digits each, column then row (0-based, from the top-left): the first pair is the goal flag, the rest are obstacles. Here: goal at column 4 row 1 (`41`, on screen E2), obstacles at (1,3), (2,3), (3,3) (B4, C4, D4). The robot starts in the bottom-left cell (75, 825) facing up. Program, no numbers (ages 4-6): Forward x4, Right, Forward x4.

https://simulator.primastem.com/#top=cfor.r004,crig,cfor.r004&s=l1144602&r=75-825-0&m=41132333&run

In maze mode a run is a game: entering an obstacle cell or bumping the field edge is a crash; ending on the goal cell is a win. The win/crash card appears after the run, whether it was started by `&run` or by the Start button. Maze digits must be smaller than the field size. If the start pose sits on the goal or an obstacle, the robot is moved to the nearest free cell.

### 6.9 House (square with an equilateral roof, one line)

Side 300. The function row draws the square (Forward 300, Right); the top row calls it 4 times, then drives up the left wall again and draws the roof: Forward (reuses 300), Right 30, Forward, Right 120, Forward. That is 6 top-row pairs, the limit. Start (300, 730), heading 0.

| Row | Pair | In the link | Meaning |
|---|---|---|---|
| top | 1 | `cfun.r004` | Function x4 (the square) |
| top | 2 | `cfor` | Forward 300 (saved) up the left wall |
| top | 3 | `crig.n030` | Right 30 (heading 30) |
| top | 4 | `cfor` | Forward 300 to the apex |
| top | 5 | `crig.n120` | Right 120 (heading 150) |
| top | 6 | `cfor` | Forward 300 down to the top-right corner |
| fn | 1 | `cfor.n300` | Forward 300 |
| fn | 2 | `crig` | Right 90 |

Trace: (300,730) -> (300,430) -> (600,430) -> (600,730) -> (300,730) [square done, heading 0] -> (300,430) -> apex (450,170) -> (600,430). All within [60, 840].

https://simulator.primastem.com/#top=cfun.r004,cfor,crig.n030,cfor,crig.n120,cfor&fn=cfor.n300,crig&s=l1047602&r=300-730-0&run

### 6.10 Letter П (two legs down from a top bar)

One line: up the left leg, along the bar, down the right leg. Top row only: Forward 400, Right, Forward 300, Right, Forward 400. Start (300, 650), heading 0 (the bottom of the left leg).

Trace: (300,650) -> (300,250) -> (600,250) -> (600,650). All within [60, 840]. Note the start is the BOTTOM of a leg: starting at y = 400 instead would put the top bar at y = 0 and the robot would stop at the edge.

https://simulator.primastem.com/#top=cfor.n400,crig,cfor.n300,crig,cfor.n400&s=l1047602&r=300-650-0&run

## 7. Common mistakes

- **Number + Function or number + Random move.** Error pair, skipped. Loop the function with a repeat (`cfun.r010`), put numbers on the commands inside it.
- **Number and repeat in one pair** (`cfor.n100.r004` is three tiles, not a pair). Error. Use the function row.
- **Too many pairs.** `top` holds 6 pairs and `fn` 5; extra pairs are dropped. Move the repeated part into `fn` and loop it with `cfun.rNNN`.
- **Hyphen or space inside a pair.** The two cells of a pair are joined by a dot: `cfor.n100`, not `cfor-n100` or `cfor n100` (those become error cells).
- **Pose in the text differs from the pose in the link.** Copy `&r=` from your own trace.
- **Values outside 1-999 or not 3 digits.** `n45` and `n1200` are invalid codes (error cells). Write `n045`; split big amounts.
- **Figure leaves the field.** Trace the path; the pen stops at 60 mm from each edge and the shape breaks.
- **Marker off** (`s` char 2 = `0`): the robot moves but draws nothing.
- **No `r`:** the robot starts in a random cell and the drawing may run off the field.
- **No `&run`:** the program loads but waits for the user to press Start. Fine if that is what they want.
- **Empty top row:** a program only in the function row never runs; the top row must call it with `cfun`.
- **Negative heading in `r`:** `r=300-600--90` breaks the `-` separator. Use 0-359 (270 instead of -90).
- **Extra encoding or decoration.** Do not URL-encode `#`, `&`, `=`, `.`, `,` or `-`, do not add spaces, and do not put punctuation right after the link.
- **Expecting a fixed figure from the dice repeat (`rrnd`) or Random move (`crnd`).** They change every run.

## 8. Self-check again before you send

- [ ] **Rows.** `top=` lists at most 6 pairs, `fn=` at most 5, separated by commas. Each pair is `command` or `command.value` (one dot, no spaces). Use `top=`/`fn=`, not the old `p=`.
- [ ] **Pairs.** One command plus at most one value; no number next to `cfun` or `crnd`; a number and a repeat never share a pair.
- [ ] **Trace.** Go through the program step by step and write down the (x, y) of every corner. Every point must stay within 60 ... (N*150 - 60) mm, i.e. 60 ... 840 on the default 6x6 field.
- [ ] **Same pose.** The `&r=x-y-h` in the link is exactly the start pose you described and traced.
- [ ] **Codes.** Every value is a 4-character code: `n`/`r`/`a`/`s`/`m`/`d`/`e` plus 3 digits (`n045`, `r007`), or `sqrt`/`rrnd`.

## 9. Advanced: the 22-field `p=` form

The share links the simulator itself writes (Share button, QR code) use an older form: `#p=` followed by all 22 board cells joined by `-`, empty cells included. It works and keeps working, but it is easy to miscount, so do not write it yourself; use `top`/`fn`. Read it only to understand a link a user pastes. If a link has `p=`, any `top`/`fn` in it is ignored.

The 22 cells in link order: top-row pairs 1-6 (slots 1-12), then function-row pairs 1-5 (slots 13-22); in each pair the top cell comes first.

| Slot | Row | Pair | Cell |   | Slot | Row | Pair | Cell |
|---|---|---|---|---|---|---|---|---|
| 1 | top | 1 | top |   | 12 | top | 6 | bottom |
| 2 | top | 1 | bottom |   | 13 | function | 1 | top |
| 3 | top | 2 | top |   | 14 | function | 1 | bottom |
| 4 | top | 2 | bottom |   | 15 | function | 2 | top |
| 5 | top | 3 | top |   | 16 | function | 2 | bottom |
| 6 | top | 3 | bottom |   | 17 | function | 3 | top |
| 7 | top | 4 | top |   | 18 | function | 3 | bottom |
| 8 | top | 4 | bottom |   | 19 | function | 4 | top |
| 9 | top | 5 | top |   | 20 | function | 4 | bottom |
| 10 | top | 5 | bottom |   | 21 | function | 5 | top |
| 11 | top | 6 | top |   | 22 | function | 5 | bottom |

An empty cell is an empty field, so empty cells show up as `--`; 21 hyphens in all. The square from 6.1 in this form (the same program as `#top=cfun.r004&fn=cfor.n300,crig`):

https://simulator.primastem.com/#p=cfun-r004-----------cfor-n300-crig-------&s=l1047602&r=300-600-0&run

## 10. Also useful

- A `.stem` file is the same data as a link: line 1 `PRIMASTEM v1`, line 2 the 22 codes of the `p=` form (section 9) joined by commas. Users can save and open these files in the simulator.
- Product documentation: https://docs.primastem.com