Document every network packet's pre, post, and desc

With pretty pictures (not a submodule because large images).

Part of this commit was originally made by Rawng.

2 files changed, 941 insertions, 0 deletions

diff --git a/old-doc/mapserver-logging b/old-doc/mapserver-logging
new file mode 100644
index 0000000..573c61f
--- /dev/null
+++ b/old-doc/mapserver-logging
@@ -0,0 +1,71 @@
+Log format:
+
+LOGLINE ::= int'.'int <MESSAGE>
+
+MESSAGE ::= 'log-start'
+          | 'log-start v2'
+          | 'log-start v3'
+          | 'log-start v4'
+          | <PC> <COORD> <PC-MESSAGE>
+          | <MOB> <MOB-MESSAGE>
+
+COORD ::= int':'int','int
+
+PC ::= 'PC'int
+
+MOB ::= 'MOB'int
+
+TARGET ::= <PC> | <MOB>
+
+SPELLRESULT ::= 'SUCCESS' | 'FAILURE'
+
+STATPLACE ::= 'LOGIN' | 'STATUP' | 'STATUP2' | 'STATRESET'
+
+XPPLACE ::= 'LOGIN' | 'LEVELUP'
+
+XPREASON ::= 'SCRIPTXP' | 'HEALXP' | 'KILLXP' | 'SHAREXP' | 'UNKNOWNXP'
+
+ZEROTARGET ::= 'null' | <TARGET>
+
+MOB-MESSAGE ::= 'DEAD'
+
+PC-MESSAGE ::= 'WPNDMG' <TARGET> int 'FOR' int WPN int				# "WPNDMG MOB01 type FOR damage WPN weapon-item" 
+             | 'WPNINJURY' <TARGET> int 'FOR' int
+             | 'MOB-TO-MOB-DMG' 'FROM' <MOB> int 'TO' <MOB> int 'FOR' int	# Summoned monster damage
+             | 'SPELLHEAL-INSTA' <PC> FOR int
+             | 'SPELLDMG' <MOB> FOR int BY spell-id
+             | 'CAST' spell-id <SPELLRESULT>
+             | 'STAT' int int int int int int <STATPLACE>			# str agi vit int dex luk
+             | 'XP' int int 'JOB' int int int 'ZENY' int '+' int <XPPLACE>	# level xp job-level skill-xp skill-pts zeny bank-zeny
+             | 'SKILLPOINTS-UP' int						# new number of unused skill points
+             | 'MAGIC' int int int int int int 'EXP' int int 'LOGIN'		# magic life war transmute nature ether magic-xp healer-xp
+             | 'SKILL-ACTIVATE' int int int					# skillid skilllvl skillpower
+             | 'SKILL-UP' int int int						# skillid skilllvl skillpower
+             | 'SKILL-DEACTIVATE' int
+             | 'MAGIC-ABSORB-DMG' int
+             | 'GAINXP' int <XPREASON>
+             | 'PICKUP' int int							# item-id count
+             | 'INJURED-BY' <ZEROTARGET> 'FOR' int
+             | 'DEAD'
+             | 'LOGOUT'
+             | 'TRADECOMMIT' 'WITH' int 'GIVE' int 'GET' int			# pc-id give-zeny get-zeny
+             | 'TRADECANCEL'
+             | 'TRADEOK'
+             | 'STATUP'
+             | 'STATRESET'
+             | 'STATUP2'
+
+NOTES:
+------
+1. Any PICKUP between TRADECOMMIT and TRADEOK is part of the trade.
+2. TRADECOMMIT is issued for both participants in a trade.
+3. INJURED-BY seems to only duplicate information we already have.
+
+
+Illegal items
+
+645, 668, 659, 731, 734, 744, 745, 755, 756, 757, 747, 748, 721, 722
+
+Restricted access
+
+725, 726, 647, 646
diff --git a/old-doc/old-spell-language b/old-doc/old-spell-language
new file mode 100644
index 0000000..5f70f89
--- /dev/null
+++ b/old-doc/old-spell-language
@@ -0,0 +1,870 @@
+--------------------------------------------------------------------------------
+== Spell language
+
+* Comments: One-line comments using '#' or '//' as prefix
+* names vs. invocations:  spells and anchors have both names
+  and invocations.  Names are used to refer to spells and
+  anchors from within scripts without revealing their
+  invocations.
+
+
+Each spell specification file consists of a sequence of definitions of
+globals, anchors, spells, and procedures.
+
+Types:
+------
+  These are the primitive types:
+  * int
+  * string
+  * dir	       (a direction: N, S, SE, NW etc.)
+  * location   (a single spot in the world)
+  * entity     (a PC, NPC, or monster)
+  * area       (a set of locations)
+  * spell      (a spell)
+  * invocation (a spell instance)
+  * fail       (a separate type that arises implicitly when a function
+    	        fails)
+
+  `fail' arises in special circumstances in some functions, e.g. when
+trying to divide by zero, or when function parameters fail to
+type-check.  When a fail value flows into an operation, than that
+operation is skipped.  When a fail value flows into a function, then
+that function evaluates to fail, except for
+
+  * if_then_else (which permits `fail' in its true or false branch)
+  * failed (which returns true iff the argument is of type fail).
+
+  We will use standard functional type notation:
+
+  `int * string -> entity' denotes the type of a function that accepts
+an integer and a string and returns an entity.  We use the return `()'
+for operations (which return nothing).
+
+Globals:
+--------
+  A `global' is a global variable, declared and defined in the
+same line:
+
+	foo = "this is a string";
+
+  Expressions can be arbitrary language expressions.  Note that globals
+can only reference the values of globals defined earlier in the same
+program.
+
+  There are two special globals:
+
+  * min_casttime : int
+    Minimal number of milliseconds of cast delay, no matter what any
+    given spell may say.  Cast delay is the time before the next spell
+    can be cast.
+
+  * obscure : int
+    Chance of a character of a given spell to be obscured (masked out
+    by an asterisk).
+
+
+  Globals can also be defined as CONST (though this should not be done
+for the special globals listed above or they will not take effect.)
+CONST-defined globals cannot be re-defined.
+
+
+Expressions:
+------------
+  Expressions occur in globals, anchors, spells, and procedures.
+Expressions evaluate to values of a given type.  Expressions can be
+simple literals, area literals, infix expressions, function
+applications, or variable refecences.
+
+- Simple literals:
+  * 42, 0xff: int literals
+  * N, S, E, W, NE, NW, SE, SW : dir literals
+  * "foo bar" : string literals
+
+- Area literals:
+  * @("new_3-1.gat", 26, 26)
+    This area denotes a single field on a map (new_3-1.gat,
+    co-ordinates (26,26).
+  * @("new_3-1.gat", 26, 26) @+ (10, 10) 
+    This area is 100 fields, stretching to a field of size 10x10 to
+    the south and east of (26,26) in new_3-1.gat.
+  * @("new_3-1.gat", 26, 26) towards S (5, 3)
+    This area is a rectangular field of depth 3 and width 5 to the
+    south of (26,26) in new_3-1.gat.  `depth 3' here means that it
+    stretches three fields to the south.  `width 5' here means that it
+    extends five fields to the east and five to the west of the
+    specified coordinate, for a total width of 11.
+    The only directions supported here are S, E, N, W.
+
+- Infix expressions:
+  Infix expressions are special functions in which the operator is
+  written between two expressions.  Infix expressions largely follow
+  the C precedence rules.  The following infix operators are
+  supported:
+  * addition (+) (operates on ints, concatenates strings, and
+    	     	  constructs the union of areas)
+  * subtraction (- : int * int -> int)
+  * multiplication (* : int * int -> int)
+  * division (/ : int * int -> int, may fail)
+  * modulo (% : int * int -> int, may fail)
+  * comparison (<, >, >=, <=, =, <> : int * int -> int)
+    Comparison operators generally work on ints and strings.
+    (In)equality checks work on all values except for areas.
+    Note that "==" and "!=" are available as alternatives for "=" and
+    "<>" (respectively).
+  * conjunction and disjunction (&&, || : int * int -> int).  Note
+    that these are not short-circuit.
+  * Bitwise or (| : int * int -> int)
+  * Bitwise and (& : int * int -> int)
+  * Bitwise xor (^ : int * int -> int)
+  * Shift left and right (<<, >> : int * int -> int)
+
+- Function applications:
+  Function applications are written as
+
+    f(arg1, ..., argn)
+
+  where each `argi' is an arbitrary expression.
+  For a complete list of Functions, see `functions' below.
+
+- Variable references:
+  The expression (foo + 1) references a variable `foo' which must have
+  been previously defined.
+
+
+Anchors:
+--------
+  Anchors are teleport anchors; spells can look them up by name.  Each
+teleport anchor is written as
+
+    TELEPORT-ANCHOR <id> : <invocation-string> = <location>
+
+  For example:
+
+    TELEPORT-ANCHOR tulimshar : "home" = @("new_3-1.gat", 26, 26) @+(10, 10) 
+
+  This maps the teleport anchor `tulimshar' to an area in new_3-1.gat
+binds it to the name "home".  The function `anchor' can look up
+teleport anchors (cf. the function library).
+
+
+Spells:
+-------
+  Each spell is written either as
+
+    [spell-modifiers] SPELL <id> : <name> = <spelldef>
+
+  or as
+
+    [spell-modifiers] SPELL <id> (<id> : <sty>) : <name> = <spelldef>
+
+  For example,
+
+    SPELL random_dance : "zxr" = ...
+
+  creates a spell `random_dance' and makes it available under the
+invocation "zxr".  The string `...' is not a valid <spelldef>; we will
+look at proper spelldefs below.  An alternative example illustrates
+the use of parameters:
+
+    SPELL shout (message : STRING) : "zzx" = ...
+
+  This defines a spell `shout' (bound to invocation "zzx") that takes
+a parameter `message' of type STRING.  Valid types are STRING and PC:
+PC parameters are automatically translated into a player character
+entity of that name, or mapped to the caster if the specified name
+does not map to a player character or is missing.
+
+  The list of spell modifiers is short:
+
+  * SILENT means that the spell's invocation will never be broadcast,
+    	   not even obscured.
+  * LOCAL means that the spell is bound to the location it was cast at
+    	  and will not `travel' with the caster.
+  * NONMAGIC means that the spell is not affected by the caster's ability
+          to perform magic.  Typically used for special (quest) keywords.
+
+  Modifiers may be given in any order, but only once.
+
+- Spell bodies
+
+  Spell bodies consist of three parts: LET bindings, spell guards and
+  effects.  LET bindings locally bind names to values.  Spell guards
+  are constraints that must be satisfied for the spell to be
+  triggered.  Effects describes what happens if the spell is
+  successfully triggered.  Spells may have multiple guards and
+  effects.
+
+  Consider the following example:
+
+    SPELL plugh (message : STRING) : "zzx" =
+          LET x = "kappa"
+              y = "sigma"
+          IN
+          (MANA 1, CATALYSTS ["Pearl"]) => EFFECT message (caster, "First branch");
+        | (MANA 20) => EFFECT message (caster, "Second branch")
+
+  This defines a spell `plugh' with two let bindings (`x' bound to
+  "kappa" and `y' bound to "sigma") and two `branches' which are
+  tested in sequence.  The first branch tests whether the caster has
+  one spellpoint and owns a pearl-- if so, the effect of sending a
+  message "First branch" to the caster is triggered.
+
+  However, if the spell guard is not satisfied, the magic engine
+  examines the second branch.  Now, if the caster has 20 spellpoints,
+  we INSTEAD trigger the effect of sending the message "Second branch"
+  to the caster.
+
+- Spell guards
+
+  Spell guards can be omitted; in that case, just use the effect
+  itself.  Otherwise they can be any of the following:
+  * MANA x:  Require x spellpoints to be present.  If this spellguard
+    is taken, x mana will be consumed implicitly.  This requirement is
+    cumulative.
+  * CASTTIME x:  Require that the caster spend x milliseconds until
+    the next spell can be cast.  This requirement is cumulative.  If
+    the total casttime for a spell is less than the global variable
+    min_casttime, then the latter supercedes the specified spell cast
+    delay.
+  * REQUIRE <expr>:  Test that the specified expression evaluates to
+    nonzero and does not fail.  Requirements are cumulative.
+  * CATALYSTS <items>: Ensure that the caster possesses all specified
+    items.  This effect is cumulative.
+  * COMPONENTS <items>: Ensure that the caster possesses all specified
+    items.  If the branch suceeeds, all items specified here are
+    consumed.  This effect is cumulative.
+
+  Items can be specified as follows:
+  * [ 700, 701 ]	-- require one item of item ID 700 and one of 701.
+  * [ 700, 3 * 701 ]	-- require 1 item of item ID 700 and 3 of 701.
+  * [ "Pearl" ]		-- require one item named `Pearl' in the item DB.
+
+  Spell guards can be combined as follows:
+  * `or': disjunction.  The first matching path is taken.
+  * (a, ..., n): conjunction.  a, n, and everything in between must be
+    satisfied.
+  * a => b:  Implication.  If `a' is satisfied, try to satisfy `b'.
+    This operation is useful to combine different branches (see
+    below.)
+
+  Different branches of spell effects are separated by the vertical
+  bar `|'.  For example,
+
+    SPELL plugh (message : STRING) : "zzx" =
+        MANA 5 => (  (CATALYSTS ["Pearl"]) =>
+                            EFFECT message (caster, "First branch");
+                   | (MANA 20) =>
+                            EFFECT message (caster, "Second branch");)
+
+  will always try to deduct 5 Mana points but then make a choice of
+  whether to go to the first branch (if the player has `Pearl') or to
+  the second (if the player does not have `Pear' but has another 20
+  spell points, for a total of 25 spell points, all of which will be
+  consumed in that case.)
+
+
+- Effects
+
+  Effects describe what happens when a spell is triggered.  Each
+  spell has at least one EFFECT specification, which looks as follows:
+
+    EFFECT <effectlist> [ ATTRIGGER <effectlist> ] [ ATEND <effectlist> ]
+
+  The three parts are as follows:
+  * EFFECT:  All effects here are executed as soon as the spell is
+    triggered.
+  * ATEND:  All steps described here are executed when the spell
+    finishes.   Note that the spell may remain active after all steps
+    from the EFFECT section have been taken; this happens when the spell
+    triggers a status change (using the `status_change' operation,
+    as described in the operations library).  In that case the spell
+    will terminate only after all status changes have finished.
+    The ATEND section is not called when the spell finishes due to the
+    caster dying.
+  * ATTRIGGER:  This section is used only for the `override_attack'
+    operation and described there.
+
+  Before effects are executed, the engine defines the following
+  variables:
+
+  * The parameter (if any)
+  * caster : entity (the caster of this spell)
+  * spellpower : int (the caster's spellpower, normally 6 -- 198)
+  * location : location (the location the spell is currently at)
+  * self_spell : spell (the current spell)
+  * self_invocation : invocation (the current spell instance)
+
+  The engine can then execute the following effects from the effect list:
+  * SKIP;	    #  a no-op
+  * ABORT;	    #  Abort the spell, don't run ATEND, don't consume a
+    		    #    trigger charge (cf. `override_attack')
+  * END;	    #  Skip to the ATEND block
+  * WAIT <expr>;    #  Wait <expr> milliseconds before continuing
+  * <id> = <expr>;  #  Set <id> to the result of evaluating <expr>
+  * (<s1> ... <sn>) #  Execute statements <s1> through <sn> in sequence
+  * IF <c>	    #  Test condition <c>.  If nonzero,
+    THEN <s1>	    #    execute <s1>.  Otherwise,
+    ELSE <s2> 	    #    execute <s2>.
+                    #    The `ELSE' branch can be omitted.
+
+  * FOREACH <k> <id> IN <expr> DO <s>
+                    # Evaluate <expr> to an area, find all entities in
+		    #   the area that match <k>, randomise this list,
+		    #   bind <id> to each in turn and execute <s>.
+
+    Example:
+
+    FOREACH ENTITY t IN rbox(location(caster), 20)
+      DO aggravate(t, 0, caster);
+      	 	    # This aggravates all entities within 20 paces of
+		    #   the caster to attack the caster.
+
+    Valid values for <k> are
+    + ENTITY : PC or mob
+    + PC
+    + MOB
+    + TARGET : mob, PC (but only if we are on a PvP map)
+
+  * FOR <id> = <start> TO <stop> DO <stmt>
+    # This will iterate from <start> to <stop> (inclusively), bind
+    # <id> to the current iteration value, and execute <stmt>.
+
+  * BREAK;
+    # This will break out of the current FOR loop, FOREACH loop, or
+    # procedure.
+
+  * <id> ( <expr1>,  ..., <exprn> );
+    # This executes an operation.  See `Operations', below, for a
+    # list.
+
+  * CALL <id> ( <expr1>,  ..., <exprn> );
+    # This will execute a procedure, after binding the actual
+    # parameters from <expr1> to <exprn> to the formal procedure
+    # parameters.
+
+  * { ... }
+    # This executes arbitrary eAthena script code.  The following
+    # variables script variables are bound implicitly:
+    # - @caster_name$ is the name of the spellcaster
+    # - @caster and @target are also bound, to useless values (sorry.)
+    #
+    # By default, script popup boxes are sent to the caster.  This can
+    # be overridden by setting the special `script_target' variable.
+
+Procedures:
+-----------
+  Procedures are defined as
+
+    PROCEDURE <id> ( <id>, ... , <id> ) = <effectlist>
+
+  For example,
+
+    PROCEDURE testproc(x) = message(caster, "foo(" + x + )");
+                            y = 10;
+                            x = 20;
+
+  defines a procedure `testproc' with one formal parameter `x'.
+  Procedure execution is nonrecursive and uses dynamic scoping.  The
+  latter means that it can modify variables in the caller's scope.  In
+  the above example, the assignment to `y' will be visible to the
+  caller.  The assignment to `x' however will be not be visible, since
+  that assignment goes to the parameter and is therefore limited in
+  scope to `testproc'.  More precisely,
+
+      EFFECT x = 0; y = 0; testproc(1);
+      	     message(caster, "x=" + x + ", y=" + y);
+
+  would print
+
+      foo(1)
+      x=0, y=10
+
+  (note how the update to x is isolated from the caller.)
+
+Functions:
+----------
+This section documents the function API.
+
+The following functions are available:
+
+  + max : int * int -> int
+    Pick the greater of two values.
+
+  + min : int * int -> int
+    Lesser of two values.
+
+  + is_in : location * area -> bool
+    Test whether a location is within an area.
+
+  + if_then_else : bool * 'a * 'a -> 'a
+    Test a condition (first parameter).  If the contition is nonzero,
+    return the second parameter, otherwise the third parameter.
+
+  + skill : entity * int -> int
+    Get the skill level that the `entity' has for the skill id.
+
+  + dex : entity -> int
+  + agi : entity -> int
+  + int : entity -> int
+  + vit : entity -> int
+  + str : entity -> int
+  + luk : entity -> int
+  + hp : entity -> int
+  + sp : entity -> int
+  + def : entity -> int
+  + mdef : entity -> int
+  + max_hp : entity -> int
+  + max_sp : entity -> int
+  + level : entity -> int
+    Status attributes.
+
+  + dir : entity -> dir
+    Direction that the entity is currently facing.
+
+  + not : int -> int
+    Logical negation. (NOT bitwise negation.)
+
+  + neg : int -> int
+    Bitwise negation.
+
+  + name_of : entity -> string
+            | spell -> string
+    Retrieves the name either of an entity or of a spell.
+
+  + location : entity -> location
+    Determines the location that the specified entity presently
+    occupies.
+
+  + random : int -> int		   	
+    random(6) yields a random value from 0 to 5.
+
+  + random_dir : int -> dir
+    random_dir(0) yields N, S, E, or W.
+    random_dir(1) yields N, S, E, W, SE, SW, NE, or NW.
+
+  + hash_entity : entity -> int
+    Retrieve a number idenfying the entity.
+
+  + is_married : entity -> int
+    Tests whether the entity is married.
+
+  + partner : entity -> entity
+    Retrieves the entity's partner, if online, or fails otherwise.
+
+  + awayfrom : location * dir * int -> location
+    awayfrom(loc, dir, distance) returns a location obtained by moving
+    at most `distance' towards `dir', starting at `loc'.  If the move
+    hits an obstacle, we stop before the obstacle.
+
+  + failed : 'a -> bool
+    True iff the input was the special failure value.
+
+  + pc : string -> entity
+    Looks up a player character by name.  Fails if there is no match.
+
+  + npc : string -> entity
+    Looks up an NPC by name.  Fails if there is no match.
+
+  + distance : location * location -> int
+    This is the `fake square distance':  The maximum of delta x and
+    delta y between the two locations.
+
+  + rdistance : location * location -> int
+    This is the `real' distance (square root of the square of dx, dy)
+
+  + anchor : string -> area
+    Looks up a teleport anchor by name and returns the associated
+    area.  Fails if the result is not an area.
+
+  + random_location : area -> location
+    Pick a random location from within an area.
+
+  + script_int : entity * string -> int
+    Read a player script variable as an integer.
+
+  + rbox : location * int -> area
+    rbox(l, n) computes rectangular box centered at `l', with a
+    `radius' of n.  The box contains (n*2 + 1)^2 squares.
+
+  + count_item : entity * int -> int
+               | entity * string -> int
+    Counts the number of instances of the specified item that the
+    entity has.  Items may be given by ID or by name.
+
+  + line_of_sight : location * location -> int
+    Determines whether there is a line-of-sight connection between the
+    two locations.
+
+  + running_status_update : entity * int -> bool
+    Determines whether the specified status update is still active.
+
+  + element : entity -> int
+    Determines what element the entity is associated with
+
+  + element_level : entity -> int
+    Determines what element level the entity has
+
+  + has_shroud : entity -> int
+    Determines whether the player is presently shrouded (i.e., whether
+    the player's name is being obscured.)
+
+  + is_equipped : entity * int -> int
+                : entity * string -> int
+    Determines whether the player has equipped the specified item
+
+  + spell_index : spell -> int
+    Determines a unique index assigned to each spell
+
+  + is_exterior : location -> bool
+    Determines whether the location is under an open sky
+
+  + contains_string : string * string -> bool
+    contains_string(a, b) determines whether the string `a' contains
+    the string `b' as a substring.
+
+  + strstr : string * string -> bool
+    strstr(a, b) returns the offset of the first instance of the
+    string `b' in the string `a', or fails if there is none.  The
+    offset is reported with a base of zero, i.e., strstr("xyz", "x") = 0.
+
+  + strlen : string -> int
+    Compute the length of a string, in characters.
+
+  + substr : string * int * int -> string
+    substr(s, offset, len) extracts a substring of the length `len' at
+    offset `offset'.  The substring is automatically clipped, i.e., the
+    function will never fail.
+
+  + sqrt : int -> int
+    Computes the square root of the specified number
+
+  + map_level : location -> int
+    Determines the map level: 0 for outside, 1 for inside, 2ff for
+    dungeon levels (going down)
+
+  + map_nr : location -> int
+    Computes the map number.  Map number and map level together uniquely
+    identify a map.
+
+  + dir_towards : location * location * int -> dir
+    dir_towards(start, end, flag) computes the direction from `start' to
+    `end'.  If flag is zero, directions are limited to N, S, E, W;
+    otherwise NE, SE, NW, SW will also be used.  The two locations must be
+    on the same map.
+
+  + is_dead : entity -> bool
+    Determines whether the specified entity is no longer alive.
+
+  + extract_healer_experience : entity * int -> int
+    Extracts `healer experience points' from the specified entity.
+    Non-PCs always have an empty pool of healer exprerience points.
+    PCs gain such experience points by killing/completing quests,
+    though this `healer experience point pool' slowly drains itself.
+    extract_healer_experience(pc, xp) extracts up to `xp' points.
+
+  + is_pc : entity -> bool
+    Determines whether the target is a player character
+
+Operations:
+-----------
+This section documents the operations API.
+
+  + sfx : entity * int * int -> ()
+        | location * int *int -> ()
+    Trigger a special effect (specified by sfx ID) for an entity or a
+    location.  The int specifies a delay until the effect is issued.
+
+  + itemheal : entity * int * int -> ()
+    itemheal(entity, hp, sp) triggers item healing.  This will
+    hopefully be slowed down if an appropriate server patch is
+    installed.
+
+  + instaheal : entity * int * int -> ()
+    itemheal(entity, hp, sp) heals instantly.
+
+  + shroud : entity * int -> ()
+    shroud(entity, flags) hides the entity's name (only for PCs).
+    Flags:  0x01: Hide PC'ss name when talking
+            0x02: Shroud vanishes when player picks something up
+            0x04: Shroud vanishes when player talks
+    The shroud will not affect players in visible range until the
+    entity has left and re-entered their field of vision.  This can be
+    enforced by warping.
+
+  + unshroud : entity -> ()
+    Counter a shroud.
+
+  + message : entity * string -> ()
+    Send a message to the entity.
+
+  + messenger_npc : location * int
+                    * string * string * int -> ()
+    messenger_npc(location, image, npc_name, message, duration)
+    creates a messenger NPC looking like the `image' at `location',
+    with name `npc_name' and delivering the `message' when clicked
+    upon.  The NPC disappears after the `duration' in ms has expired.
+
+  + move : entity * dir -> ()
+    Move the entity into the specified direction, unless that
+    direction is blocked.
+
+  + warp : entity * location -> ()
+    Warp entity to specified location.
+
+  + spawn : area * entity * int * int * int * int -> ()
+    spawn(area, owner, mob_id, attitude, count, lifetime) spawns for a
+    limited `lifetime' (in ms) a total of `count' monsters of kind
+    `mob_id' in `area'.  `attitude' specifies how they behave:
+      0 : attack everyone
+      1 : be friendly
+      2 : attack enemies of `owner' and give XP to `owner' if successful
+
+  + banish : entity -> ()
+    If the entity was spawned by the `spawn' operation, eliminate it.
+
+
+  + status_change : entity * int * int
+                    * int * int * int * int -> ()
+    status_change(entity, status, v1, v2, v3, v4, duration) initiates
+    a status change.  The precise status change (and the meaning of
+    `v1', `v2', `v3', `v4') varies depending on `status'.  This
+    operation may delay spell termination (and the ATEND effect).
+    ATEND can therefore be used to notify the caster that the status
+    change has finished.
+
+  + stop_status_change : entity * int
+    Stops a status change
+
+  + override_attack : entity * int * int
+                             * int * int *int * int -> ()
+    override_attack(entity, charges, delay, range, icon, animation, stop)
+    overrides the entity's current attack (only for PCs).  The entity
+    will have `charges' attacks that instead result in calling the
+    ATTRIGGER effect for this spell.  When this operation is called,
+    the spell environment (variables etc.) is cloned into a separate
+    invocation.  This special invocation will be triggered every time
+    the entity tries to attack, until they have run out of charages (at
+    which time the previous behaviour is restored.)
+    `delay' specifies the attack delay.
+    `range' specifies the attack range as shown in the client GUI.
+    `icon' is the ID of a status-effect ID that will be displayed
+    while the spell is in effect.
+    `animation' is the attack animation ID that should be used.
+    `stop' decides whether attacking should stop once the spell is out
+    of charges (1) or continue (0). (Note: this doesn't properly work,
+    possibly due to client issues.  Always use 0.)
+
+    Note that if the ATTRIGGER effect ABORTs, no charge will be
+    consumed.
+
+    ATTRIGGER can refernece the player's target via the `target'
+    variable.
+
+    Example:
+
+    SPELL tshuffle : "zvp" =
+        (MANA 1, CATALYSTS ["Pearl"]) =>
+        EFFECT
+                override_attack(caster, 3, 500, 10, 700, 31);
+        ATTRIGGER
+                IF (not (line_of_sight(location, location(target))))
+                THEN (message (caster, "No line of sight!"); ABORT;)
+                FOR i = 0 TO 10 DO (move(target, random_dir(0)););
+
+    This overrides the caster's attack for three attacks (attack delay
+    500, range 10) to instead randomly move around any entity that the
+    player tries to attack by up to 11 paces.
+
+  + create_item : entity * int * int -> ()
+                | entity * string * int -> ()
+    create_item(entity, item, count) gives the `entity' `count'
+    instances of `item'.  As usual, `item' can be either a string name
+    or an item ID.
+
+  + aggravate : entity * int * entity -> ()
+    aggravate (victim, mode, target) causes the `victim' to
+      mode = 0: attack `target'
+      mode = 1: become universally permanently aggressive
+      mode = 2: both of the above
+
+  + injure : entity * entity * int * int -> ()
+    injure(attacker, defender, hp, sp) causes damage to the defender
+    from the attacker (possibly killing, giving XP etc.), unless the
+    defender is immortal (NPC) or a PC on a non-PvP map.
+
+  + emote : entity * int -> ()
+    Issues the specified emotion to the specified entity.
+
+  + set_script_variable : entity * string * int -> ()
+    Sets a script variable to the specified value
+
+  + set_hair_colour : entity * int -> ()
+    Sets the hair colour of the specified entity to the specified
+    value (must be a PC).
+
+  + set_hair_style : entity * int -> ()
+    Adjusts the hair style of a PC.
+
+  + drop_item : location * (int | string) * int * int -> ()
+    drop_item(place, "name", count, duration) drops `count' items
+    (where count may be zero) of name "name" at `place'.  The items
+    vanish again after `duration'.
+
+  + drop_item_for : location * (int | string)
+                    * int * int * entity * int -> ()
+    drop_item_for(place, obj, count, duration, owner, delay) works
+    like drop_item(place, obj, count, duration), except that the item
+    can only be picked up by `owner' for the next `delay'
+    milliseconds, modulo pickup rules (spousal pickup, out-of-range).
+
+  + gain_experience : entity * int * int * int -> ()
+    gain_experience(player, base_xp, job_xp, reason) gives expereince
+    points to `player'.  If reason is 0, they are handed out normally,
+    but if reason is 1, then those experience points are NOT added to
+    the pool of experience points that healers can draw from `player'.
+
+
+Script API updates:
+-------------------
+Two new script API functions are available:
+
+  * getspellinvocation : string -> string
+    Looks up a spell by spell ID and returns the spell's invocation.
+  * getanchorinvocation : string -> string
+    Looks up a teleport anchor by anchor ID and returns the invocation.
+
+
+Syntax Reference:
+-----------------
+
+SPELLCONF ::= (GLOBAL | ANCHOR | SPELL | PROCEDURE | ';')*  (* The ';' are only for decorative purposes *)
+
+  VALUE ::= <int>
+          | <hexint>
+          | <id>
+	  | <string>
+	  | <dir>	(* one of {N, S, E, W, NE, SE, NW, SW} *)
+
+  EXPR ::= (VALUE)
+	 | (AREA)
+         | (EXPR) '+' (EXPR)
+         | (EXPR) '*' (EXPR)
+         | (EXPR) '-' (EXPR)
+         | (EXPR) '/' (EXPR)
+         | (EXPR) '%' (EXPR)
+         | (EXPR) '<' (EXPR)
+         | (EXPR) '>' (EXPR)
+         | (EXPR) '<>' (EXPR)
+         | (EXPR) '=' (EXPR)
+         | (EXPR) '!=' (EXPR)
+         | (EXPR) '==' (EXPR)
+         | (EXPR) '<=' (EXPR)
+         | (EXPR) '>=' (EXPR)
+         | (EXPR) '&&' (EXPR)
+         | (EXPR) '||' (EXPR)
+         | (EXPR) '|' (EXPR)
+         | (EXPR) '^' (EXPR)		(* XOR *)
+         | (EXPR) '&' (EXPR)		(* binary AND *)
+         | (EXPR) '<<' (EXPR)
+         | (EXPR) '>>' (EXPR)
+	 | <id> '(' ((EXPR) /* ',') ')'
+	 | <id>
+	 | '(' (EXPR) ')'
+
+  INVOCATION ::= <string>  (* used for convenience *)
+
+  LOCATION ::= '@' '(' (EXPR) ',' (EXPR) ',' (EXPR) ')'  (* <map name, x, y> *)
+
+  AREA ::= (LOCATION)
+         | (LOCATION) '@' '+' '(' (EXPR) ',' (EXPR) ')'	(* width and height around location, passable only  *)
+	 | (LOCATION) 'towards' (EXPR) ':' '(' (EXPR) ',' (EXPR) ')' (* towards dir: Bar-shaped, width and depth; only NSEW supported *)
+
+  ITEMS ::= '[' (ITEMC) /+ ',' ']'
+
+  ITEMC ::= (ITEM)
+          | <int> '*' (ITEM)
+
+  ITEM  ::= <int>
+          | <id>
+
+* global
+
+  GLOBAL ::= 'CONST'? <id> '=' (EXPR) ';'
+
+  Available globals:
+  - min_casttime : int		(* min # of ticks for each spell (BEFORE scaling according to battle.conf) *)
+  - obscure : int		(* obscure percentage *)
+
+* teleport-anchor
+
+  ANCHOR ::= 'TELEPORT-ANCHOR' <id> ':' (INVOCATION) '=' (EXPR)
+
+  For example,
+
+    TELEPORT-ANCHOR t : "tulimshar" = @("map_3-1.gat", 44, 70)
+
+  creates a teleport anchor with name `t' and invocation `tulimshar' at the speicfied location.
+
+* spell
+
+  SPELL ::= spellmod 'SPELL' <id> (ARG)? ':' (INVOCATION) '=' (SPELLDEF)
+
+  SPELLMOD ::= ('SILENT' | 'LOCAL')*
+
+  (silent:  invocation silently dropped.  local:  `location' variable doesn't change after spell init.)
+
+  ARG ::= '(' <id> ':' (ARGTYPE) ')"
+
+  ARGTYPE ::= 'PC'	(* yields a pc, or self *)
+	    | 'STRING'
+
+  SPELLDEF ::= ((SPELLBODY) /* '|')
+             | 'LET' (DECL)* 'IN' ((SPELLBODY) /* '|')
+
+  SPELLBODY ::= (SPELLGUARD) '=>' (SPELLBODY)
+              | 'EFFECT' (EFFECT) ('ATTRIGGER' (EFFECT))? ('ATEND' (EFFECT))?
+
+  (* `ATTRIGGER' is executed as a separate effect if the spell is `triggered'.  If the trigger has a target, it is denoted
+   * in the variable `target'.
+   * `ATEND' is invoked for normal termination, i.e., after the spell is over or has been dispelled.  `ATEND' is NOT used
+   * for the triggered effect; instead, spawn a separate spell in ATTRIGGER if that is desired. *)
+
+  DECL ::= <id> '=' (EXPR) ';'
+
+  SPELLGUARD ::= (PREREQ)
+  	       | (SPELLGUARD) 'or' (SPELLGUARD)
+	       | '(' (SPELLGUARD) /+ ',' ')'
+
+  PREREQ ::= 'REQUIRE' (EXPR)
+  	   | 'CATALYSTS' (ITEMS)
+	   | 'COMPONENTS' (ITEMS)
+	   | 'MANA' (EXPR)
+	   | 'CASTTIME' (EXPR)		(* # of ticks until the next spell can be cast *0
+
+  EFFECT ::= EFFECT ';' EFFECT
+           | '(' (EFFECT) ')'
+	   | 'SKIP'			(* no-op *)
+	   | 'ABORT'			(* abort spell.  If used in a trigger, no charges will be consumed. *)
+	   | 'END'			(* skip to atend *)
+	   | 'BREAK'			(* break out of loop *)
+	   | <id> '=' (EXPR)		(* interpreted in the current context, eval'ds trictly *)
+	   | 'FOREACH' (SELECTION) <id> 'IN' (AREA) 'DO' (EFFECT)	(* randomises the subjects first *)
+	   | 'FOR' <id> '=' (EXPR) 'TO' (EXPR) 'DO' (EFFECT)	(* bounds are evaluated when the loop begins, no updates are respected *)
+	   | 'IF' (EXPR) 'THEN' (EFFECT) ('ELSE' (EFFECT))?
+	   | 'WAIT' (EXPR)		(* amount in ticks before continuing. *)
+       	   | <id> '(' (EXPR) /* ',' ')'	(* operation *)
+	   | 'CALL' <id> '(' (EXPR) /* ',' ')'	(* procedure call *)
+	   | '{' ... '}'		(* script *)
+
+  SELECTION ::= 'PC'
+              | 'MOB'
+	      | 'ENTITY' (* MOB or PC *)
+	      | 'TARGET' (* like ENTITY, but includes PCs only on PvP maps *)
+	      | 'SPELL'
+	      | 'NPC'
+
+* procedures
+
+  Procedures may be invoked via `CALL'.  They use dynamic scoping.
+
+  PROCEDURE ::= 'PROCEDURE' <id> '(' <id> /* ',' ')' '=' (EFFECT)