Mercurial > scansion / file diff

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/usage/script-basics.md	Fri Feb 01 11:22:20 2019 +0000
@@ -0,0 +1,62 @@
+# 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.