LANGUAGE_GUIDE.md

# RoboScript Help

RoboScript lets you tell the robot what to do, step by step. It's designed to be easy to read—almost like writing instructions in plain English!

Each line of code is one instruction. The robot executes them in order, from top to bottom. Blank lines are ignored, so feel free to add them to keep your code tidy and readable.

Oh, and don't worry about uppercase or lowercase: `look left`, `Look Left`, and `LOOK LEFT` all do the same thing.

---

## Basic Movements

**`look`** rotates the head to look in a direction:
```
look left
look right
look up
look down
```

**`turn`** rotates the whole body (the head follows along):
```
turn left
turn right
```

**`tilt`** tilts the head sideways, like when you're curious:
```
tilt left
tilt right
```

**`head`** moves the head in space without rotating it:
```
head up
head down
head left
head right
head forward
head backward
```

Each of these commands can be reset to the neutral position:
```
look center
turn center
tilt center
```
You can also use `straight` or `neutral` instead of `center`—they all work the same.

---

## Controlling Intensity and Duration

Every movement has a default size and speed, so you can just write `look left` and it works. But if you want more control, you can specify exactly how much or how fast.

**Intensity** is how far the robot moves. For rotations, it's in degrees. For translations, it's in millimeters. Just write the number—no need to write "degrees" or "mm":
```
look left 45
head up 25
```

**Duration** is how long the movement takes, in seconds. Add an `s` after the number:
```
look left 45 3.5s
```

You can also specify just the duration (a default intensity will be used):
```
look up 2s
```

---

## Using Words Instead of Numbers

If you prefer not to use numbers, you can use descriptive words instead.

**For intensity** (how far to move):
`tiny`, `small`, `alittle`, `medium`, `big`, `alot`, `maximum`...

**For speed** (how fast to move):
`superslow`, `slow`, `fast`, `superfast`, `veryfast`...

You can use one, both, or neither:
```
turn left superfast
turn right maximum 1.5s
look up big and slow
```

Many similar words work too—feel free to experiment!

---

## Combining Movements

Use `and` to combine directions within the same command:
```
look up and left
look down maximum and left alittle
```

You can also combine *different* commands to make them happen at the same time:
```
head up and look right
head up and look right and tilt left
```

This creates smooth, expressive movements where everything happens together.

---

## Antennas

The robot has two antennas you can move. You can control them together or separately.

**Both antennas together:**
```
antenna both up
antenna both down
```

**Each antenna independently:**
```
antenna left up
antenna right down
```

**Combining antenna movements:**
```
antenna left up and antenna right down
```

For direction, you can use `up`, `down`, `left`, or `right`:
```
antenna left left
antenna right right
```

You can also use clock positions if you want precise control. Think of a clock face: 12 is straight up, 3 is to the side, 6 is down:
```
antenna left 2 and antenna right 10
```

---

## Pausing and Repeating

**`wait`** pauses the robot for a moment. Don't forget the `s`!
```
wait 1s
wait 0.5s
```

**`repeat`** runs a sequence multiple times. The number after `repeat` is how many times to repeat. The commands to repeat must be **indented** (start with spaces):
```
repeat 3
    tilt left maximum fast
    tilt right maximum fast
tilt center
```

In this example, the robot tilts left then right, three times in a row. The last line (`tilt center`) is not indented, so it runs only once, after all the repetitions are done.

You can nest repeats inside each other:
```
repeat 2
    antenna up
    repeat 3
        look left
        look right
    antenna down
```

---

## Comments

Lines starting with `#` are comments—they're ignored by the robot. Use them to leave notes for yourself or others:
```
# Wave hello
antenna both up
wait 0.5s
antenna both down
```

---

## Giving Your Script a Name

You can optionally add a description at the very beginning of your script, in quotes:
```
"My happy dance"
look left
look right
antenna both up
```

This is just for you to remember what the script does—it doesn't change how the robot behaves.

---

## Watch Out!

A few common mistakes to avoid:

**Don't forget the `s` after durations:**
```
wait 2s      ✓
wait 2       ✗ (this won't work!)
```

**Always indent after `repeat`:**
```
repeat 3
    look left    ✓ (indented with spaces)

repeat 3
look left        ✗ (not indented—error!)
```

**You can't combine `wait` with movements using `and`:**
```
look left and wait 1s    ✗ (doesn't work)

look left                ✓ (use separate lines instead)
wait 1s
```

**Stick to one style of indentation.** Use either spaces or tabs, but don't mix them in the same script.

---

## Quick Reference

| Command | What it does | Example |
|---------|--------------|---------|
| `look` | Rotate head to look somewhere | `look left 45` |
| `turn` | Rotate whole body | `turn right` |
| `tilt` | Tilt head sideways | `tilt left` |
| `head` | Move head in space | `head forward 10` |
| `antenna` | Move antennas | `antenna both up` |
| `wait` | Pause | `wait 1.5s` |
| `repeat` | Repeat a sequence | `repeat 3` |
| `#` | Comment (ignored) | `# This is a note` |