.. _command-ref:

Commands
========
The :ref:`commandList` sections contain commands and parameters that control
the characters. Brief descriptions of the commands used in these command lists
follow. Unless specified otherwise, commands are used in both Back to Skool and
Skool Daze.

AddLines
--------
The :class:`~ai.AddLines` command is used in the command lists
``GrassOnEric-Wacker`` and ``HiddenPeaShooter-Wacker`` (Skool Daze only) to add
to Eric's lines total after he has been found guilty of misdeeds. The number of
lines to be added to the total is specified by the command's sole argument.

AwaitAssemblyTime
-----------------
The :class:`~ai.AwaitAssemblyTime` command is used in the command list
``Assembly-Wacker`` (Back to Skool only). It makes the headmaster return to the
start of the command list unless it's time to go down to the stage for
assembly.

Catch
-----
The :class:`~ai.Catch` command is used internally to control Eric while he's
trying to catch a mouse or frog. It makes Eric bend over, checks to see whether
an animal is present (and if it is, adds it to the appropriate inventory), and
then makes Eric stand up.

.. _chaseEricOut:

ChaseEricOut
------------
The :class:`~ai.ChaseEricOut` command is used in the ``ChaseEricOut-Take``
command list in Back to Skool. It controls Miss Take as she chases Eric, with
the intent of making him leave the girls' skool and return to the boys'. It is
very similar to the :ref:`shadowEric` command, except that it makes the
headmistress go no further than the skool gate.

The ``ChaseEricOut-Take`` command list takes control of Miss Take whenever the
:ref:`monitorEric` command deems it necessary for Miss Take to abandon her
regular skool duties and start hounding our hero.

.. _checkIfTouchingEric:

CheckIfTouchingEric
-------------------
The :class:`~ai.CheckIfTouchingEric` command is used in the command list
``MumpsWalkabout-Bully`` (Skool Daze only), which is used by the Bully when he
has mumps. It checks whether the Bully is touching Eric, and alerts whichever
teacher is following the YouHaveMumps-Teacher command list (Mr Rockitt by
default) if necessary.

.. _climbOverSkoolGate:

ClimbOverSkoolGate
------------------
The :class:`~ai.ClimbOverSkoolGate` command is used internally to control Eric
when he is stepping off a fully grown plant over the closed skool gate. It
guides him over the gate and down to the ground on the other side.

ConductAssembly
---------------
The :class:`~ai.ConductAssembly` command is used in the command list
``Assembly-Wacker`` (Back to Skool only). It makes the headmaster tell the kids
they're in detention.

.. _conductClass:

ConductClass
------------
The :class:`~ai.ConductClass` command is used in the following command lists:

* ``MapRoom-Teacher``
* ``ReadingRoom-Teacher``
* ``ExamRoom-Teacher``
* ``WhiteRoom-Teacher``
* ``UpperRoom-Teacher``
* ``MiddleRoom-Teacher``
* ``BlueRoom-Teacher``
* ``YellowRoom-Teacher``
* ``ScienceLab-Teacher``

It controls a teacher from the point where he reaches the edge of the
blackboard. If the teacher is teaching Eric, it makes the teacher wait until
the Swot shows up, and then hands over control to :ref:`conductClassWithEric`.
Otherwise it immediately hands over control to the
:ref:`conductClassWithoutEric` command.

.. _conductClassWithEric:

ConductClassWithEric
--------------------
The :class:`~ai.ConductClassWithEric` command is used internally to control a
teacher who is teaching Eric and the Swot. It takes over control from the
:ref:`conductClass` command as soon as the Swot shows up and sits down. It's
responsible for making the teacher:

* listen to the Swot's tales (if any)
* dish out lines after the Swot has told tales
* wipe the blackboard
* walk to the middle of the blackboard
* write on the blackboard (occasionally)
* tell the kids what to do during class, or ask questions and wait for the
  answers
* hunt down Eric if he's playing truant

.. _conductClassWithoutEric:

ConductClassWithoutEric
-----------------------
The :class:`~ai.ConductClassWithoutEric` command is used internally to control
a teacher who is teaching a class that does not contain Eric and the Swot. It
takes over control from the :ref:`conductClass` command immediately. It
controls a teacher from the point where he reaches the edge of the blackboard
and is responsible for making him:

* wipe the blackboard
* walk to the middle of the blackboard
* write on the blackboard (occasionally)
* tell the kids what to do during class

Dethroned
---------
The :class:`~ai.Dethroned` command is used internally to control a character
who has been pushed out of his seat in class. It makes him sit stunned on the
floor for a brief period, then stand up, after which it's up to the
:ref:`findSeat` command to reseat him.

.. _doAssemblyDuty:

DoAssemblyDuty
--------------
The :class:`~ai.DoAssemblyDuty` command is used in the ``AssemblyDuty`` command
list (Back to Skool only) to control Mr Withit as he does assembly duty. It
makes Mr Withit do nothing (i.e. stand still) unless Eric is absent from the
assembly hall, in which case it hands over control to the :ref:`fetchEric`
command; when that command exits, the command list is restarted. The
``DoAssemblyDuty`` command itself exits when assembly is over (i.e. Mr Wacker
has finished speaking).

.. _dropStinkbomb:

DropStinkbomb
-------------
The :class:`~ai.DropStinkbomb` command is used internally to make a
stinkbomb-carrying character (i.e. Eric) drop a stinkbomb (Back to Skool only).

.. _dumpWaterPistol:

DumpWaterPistol
---------------
The :class:`~ai.DumpWaterPistol` command is used internally to make Eric throw
away the water pistol. The water pistol will be relocated in a random desk, and
will contain water (as opposed to sherry).

.. _endGame:

EndGame
-------
The :class:`~ai.EndGame` command is used in the following command lists:

* ``ExpelEric:TooManyLines``
* ``YouHaveMumps-Teacher`` (Skool Daze only)
* ``ExpelEric:NotABird`` (Back to Skool only)

Unsurprisingly, the command ends the game.

.. _evadeMouse:

EvadeMouse
----------
The :class:`~ai.EvadeMouse` command is used internally to control a character
who is scared of mice and has spotted one nearby. It makes the character either
jump up and down or stand on a chair.

.. _fall:

Fall
----
The :class:`~ai.Fall` command is used in the ``WaterDrop``, ``SherryDrop`` and
``Conker`` command lists (Back to Skool only) to control the descent of a drop
of water or sherry from a cup, or the descent of a conker from a tree. Until
the object has been knocked out of its resting place, the command does nothing.
Otherwise, it guides the object to the floor, and interacts appropriately with
any character it hits. After the object has hit somebody or the floor, it is
hidden from view.

.. _fallToFloor:

FallToFloor
-----------
The :class:`~ai.FallToFloor` command is used internally to control Eric's
descent to the floor. It is invoked in the following situations:

* by the :ref:`rideBike` command when Eric falls off a bike that has lost
  momentum
* when Eric falls off a fully grown plant that has just died

.. _fetchEric:

FetchEric
---------
The :class:`~ai.FetchEric` command is used internally by the
:ref:`conductClassWithEric` command to make a teacher track down the truant
Eric and shepherd him back to the classroom.

.. _findEric:

FindEric
--------
The :class:`~ai.FindEric` command is used in the following command lists:

* ``ExpelEric:TooManyLines``
* ``ExpelEric:NotABird`` (Back to Skool only)
* ``BullyHasMumps-Boy`` (Skool Daze only)
* ``GrassOnEric-Boy`` (Skool Daze only)
* ``GrassOnEric-Wacker`` (Skool Daze only)
* ``HiddenPeaShooter-Boy`` (Skool Daze only)
* ``HiddenPeaShooter-Wacker`` (Skool Daze only)
* ``YouHaveMumps-Teacher`` (Skool Daze only)

The command is used to make a character look for Eric (to give him a message);
it also stops the skool clock (which can be restarted later on with a
:ref:`setClock` command) to allow Eric to be found before the bell rings. When
Eric has been found, he is frozen so that he has no choice but to listen to the
message.

FindEricIfMissing
-----------------
The :class:`~ai.FindEricIfMissing` command is used in the command list
``DinnerDuty``. It makes whichever teacher is on dinner duty go and look for
Eric if he's not in the dinner hall.

.. _findSeat:

FindSeat
--------
The :class:`~ai.FindSeat` command is used in the following command lists in
Skool Daze:

* ``ExamRoom-Boy``
* ``ExamRoom-Bully``
* ``ExamRoom-Swot``
* ``ExamRoom-Tearaway``
* ``MapRoom-Boy``
* ``MapRoom-Bully``
* ``MapRoom-Swot``
* ``MapRoom-Tearaway``
* ``ReadingRoom-Boy``
* ``ReadingRoom-Bully``
* ``ReadingRoom-Swot``
* ``ReadingRoom-Tearaway``
* ``WhiteRoom-Boy``
* ``WhiteRoom-Bully``
* ``WhiteRoom-Swot``
* ``WhiteRoom-Tearaway``

and the following command lists in Back to Skool:

* ``BlueRoom-Boy``
* ``BlueRoom-Bully``
* ``BlueRoom-Swot``
* ``BlueRoom-Tearaway``
* ``MiddleRoom-Girl``
* ``ScienceLab-Boy``
* ``ScienceLab-Bully``
* ``ScienceLab-Swot``
* ``ScienceLab-Tearaway``
* ``UpperRoom-Girl``
* ``YellowRoom-Boy``
* ``YellowRoom-Bully``
* ``YellowRoom-Swot``
* ``YellowRoom-Tearaway``

It makes a boy or girl find a seat in the classroom and sit down; it also makes
the character find another seat if he's knocked out of one (unless the
character is the Swot, who must return to the same seat to avoid having to move
his speech bubble during lessons).

The command takes two optional True (1) or False (0) arguments (which are both
True by default). When the first argument is True, the character will seek out
the back seat in the classroom first. Otherwise, when the second argument is
True, the character will go to the next seat in front of him, or to the back
seat if there isn't one (which is what happens when a character is pushed out
of his seat). When both arguments are False, the character will sit in the seat
he's standing next to (which is what happens when a character rises after being
decked while seated).

.. _fireCatapult:

FireCatapult
------------
The :class:`~ai.FireCatapult` command is used internally to make a
catapult-carrying character (i.e. Eric or the Tearaway) fire his catapult.

.. _fireNowAndThen:

FireNowAndThen
--------------
The :class:`~ai.FireNowAndThen` command is used as an argument to the
:ref:`setControllingCommand` command to make the Tearaway fire his catapult
occasionally. If the command decides that the time is ripe to send a projectile
whizzing through the air, it passes control to the :ref:`fireCatapult` command.

.. _fireWaterPistol:

FireWaterPistol
---------------
The :class:`~ai.FireWaterPistol` command is used internally to make a water
pistol-carrying character (i.e. Eric) fire his water pistol (Back to Skool
only).

.. _flyOverSkoolGate:

FlyOverSkoolGate
----------------
The :class:`~ai.FlyOverSkoolGate` command is used internally to control Eric
when he is flying over the closed skool gate (after hitting it while standing
on the saddle of the bike - see the :ref:`rideBike` command). It guides Eric
over the gate and down to the ground, upon which he will land in the sitting
position.

Follow
------
The :class:`~ai.Follow` command is used in the command list
``Stampede-Follower`` (Skool Daze only). It is used by little boys 2-11 to sync
their movements with those of the stampede leader, little boy 1. (Internally it
syncs destinations, and hands over control to the :ref:`goTo` command.) The
command takes a single argument: the unique ID of the character to follow.

Freeze
------
The :class:`~ai.Freeze` command is used internally by the :ref:`findEric`
command to freeze Eric once he has been found. It continually monitors the
keyboard to check whether Eric has acknowledged delivery of a message (by
pressing 'U'). It is then up to the :ref:`tellEric` or :ref:`tellEricAndWait`
command to unfreeze Eric as appropriate.

.. _goTo:

GoTo
----
The :class:`~ai.GoTo` command is arguably the most important command ever in
the history of Pyskool. Without it, the characters would stay rooted to the
spot, Pyskool would be boring, and you wouldn't be reading this. Sad. Anyway,
``GoTo`` takes a single argument, which must be one of the following:

* a skool location identifier (as found in the :ref:`skoolLocations` section)
* an identifier of the form ``Location:characterId``, where ``characterId`` is
  the unique ID of a character; this identifier resolves to the current
  location of the character with the given ID

I leave it to the reader to guess what the command does.

GoToRandomLocation
------------------
The :class:`~ai.GoToRandomLocation` command is used in many command lists to
make a character go to one of his :ref:`random locations <randomLocations>`.

GoTowardsXY
-----------
The :class:`~ai.GoTowardsXY` command is used internally to make a character
turn round or take one step in the direction of the destination ``x`` and ``y``
coordinates specified in the two arguments, instead of continuing all the way
to the destination. The command is used primarily by the :ref:`findEric` and
:ref:`fetchEric` commands, which require tracking of a moving target (our hero)
rather than a fixed destination.

GoToXY
------
The :class:`~ai.GoToXY` command is used internally to make a character go to a
location specified by an `(x, y)` pair of coordinates. In fact, the :ref:`goTo`
command resolves its location ID parameter into an `(x, y)` pair of coordinates
and then hands over control to ``GoToXY``. Unsurprisingly, ``GoToXY`` takes two
arguments: `x` and `y`, as in::

  GoToXY, 23, 17

Although ``GoToXY`` is not used explicitly in any of the stock command lists,
there is nothing to stop you using it in a command list if you wish.

.. _grassAndAnswerQuestions:

GrassAndAnswerQuestions
-----------------------
The :class:`~ai.GrassAndAnswerQuestions` command is used in the following
command lists in Skool Daze:

* ``MapRoom-Swot``
* ``ReadingRoom-Swot``
* ``ExamRoom-Swot``
* ``WhiteRoom-Swot``

and the following command lists in Back to Skool:

* ``BlueRoom-Swot``
* ``YellowRoom-Swot``
* ``ScienceLab-Swot``

It makes the Swot tell tales to the teacher just before class starts, and
answer the teacher's questions later.

.. _grow:

Grow
----
The :class:`~ai.Grow` command is used in the ``Plant`` command list (Back to
Skool only) to control the growth of a plant after it has been watered. If the
plant is not growing, the command does nothing. Otherwise, it animates the
plant growth, and lifts any characters who are standing on the plant. When the
plant dies, it drops any characters who were standing on the plant, and hides
it from view.

.. _hit:

Hit
---
The :class:`~ai.Hit` command is used internally to make a fist-wielding
character (i.e. Eric or the Bully) throw a punch.

.. _hitNowAndThen:

HitNowAndThen
-------------
The :class:`~ai.HitNowAndThen` command is used as an argument to the
:ref:`setControllingCommand` command to make the Bully throw a punch
occasionally. If the command decides that the time is ripe to send a fist
whizzing through the air, it passes control to the :ref:`hit` command.

.. _hop:

Hop
---
The :class:`~ai.Hop` command is used internally by the :ref:`moveFrog` command
to control the movements of a frog as it embarks on a long hop or a short hop,
or turns round.

.. _jump:

Jump
----
The :class:`~ai.Jump` command is used internally to control Eric while he's
jumping. It lifts him into the air, checks to see whether he has reached a
shield, a cup, or the safe, and then lets him drop (unless there is an
unconscious kid or a plant pot below).

.. _jumpIfOpen:

JumpIfOpen
----------
The :class:`~ai.JumpIfOpen` command is used in the command lists
``UpperRoom-Teacher`` and ``MiddleRoom-Teacher`` (Back to Skool only) to jump
back to the start of the command list if the boys' skool door is still open.
The command takes two arguments: the unique ID of the door (see :ref:`doors`)
to check for openness, and the number of commands to jump back or ahead, as
in::

  JumpIfOpen, SkoolDoor, -5

.. _jumpIfShut:

JumpIfShut
----------
The :class:`~ai.JumpIfShut` command is used in the command list
``ShutGateAndDoor-Albert`` (Back to Skool only) to jump ahead in the command
list if the boys' skool door or the skool gate is already shut. The command
takes two arguments: the door or gate's unique ID (see :ref:`doors`), and the
number of commands to jump ahead, as in::

  JumpIfShut, SkoolGate, 3

.. _jumpOffSaddle:

JumpOffSaddle
-------------
The :class:`~ai.JumpOffSaddle` command is used internally to control Eric when
he is jumping off the saddle of the bike (see the :ref:`rideBike` command). It
lifts him into the air, checks to see whether he has reached a cup (into which
a frog may be placed), and then lets him drop to the floor.

.. _jumpOutOfWindow:

JumpOutOfWindow
---------------
The :class:`~ai.JumpOutOfWindow` command is used internally to control Eric
when he is stepping off a fully grown plant through an open window. It guides
him through the window and down to the ground, upon which he may land with his
feet or his back.

.. _kiss:

Kiss
----
The :class:`~ai.Kiss` command is used internally to control Eric while he's
kissing (or trying to kiss) Hayley. If Hayley is neither facing Eric nor in
front of him at the time of the attempted kiss, Eric will take a step forward
and then back again, with no kiss scored. If Hayley is in front of Eric and
facing him, one of two things will happen: (a) Eric will score a kiss, or (b)
Hayley will smack Eric in the face (if she feels he's tried to grab one kiss
too many already). If Eric does land a kiss, his lines total will be reduced by
1000 (or to zero if he has less than 1000 lines).

.. _knockedOut:

KnockedOut
----------
The :class:`~ai.KnockedOut` command is used internally to control a child
character who has been knocked out (by Eric, the Bully, or the Tearaway).
``KnockedOut`` keeps the character out cold for a brief period and then makes
him stand up; after that, the character will resume whatever he was doing
before.

This command would not really be useful in a command list, but if you want to
use it, go knock yourself out. (Groan. - Ed.)

KnockedOver
-----------
The :class:`~ai.KnockedOver` command is used internally to control an adult
character who has been downed by a catapult pellet or a stampeding boy.
``KnockedOver`` stuns the character, makes him reveal his safe combination
letter (if appropriate), also makes him give lines to the nearest main child
character (if any), and then helps him up off the floor; after that, the
character will resume whatever he was doing before.

.. _monitorEric:

MonitorEric
-----------
The :class:`~ai.MonitorEric` command is used as a subcommand (set by the
:ref:`setSubcommand` command) in the following command lists in Back to Skool:

* ``Kitchen-Teacher``
* ``MiddleRoom-Teacher``
* ``UpperRoom-Teacher``

The ``MonitorEric`` command makes Miss Take her keep an eye out for Eric in the
girls' skool when it's not playtime. If she spots him, her command list is
switched to the one named by the command's sole argument.

.. _moveAboutUntil:

MoveAboutUntil
--------------
The :class:`~ai.MoveAboutUntil` command is used to make a character repeatedly
walk a random number of paces away from a fixed point and back again. The fixed
point will be the point the character reached before ``MoveAboutUntil`` was
invoked.

The command takes a single argument, which determines when the character should
proceed to the next command in his command list. For Skool Daze, possible
arguments and their meanings are:

* ``Boy1Ready`` - little boy no. 1 is ready to start the first stampede
* ``Boy1ReadyAgain`` - little boy no. 1 is ready to start the second stampede
* ``EndOfLesson`` - the end of the lesson
* ``EricHasMumps`` - Eric has caught mumps from the Bully
* ``EricWasTold`` - Eric has been informed of (a) the Swot's plan to grass him
  up to the headmaster, (b) the hidden pea shooter on the fire escape, or (c)
  the contagious nature of the Bully's condition
* ``ExamRoomReady`` - it's time to start the lesson in the Exam Room
* ``MapRoomReady`` - it's time to start the lesson in the Map Room
* ``ReadingRoomReady`` - it's time to start the lesson in the Reading Room
* ``SwotGrassed`` - the Swot has grassed on Eric
* ``SwotReady`` - the Swot is at the fire escape, waiting for Eric to be
  informed that he's going to tell tales to the headmaster
* ``TearawayReady`` - the Tearaway is ready to race the headmaster to the fire
  escape to collect the hidden pea shooter
* ``WackerReady`` - the headmaster is either (a) in his study, where the Swot
  may find him in order to grass on Eric, or (b) ready to race the Tearaway to
  the fire escape to collect the hidden pea shooter
* ``WhiteRoomReady`` - it's time to start the lesson in the White Room

For Back to Skool, possible arguments and their meanings are:

* ``BlueRoomReady`` - it's time to start the lesson in the Blue Room
* ``EndOfLesson`` - the end of the lesson
* ``MiddleRoomReady`` - it's time to start the lesson in the Middle Room of the
  girls' skool
* ``ScienceLabReady`` - it's time to start the lesson in the Science Lab
* ``TimeForAssembly`` - it's time to sit down for assembly
* ``UpperRoomReady`` - it's time to start the lesson in the Upper Room of the
  girls' skool
* ``YellowRoomReady`` - it's time to start the lesson in the Yellow Room

.. _moveBike:

MoveBike
--------
The :class:`~ai.MoveBike` command is used in the ``Bike`` command list (Back to
Skool only) to control the bike when Eric is not sitting on the saddle. If the
bike has not been unchained yet, or is resting on the ground, the command does
nothing. Otherwise, it moves the bike along until it runs out of momentum, at
which point it will fall over.

.. _moveDeskLid:

MoveDeskLid
-----------
The :class:`~ai.MoveDeskLid` command is used in the ``DeskLid`` command list
(Back to Skool only) to control a desk lid when it has been raised (by Eric).
When the desk lid is not raised, the command does nothing. Otherwise, it
transfers the contents of the desk (if any) to Eric's pocket. When the desk lid
is ready to drop, it is hidden from view.

.. _moveFrog:

MoveFrog
--------
The :class:`~ai.MoveFrog` command is used in the ``Frog`` command list (Back to
Skool only). It is used to control the movements of a frog. When a frog decides
to move, it chooses from three options: turn round, short hop, and long hop.
Each of these movements is controlled by the :ref:`hop` command.

.. _moveMouse:

MoveMouse
---------
The :class:`~ai.MoveMouse` command is used in the ``Mouse`` command list (Back
to Skool only). It is used to control the movements of a mouse: scamper up and
down a few times, hide for a brief period, repeat.

.. _movePellet:

MovePellet
----------
The :class:`~ai.MovePellet` command is used in the ``Pellet`` command list to
control a catapult pellet. If the pellet has not been launched, the command
does nothing. Otherwise, it moves the pellet through the air, checking whether
any shields or unfortunate characters lie in its path. When a pellet has
finished its flight, it is hidden from view.

.. _moveWater:

MoveWater
---------
The :class:`~ai.MoveWater` command is used in the ``Water`` command list (Back
to Skool only) to control a jet of water fired from a water pistol. If the
water has not been fired, the command does nothing. Otherwise, it moves the
water through the air, checking whether any cups or plant pots lie in its path.
When the water has finished its flight, it is hidden from view.

OpenDoor
--------
The :class:`~ai.OpenDoor` command is used in the following command lists (Back
to Skool only):

* ``UpperRoom-Teacher``
* ``MiddleRoom-Teacher``
* ``OpenGateAndDoor-Albert``

It takes one argument, namely the unique ID of the door (see :ref:`doors`) to
open. Unsurprisingly, it makes the character open the door in question - unless
that door is already open, in which case the command does nothing.

.. _pause:

Pause
-----
The :class:`~ai.Pause` command is used internally by the :ref:`kiss` command to
occupy Hayley (i.e. prevent her from executing her current command list) while
she is responding to an attempted kiss from Eric. The command exits (and Hayley
will resume her current command list) after the response (a kiss or slap in the
face) has been made.

.. _releaseMice:

ReleaseMice
-----------
The :class:`~ai.ReleaseMice` command is used internally to control Eric when
he's releasing mice. It makes Eric bend over, releases up to five mice
(depending on how many Eric has caught) at the spot in front of Eric, and then
makes Eric stand up.

.. _restart:

Restart
-------
The :class:`~ai.Restart` command is used in many command lists to return to the
first command in the list. For example::

  [CommandList Walkabout1-Wacker]
  GoTo, HeadsStudy:Left
  GoToRandomLocation
  Restart

This command list is used by the headmaster; it makes him go to his study, then
to one of his :ref:`random locations <randomLocations>`, and then back to his
study, and so on.

.. _rideBike:

RideBike
--------
The :class:`~ai.RideBike` command is used internally to control Eric while he's
on the bike (Back to Skool only). It may hand over control to another command
depending on what happens while Eric is on the bike:

* :ref:`fallToFloor` (if the bike runs out of momentum)
* :ref:`jumpOffSaddle` (if Eric jumps off the saddle)
* :ref:`flyOverSkoolGate` (if the bike hits the closed skool gate while Eric is
  standing on the saddle)

Say
---
The :class:`~ai.Say` command is used internally to make a character say
something. It takes two arguments: the thing to say, and an optional second
argument specifying whether to notify listeners when done (which defaults to
``False``, and is set to ``True`` only during lessons so that the teacher and
the swot don't talk over each other). For example::

  Say, 'Hello mum!'

would make a character say 'Hello mum!'.

Although ``Say`` is not used explicitly in any of the stock command lists,
there is nothing to stop you using it in a command list if you wish.

.. _setClock:

SetClock
--------
The :class:`~ai.SetClock` command is used in the following command lists in
Skool Daze:

* ``BullyHasMumps-Boy``
* ``GrassOnEric-Boy``
* ``GrassOnEric-Wacker``
* ``HiddenPeaShooter-Boy``
* ``HiddenPeaShooter-Wacker``

The command restarts the clock with a certain amount of time remaining until
the bell rings, specified by the sole parameter. ``SetClock`` is always used at
some point after a :ref:`findEric` command, which stops the clock to allow
enough time for Eric to be found. In the ``BullyHasMumps-Boy``,
``GrassOnEric-Boy`` and ``HiddenPeaShooter-Boy`` command lists, ``SetClock`` is
used to ensure that the special playtime has enough time to run until the next
lesson.

The ``SetClock`` command is also used in the ``Assembly-Wacker`` command list
in Back to Skool. It is used to ensure that the bell rings shortly after Mr
Wacker has finished delivering the detention message.

.. _setControllingCommand:

SetControllingCommand
---------------------
The :class:`~ai.SetControllingCommand` command is an awkwardly named command
that takes another command - and that command's parameters - as its arguments,
as in::

  SetControllingCommand, OtherCommand, SomeParameter

What happens then is that on every pass through the main loop of the game,
``OtherCommand`` (the 'controlling' command) will be called for the character
so controlled. The idea is that ``OtherCommand`` will make the character do
something continuously (e.g. walk fast) or occasionally (e.g. fire a catapult
or throw a punch).

In the stock command lists, ``SetControllingCommand`` uses the following
commands as parameters:

* :ref:`checkIfTouchingEric` - used by the Bully in the command list
  ``MumpsWalkabout-Bully`` to see whether he has passed on his foul disease to
  our hero
* :ref:`fireNowAndThen` - used by the Tearaway in many command lists to make
  him fire his catapult occasionally
* :ref:`hitNowAndThen` - used by the Bully in many command lists to make him
  throw punches occasionally
* :ref:`stalkAndHit` - used by the Bully in the command list
  ``Walkabout-Bully`` to make him hunt down our hero's girlfriend and deck her
* :ref:`walkFast` - used by the headmaster in the command lists
  ``GrassOnEric-Wacker`` and ``HiddenPeaShooter-Wacker`` to make him rush to
  find Eric or rush to the fire escape
* :ref:`watchForEric` - used by Albert in the command list
  ``ShutGateAndDoor-Albert`` to make him keep his eyes peeled for an escaping
  Eric

The 'controlling' command remains in effect until the following command in the
command list has completed. For example, in the command list
``MapRoom-Tearaway`` the first two commands are::

  SetControllingCommand, FireNowAndThen
  GoTo, MapRoom:0

so ``FireNowAndThen`` is called for the Tearaway on every pass through the main
loop of the game until he reaches the location ``MapRoom:0``.

SetRestartPoint
---------------
The :class:`~ai.SetRestartPoint` command is used in the following command lists
in Back to Skool:

* ``GirlsSkoolWalkabout-Teacher``
* ``MiddleRoom-Teacher``
* ``OpenGateAndDoor-Albert``
* ``UpperRoom-Teacher``

The command has the effect of discarding itself and all previous commands in
the command list, so that any :ref:`restart` or :ref:`startLessonIfReady`
command appearing further down the command list will bring control back up the
list to the command following ``SetRestartPoint`` instead of the top of the
list.

For example, the ``GirlsSkoolWalkabout-Teacher`` command list looks like this::

  GoTo, DrinksCabinet
  ShutDoor, DrinksCabinet
  SetRestartPoint
  GoToRandomLocation
  Restart

The ``SetRestartPoint`` command here effectively makes itself and all previous
commands disappear, so when ``Restart`` is reached at the end, control passes
to ``GoToRandomLocation`` instead of ``GoTo, DrinksCabinet``.

.. _setSubcommand:

SetSubcommand
-------------
The :class:`~ai.SetSubcommand` command places a subcommand in the character's
current command list. This subcommand is then executed on each pass through the
main loop, before and in addition to the current command in the character's
command list. The parameters of ``SetSubcommand`` are the subcommand name and
the subcommand's parameters, as in::

  SetSubcommand, SomeSubcommand, SomeParameter1, SomeParameter2

The ``SetSubcommand`` command is used in the following command lists in Back to
Skool:

* ``Kitchen-Teacher``
* ``MiddleRoom-Teacher``
* ``UpperRoom-Teacher``

In these command lists, ``SetSubcommand`` is used to place the
:ref:`monitorEric` subcommand in Miss Take's command list, which makes her keep
an eye out for Eric in the girls' skool when it's not playtime.

The subcommand persists for the duration of the command list (which is usually
until the end of the lesson).

.. _shadowEric:

ShadowEric
----------
The :class:`~ai.ShadowEric` command is used in the ``ShadowEric`` command list,
which Mr Wacker adopts after he's been alerted that Eric is trying to escape
(see the :ref:`watchForEric` command). The command makes Mr Wacker track down
Eric and shadow him until the bell rings.

ShutDoor
--------
The :class:`~ai.ShutDoor` command is used in the following command lists (Back
to Skool only):

* ``Kitchen-Teacher``
* ``GirlsSkoolWalkabout-Teacher``
* ``ShutGateAndDoor-Albert``

It takes one argument, namely the unique ID of the door (see :ref:`doors`) to
shut. Unsurprisingly, it makes the character shut the door in question - unless
that door is already shut, in which case the command does nothing.

.. _signal:

Signal
------
The :class:`~ai.Signal` command is used in the following command lists (Skool
Daze only):

* ``BullyHasMumps-Boy``
* ``GrassOnEric-Boy``
* ``GrassOnEric-Swot``
* ``GrassOnEric-Wacker``
* ``HiddenPeaShooter-Boy``
* ``HiddenPeaShooter-Tearaway``
* ``HiddenPeaShooter-Wacker``
* ``Stampede-Leader``

The command takes a single argument: the name of the signal to set. Signals are
used by the :ref:`moveAboutUntil` command to make a character pace up and down
until the time is right to proceed to the next command in the command list.
This scheme allows characters' movements to be coordinated.

For example, take a look at the command list ``HiddenPeaShooter-Boy``, which is
used by little boy no. 10 in the ``Playtime-HiddenPeaShooter`` lesson::

  GoTo, Gym
  MoveAboutUntil, TearawayReady
  MoveAboutUntil, WackerReady
  FindEric
  TellEricAboutTearaway
  Signal, EricWasTold
  GoToRandomLocation
  MoveAboutUntil, EndOfLesson

This command list makes the boy find and tell Eric about the pea shooter, but
only after both the headmaster and the Tearaway have arrived at the Revision
Library (where their race to the fire escape begins). The boy then signals that
he has told Eric what's up, whereupon the headmaster and the Tearaway begin
their race.

See also the :ref:`unsignal` command.

SitForAssembly
--------------
The :class:`~ai.SitForAssembly` command is used in the following command lists
(Back to Skool only):

* ``Assembly-Boy-1``
* ``Assembly-Boy-2``
* ``Assembly-Bully``
* ``Assembly-Tearaway``

It makes the character sit down in the assembly hall until the headmaster has
finished speaking.

.. _sitStill:

SitStill
--------
The :class:`~ai.SitStill` command is always found immediately after the
``FindSeat`` command when it appears in a command list. It makes the character
stay seated (in other words, do nothing).

.. _stalkAndHit:

StalkAndHit
-----------
It sounds brutal, but there really was a command list in Back to Skool that
contained instructions to make the Bully track down Eric's girlfriend in order
to knock her about. In Pyskool, the equivalent (but more flexible) command is
:class:`~ai.StalkAndHit`, which takes a single argument: the unique ID of the
character to track down. The command is used in the ``Walkabout-Bully`` command
list (Back to Skool only).

``StalkAndHit`` should be used as an argument to the
:ref:`setControllingCommand` command, as in::

  SetControllingCommand, StalkAndHit, HEROINE

As a controlling command, ``StalkAndHit`` continually updates the character's
destination to match that of the target, and makes him throw punches now and
then along the way.

StartDinnerIfReady
------------------
The :class:`~ai.StartDinnerIfReady` command is used in the command list
``DinnerDuty``. It restarts the command list unless it's time to start looking
out for Eric during dinner.

.. _startLessonIfReady:

StartLessonIfReady
------------------
The :class:`~ai.StartLessonIfReady` command is used in the following command
lists in Skool Daze:

* ``DinnerDuty``
* ``ExamRoom-Teacher``
* ``MapRoom-Teacher``
* ``ReadingRoom-Teacher``
* ``WhiteRoom-Teacher``

and the following command lists in Back to Skool:

* ``BlueRoom-Teacher``
* ``YellowRoom-Teacher``
* ``ScienceLab-Teacher``
* ``UpperRoom-Teacher``
* ``MiddleRoom-Teacher``

The command takes a single argument, which is the name of a signal that
indicates which room the teacher will teach in when ready. In Skool Daze, these
signals are:

* ``ExamRoomReady``
* ``MapRoomReady``
* ``ReadingRoomReady``
* ``WhiteRoomReady``

and in Back to Skool:

* ``BlueRoomReady``
* ``MiddleRoomReady``
* ``ScienceLabReady``
* ``UpperRoomReady``
* ``YellowRoomReady``

The command restarts the command list unless it's time to start the lesson,
in which case it raises the named signal (so the kids know when to sit down).

Stink
-----
The :class:`~ai.Stink` command is used in the ``Stinkbomb`` command list (Back
to Skool only) to control a stinkbomb after it's been dropped. If the stinkbomb
has not been dropped, the command does nothing. Otherwise, it animates the
stinkbomb cloud, checking whether any characters with a sensitive nose are
nearby, and compelling them to open the nearest window. When the stench has
dissipated, the cloud is hidden from view.

.. _stopEric:

StopEric
--------
The :class:`~ai.StopEric` command is used internally by the :ref:`watchForEric`
command to make Albert raise his arm and alert Mr Wacker when he has spotted
Eric trying to escape. The command exits when Eric leaves the 'danger zone'
near Albert.

TellClassWhatToDo
-----------------
The :class:`~ai.TellClassWhatToDo` command is used internally by the
:ref:`conductClassWithEric` and :ref:`conductClassWithoutEric` commands to make
a teacher tell the class what to do (which usually involves writing an essay,
turning to a certain page in their books, or revising for their exams).

.. _tellEric:

TellEric
--------
The :class:`~ai.TellEric` command is used in the following command lists:

* ``ExpelEric:TooManyLines``
* ``ExpelEric:NotABird`` (Back to Skool only)
* ``GrassOnEric-Wacker`` (Skool Daze only)
* ``HiddenPeaShooter-Wacker`` (Skool Daze only)
* ``YouHaveMumps-Teacher`` (Skool Daze only)

It makes the character deliver the message in the command's sole argument, and
then unfreeze Eric (if he was frozen, as by the :ref:`findEric` command).

.. _tellEricAndWait:

TellEricAndWait
---------------
The :class:`~ai.TellEricAndWait` command is used in the following command lists
(Skool Daze only):

* ``BullyHasMumps-Boy``
* ``GrassOnEric-Boy``
* ``HiddenPeaShooter-Boy``

It makes the character deliver the message in the command's sole argument, and
then unfreeze Eric (if he was frozen, as by the :ref:`findEric` command) as
soon as he has registered understanding of the message so delivered. If Eric is
slow to respond, the message will be repeated periodically.

TellKidsToSitDown
-----------------
The :class:`~ai.TellKidsToSitDown` command is used internally by the
:ref:`startLessonIfReady` command to make a character (a teacher, normally)
tell the kids to sit down when it's time to start class.

TripPeopleUp
------------
The :class:`~ai.TripPeopleUp` command is used as an argument to the
:ref:`setControllingCommand` command in the command lists ``Stampede-Leader``
and ``Stampede-Follower`` (Skool Daze only); it makes the character trip up
anyone in his path as he proceeds to his destination.

.. _unsignal:

Unsignal
--------
The :class:`~ai.Unsignal` command is used in the command lists
``Stampede-Leader`` and ``HiddenPeaShooter-Tearaway`` (Skool Daze only), to
lower signals previously raised. It takes a signal name as its sole argument,
as in::

  Unsignal, TearawayReady

WaitAtDoor
----------
The :class:`~ai.WaitAtDoor` command is used in the command list
``ShutGateAndDoor-Albert`` (Back to Skool only) to make Albert wait at the
skool door or the skool gate until all the characters are on the correct side
and it's therefore safe to shut the door or gate. The character flags `B` and
`G` (see :ref:`characters`) are used to determine which skool (and hence which
side of the door) a character belongs to. The ``WaitAtDoor`` command takes a
single argument: the unique ID of the door or gate (see :ref:`doors`).

.. _waitUntil:

WaitUntil
---------
The :class:`~ai.WaitUntil` command is used in the command list
``Assembly-Teacher`` (Back to Skool only) by Mr Creak and Mr Rockitt. It makes
the teacher do nothing (i.e. stand still) until a signal is raised. The command
takes a single argument: the name of the signal to wait for
(``AssemblyFinished`` in this case).

WalkAround
----------
The :class:`~ai.WalkAround` command is used in the following command lists in
Skool Daze:

* ``BigWindow``
* ``RandomWalkabout``
* ``Stampede-Leader``
* ``Walkabout-Bully``
* ``Walkabout-Tearaway``

and the following command lists in Back to Skool:

* ``PlaytimeWalkabout-Boy/Girl``
* ``Walkabout-Bully``
* ``Walkabout-Tearaway``

It takes a single argument, which is the number of walkarounds to do - a
"walkaround" being a short trip away from the origin (wherever the character
was when the ``WalkAround`` command was invoked) and back again.

The ``WalkAround`` command is also used internally by the :ref:`moveAboutUntil`
command.

.. _walkFast:

WalkFast
--------
The :class:`~ai.WalkFast` command is used as an argument to
:ref:`setControllingCommand` in the command lists ``GrassOnEric-Wacker`` and
``HiddenPeaShooter-Wacker`` (Skool Daze only) to make the headmaster rush on
his way to the fire escape (to find the hidden pea shooter) or to Eric (to give
him lines).

WalkUpOrDown
------------
The :class:`~ai.WalkUpOrDown` command is used internally by the
:ref:`conductClassWithEric` and :ref:`conductClassWithoutEric` commands to make
a teacher turn round and walk three paces. Called repeatedly, it makes the
teacher walk up and down.

.. _watchForEric:

WatchForEric
------------
The :class:`~ai.WatchForEric` command is used as an argument to
:ref:`setControllingCommand` in the command list ``ShutGateAndDoor-Albert``
(Back to Skool only) to make Albert keep his eyes peeled for our hero jumping
out of skool windows. If Albert does spot Eric trying to escape, control is
handed over to the :ref:`stopEric` command. The ``WatchForEric`` command takes
two arguments: the name of the command list to use for the character who will
be alerted by Albert when he spots Eric trying to escape (``ShadowEric`` in the
stock Pyskool); and the alert message to be screamed by Albert.

WipeBoard
---------
The :class:`~ai.WipeBoard` command is used internally by the
:ref:`conductClassWithEric` and :ref:`conductClassWithoutEric` commands to make
a character wipe a blackboard clean.

Write
-----
The :class:`~ai.Write` command is used internally to control Eric while he's
writing on a blackboard. It would be of no use in a command list.

WriteOnBoard
------------
The :class:`~ai.WriteOnBoard` command is used internally by the
:ref:`conductClassWithEric`, :ref:`conductClassWithoutEric` and
:ref:`writeOnBoardUnless` commands to make a character write on a blackboard.
The character should (ideally) be standing at the target blackboard before this
command is invoked.

The command takes a single argument, namely the message to be written on the
board. So if you wanted to use the command explicitly in a command list, you
could put something like::

  GoTo, ExamRoomBlackboard:Middle
  WriteOnBoard, 'Pyskool rox!'

.. _writeOnBoardUnless:

WriteOnBoardUnless
------------------
The :class:`~ai.WriteOnBoardUnless` command is used in the following command
lists in Skool Daze:

* ``ExamRoom-Tearaway``
* ``ReadingRoom-Tearaway``
* ``WhiteRoom-Tearaway``
* ``WriteOnBoards-Tearaway``

and the following command lists in Back to Skool:

* ``BlueRoom-Tearaway``
* ``ScienceLab-Tearaway``
* ``WriteOnBoardsInBoysSkool-Tearaway``
* ``WriteOnBoardsInGirlsSkool-Tearaway``
* ``YellowRoom-Tearaway``

It makes the Tearaway write on a blackboard unless the board has already been
written on or the signal named in the command's sole argument has been raised.
The signals used in Skool Daze are:

* ``EndOfLesson`` - the lesson has ended
* ``ExamRoomReady`` - it's time to start the lesson in the Exam Room
* ``ReadingRoomReady`` - it's time to start the lesson in the Reading Room
* ``WhiteRoomReady`` - it's time to start the lesson in the White Room

and the signals used in Back to Skool are:

* ``BlueRoomReady`` - it's time to start the lesson in the Blue Room
* ``EndOfLesson`` - the lesson has ended
* ``ScienceLabReady`` - it's time to start the lesson in the Science Lab
* ``YellowRoomReady`` - it's time to start the lesson in the Yellow Room
