 
///////////////////////////////////////////////////////////////////////////
//   Advanced Abuse Editing : Builtin Function Documentation (v0.666)    //
//   Maintained by: Tony Cannon (cannon@cs.stanford.edu)                 //
//                              (Ponder on #abuse irc channel)           //
//   Version 0.666 Released Tuesday, September 12th, 1995                //
///////////////////////////////////////////////////////////////////////////
 
                        --== Introduction ==--
This is an attempt to document (as much as possible) all of the lisp
functions built into Abuse.  Why?  If you want to make something besides
a 2D scoller, you're going to have to start hacking the lisp eventually.
You're also going to have to start mucking around the lisp to create
a new creature, or just change the ai of an existing one.  Hopefully,
the registered version of Abuse will eventually include some sort of
comprehensive documentation covering all the functions, but until (if?)
that happens, this should help some of you get started.
 
                    --== This Document is Not ==--
This is not a tutorial by any stretch of the imagination.  It's just
a list of functions and as much as I've been able to infer about each
one by looking at the source code.  Nor is it the Abuse FAQ.  The Abuse
FAQ is maintained by Mike Perry (mj-perry@ux4.cso.uiuc.edu) and can 
be obtained either from usenet or from the bot on the #abuse irc channel.
It's not a lisp manual, either.  If you need help on lisp, I recommend 
buying a book, taking a course, or browsing one of the web pages mentioned 
in the Abuse FAQ.  It won't tell you how to use the level editor, or how to
make $10,000 though some stupid pyramid scheme (thank god).  It won't take 
out the garbage, or feed the cat.  It's just a list of functions.
 
                  --== How'd you figure this out? ==--
By looking at the files lsp/*.lsp in the abuse directory and playing with
the editor a bit.  Of course, there's only so much you can figure out
from (largely) undocumented source.  There are quite a few holes in this,
but it's better than nothing.  Hopefully, it'll fill in more as people
send in what they've figured out or when I get more time to play with it.
 
                   --== What can I do with this? ==--
I'd appreciate it if you'd only distribute this in it's entire, unedited 
format.  Send comments and suggestions to the Tony Cannon via 
cannon@cs.stanford.edu.  Other than that, feel free to distribute it in
any form to any forum so long as you do not derive any profit from said
distribution.  This release only contains most of the functions from A-R.  
I'd recommend looking at (def_char) for starters.
 
;;------------------------------------------------------------------------
  Object Function: activated
  Usage:           (activated)
  Returns:         T or nil
  Returns T if the (me) object is activated, nil otherwise.  An object
  is activated when the (bg) enters it's range (dunno)
;;------------------------------------------------------------------------
  Function:        ascatter_line
  Usage:           (ascatter_line x1 y1 x2 y2 color1 color2 (????3????))
  Returns:         dunno
  dunno
;;------------------------------------------------------------------------
  Object Function: add_ammo
  Usage:           (add_ammo weapon_type amount)
  Returns:         dunno
  Adds [amount] ammo to the weapon [weapon_type].  Amount can be
  negative to subract ammo.  Make sure to call (has_weapon) to see
  if the player has that weapon or not.  If they don't you can call
  (give_weapon) to give it to them.
;;------------------------------------------------------------------------
  Object Function: add_hp
  Usage:           (add_hp amount)
  Returns:         dunno
  Gives [amount] of hitpoints to the current object.  For example,
  you might do (with_object (bg) (add_hp (hp))) to double the main
  character's hitpoints.
;;------------------------------------------------------------------------
  Function:        add_light
  Usage:           (add_light ??? x y ??? ??? ??? ???)
  Returns:         the new light
  Creates a new light at position [x] [y].  Note that this light
  isn't linked to anything, it's just created.  If you want to link,
  use thel link_light function.
;;------------------------------------------------------------------------
  Function:        add_object
  Usage:           (add_object obj_class x y ???optional)
  Returns:         The newly created object
  Creates a new object specifed by the [obj_class] and starts it off at
  location [x] [y].  The object isn't linked to anything.  You might
  say something like: (add_object SMALL_DARK_CLOUD (x) (y)).  If you
  want to add a light, call add_light, not add_object.
;;------------------------------------------------------------------------
  Function:        add_object_after
  Usage:           (add_object_after obj_class x y)
  Returns:         The newly created object
  Just like add_object as far as I can tell.  I'm guessing that this
  puts the object at the end of some global list instead of at the
  beginning so that other objects are drawn in front of it.  Just a
  guess, though.  See add_object for more info.
;;------------------------------------------------------------------------
  Funciton:        add_panim
  Usage:           (add_panim part_class x y dir)
  Returns:         dunno
  dunno.  Creats a new particle animation at location [x] [y].  
  [part_class] is a class previously declared with the def_particle
  function, I think.  What's a particle?  I have no clue.
;;------------------------------------------------------------------------
  Object Function: aistate
  Usage:           (aistate)
  Returns:         An object's current aistate
  Gets the current value of the aistate.  In Abuse, the aistate is
  a pointer in the finite state machine used to control most object's
  AI functions.  You'll almost always use (aistate) in a construct
  similar to: (select (aistate) (0 blah) (1 blah)).  You can set
  the aistate with the (set_aistate) function.
;;------------------------------------------------------------------------
  Object Function: aitype
  Usage:           (aitype)
  Returns:         An object's current aitype
  It looks like aitypes are used to distinguish between several
  different "flavors" of objects that all use the same AI function.
  For example, you can use the aitype to select how many hitpoints
  to give a mob or which palette to use to draw it.  The aitype
  is usually accessible in the editor by use of the fields sub-
  function in (def_char).  You can set the aitype with the
  (set_aitype) function.
;;------------------------------------------------------------------------
  Object Function: ammo_total
  Usage:           (ammo_total weapon_type)
  Returns:         How much ammo the object has
  Good for counting exactly how much ammo the object has in a 
  certain slot.  For example, in the (bg)'s ai, you might do:
  (ammo_total (current_weapon_type)).  I can't see why you'd want
  to do this outside of the (bg)...
;;------------------------------------------------------------------------
  Function:        argc
  Usage:           (argc)
  Returns:         Int
  Use (argc) to extract the number of command line parameters.  For
  example, if you started abuse by just typing "abuse -edit", then
  (argc) would return 2.
;;------------------------------------------------------------------------
  Function:        argv
  Usage:           (argv [n])
  Returns:         String
  (argv) will extract the [n]th argument from the command line.
  Note that n is 0 as in C and C++.  So, if you started abuse with the 
  command line "abuse -edit", then (argv 1) returns "-edit".
;;------------------------------------------------------------------------
  Function:        bg
  Usage:           (bg)
  Returns:         A pointer to the player object
  Use (bg) whenever you need to obtain a pointer to the player object.
  For example, you might say (with_object (bg) (set_hp 100)) to 
  give the player 100% health.
;;------------------------------------------------------------------------
  Function:        blocked_down
  Usage:           (blocked_down block_flags)
  Returns:         T or nil
  Parses the block_flags (for example, the flags returned by the
  move function) to see if the blocked_down bit is set or something.
  You might say, (if (blocked_down (move 0 0 0)).
;;------------------------------------------------------------------------
  Function:        blocked_left
  Usage:           (blocked_left block_flags)
  Returns:         T or nil
  See blocked_down, it's probably the same
;;------------------------------------------------------------------------
  Function:        blocked_right
  Usage:           (blocked_right block_flags)
  Returns:         T or nil
  See blocked_down, it's probably the same
;;------------------------------------------------------------------------
  Function:        blocked_up
  Usage:           (blocked_up block_flags)
  Returns:         T or nil
  See blocked_down, it's probably the same
;;------------------------------------------------------------------------
  Object Function: bmove
  Usage:           (bmove obj_ptr)
  Return:          The object hit
  dunno. Move like a bullet.  As best as I can figure out, it
  takes the values from a call to (set_course) and moves the
  object 1 step.  If it hits anything in its path _besides_ 
  [obj_ptr] it will return that object.  Otherwise, it will
  return nil.  Updates both x and y of this object.
;;------------------------------------------------------------------------
  Function:        break
  Usage:           break
  Return:          dunno
  Stops execution of the currently running program and shells
  into the lisp interpreter.  Pretty cool, but unlikely that
  you'd use it in a game (although you could get clever, I
  guess).
;;------------------------------------------------------------------------
  Function:        can_see
  Usage:           (can_see sourcex sourcey destx desty obj_ptr)
  Return:          T or nil
  Returns whether or not there is a line of sight from 
  [source] to [dest].  I assume the things that block you from
  moving are the same things that can block a line of sight.
  I dunno what obj_ptr is (or even if it really is an obj_ptr)
  because it's always nil.  I suppose it might be an objec that
  can also block sight, but again, I dunno.
;;------------------------------------------------------------------------
  Function:        current_weapon_type
  Usage:           (current_weapon_type)
  Returns:         The currently selected weapon.
  Returns the current weapons selected by the main character. 
  For example, you might want to do a:
  (if (> (ammo_total (current_weapon_type)) 0) to see if the player
  can fire the weapon.
;;------------------------------------------------------------------------
  Object Function: damage_fun
  Usage:           (damage_fun amount from hitx hity push_xvel push_yvel)
  Returns:         dunno
  Causes the current object to take [amount] damage.  I suppose this
  entails subtracting [amount] from the object's hitpoints.  It also
  "moves" them with velocity [push], but I'm not sure if this is
  added directly to the position or the velocity.  [hit] is the location
  that the damage occured, and I think [from] is the object that
  damaged you, though I can't know for certain.
;;------------------------------------------------------------------------
  Function:        def_char
  Usage:           (def_char obj_class (sub_function)*)
  Returns:         nothing important
  (def_char) is the function you use to create new types of objects.
  Everything you see in the object window of the editor (and more) 
  has a def_char associated with it somewhere in the lisp code (unless
  it's pre-compiled, but I don't think any are).  [obj_class] is the
  way you refer to the new object.  There are several different
  sub_functions that you have to call as parameters to the def_char
  to fully define the object.  They are described below:
 
      Sub-function:  vars
      Usage:         (vars [var]*)
      The (vars) function creates a set of local variables visible 
      only inside this object.  You can set these variables using
      (setq) and you can get their values by just typing the token.
      For example, I might type in an ai_function: (setq tics (+ tick 1))
      You can put as many vars as you want, bounded only by what's
      sensible and probably a cap on some array in JC's interpreter.
 
      Sub-function:  funs
      Usage:         (func [func-pair]*)
      The (funs) function lets you hook you certain functions to 
      the object's methods.  Each [func-pair] is of the form
      (fun-type fun-you've-written), where fun-type is one of
      the following:
          ai_fun - The brain of the object.  The ai_fun is called
             every tick.  Most ai_funs are a finite state machine
             using the aistate as a state pointer.  The function
             you write for ai_fun shouldn't take any arguments.
          constructor - Just like a C++ constructor.  This function
             is called when the object is just created.  It takes
             no arguments.
          damage_fun - The function to be called when this object
             takes damage.  Arguments?  Yes, actually.  This funciton
             needs to have the same type of arguments as the builtin
             do_damage.
          draw_fun - The function called whenever an object needs
             to be draw.  It also takes no arguments.
          move_fun - The function called to move the object around.
             It takes three parameters: the first is the x direction
             (<0 for left >0 for right), the next is the y direction
             (<0 for up   >0 for down), and the last is the status
             of the mouse buttons (bit 1 is set for the right,
             bit 2 for the left).  I've only seen move functions
             on the player, in which case, the three variables just
             represent keystrokes.  *NOTE* The move function NEEDS
             to return blocked_flags.  I'm not sure how to
             assemble them, though.
          reload_fun - It think this is the function that's called
             whenever an item is loaded _after_ the first time,
             as opposed to the constructor which is called on the
             first time.  Don't quote me, though.  This function
             takes no arguments.
          type_change_fun - The function called when the aitype 
             changes.  I think.  Guess what?  This doesn't take
             any arguments either.
          user_fun - The userfun can be invoked at any time by
             calling (user_fun signal value) from inside the
             object.  The parameters are, of course, the signal
             and the value.  I have no idea if this description is
             accurate, but it seems like it to me.
 
      I'm not sure what happens when you try to make a function
      that's not one of the above.  It _could_ be that you can 
      invoke it by just calling it by name (as in the user_fun),
      but I'm not certain.   
 
      Sub-function:  fields
      Usage:         (fields [field-pair]*)
      You use the (fields) function to provide hooks into the editor.
      Each field-pair is of the form (var prompt) where both are strings.
      The var is the name of the variable that you'd like to modify.
      They can be both builtin variables (hp, aitype, xvel) or things
      that you've mentioned in the vars sub-function.  The prompt is
      what you want to appear to the left of the text-field for this
      variable in the editor.  Both must be quoted For example, I might use:
      (fields ("aitype" "Mob Type (0-15):")
 
      Sub-function:  abilities
      Usage:         (abilites [ability-pair]*)
      Used to set constants in the object.  The ability-pair is of the
      form (constant value).  For example, (run_top_speed 10).  In order
      to read the value of an ability, you need to use the 
      (get_ability) function.
 
      Sub-function:  range
      Usage:         (range x y)
      Sets the range for this object. 
 
      Sub-function:  draw_range
      Usage:         (draw_range x y)
      Sets the drawing range for this object. 
 
      Sub-function:  flags
      Usage:         (flags [flag-pair]*)
      Sets up all kinds of little quirky things about an object.
      Each flag-pair is of the form (flag value) where value is
      PROBABLY either T or nil.  I say probably because I've never
      seen a flag with a nil value.  Oh well, here's the flags I've
      found:
         unlistable - The item won't appear in the objects window
            of the editor
         add_front - When you create this object, put it in front
            of all other object so it's drawn on top.
         hurtable - You can hurt this object.
         force_health - Dunno.  Only appears in ants.
         can_block - This object behaves as an obstruction.  You
            can't walk thought it. (More specifically, trying to
            move through it will set the blocking flags)
         unactive_shield - Dunno.  Only appears in hidden_walls.
 
      Sub-function:  states
      Usage:         (states [spe] [state-pair]*)
      Defines all the different positions the object can have.  The
      [spe] is the .spe file where the frames for all these states
      can be found.  Each [state-pair] is of the form 
      (state frame-list).  The state is just a token to refer to
      this state by (as in (set_state) and (state)).  The frame-list
      is a lisp form containing the names for all frames for this
      state.  Examples include a single frame, "bomb.pcx", a list
      of frames, `("one.pcx" "two.pcx"), and a sequence of frames
      built by the (seq) function, (seq "f" 9 12) which evaluates
      to `("f0009.pcx" "f0010.pcx" "f0011.pcx" "f0012.pcx").
 
  No example is given because it probably wouldn't be helpful and
  because there are TONS in the source.
;;------------------------------------------------------------------------
  Function         def_image
  Usage:           (setf [some_image] (def_image [spe] [name]))
  Returns:         dunno
  Lets you refer to the image [name] in the [spe] .spe file by the token
  [some_image] so you can use it in a call to (put_image).  Not very
  descriptive, I know.  For example, you might say:
     (setf an_image (def_image "art/misc.spe" "some_image.pcx"))
     (put_image 20 5 an_image)
;;------------------------------------------------------------------------
  Function:        def_particle
  Usage:           (def_particle '[part_class] [spe])
  Returns:         dunno
  Here's a guess, but I dunno.  Defines a particle animation that you
  can use for special affects.  The [part_class] is the class that you'll
  need to pass to (add_panim) to display the effect.  The [spe] is
  the name of the file that contains the effect.
;;------------------------------------------------------------------------
  Function:        def_sound
  Usage:           (def_sound '[sound_class] [file])
  Returns:         sound_class
  Creates a sound resource that you can refer to by [sound_class].
  Is used in cooperation with the function (play_sound).  [file]
  is the path from the abuse directory to the .wav.  For example,
  (def_sound 'SBALL_SND "sfx/ball01.wav")).  (def_sound) returns
  the class of the sound, in this case, SBALL_SND.
;;------------------------------------------------------------------------
  Function:        def_tint
  Usage:           (def_tint [spe])
  Returns:         the tint
  Dunno.  Haven't messed with it yet.
;;------------------------------------------------------------------------
  Function:        delete_light
  Usage:           (delete_light [light])
  Returns:         dunno.
  Completely removes a light from the game.  [light] is the actual
  light object that you want to remove.  For example, you could type
  (delete_light (get_light 0)) from inside some object with a link
  to a light.
;;------------------------------------------------------------------------
  Object Function: dev_draw
  Usage:           (dev_draw)
  Returns:         dunno, probably nothin'.
  Basically, calls the normal draw function if and only if the editor
  is currently running.  Sensors, gates, etc. all use def_draw for
  their draw functions.
;;------------------------------------------------------------------------
  Object Function: do_damage
  Usage:           (do_damage amount who ???x ???y)
  Returns:         dunno, probably nothin'.
  Does [amount] damage to [who].  [x] and [y] are probably the
  amount to recoil, or maybe xvel and yvel like in damage_fun.
  I dunno.
;;------------------------------------------------------------------------
  Object Function: draw
  Usage:           (draw)
  Returns:         dunno
  Draw the person in a very standard way.
;;------------------------------------------------------------------------
  Function:        draw_line
  Usage:           (draw_line x1 y1 x2 y2 color)
  Returns:         dunno
  Draws a line in the usual fashion.  Here's another example for the
  faint of heart: (draw_line 10 10 20 20 (find_rgb 128 128 128)) draws
  a 45 degree, greyish line.
;;------------------------------------------------------------------------
  Function:        draw_predator
  Usage:           (draw_predator)
  Returns:         dunno
  dunno
;;------------------------------------------------------------------------
  Function:        draw_tint
  Usage:           (draw_tint tint)
  Returns:         dunno
  Draws the object with some sort of spiffy palette stuff happening,
  I guess.  Haven't messed with it (dunno).
;;------------------------------------------------------------------------
  Function:        draw_transparent
  Usage:           (draw_transparent ??? ???)
  Returns:         dunno
  Draws the object as some sort of a semi-solid filter.  I have no
  idea what the two parameters do as I haven't messed with it at all
  (dunno).
;;------------------------------------------------------------------------
  Object Function: direction
  Usage:           (direction)
  Returns:         -1 or +1 (the value of direction)
  The game engine uses an objects direction to determine whether or
  not it's image should be flipped horizontally when drawn (that's
  a guess).  1 means facing right (the default), -1 means facing
  left.  You can change the direction of this object with the
  (set_direction) function.
;;------------------------------------------------------------------------
  Object Function: facing
  Usage:           (facing)
  Returns          -1 or +1
  I have no how this would be different from direction (dunno).
;;------------------------------------------------------------------------
  Object Function: fade_count
  Usage:           (fade_count)
  Returns:         The value of fade_count
  I'm not sure.  Seems to be used as a counter in a lot of code,
  but I don't know if different values of fade count cause the
  image to be drawn in a different way or not.  You can set the
  value of fade_count with the (set_fade_count) function.
;;------------------------------------------------------------------------
  Function:        find_object_in_angle
  Usage:           (find_object_in_angle start end list)
  Returns:         object or nil
  Looks for an object inside the angle [start] [end].  If it finds
  an (active?) object who's class matches one of those in list, then
  it will return that object.  Otherwise, returns nil.  For example,
  (find_object_in_angle 0 180 (list ANT_ROOF))
;;------------------------------------------------------------------------
  Function:        find_object_in_area
  Usage:           (find_object_in_area x1 y1 x2 y2 list)
  Returns:         object or nil
  Same as find_object_in_angle, except searches a rectangular area
  rather than the range between two angles.   A good example is
  (find_object_in_area 0 0 320 200 bad_guy_list).
;;------------------------------------------------------------------------
  Function:        find_rgb
  Usage:           (find_rgb red green blue)
  Returns:         object or nil
  Returns the index of the palette which best matches the RGB
  color specified.  Just what you need to pass colors to the 
  different line drawing functions and such.  For example,
  (make_view_solid (find_rgb 255 255 255)).
;;------------------------------------------------------------------------
  Object Function: first_focus
  Usage:           (first_focus)
  Returns:         An object or nil
  This is completely off the cuff (i.e. I dunno), but here goes.
  (first_focus) return the first in a list of objects within range
  of the current object.  This is useful when you need to do something
  to all objects that are in your range, not just the object you're
  currently linked to.  If there are no objects in range, this returns
  nil.
;;------------------------------------------------------------------------
  Object Function: float_tick
  Usage:           (float_tick)
  Returns:         Something really odd
  I have no idea what this does.  Here's a bit I've noticed, though.
  (float_tick) is only called from (bounce_move) and the boulder_ai.
  A value of T means that nothing was hit.  (car (float_tick)) is
  a valid set of block_flags.  Weird, eh?
;;------------------------------------------------------------------------
  Function:        frame_panic
  Usage:           (frame_panic)
  Returns:         T or nil
  (frame_panic) returns whether or not the frame-rate is in a critical
  state.  When things start draaaggging, (frame_panic) is probably
  true.  You might want to check frame_panic before doing anything
  extraordinary, but not necesary.  For example:
  (if (not (frame_panic)) (pyrotechnics) nil)
;;------------------------------------------------------------------------
  Function:        freeze_player
  Usage:           (freeze_player how_long)
  Returns:         dunno
  Stops the action for [how_long] ticks or until the user presses a
  mouse button.  Those little training messages do a 
  (with_object (bg) (freeze_player 100)) in their ai functions.
;;------------------------------------------------------------------------
  Function:        game_tick
  Usage:           (game_tick)
  Returns:         the game time.
  Returns the absolute game time, in ticks.  Or something.  I guess
  you can use it for one of those par-time like things in DOOM, or
  if you need something to happen every n ticks:
  (eq (mod (game_tick) n) 0).
;;------------------------------------------------------------------------
  Object Function: get_ability
  Usage:           (get_ability ability)
  Returns:         whatever ability
  The (get_ability) function is used to retrieve the value of
  [ability] set in the (def_char) for this object.  As far as I know,
  you can't change the value of an ability.  For example, you could
  do a (get_ability top_run_speed).
;;------------------------------------------------------------------------
  Object Function: get_light
  Usage:           (get_light n)
  Returns:         a light object
  Use this function to get the [n]th light linked to you.  Such as:
  (eq (light_r2 (get_light 0)) 100).
;;------------------------------------------------------------------------
  Object Function: get_object
  Usage:           (get_object n)
  Returns:         an object.
  Returns the [n]th object in your link list.  Most often used in
  with (with_object) to perform some action inside another object.
  Like: (with_object (get_object 0) (set_x 10)).
;;------------------------------------------------------------------------
  Function:        give_weapon
  Usage:           (give_weapon weapon_type)
  Returns:         dunno
  Gives the player the weapon [type].  Once the player has a weapon,
  you can start filling it up using the (add_ammo) function.  Use
  (has_weapon) to see if someone has a weapon before giving it to
  them.
;;------------------------------------------------------------------------
  Object Function: gravity
  Usage:           (gravity)
  Returns:         the value of gravity
  I assume the internal variable gravity is used by the builtin
  movement functions to make things fall.  You can see if gravity
  is turned on or not by checking this value.  You can also set the
  value of gravity using the (set_gravity) function.
;;------------------------------------------------------------------------
  Object Function: has_object
  Usage:           (has_object obj_ptr)
  Returns:         T or nil
  Determines whether or not the [obj_ptr] is in the current object's
  link list.  If so, (has_object) returns T.  It returns nil otherwise.
  This is useful if you want to link something, but aren't sure if
  you're already linked (I dunno what linking the same object twice
  might do).
   (if (has_object some_object) nil (link_object some_object))
;;------------------------------------------------------------------------
  Function:        has_weapon
  Usage:           (has_weapon weapon_type)
  Returns:         T or nil
  Checks to see whether or not the player already has the weapon
  [weapon_type].  If they don't, you can use (give_weapon) to give
  it to them.  If they do, you can use (add_ammo) to give them some
  more ammo, or take it away.  For example:
  (if (has_weapon type) (add_ammo type 10) (give_weapon type))
;;------------------------------------------------------------------------
  Function:        hurt_radius
  Usage:           (hurt_radius x y rad amount obj_ptr ???)
  Returns:         dunno
  Damages everyone within [rad] pixels of position [x] [y] by
  [amount] damage, except for the object [obj_ptr].  If you want
  to damage everyone, set [obj_ptr] to nil.  I have no idea what
  the last parameter is for, but it ranges from 10 to 30 in the
  Abuse code.  You might write, (hurt_radius (x) (y) 19 30 (me) 15)
  to damage everyone around you, but not take damage yourself.
;;------------------------------------------------------------------------
  Object Function: hp
  Usage:           (hp)
  Returns:         The value of the hp variable.
  (hp) returns how many hitpoints the current object has left.
  There's nothing special about how many (hp) a creature has, it
  seems.  What I mean is, just because a creature's hitpoints
  drop below 0 doesn't mean that it will die.  It's up to you to
  detect that in the damage_fun and take the appropriate action
  if necessary (see def_char for description of damage_fun).
  Like:  (if (< (hp) 0) (die_fun) nil)
;;------------------------------------------------------------------------
  Object Function: isa_player
  Usage:           (isa_player)
  Returns:         T or nil
  Use (isa_player) to determine whether or not the object is
  controlled by a player.  
;;------------------------------------------------------------------------
  Object Function: jump_state
  Usage:           (jump_state state)
  Returns:         dunno
  I dunno what this does.  I can speculate, but would rather not.
;;------------------------------------------------------------------------
  Function:        last_savegame_name
  Usage:           (last_savegame_name)
  Returns:         String
  Recalls the name of the last save game.  Is most useful when
  passed as the argument to (request_level_load).  Make sure that
  the game has already been saved, though, as in:
  (if (my_level_been_saved_fun) (request_level_load (last_savegame_name)) 
  nil)
;;------------------------------------------------------------------------
  Function:        level_name
  Usage:           (level_name)
  Returns:         String
  Returns the name of the level.  This can also be used as an argument
  to (request_level_load).
;;------------------------------------------------------------------------
  Function:        light_r2
  Usage:           (light_r2 light)
  Returns:         Int
  (light_r2) will let you look at the second radius of the [light]
  object.  Is pretty cool because it lets you do some neat dimming
  effects, like:  (set_light_r2 (- (light_r2 (get_light 0)) 1))
  You can set the value of a light's r2 using (set_light_r2), of
  course.
;;------------------------------------------------------------------------
  Object Function: link_light
  Usage:           (link_light light)
  Returns:         dunno
  (link_light) will add the [light] object to the current objects
  list of lights.  After linking, you can get to the light by
  calling (get_light).  For example, if you're doing some sort of
  adventure game and the user lights a lantern, you might want to
  do a (link_light (add_light 0 (x) (y) 1 (aitype) 0 0)).
;;------------------------------------------------------------------------
  Object Function: link_object
  Usage:           (link_light obj_ptr)
  Returns:         dunno
  As in (link_light), (link_object) puts [obj_ptr] in the current
  object's link list.  You can now recall that object with the 
  (get_object) function.  These dynamic links, as far as I can tell,
  are identical to the links you set up using the level editor.
;;------------------------------------------------------------------------
  Function:        load
  Usage:           (load file)
  Returns:         dunno
  Use load to get the Abuse to interpret a lisp source file.  The
  [file] should be the compete path to the file you want to load from
  the Abuse directory.  You'll use load most often from whatever
  your main lisp file is, for most of you "abuse.lsp".  Suppose you'd
  written the source for a new type of platform that could move between
  n points instead of just 2 in the file "nplat.lsp" in the lsp 
  directory.  Before you can play with that platform in the editor,
  you have to put the line: (load "lsp/nplat.lsp") in abuse.lsp.
;;------------------------------------------------------------------------
  Function:        load_big_font
  Usage:           (load_big_font spe font)
  Returns:         dunno
  I suppose this loads the "big_font" for the game out of [spe].  I
  don't have a computer to mess around with, so I don't really know.
  Figure it out later.
;;------------------------------------------------------------------------
  Function:        load_console_font
  Usage:           (load_console_font spe font)
  Returns:         dunno
  Probably the same as (load_big_font), but the font used for the
  lisp console in the editor.
;;------------------------------------------------------------------------
  Function:        load_color_filter
  Usage:           (load_color_filter spe)
  Returns:         dunno
  Specifies the [spe] which contains the palette to be used to calculate
  the color filter, I'd imagine.  
;;------------------------------------------------------------------------
  Function:        load_palette
  Usage:           (load_palette [spe])
  Returns:         dunno
  Specifies the [spe] which contains the palette to be used during
  the game, I suppose.
;;------------------------------------------------------------------------
  Function:        load_small_font
  Usage:           (load_small_font spe font)
  Returns:         dunno
  Probably the same as (load_big_font), but the font used for 
  drawing things in small type (I dunno).
;;------------------------------------------------------------------------
  Function:        load_tiles
  Usage:           (load_tiles spe*)
  Returns:         dunno
  Loads the [spe]'s containing all the tiles which will be made
  available in the editor.  If you'd make your own background
  tiles in the art/back directory called wumpus.spe and fuzzy.spe, you'd 
  have to call (load_tiles "art/back/wumpus.spe" "art/back/fuzzy.spe")
  before you can use them in the editor.
;;------------------------------------------------------------------------
  Object Function: local_player
  Usage:           (local_player)
  Returns:         T or nil
  Determines whether or not the object in question is a local player or
  not.  I'm thinking that (isa_player) will return T for both local
  and networked players, but (local_player) will only return true
  if we're talking about the player on the local client.  Good for
  stuff like invisiblity.
;;------------------------------------------------------------------------
  Object Function: lower
  Usage:           (lower)
  Returns:         dunno
  Moves the object below all other objects.  I guess this affects
  drawing order or something.  For example, you grab an object
  and say (with_obj0 (if (isa_player) nil (lower))).
;;------------------------------------------------------------------------
  Object Function: me
  Usage:           (me)
  Returns:         An obj_ptr
  Use (me) to get a pointer to yourself.  This is just like the
  this pointer in C++, the self in Objective C, etc. etc.  Good when
  you need to pass yourself to some other object, possibly for linking
  purposes.
;;------------------------------------------------------------------------
  Function:        make_view_solid
  Usage:           (make_view_solid color)
  Returns:         dunno
  Flashes the entire screen to [color].  You might do something like
  (make_view_solid (find_rgb 255 20 20)) to simulate being hit by
  a rocket in DOOM. :)
;;------------------------------------------------------------------------
  Object Function: morphing
  Usage:           (morphing)
  Returns:         dunno
  Dunno.  Only used once in top draw.  Doesn't appear to be a way
  to set it.
;;------------------------------------------------------------------------
  Object Function: move
  Usage:           (move xm ym but)
  Returns:         blocked_flags
  Move seems to be the builtin function to move things around on
  the screen.  [xm] and [ym] definitely reflect the value of the
  button presses.  xm < 0 is left, xm > 0 is right, ym < 0 is
  up, ym > 0 is down.  Bit 1 of but is a bool for the right mouse
  button, but 2 is a bool for the left.  A good deal of the guts
  of moving someone around is _missing_ from the source, so I assume
  it's done by (move).  This includes setting accelerations, the
  standard x += xvel, etc.  I don't think move accounts for gravity,
  though.  Move returns whether or not the object hit something
  along the way in the blocked_flags, which can be parsed with the
  (blocked_*) functions.
;;------------------------------------------------------------------------
  Object Function: mover
  Usage:           (mover xm ym but)
  Returns:         blocked_flags
  How is mover different from move?  I have no clue.  I speculate,
  though, that mover accounts for gravity and move does not.  See
  (move) for more info.
;;------------------------------------------------------------------------
  Object Function: next_focus
  Usage:           (next_focus some_ptr)
  Returns:         The next item in the list
  (next_focus) will, I hope, return the next item in some list of
  object that have something in common, probably they're all in 
  range of the current object.  The [some_ptr] is an object that
  was recovered with either (first_focus) or a previous call to 
  (next_focus).
;;------------------------------------------------------------------------
  Function:        next_savegame_name
  Usage:           (next_savegame_name)
  Returns:         String?
  Use (next_savegame_name) to return the next slot available for
  a call to (save_game).  For example, all those Save Stations in
  Abuse eventually call the code (save_game (next_savegame_name)).
;;------------------------------------------------------------------------
  Object Function: next_picture
  Usage:           (next_picture)
  Returns:         T or nil
  Advances the current frame by 1.  If we're at the end of the 
  frames for this state, stay there and return nil.  Sort of 
  like (set_current_frame (+ (current_frame) 1)).
;;------------------------------------------------------------------------
  Object Function: otype
  Usage:           (otype)
  Returns:         An obj_class
  Converts the obj_ptr for the current object back to the class
  for that object. Is useful when you want to do something differnet
  depending on what an object is.  For example, if I want everyone
  to be damaged by lava, except for FIRE_HOUNDS, which should be
  healed, I might do this in the lava_ai.
  (let ((target (find_object_in_area (- (x) 10) (+ (x) 10) (y) (+ y 3)
             bad_guy_list)))
    (with_object target (if (eq (otype) FIRE_HOUNDS)
         (set_hp (+ (hp) 10))
         (do_damage target 10))
    )
  )
;;------------------------------------------------------------------------
  Object Function: picture_height
  Usage:           (picture_height)
  Returns:         Int
  Use (picture_height) to return the height of the current frame
  of this object.  Is useful for centering, formatting, etc.  If
  I wanted to center along the y, I might do
  (let ((oldy (y))) 
     (set_y (+ y (/ (picture_height) 2)))
     (draw)
     (set_y oldy)
  )
;;------------------------------------------------------------------------
  Object Function: picture_width
  Usage:          (picture_width)
  Returns:        Int
  Returns the width of the current frame of this object.  Is not as
  useful as picture_height, as you can specify the home x location of
  an object in satan paint, but I suppose it may come in handy
  sometime.
;;------------------------------------------------------------------------
  Object Function: platform_push
  Usage:           (platform_push x y)
  Returns:         dunno
  I assume this moves the player by amount [x] [y] as if they were on
  a platform.  This really could be done in lisp, but I guess was
  compiled for speed.  Oh well.
;;------------------------------------------------------------------------
  Function:        play_sound
  Usage:           (play_sound sound_class volume x y)
  Returns:         dunno
  Plays the sound [sound_class] as if it had come from location
  [x] [y] at the specified [volume].  Before you can use this
  function, you need to use (def_sound) to hook the .wav file up
  to a certain sound class.
;;------------------------------------------------------------------------
  Object Function: player_number
  Usage:           (player_number)
  Returns:         Int
  Returns which player number the object is.  I'm not sure what happens
  if you call this when object (not (isa_player)).  Evidently, the
  local player is always player number 0, with networked players taking
  up numbers >= 1.  There's no use for this until the network patch
  comes out, as you'll always get a 0 back.
;;------------------------------------------------------------------------
  Function:        player_b1_suggest
  Usage:           (player_b1_suggest)
  Returns:         T or nil
  Gets the state of the first mouse button.  If you're inside a move
  function, you should use the value of the but parameter and not
  (player_b1_suggest).  Just a suggestion :).
;;------------------------------------------------------------------------
  Function:        player_b2_suggest
  Usage:           (player_b2_suggest)
  Returns:         T or nil
  Gets the state of the second mouse button.  If you're inside a move
  function, you should use the value of the but parameter and not
  (player_b1_suggest).  Just a suggestion :).
;;------------------------------------------------------------------------
  Function:        player_pointer_x
  Usage:           (player_pointer_x)
  Returns:         Int
  (player_pointer_x) returns the absolute x position of the mouse.
;;------------------------------------------------------------------------
  Function:        player_pointer_y
  Usage:           (player_pointer_y)
  Returns:         Int
  (player_pointer_y) returns the absolute y position of the mouse.
;;------------------------------------------------------------------------
  Function:        player_x_suggest
  Usage:           (player_x_suggest)
  Returns:         Int
  I'm pretty sure this function returns -1 if the left button is
  pressed, 1 if the right button is pressed and 0 otherwise.  I'm
  not sure it actually exists, as it's not in the source code, but
  player_y_suggest does, so you'd figure, right?  If you're in a move
  function, you should probably use the xm parameter and not
  (player_x_suggest).
;;------------------------------------------------------------------------
  Function:        player_y_suggest
  Usage:           (player_y_suggest)
  Returns:         Int
  Probably returns -1 if the up button is pressed, 1 if the down
  button is pressed and 0 otherwise.  If in a move function, you 
  should probably use the value of the ym parameter instead.
;;------------------------------------------------------------------------
  Function:        print
  Usage:           (print something)
  Returns:         dunno
  Prints something to the console.  I've tried int's and objects,
  and they both work.  Silly me didn't try a string.  Oh well.
;;------------------------------------------------------------------------
  Function:        put_image
  Usage:           (put_image x y image_def)
  Returns:         dunno
  Slaps in image down at position [x] [y].  The [image_def] is an
  image definition that was previously set up with (def_image).
  See def_image for more information, but you can do something like:
  (put_image 0 0 (def_image "art/misc.spe" "some_image.pcx"))
;;------------------------------------------------------------------------
  Object Function: remove_object
  Usage:           (remove_object obj_ptr)
  Returns:         dunno
  _PERSONALLY_ I think this should be called unlink_object for
  parallellism, but that's just my opinion.  As far as I can tell,
  (remove_object) removes the [obj_ptr] from the current object's
  link list.
;;------------------------------------------------------------------------
  Function:        reset_player
  Usage:           (reset_player)
  Returns:         dunno
  Speculation: Sets the player up in a state of reset (whatever that
  means).   Probably maxes out the health and does some other stuff.
  This is most commonly done in a network game where loading a level
  is not an option (screws everyone else up).  Of course, there _are_
  no network games as of yet, so all bets are off.
;;------------------------------------------------------------------------
  Function:        rand_on
  Usage:           (rand_on)
  Returns:         Something...
  I dunno what this does.  It looks like it and (set_rand_on) might
  have something to do with seeding the random number generator,
  but I'm not sure.
;;------------------------------------------------------------------------
  Function:        random
  Usage:           (random n)
  Returns:         Int
  Picks a random number between either 0 and [n] or 1 and [n].  I
  don't have Abuse handy to check, at the moment.  Is good for
  placing explosions in a chaotic way.
;;------------------------------------------------------------------------
  Function:        request_end_game
  Usage:           (request_end_game n)
  Returns:         dunno
  Asks for the game to end.  I have no idea what [n] is, or what happens
  if the request is denied.  Maybe it's only polite syntax.
;;------------------------------------------------------------------------
  Function:        request_level_load
  Usage:           (request_level_load level)
  Returns:         dunno
  Asks for the interpretert to load the level [level].  [level] should
  be the full path to the file you want to load from the abuse
  directory.  Can the request be denied?  Obviously if the file isn't
  there, but what if it is?  Dunno.
;;------------------------------------------------------------------------