docs/usage/script-basics.md

# Script basics

Scansion scripts are designed to be extremely easy to read and write. They are based
on natural language statements as far as possible.

## Metadata

A script begins with an optional title and description:

```
# Script Title
# A short description of the script.
```

Scripts may also contain one or more tags. A tag is either a simple string or
may also include an associated value. They are one tag per line, each beginning
with `##`:

```
## slow
## status: stable
```

Tags are useful to group scripts, and allow you to easily filter when running
Scansion with many scripts at once, e.g. with `--only-tags "status: stable"` or
`--skip-tags slow`.

## Defining characters

Every script defines one or more characters that will perform actions in the
script.

Definitions consist of the type and name of the character, as well as any additional
properties specific to that character.

For example, an XMPP client called Romeo might be defined like this:

```
[Client] Romeo
	jid: romeo@example.com
	password: s3cr3t!
```

## Actions

Once you have defined characters, you can have them perform actions. For example
our client Romeo will connect to the server and broadcast his availability to
contacts:

```
Romeo connects

# Send presence!
Romeo sends:
	<presence/>
```

Different types of characters support different actions, see for example the
[Client class](../character-classes/client.md).

Note: lines beginning with a '#' are comments, and are useful to add descriptions to
each action, and help keep scripts readable.