  _________________________________________
      __
     / .`|  _ _   ____  _ _ _    _ _   _ _
    / __/ /  ` / /   / / ` ` | /  ` / / ` /
   / /   / /  / / /-/ / / / / / /  / / . /
  /_/   /__._/ /___/ /_/_/_/ /__._/ /_/_/

  _________________________________________

   N  t  d    &    c  o  o  l  s  p  o  t
  _________________________________________



INTRODUCTION
------------

Welcome to the scripters/hackers/lunaticks file.  If you were after 
the regular readme, you're in the wrong place.  This file contains 
some information about the "internals" of Pacman.  Don't expect this 
file to be COMPLETE, I only listed some of the more obvious stuff.

Please note.  Like every addon should, Pacman aliases and variables 
are carefully named to avoid conflict with other scripts.   All 
internal aliases and variables begin with "pc." (unless they are -l 
aliases or variables.  And yes, variables can be -l).  This "pc." 
prefix will be missed off throughout this file, since it can always 
be assumed present.


LEVEL
-----

We're giving you this information, but we're not running around 
explaining it.  If you're not already a good enough scripter to 
understand the techniques used, may we suggest you RTFM.  You WILL 
need to understand - REALLY understand - all of the following:

 - dynamic variables  (%pc. [ $+ [ $ident ] ])
 - tokens.  all of them.  properly.
 - timers.


LEVEL FILES
-----------

All level files are just text files in the following format:

Line 1: width,height
Line 2: pacman starting x,y
Line 3: monster1 x,y.monster2 x,y.monster3 x,y.monster4 x,y
Line 4: Colour of  
Line 5: Colour of  
Line 6: Colour of  
Line 7: bmp to use for walls
Line 8: Colour of background
Line 9 to $calc((width * height) + 9): level data

The level data is as follows.  On each new line is the data for a 
new square.  There is no delimiter for end of row, etc.  (The script 
automatically breaks the stream into rows according to the w/h given 
in line 1.)  Values for the squares can be the following:

0 	- empty
1 	- dot
2 	- big dot
3 	- warp
4 	- impassable to pacman
5 	- wall (solid)

Special notes:

- Pacman's initial starting position should be 0 (empty).
- warp squares are followed by ":x,y" where x and y are where to goto.
- internally, there is also type 6 for bonus.  Level files SHOULD NOT
  include type 6 squares, however.


IDENTIFIERS
-----------

coord 	- returns pixel value given X/Y grid pos (top left corner)
p 	- returns what "piece" is in a given square (1,2,3,4,5)


SYSTEM
------

loadlvl - loads any level file (duh)
	  level file is $1- (long filename support!)
lvl	- loads a standard, included level given a level number
	  $1 is number 1-9
nextlvl - hops onto the next level (or calls victory if level 9)
fatal	- crash and burn (message $1-).
pause	- With -s to pause or -u to unpause.  NB: doesnt work :)


GFX
---

win	- fires up the pacman window
db	- "draw board", draws the entire board
ds	- "draw square", draws the square ($1,$2)
du	- "draw you", draws pacman
dm	- "draw monster", draws monster number $1
upd	- "update", redraws only squares that have changed
bonus	- used for fruit handling.


SCOREBAR
--------


swin	- creates scorewin
dswin	- draws scorewin


VARS
----

upd	- tokenised string of what squares need updating. in the form:
	  x1:y1.x2:y2.x3:y3 (etc)
qmove	- queues up coming pacman movements.  if travelling left, user 
	  presses up, pacman will go up at NEXT chance there is to go 
	  up.  even if it couldnt go up when the key was pressed.
ux / uy - pacmans coords
dots	- the number of dots left on the board
b.x.y	- the board, where [ x ] and [ y ] are numbers (dynamic array)
w.x.y	- the warps, where [ x ] and [ y ] are numbers (dynamic array)
	  the x and y used to reference are where the warp IS, and
	  each var like this contains x,y for where the DESTINATION is


MONSTER VARS
------------

All monster vars begin with "%pc.m.n." - where [ n ] is the number 
from 1 to 4 of which monster it is (dynamic vars again).  Subset to 
that are several values:

BASIC SUB-VARS:

x / y	- their current coords
ox / oy	- their "original" (home) coords
d	- for "doped", set to $true if the monsters are harmless (blue)
gh	- for "going home", set to $true if they have to return home
	  to un-blue themself, after touching pacman

AI SUB-VARS:

dir	- current direction.  possibly not used (?)
nogood	- directions which are no good, tokenized left.right.up.down
must	- the direction it must achieve before altering course
mh	- "movement history" (see 'AI explained' below)
cycles	- up to 15, then change, see 'AI explained' below

MONSTER ALIASES
---------------

sleep	- monster $1 set to blue
unsleep	- monster $1 set un-blue
gohome	- directs monster $1 at its home coords (var ox/oy, see above)
checkmeet
	- checks if pacman is touching monster $1

AI ALIASES
----------

Dont expect to understand this.  I don't, and I wrote it :)

gotopoint
	- basic directional alias.  Move monster $1 to ($2,$3)
	  Self-repeating, calls itself until it gets there, so you 
	  can call once and forget.
clearspecial
	- clears special AI vars.  csa is "clear special all".
gotthere
	- when gotopoint succeeds, it "gotthere".
_monmove
	- ident, returns $true/$false, for whether monster $1 can 
	  move in dir $2 (left/right/up/down)
monmove	- moves monster $1 in dir $2 (left/right/up/down)


THE AI EXPLAINED (ROFL)
-----------------------

Erm... well... such crap AI hardly merits explanation.  It doesnt even 
do what it's supposed to do according to these rules.  But hey.  Here 
is how it was SUPPOSED to work...

1. Ghosts (nearly!) always try and move to pacman's coordinates.
2. After 15 steps, they refresh their target coordinates (so that they 
   keep heading at pacman, not where he was ages ago).
3. When they have to go home, their target is (obviously) their home 
   coords.
4. When heading home, the "refresh after 15 steps" does not apply.
5. Ordinarily, movement direction is chosen by comparing current to 
   target coords.  When it needs to move in two directions (eg, up 
   and left), and CAN move in both, it chooses randomly.
6. If it gets to the right x OR y, but cant move in the 'other' 
   direction, it forces itself to move in the opposite-to-other 
   direction until it can.  That made no sense at all.  This might:

                   D
      --------------------------
                   C

   C is current, D is destination.  C(x) == D(x); it needs to 
   move UP but it cannot.  So it moves left or right (random choice)
   CONTINUALLY until it CAN move up.
7. Each monster tracks its movement history, or more accurately, its 
   direction change history.  If it detects a loop, it forces itself 
   not to take the same direction again to break the loop.  Currently 
   only works on loops of length 2, which kinda sucks.