.. _ini-file:

The ini file
============
The ini file (`skool_daze.ini` or `back_to_skool.ini`) determines many aspects
of the game, such as the names of the characters, the order of the lessons, and
what characters do during lessons. Each section of the ini file is described
below.

What follows is a description of every section of the ini files, and every
command found in the command lists that control the characters. Armed with this
knowledge, you'll be able to start mucking around with how Pyskool works and
the game characters behave.

If you can't be bothered to read any of this and instead just want to get your
modding hands dirty right now, head over to :ref:`example-customisations`.

If you're even lazier than that, head over to :ref:`example-ini-files` for a
description of the ready-made customised ini files distributed with Pyskool.

[AssemblyMessages]
------------------
The ``AssemblyMessages`` section contains all the information required to build
a message used by the headmaster during assembly in Back to Skool. There are
three types of entry in this section::

  MESSAGE, assemblyMessageTemplate

which defines the template for the assembly message, and::

  VERB, verb
  NOUN, noun

which define the verbs and nouns to substitute into the message template. There
must be at least one verb and one noun; they are chosen at random to form the
message.

The ``AssemblyMessages`` section appears only in `back_to_skool.ini`.

.. _bike:

[Bike]
------
The ``Bike`` section contains a single line of the form::

  bikeId, spriteGroupId, initialAnimatoryState, initialLocation, commandListId, topLeft, size, coords

where:

* ``bikeId`` is the bike's ID
* ``spriteGroupId`` is the ID of the :ref:`sprite group <spriteGroup>` to use
  for the bike
* ``initialAnimatoryState`` is the bike's initial animatory state
* ``initialLocation`` is the bike's initial coordinates (in `(x, y)` form)
  after being unchained
* ``commandListId`` is the unique ID of the :ref:`command list <commandList>`
  that the bike will use
* ``topLeft`` is the coordinates (in `(x, y)` form) of the top left of the
  image of the base of the tree with no bike attached
* ``size`` is the size of the image (in `(width, height)` form)
* ``coords`` are the coordinates (in `(x, y)` form) of the mutable image in the
  play area

The bike images can be found in `mutables.png` (or `mutables_ink.png` and
`mutables_paper.png` if ``GraphicsMode`` is 1 - see :ref:`graphics`).
`mutables.png` is arranged so that the image of the bike attached to the base
of the tree is at `(x + width, y)`, where `(x, y)` are the coordinates of the
image of the base of the tree with no bike attached. These two images are the
same size.

The ``Bike`` section appears only in `back_to_skool.ini`.

.. _blackboardMessages:

[BlackboardMessages]
--------------------
The ``BlackboardMessages`` section contains a list of messages written on the
blackboard by the teachers or the tearaway. Each line in this section takes the
form::

  characterId, message

where:

* ``characterId`` is the unique ID of the teacher or the tearaway
* ``message`` is the message

There are two special characters used in the blackboard messages: ``^`` and
``$``. ``^`` represents the newline character, and ``$`` is used to prefix the
unique ID of a character, as in::

  TEARAWAY, i hate^$WACKER

where ``$WACKER`` will be replaced by whatever name has been given to the
character whose unique ID is ``WACKER`` (see :ref:`characters`).

[Blackboards]
-------------
The ``Blackboards`` section defines the blackboards in the classrooms. Each
line takes the form::

  roomId, x, y

where:

* ``roomId`` is the classroom's unique ID (see :ref:`rooms`)
* ``x`` is the x-coordinate of the leftmost column of the blackboard
* ``y`` is the y-coordinate of the top row of the blackboard

.. _catapultPellets:

[CatapultPellets]
-----------------
Each line in the ``CatapultPellets`` section takes the form::

  characterId, pelletId, spriteGroupId, commandListId, range, hitZone

where:

* ``characterId`` is the unique ID of the catapult-wielding character
* ``pelletId`` is the unique ID of the catapult pellet
* ``spriteGroupId`` is the ID of the :ref:`sprite group <spriteGroup>` to use
  for the pellet
* ``commandListId`` is the unique ID of the :ref:`command list <commandList>`
  that the pellet will use
* ``range`` is the distance the pellet will fly after being launched
* ``hitZone`` is the size of the interval at the end of the pellet's flight
  where it can knock a character over

Each character whose unique ID appears in this section will be fitted out with
a catapult. In the stock Pyskool this will be Eric and the Tearaway - the only
characters with catapult-firing sprites.

.. _chairs:

[Chairs]
--------
The ``Chairs`` section contains one line for each classroom in the skool. Each
line takes the form::

  roomId, x1, x2, x3..., xN

where:

* ``roomId`` is the classroom's unique ID (see :ref:`rooms`)
* ``x1``, ``x2``, ``x3`` and so on are the x-coordinates of the chairs in the
  classroom

The order in which the x-coordinates are listed is significant: ``x1`` should
correspond to the 'front seat' and ``xN`` should correspond to the 'back seat'.
So if ``x1`` < ``xN`` (as in the stock `skool_daze.ini` and
`back_to_skool.ini`), characters will sit down facing left; if ``x1`` > ``xN``,
characters will sit down facing right.

.. _characters:

[Characters]
------------
Each line in the ``Characters`` section takes the form::

  characterId, name[/title], spriteGroupId, initialAnimatoryState, (x, y), flags

and corresponds to a single character, where:

* ``characterId`` is the character's unique ID (which should be alphanumeric
  and is used to refer to the character in other parts of the ini file)
* ``name`` is the character's name (as displayed in the game), and ``title``
  (if supplied) is the name used by the Swot to address the character
* ``spriteGroupId`` is the ID of the :ref:`sprite group <spriteGroup>` to use
  for the character
* ``initialAnimatoryState`` is the character's initial animatory state
* ``(x, y)`` are the character's initial coordinates
* ``flags`` is a string of flags defining the character's abilities and
  vulnerabilities

The initial animatory state takes form ``Ln`` or ``Rn``, where ``L`` means
facing left, ``R`` means facing right, and ``n`` is the index of the ``WALKn``
sprite (see :ref:`spriteGroup`).

Recognised flags and their meanings are:

* ``A`` - is an adult
* ``B`` - belongs in the boys' skool
* ``C`` - can be knocked over by a conker (see also ``Z``)
* ``D`` - can open doors and windows
* ``E`` - responsible for expelling Eric
* ``F`` - can be knocked out by a fist
* ``G`` - belongs in the girls' skool
* ``H`` - responsible for fetching Eric when he's trying to escape
* ``K`` - holds the key to the safe
* ``L`` - can give lines
* ``M`` - is scared of mice
* ``N`` - can smell stinkbombs (and will open a nearby window if possible)
* ``P`` - can be knocked over by a catapult pellet
* ``R`` - can receive lines
* ``S`` - holds a safe combination letter
* ``W`` - usually walks (unlike kids who sometimes run)
* ``X`` - holds a bike combination digit
* ``Y`` - holds a storeroom door combination letter
* ``Z`` - will be temporarily paralysed if struck by a falling conker (see also
  ``C``)

[CharacterWidths]
-----------------
The ``CharacterWidths`` section is used to determine the location and size of
the font bitmaps in the `font.png` graphic. Each line takes the form::

  "char", offset, width

where:

* ``char`` is the font character (e.g. ``f``, ``@``, ``!``)
* ``offset`` is the font character's distance in pixels from the left of the
  image
* ``width`` is its width in pixels

.. _commandList:

[CommandList ...]
-----------------
The ``[CommandList ...]`` section names take the form::

  CommandList commandListId

where ``commandListId`` is a descriptive unique ID for the list of commands
that follows. These unique IDs are used in the :ref:`lessons` sections: for
each type of lesson there is, every character is assigned a single command list
to follow.

One example of a command list is::

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

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

Each line in a command list takes the form of the command name followed by a
comma-separated list of arguments. See the
:ref:`command reference <command-ref>` for more details on the commands that may
be used to control a character.

.. _conker:

[Conker]
--------
The ``Conker`` section defines a conker (as knocked out of the tree by a
catapult pellet). It contains a single line of the form::

  objectId, spriteGroupId, commandListId, minX, maxX, minY, maxY

where:

* ``objectId`` is a unique ID for the conker
* ``spriteGroupId`` is the ID of the :ref:`sprite group <spriteGroup>` to use
  for the conker
* ``commandListId`` is the unique ID of the :ref:`command list <commandList>`
  that the conker will use when knocked out of the tree
* ``minX``, ``maxX``, ``minY`` and ``maxY`` define the rectangle inside the
  tree that contains the conker; a pellet that hits a spot in that rectangle
  will cause a conker to fall

The ``Conker`` section appears only in `back_to_skool.ini`.

.. _cups:

[Cups]
------
The ``Cups`` section contains information about cups (of which there are four
in Back to Skool, and none in Skool Daze). Each line describes a single cup,
and takes the form::

  cupId, emptyTopLeft, size, coords

where:

* ``cupId`` is the unique ID of the cup
* ``emptyTopLeft`` is the coordinates (in `(x, y)` form) of the top left of the
  image of the cup when empty
* ``size`` is the size of the image (in `(width, height)` form)
* ``coords`` are the coordinates (in `(x, y)` form) of the cup in the skool

The cup images can be found in `mutables.png` (or `mutables_ink.png` and
`mutables_paper.png` if ``GraphicsMode`` is 1 - see :ref:`graphics`).
`mutables.png` is arranged so that the image of a cup when it contains water is
at `(x + width, y)`, and the image of a cup when it contains sherry is at
`(x + 2 * width, y)` (where `(x, y)` are the coordinates of the image of the
cup when empty). The three images for any given cup are the same size.

The ``Cups`` section appears only in `back_to_skool.ini`.

.. _deskLid:

[DeskLid]
---------
The ``DeskLid`` section contains a single line of the form::

  deskLidId, spriteGroupId, commandListId

where:

* ``deskLidId`` is the unique ID of the desk lid
* ``spriteGroupId`` is the ID of the :ref:`sprite group <spriteGroup>` to use
  for the desk lid when raised
* ``commandListId`` is the unique ID of the :ref:`command list <commandList>`
  that the desk lid will use when raised

The ``DeskLid`` section appears only in `back_to_skool.ini`.

.. _desks:

[Desks]
-------
The ``Desks`` section contains one line for each classroom in the skool. Each
line takes the form::

  roomId, x1, x2...

where

* ``roomId`` is the classroom's unique ID (see :ref:`rooms`)
* ``x1``, ``x2`` and so on are the x-coordinates of the desks in the classroom

The ``Desks`` section appears only in `back_to_skool.ini`.

.. _doors:

[Doors]
-------
The ``Doors`` section contains details of the doors in the game. Each line
takes the form::

  doorId, x, bottomY, topY, initiallyShut, autoShuts, shutTopLeft, size, coords

where:

* ``doorId`` is the door's unique ID
* ``x`` is the door's x-coordinate
* ``bottomY`` and ``topY`` are the y-coordinates of the bottom and top of the
  door
* ``initiallyShut`` is ``Y`` if the door should be shut when the game starts
* ``autoShuts`` is ``Y`` if the door should swing shut after a short time
* ``shutTopLeft`` is the coordinates (in `(x, y)` form) of the top left of the
  image of the door when shut
* ``size`` is the size of the image (in `(width, height)` form)
* ``coords`` are the coordinates (in `(x, y)` form) of the door in the skool

The door images can be found in `mutables.png` (or `mutables_ink.png` and
`mutables_paper.png` if ``GraphicsMode`` is 1 - see :ref:`graphics`).
`mutables.png` is arranged so that the image of a door when open is at
`(x + width, y)`, where `(x, y)` are the coordinates of the image of the same
door/window when shut. The open/shut images for any given door are the same
size.

The ``Doors`` section appears only in `back_to_skool.ini`.

[Eric]
------
The ``Eric`` section describes our hero, Eric. It contains a single line in the
format::

  characterId, name, spriteGroupId, initialAnimatoryState, (x, y), flags

where:

* ``characterId`` is Eric's unique ID (which should be alphanumeric)
* ``name`` is Eric's name
* ``spriteGroupId`` is the ID of the :ref:`sprite group <spriteGroup>` to use
  for Eric
* ``initialAnimatoryState`` is Eric's initial animatory state
* ``(x, y)`` are Eric's initial coordinates
* ``flags`` is a string of flags defining Eric's abilities and vulnerabilities

For a description of the format of the initial animatory state and the
available flags, see :ref:`characters`.

.. _floors:

[Floors]
--------
The ``Floors`` section contains details of the "floors" in the skool. A "floor"
(note the quotes) is a region of the skool that cannot be reached from another
region of the skool without navigating a staircase. For example, in Skool Daze,
the region to the left of the Map Room wall is one floor, and the region to the
right of the Map Room wall is another floor. You can't get from one to other
without going up or down a staircase (walking through walls is prohibited).

Each line in this section takes the form::

  floorId, minX, maxX, y

where:

* ``floorId`` is the floor's unique ID
* ``minX`` and ``maxX`` are the x-coordinates of the left and right limits of
  the floor
* ``y`` is the y-coordinate of the floor (3 = top floor, 10 = middle floor,
  17 = bottom floor)

The unique IDs are used in the :ref:`routes` section.

.. _frogs:

[Frogs]
-------
Each line in the ``Frogs`` section takes the form::

  frogId, spriteGroupId, initialAnimatoryState, initialLocation, commandListId

where:

* ``frogId`` is the unique ID of the frog
* ``spriteGroupId`` is the ID of the :ref:`sprite group <spriteGroup>` to use
  for the frog
* ``initialAnimatoryState`` is the frog's initial animatory state
* ``initialLocation`` is the frog's initial coordinates (in `(x, y)` form)
* ``commandListId`` is the unique ID of the :ref:`command list <commandList>`
  that the frog will use

Any frog defined in this section will be catchable by ERIC, and show up in the
on-screen inventory when caught.

The ``Frogs`` section appears only in `back_to_skool.ini`.

.. _game:

[Game]
------
The ``Game`` section contains configuration parameters in the format::

  parameterName, parameterValue

Recognised parameters are:

* ``AllShieldsScore`` - points awarded for hitting all the shields
* ``Cheat`` - 0 = disable cheat keys, 1 = enable cheat keys
* ``ImagesDir`` - the base directory containing the game images
* ``ImageSet`` - the name of the image set to use
* ``InitialColumn`` - the x-coordinate of the leftmost column of the screen
  when the game starts
* ``GameFps`` - the number of frames per second at which the game should
  attempt to run; raise it to increase the game speed, or lower it to decrease
  the game speed
* ``LessonLength`` - the length of a lesson period in frames (see ``GameFps``)
* ``LessonStartTime`` - when a lesson starts (i.e. teacher will tell kids to
  sit down) in frames (see ``GameFps``) from the start of the period
* ``MaxLines`` - the maximum number of lines Eric may accumulate before being
  expelled
* ``Name`` - the name of the game
* ``PlayTuneOnRestart`` - 1 to play the theme tune after restarting the game
  for advancing a year; 0 otherwise
* ``QuickStart`` - 0 to scroll the skool into view and play the theme tune (as
  in the original games); 1 to skip this sequence
* ``RestartOnYearEnd`` - 1 if the game should restart after advancing a year
  (as in Back to Skool); 0 otherwise (as in Skool Daze)
* ``SafeOpenScore`` - points awarded for opening the safe with the correct
  combination
* ``SoundsDir`` - the base directory containing the sound samples
* ``UpAYearMessage`` - message printed in the lesson box when Eric has
  completed the game and advanced a year
* ``UpAYearScore`` - points awarded for advancing a year

[Grass]
-------
The ``Grass`` section contains five lines of the form::

  Writers, characterId[, characterId...]
  WriteTale, <text>
  Hitters, characterId[, characterId...]
  HitTale, <text>
  AbsentTale, <text>

The information in this section is used by the Swot to determine who can be
blamed for hitting him or writing on a blackboard, and what to say when telling
tales.

The ``Writers`` line contains a comma-separated list of IDs of characters who
can be blamed for writing on a blackboard. The ``WriteTale`` line contains the
text of the blackboard-writing tale.

The ``Hitters`` line contains a comma-separated list of IDs of characters who
can be blamed for hitting the Swot. The ``HitTale`` line contains the text of
the so-and-so-hit-me tale.

The ``AbsentTale`` line contains the text that will be spoken by the Swot when
he's telling on Eric for being absent during class.

The text of a tale may contain ``$TITLE`` (which will be replaced by the
teacher's title, as defined in the :ref:`characters` section), ``$1`` (which
will be replaced by the name of the hitter or writer chosen from the
``Hitters`` or ``Writers`` list), or ``$characterId`` (where ``characterId`` is
the unique ID of any character, and which will be replaced by the name of that
character).

.. _images:

[Images]
--------
Each line in the ``Images`` section takes the form::

  imageId, path

where

* ``imageId`` is the unique ID of an image
* ``path`` is the location of the corresponding image file on disk (relative to
  the ``ImagesDir`` directory declared in the :ref:`game` section)

Recognised image IDs and the images they refer to are:

* ``FONT``: the skool font
* ``INVENTORY``: mouse, frog, water pistol etc. (Back to Skool only)
* ``LOGO``: the logo
* ``MUTABLES``: doors, windows etc. (Back to Skool) or shields and safe (Skool
  Daze)
* ``MUTABLES_INK``: doors, windows etc. (Back to Skool only)
* ``MUTABLES_PAPER``: doors, windows etc. (Back to Skool only)
* ``SCOREBOX``: , the score/lines/hi-score box
* ``SKOOL``: the skool (full colour)
* ``SKOOL_INK``: the skool (ink colours only)
* ``SKOOL_PAPER``: the skool (paper colours only)
* ``SPEECH_BUBBLE``: speech bubble and lip
* ``SPRITES``: the characters in various 'animatory states'

.. _inventory:

[Inventory]
-----------
Each line in the ``Inventory`` section takes the form::

  itemId, topLeft, size

where:

* ``itemId`` is the unique ID of an item that can be collected
* ``topLeft`` is the coordinates (in `(x, y)` form) of the top left of the
  image of the item in `inventory.png`
* ``size`` is the size of the image (in `(width, height)` form)

The item IDs recognised by Pyskool are as follows:

* ``FROG`` - a frog
* ``MOUSE`` - a mouse
* ``SAFE_KEY`` - the key to the head's safe
* ``SHERRY_PISTOL`` - a water pistol (containing sherry)
* ``STINKBOMBS3`` - three stinkbombs
* ``STINKBOMBS2`` - two stinkbombs
* ``STINKBOMBS1`` - one stinkbomb
* ``STOREROOM_KEY`` - the key to the science lab storeroom
* ``WATER_PISTOL`` - a water pistol (containing water)

The order in which the items appear in the ``Inventory`` section determines the
order in which they will be printed in the on-screen inventory.

See also the :ref:`mice` and :ref:`frogs` sections (for details on those
animals), and the ``InventoryPos`` and ``MouseInventoryPos`` game configuration
parameters in the :ref:`game` section.

The ``Inventory`` section appears only in `back_to_skool.ini`.

.. _lessons:

[Lesson ...]
------------
The ``[Lesson ...]`` section names take the form::

  Lesson lessonId [*]characterId, roomId

if the lesson will take place with a teacher in a classroom or the dinner hall,
or::

  Lesson lessonId locationId

if the lesson is an unsupervised period, where:

* ``lessonId`` is the lesson ID as it appears in the :ref:`timetable` section
* ``characterId`` is the character ID of the teacher taking Eric's class
  (prefixed by '*' if the teacher's  name should not be printed in the lesson
  box, as during ``DINNER``)
* ``roomId`` is the ID of the room in which Eric's class will take place
* ``locationId`` is one of ``PLAYTIME``, ``REVISION LIBRARY``, and ``ASSEMBLY``

Each line in a ``[Lesson ...]`` section takes the form::

  characterId, commandListId

where

* ``characterId`` is the unique ID of a character (see :ref:`characters`)
* ``commandListId`` is the ID of the :ref:`command list <commandList>` that
  will control the character's movements during the lesson

A command list is a sequence of commands - such as :ref:`goTo` or
:ref:`findSeat` - that make a character appear intelligent (kind of). See
:ref:`commandList` for more details.

In any ``[Lesson ...]`` section there should be one line for each character
defined in the :ref:`characters` section.

[LessonMessages]
----------------
The ``LessonMessages`` section contains a list of messages that will be used by
teachers who are not teaching Eric, or teachers who are teaching Eric but have
chosen not to do a question-and-answer session. Each line in the section takes
the form::

  characterId|*, lessonMessage[, condition]

where:

* ``characterId`` is the unique ID of a teacher
* ``lessonMessage`` is the message to add to that teacher's repertoire
* ``condition`` is a condition identifier that must evaluate to true before the
  message can be used

If ``*`` is used instead of a specific character ID, the message will be placed
in every teacher's repertoire. The message may contain the character sequence
``$n``, which will be replaced by a random number between 100 and 999. The only
recognised condition identifier is:

* ``BoardDirty``

which, if specified, means the message will be used only if the blackboard (if
there is one) has been written on. Any other condition identifier will evaluate
to true.

.. _linesMessages:

[LinesMessages]
---------------
The ``LinesMessages`` section contains a list of admonitions delivered by
lines-givers when Eric has been spotted doing something he shouldn't. Each line
in this section takes the form::

  characterId|*, linesMessageId, linesMessage

where

* ``characterId`` is the unique ID of the lines-giving character
* ``linesMessageId`` is the unique ID of the following message
* ``linesMessage`` is the admonition itself

If ``*`` is used instead of a character ID, the lines message will be used by
all lines-givers (unless they have been explicitly assigned a lines message
with the same lines message ID). For example::

  WITHIT, NO_HITTING, BE GENTLE^NOW
  *, NO_HITTING, DON'T HIT^YOUR MATES

would make Mr Withit scream "BE GENTLE NOW" whenever he sees Eric throwing a
punch, whereas every other teacher would scream "DON'T HIT YOUR MATES" instead.

A lines message always spans two lines on-screen. A caret (``^``) is used to
indicate where the words should be wrapped.

Lines message IDs used in both Skool Daze and Back to Skool are:

* ``BE_PUNCTUAL`` - Eric was late for class
* ``COME_ALONG_1`` - the truant Eric is being guided to the classroom
* ``COME_ALONG_2`` - the truant Eric is still being guided to the classroom
* ``GET_ALONG`` - Eric is not in class when he should be
* ``GET_OUT`` - Eric's somewhere that only staff are allowed to be
* ``GET_UP`` - Eric is sitting on the floor
* ``NEVER_AGAIN`` - teacher thinks Eric knocked him down
* ``NO_CATAPULTS`` - catapults are forbidden
* ``NO_HITTING`` - Eric must not throw punches
* ``NO_TALES`` - the Swot gets his just deserts
* ``NO_WRITING`` - Eric mustn't write on blackboards
* ``SIT_DOWN`` - Eric is not sitting down in class
* ``STAY_IN_CLASS`` - Eric popped out of class and then returned

Lines message IDs used only in Skool Daze are:

* ``COME_ALONG_3`` - the truant Eric still hasn't made it to the classroom
* ``NO_JUMPING`` - jumping is not allowed in Skool Daze
* ``NO_SITTING_ON_STAIRS`` - sitting on stairs is not allowed in Skool Daze

Lines message IDs used only in Back to Skool are:

* ``BACK_TO_SKOOL`` - Eric should be back in the boys' skool by now
* ``GET_OFF_PLANT`` - standing on plants is not good
* ``NO_BIKES`` - riding bikes inside the skool is also not good
* ``NO_STINKBOMBS`` - stinkbombs are prohibited
* ``NO_WATERPISTOLS`` - as are water pistols
* ``SIT_FACING_STAGE`` - Eric needs to face the headmaster during assembly

The lines message IDs are used internally, and should not be changed. If a
particular lines message ID is missing from the list, then lines will not be
given for the infraction it refers to. So if there were no entry in the
``LinesMessages`` section with the lines message ID ``NO_HITTING``, no lines
would ever be dished out for hitting.

.. _mice:

[Mice]
------
Each line in the ``Mice`` section takes the form::

  mouseId, spriteGroupId, initialAnimatoryState, initialLocation, commandListId

where:

* ``mouseId`` is the unique ID of the mouse
* ``spriteGroupId`` is the ID of the :ref:`sprite group <spriteGroup>` to use
  for the mouse
* ``initialAnimatoryState`` is the mouse's initial animatory state
* ``initialLocation`` is the mouse's initial coordinates (in `(x, y)` form)
* ``commandListId`` is the ID of the :ref:`command list <commandList>` that the
  mouse will use

Any mouse defined in this section will be catchable by ERIC, and show up in the
on-screen mouse inventory when caught.

The ``Mice`` section appears only in `back_to_skool.ini`.

[NoGoZones]
-----------
Each line in the ``NoGoZones`` section corresponds to a region of the skool
Eric is never supposed to enter. The lines take the form::

  zoneId, minX, maxX, bottomY, topY

where:

* ``zoneId`` is a descriptive ID for the zone (not used anywhere else)
* ``minX`` is the lower x-coordinate of the zone
* ``maxX`` is the upper x-coordinate of the zone
* ``bottomY`` is the y-coordinate of the bottom of the zone
* ``topY`` is the y-coordinate of the top of the zone

Whenever Eric is spotted in one of these zones by a teacher, the ``GET_OUT``
:ref:`lines message <linesMessages>` will be delivered in screeching tones.

.. _plants:

[Plants]
--------
The ``Plants`` section contains information about plants (of which there are
four in Back to Skool, and none in Skool Daze). Each line describes a single
plant, and takes the form::

  plantId, spriteGroupId, x, y, commandListId

where:

* ``plantId`` is the unique ID of the plant
* ``spriteGroupId`` is the ID of the :ref:`sprite group <spriteGroup>` to use
  for the plant
* ``x`` and ``y`` are the coordinates of the plant (when it is growing or has
  grown)
* ``commandListId`` is the unique ID of the :ref:`command list <commandList>`
  that the plant will use when watered

The ``Plants`` section appears only in `back_to_skool.ini`.

[QuestionsAndAnswers ...]
-------------------------
The ``[QuestionsAndAnswers ...]`` section names take the form::

  QuestionsAndAnswers characterId

where ``characterId`` is the unique ID of a teacher (see :ref:`characters`).

There are at least three types of entry in a ``[QuestionsAndAnswers ...]``
section. The first type of entry is the ``Question`` entry::

  Question, questionId, groupId, questionTemplate

where:

* ``questionId`` is a unique (within the section) ID for the question
* ``groupId`` is the ID of the group of QAPairs (see below) the question is
  associated with
* ``questionTemplate`` is the question template

There should be at least one ``Question`` entry in a
``[QuestionsAndAnswers ...]`` section.

The second type of entry is the ``Answer`` entry::

  Answer, questionId, answerTemplate

where:

* ``questionId`` is the ID of the question to which this is the answer
* ``answerTemplate`` is the answer template

There should be one ``Answer`` entry for each ``Question`` entry in a
``[QuestionsAndAnswers ...]`` section.

The third type of entry in this section is the ``QAPair`` entry::

  QAPair, groupId, qa1, qa2

where

* ``groupId`` is the ID of the group of QAPairs to which this particular
  ``QAPair`` belongs
* ``qa1`` and ``qa2`` are the words that will replace the macros in
  ``questionTemplate`` and ``answerTemplate``

There should be at least one ``QAPair`` entry per ``[QuestionsAndAnswers ...]``
section (and ideally many more than one, to prevent the question-and-answer
sessions between teachers and the swot from being rather monotonous).

The optional fourth type of entry in a ``[QuestionsAndAnswers ...]`` section
consists of three lines::

  SpecialQuestion, question
  SpecialAnswer, answer
  SpecialGroup, groupId, qaPairIndex

and is used to define the "special" question Eric will need the answer to in
order to obtain the relevant teacher's safe combination letter. The
``SpecialQuestion`` keyword is followed by the text of the special question
(which will be posed by the teacher at the start of the lesson). The
``SpecialAnswer`` keyword is followed by the text of the Swot's answer to the
special question (which will contain a macro to be expanded). The
``SpecialGroup`` keyword is followed by ``groupId`` (which specifies the ID of
the group of QA Pairs from which the "magic word" will be taken), and
``qaPairIndex`` (which is 0 or 1, and refers to which element of the QAPair
will be the magic word). Once Eric has figured out what the magic word is, he
will need to write it on a blackboard and hope that the teacher sees it while
all the shields are flashing, whereupon the teacher will reveal his safe
combination letter.

If the ``SpecialQuestion``, ``SpecialAnswer`` and ``SpecialGroup`` lines are
not present, there will be no magic word associated with the teacher. In that
case, simply knocking the teacher over with a catapult pellet will make him
reveal his safe combination letter.

.. _randomLocations:

[RandomLocations]
-----------------
The ``RandomLocations`` section contains lists of suitable locations for the
characters to visit when they go on walkabouts (e.g. during playtime). Each
line takes the form::

  characterId, (x1, y1), (x2, y2)...

where:

* ``characterId`` is the character's unique ID (see :ref:`characters`)
* ``(x1, y1)`` and so on are the coordinates of locations in the skool

There must be at least one pair of coordinates per line, and there should be
one line for each character defined in the ``[Characters]`` section.

.. _rooms:

[Rooms]
-------
The ``Rooms`` section contains one line for each room or region in the skool
that Eric will be expected to show up at when the timetable requires it. Each
line takes the form::

  roomId, name, y, minX, maxX, getAlong

where:

* ``roomId`` is the room's unique ID
* ``name`` is the room's name (as displayed in the lesson box at the bottom of
  the screen)
* ``y`` is the room's y-coordinate (3 = top floor, 10 = middle floor)
* ``minX`` and ``maxX`` are the x-coordinates of the left and right ends of the
  room
* ``getAlong`` is `Y`` if Eric should get lines for being in the room when the
  timetable does not require his presence

.. _routes:

[Routes]
--------
The ``Routes`` section is one of the most important sections in the ini file.
It defines the routes (a route may be considered as a list of staircases) that
the characters must take to get from where they are to wherever they are going.
Any errors here will result in the characters wandering aimlessly around the
skool, unable to find classrooms, the playground, or the toilets. Disaster!

Anyway, each line in this section takes the form::

  homeFloorId, *|destFloorId[, destFloorId[, ...]], nextStaircaseId

where:

* ``homeFloorId`` is the unique ID of one floor (see :ref:`floors`) - the
  'home' floor
* ``destFloorId`` is the unique ID of another floor (see :ref:`floors`) - the
  destination floor
* ``nextStaircaseId`` is the unique ID of the staircase (see :ref:`staircases`)
  that must be climbed or descended first on a journey from the home floor to
  the destination floor

How this works is best illustrated by example. Let's look at the routes defined
for the bottom floor in Back to Skool to everywhere else in the skool::

  Bottom, LeftMiddle, LeftTop, UpToToilets
  Bottom, GirlsMiddle, GirlsTop, GirlsSkoolLower
  Bottom, *, UpToStage

The first line says that to get from the bottom floor (``Bottom``) to the
floors called ``LeftMiddle`` and ``LeftTop`` (see :ref:`floors`), the first
staircase you need to navigate is ``UpToToilets`` (see :ref:`staircases`). The
second line says that to get from the bottom floor to the middle floor
(``GirlsMiddle``) or top floor (``GirlsTop``) in the girls' skool, you need to
use the ``GirlsSkoolLower`` staircase first. The third line says that to get
anywhere else (``*``) from the bottom floor, you need to take the stairs up to
the stage (``UpToStage``).

[Safe]
------
The ``Safe`` section contains a single line of the form::

  topLeft, size, coords

where:

* ``topLeft`` is the coordinates (in `(x, y)` form) of the top left of the
  normal image of the safe
* ``size`` is the size of the image (in `(width, height)` form)
* ``coords`` are the coordinates (in `(x, y)` form) of the safe in the play
  area

The safe images can be found in `mutables.png` (or `mutables_ink.png` and
`mutables_paper.png` if ``GraphicsMode`` is 1 - see :ref:`graphics`).
`mutables.png` is arranged so that the inverse image of the safe is at
`(x + width, y)`, where `(x, y)` are the coordinates of the normal image of the
safe.

If the safe will never need to flash (as in Back to Skool), ``topLeft`` and
``size`` will not be used, and so may be set to any value.

.. _screen:

[Screen]
--------
The ``Screen`` section contains parameters that determine the appearance and
layout of the screen. Each line has the form::

  parameterName, parameterValue

Recognised parameters are:

* ``Background`` - the background colour of the screen
* ``GraphicsMode`` - 0 = hi-res colour; 1 = spectrum mode, meaning just two
  colours (ink and paper) per 8x8-pixel block
* ``Height`` - the height of the screen (in tiles)
* ``InventoryPos`` - the x, y coordinates of the inventory on screen
* ``LessonBoxAttribute`` - the attribute byte of the lesson box
* ``LessonBoxPos`` - the x, y coordinates of the lesson box on screen
* ``LogoPos`` - the x, y coordinates of the logo on screen
* ``MouseInventoryPos`` - the x, y coordinates of the mouse inventory on screen
* ``Scale`` - the scale factor to use for graphics; 1 = original Spectrum size
* ``ScoreBoxAttribute`` - the attribute value (bright/ink/paper) for the score
  box
* ``ScoreBoxPos`` - the x, y coordinates of the score/lines/hi-score box on
  screen
* ``ScoreBoxXOffset`` - used for positioning text in the score box
* ``ScrollFps`` - the number of frames per second at which the screen should be
  scrolled (when the game starts and during play); raise it to make the screen
  scroll faster, or lower it to scroll more slowly
* ``ScrollColumns`` - the number of columns to scroll when Eric approaches the
  left or right edge of the screen
* ``ScrollLeftOffset`` - how close Eric can get to the right edge of the screen
  before it scrolls left
* ``ScrollRightOffset`` - how close Eric can get to the left edge of the screen
  before it scrolls right
* ``Width`` - the width of the screen (in tiles)

.. _sherryDrop:

[SherryDrop]
------------
The ``SherryDrop`` section defines a drop of sherry (as knocked out of a cup by
a catapult pellet). It contains a single line of the form::

  objectId, spriteGroupId, commandListId

where:

* ``objectId`` is a unique ID for the drop of sherry
* ``spriteGroupId`` is the ID of the :ref:`sprite group <spriteGroup>` to use
  for the drop of sherry
* ``commandListId`` is the unique ID of the :ref:`command list <commandList>`
  that the drop of sherry will use when knocked out of a cup

The ``SherryDrop`` section appears only in `back_to_skool.ini`.

[Shields]
---------
The ``Shields`` section contains information about shields (of which there are
15 in Skool Daze, and none in Back to Skool). Each line describes a single
shield, and takes the form::

  score, topLeft, size, coords

where:

* ``score`` is the number of points awarded for making the shield flash or
  unflash
* ``topLeft`` is the coordinates (in `(x, y)` form) of the top left of the
  normal image of the shield
* ``size`` is the size of the image (in `(width, height)` form)
* ``coords`` are the coordinates (in `(x, y)` form) of the shield in the play
  area

The shield images can be found in `mutables.png` (or `mutables_ink.png` and
`mutables_paper.png` if ``GraphicsMode`` is 1 - see :ref:`graphics`).
`mutables.png` is arranged so that the inverse image of a shield is at
`(x + width, y)`, where `(x, y)` are the coordinates of the normal image of the
shield.

.. _sitDownMessages:

[SitDownMessages]
-----------------
The ``SitDownMessages`` section contains one line for each teacher of the
form::

  characterId, sitDownMessage

where

* ``characterId`` is the teacher's unique ID (see :ref:`characters`)
* ``sitDownMessage`` is what the teacher says at the start of a lesson

For example::

  CREAK, SIT DOWN YOU LITTLE ANARCHISTS

.. _skoolLocations:

[SkoolLocations]
----------------
The ``SkoolLocations`` section contains a list of descriptive IDs for commonly
used locations in the skool. These descriptive IDs are used by the :ref:`goTo`
command in the command lists that control the characters (see
:ref:`commandList`). Each line in this section takes the form::

  locationId, x, y

where

* ``locationId`` is the descriptive ID
* ``x`` and ``y`` are the coordinates of the location

An example of a location ID is ``BlueRoomDoorway``, which means exactly what
you think it means.

.. _sounds:

[Sounds]
--------
Each line in the ``Sounds`` section takes the form::

  soundId, path

where

* ``soundId`` is the unique ID of a sound sample
* ``path`` is the location of the sound sample on disk (relative to the
  ``SoundsDir`` directory declared in the :ref:`game` section)

Recognised sound sample IDs and the samples they refer to are:

* ``ALL_SHIELDS``: Eric has hit all the shields
* ``BELL``: the bell
* ``BIKE``: Eric has written the bike combination on a blackboard
* ``CATAPULT``: Eric has fired his catapult
* ``CONKER``: Eric has knocked out Albert with a conker
* ``DESK``: Eric has found the water pistol or stinkbombs in a desk
* ``FROG``: Eric has caught the frog or placed it in a cup
* ``KISS``: Eric has kissed someone
* ``KNOCKED_OUT``: Eric has been knocked over or out of his chair
* ``LINES1``: lines screech 1
* ``LINES2``: lines screech 2
* ``MOUSE``: Eric has caught a mouse
* ``OPEN_SAFE``: Eric has opened the safe (by getting the combination)
* ``SAFE_KEY``: Eric has got the safe key
* ``SHERRY``: Eric has filled the water pistol with sherry
* ``SHIELD``: Eric has hit a shield
* ``STOREROOM_KEY``: Eric has written the storeroom combination on a blackboard
* ``TUNE``: opening tune
* ``UP_A_YEAR``: Eric has gone up a year
* ``WALK0``: Eric walking (1)
* ``WALK1``: Eric walking (2)
* ``WALK2``: Eric walking (3)
* ``WALK3``: Eric walking (4)
* ``WATER_PISTOL``: Eric has fired his water pistol

[SpecialPlaytimes]
------------------
The ``SpecialPlaytimes`` section is used only in `skool_daze.ini`, and contains
a list of lesson IDs that refer to playtimes which will be considered
"special". A special playtime does not appear in the timetable proper (though
you could insert it), but three times out of eight a random special playtime is
substituted for an actual playtime timetable entry. In the stock
`skool_daze.ini` the ``SpecialPlaytimes`` section looks like this::

  Playtime-Mumps
  Playtime-SwotGrass
  Playtime-HiddenPeaShooter

Thus, three playtimes out of every eight in Skool Daze mode will be one of
those where you have to steer clear of the pestilential Bully, prevent the Swot
from reaching the head's study, or fix the race to the fire escape between the
Tearaway and the headmaster.

.. _spriteGroup:

[SpriteGroup ...]
-----------------
The ``[SpriteGroup ...]`` section names take the form::

  SpriteGroup spriteGroupId

where ``spriteGroupId`` is a unique ID for a group of sprites in `sprites.png`
(see :ref:`graphics`) - such as ``BOY`` for the little boys, or ``TEARAWAY``
for the tearaway. The unique ID can be anything you like; it is used only in
the :ref:`characters` section later on to link a character to a specific group
of sprites.

Each line in a ``SpriteGroup`` section represents a single sprite from
`sprites.png` and takes the form::

  spriteId, index

where

* ``spriteId`` is the descriptive ID for the sprite (unique within the section)
* ``index`` is the index of the sprite as it appears in `sprites.png`

Recognised sprite IDs and their meanings are:

* ``ARM_UP``: arm up (as if writing or opening door) - Eric, the Tearaway, the
  Heroine and teachers
* ``BENDING_OVER``: bending over - Eric
* ``BIKE_ON_FLOOR``: bike resting on the floor
* ``BIKE_UPRIGHT``: bike upright
* ``CATAPULT0``: firing catapult (1) - Eric and the Tearaway
* ``CATAPULT1``: firing catapult (2) - Eric and the Tearaway
* ``CONKER``: conker
* ``DESK_EMPTY``: desk lid (empty desk)
* ``DESK_STINKBOMBS``: desk lid (with stinkbombs)
* ``DESK_WATER_PISTOL``: desk lid (with water pistol)
* ``FLY``: catapult pellet in flight
* ``HITTING0``: hitting (1) - Eric and the Bully
* ``HITTING1``: hitting (2) - Eric and the Bully
* ``HOP1``: frog hopping (phase 1)
* ``HOP2``: frog hopping (phase 2)
* ``KISSING_ERIC``: kissing Eric - the Heroine
* ``KNOCKED_OUT``: lying flat on back - kids
* ``KNOCKED_OVER``: sitting on floor holding head - adults
* ``PLANT_GROWING``: plant (half-grown)
* ``PLANT_GROWN``: plant (fully grown)
* ``RIDING_BIKE0``: riding bike (1) - Eric
* ``RIDING_BIKE1``: riding bike (2) - Eric
* ``RUN``: mouse
* ``SHERRY_DROP``: drop of sherry (knocked from a cup)
* ``SIT``: frog sitting
* ``SITTING_ON_CHAIR``: sitting on a chair - kids
* ``SITTING_ON_FLOOR``: sitting on the floor - kids
* ``STINKBOMB``: stinkbomb cloud
* ``WALK0``: standing/walking (1) - all characters
* ``WALK1``: midstride (1) - all characters
* ``WALK2``: standing/walking (2) - all characters
* ``WALK3``: midstride (2) - all characters
* ``WATER_DROP``: drop of water (knocked from a cup)
* ``WATER0``: water fired from a pistol (phase 1)
* ``WATER1``: water fired from a pistol (phase 2)
* ``WATER2``: water fired from a pistol (phase 3)
* ``WATER3``: water fired from a pistol (phase 4)
* ``WATER4``: water fired from a pistol (phase 5)
* ``WATERPISTOL``: shooting water pistol - Eric

.. _staircases:

[Staircases]
------------
The ``Staircases`` section contains details of the staircases in the skool.
Each line takes the form::

  staircaseId[:alias], bottom, top[, force]

where:

* ``staircaseId`` is the staircase's unique ID
* ``alias`` is an optional alias for the staircase (also unique)
* ``bottom`` and ``top`` are the coordinates of the bottom and top of the
  staircase (in `(x, y)` form)
* ``force``, if present, indicates that the staircase must be climbed or
  descended by Eric if he moves to a location between the bottom and the top

In the stock Pyskool, ``force`` is used only for the staircase in Back to Skool
that leads down to the assembly hall stage; it's the only staircase that you
must go up or down if you approach it.

An example of a line from the ``Staircases`` section is::

  UpToStudy:DownFromStudy, (91, 10), (84, 3)

which defines the staircase that leads up to the head's study in Back to Skool.
This staircase's unique ID is ``UpToStudy``, but it can also be referred to as
``DownFromStudy``. These unique IDs and aliases are used later on in the
:ref:`routes` section.

.. _stinkbombs:

[Stinkbombs]
------------
Each line in the ``Stinkbombs`` section takes the form::

  characterId, stinkbombId, spriteGroupId, commandListId

where:

* ``characterId`` is the unique ID of the character to give stinkbomb-dropping
  ability to
* ``stinkbombId`` is the unique ID of the stinkbomb
* ``spriteGroupId`` is the ID of the :ref:`sprite group <spriteGroup>` to use
  for the stinkbomb when dropped
* ``commandListId`` is the unique ID of the :ref:`command list <commandList>`
  that the stinkbomb will use when dropped

Each character whose unique ID appears in this section will be given the
ability to drop a stinkbomb. In the stock Pyskool this will be Eric.

The ``Stinkbombs`` section appears only in `back_to_skool.ini`.

.. _timetable:

[Timetable]
-----------
The ``Timetable`` section contains an ordered list of lesson IDs. Lessons
happen starting with the first in the list, and proceed one by one to the end
of the list. When the last lesson in the list is finished, the game loops back
round to the first lesson in the list.

An example of a lesson ID is ``Creak-BlueRoom-1``, which refers to the first of
a set of lessons in which Eric and the Swot are taught by Mr Creak in the Blue
Room. The lesson ID could be anything, but it's helpful to make it descriptive.

A lesson can be thought of as a set of entries from the personal timetables
of the characters. These sets of entries can be found in the :ref:`lessons`
sections.

[Walls]
-------
The ``Walls`` section contains details of the impenetrable barriers in the
skool. Each line takes the form::

  wallId, x, bottomY, topY

where:

* ``wallId`` is the wall's unique ID
* ``x`` is the wall's x-coordinate
* ``bottomY`` and ``topY`` are the y-coordinates of the bottom and top of the
  wall

For example::

  FarLeftWall, 0, 20, 0

defines the wall at the far left (x=0) of the skool, which stretches from the
bottom floor (y=20) to the ceiling of the top floor (y=0).

.. _water:

[Water]
-------
Each line in the ``Water`` section takes the form::

  characterId, waterId, spriteGroupId, commandListId

where:

* ``characterId`` is the unique ID of the character to give water pistol-firing
  ability to
* ``waterId`` is the unique ID for the water sprite
* ``spriteGroupId`` is the ID of the :ref:`sprite group <spriteGroup>` to use
  for the water fired from the pistol
* ``commandListId`` is the unique ID of the :ref:`command list <commandList>`
  that the water will use when fired from the pistol

Each character whose unique ID appears in this section will be given the
ability to fire a water pistol. In the stock Pyskool this will be Eric alone;
he is the only character with a water pistol-firing sprite.

The ``Water`` section appears only in `back_to_skool.ini`.

.. _waterDrop:

[WaterDrop]
-----------
The ``WaterDrop`` section defines a drop of water (as knocked out of a cup by a
catapult pellet). It contains a single line of the form::

  objectId, spriteGroupId, commandListId

where:

* ``objectId`` is a unique ID for the drop of water
* ``spriteGroupId`` is the ID of the :ref:`sprite group <spriteGroup>` to use
  for the drop of water
* ``commandListId`` is the unique ID of the :ref:`command list <commandList>`
  that the drop of water will use when knocked out of a cup

The ``WaterDrop`` section appears only in `back_to_skool.ini`.

.. _windows:

[Windows]
---------
The ``Windows`` section contains details of the windows in the game. Each line
takes the form::

  windowId, x, bottomY, topY, initiallyShut, openerCoords, shutTopLeft, size, coords

where:

* ``windowId`` is the window's unique ID
* ``x`` is the window's x-coordinate
* ``bottomY` and ``topY`` are the y-coordinates of the bottom and top of the
  window
* ``initiallyShut`` is ``Y`` if the window should be shut when the game starts
* ``openerCoords`` are the coordinates (in `(x, y)` form) at which a character
  should stand in order to open the window
* ``shutTopLeft`` is the coordinates (in `(x, y)` form) of the top left of the
  image of the window when shut
* ``size`` is the size of the image (in `(width, height)` form)
* ``coords`` are the coordinates (in `(x, y)` form) of the window in the skool

The window images can be found in `mutables.png` (or `mutables_ink.png` and
`mutables_paper.png` if ``GraphicsMode`` is 1 - see :ref:`graphics`).
`mutables.png` is arranged so that the image of a window when open is at
`(x + width, y)`, where `(x, y)` are the coordinates of the image of the same
window when shut. The open/shut images for any given window are the same size.

The ``Windows`` section appears only in `back_to_skool.ini`.
