///////////////////////////////////////////////////////////////////////////
// Advanced Abuse Editing : Builtin Function Documentation (v1.000) //
// Maintained by: Tony Cannon (cannon@cs.stanford.edu) //
// (Ponder on #abuse irc channel) //
///////////////////////////////////////////////////////////////////////////

Section I. Things Not Related to Editing

--== 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.

Section II. How to Read This Document

--== My God This Is BIG ==--
Yes, it is big, isn't it? If you really want to learn all of this, you
can just sit down and start with (activated) and make your way down. I
HIGHLY discourage that, though. Personally, I think the best way to read
this is to start with the following topics, and fill your way out from
there:

New Objects: ai_fun, def_char, move_fun, def_char again, ai_state,
draw_fun, def_char, def_char, damage_fun, one more look at
def_char.
Linking: add_object, get_object, with_object, link_object, remove_object
Lighting: add_light, get_light, link_light, delete_light, set_light_r2,
set_ambiend_light.
Finding Things: bg, first_focus, next_focus, can_see, find_object_*

Section IV. Credits

Special Thanks goes to...
Jonathan Clark <jc@crack.com>...................Help all over the place!

;;------------------------------------------------------------------------
Object Function: activated
Usage: (activated)
Returns: T or nil
Returns T if the (me) object is activated, nil otherwise.
An activated object is one who's aistate does not equal 0. Thus,
you could have just done a (not (eq (aistate) 0)), but (activated)
is shorter.
;;------------------------------------------------------------------------
Function: ascatter_line
Usage: (ascatter_line x1 y1 x2 y2 color1 color2 spread)
Returns: dunno
Draws a fuzzy line between points 1 and 2 using colors 1 and 2. You
can control the fuzziness with the [spread] parameter, which should
take a value between 0 and 8.
;;------------------------------------------------------------------------
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 type x y r1 r2 xshift yshift)
Returns: the new light
Creates a new light at position [x]+[xshift] [y]+[yshift]. Note that
this light isn't linked to anything, it's just created. If you want to link,
use thel link_light function. Use the [type] field to determine which
kind of light you want (half dome, etc.)
;;------------------------------------------------------------------------
Function: add_object
Usage: (add_object obj_class x y [aitype])
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. The [aitype]
parameter at the end is strictly optional.
;;------------------------------------------------------------------------
Function: add_object_after
Usage: (add_object_after obj_class x y [aitype])
Returns: The newly created object
Just like add_object, except that the object is added directly
after the current object in the global object list.
;;------------------------------------------------------------------------
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 generic, 4 byte variable used to describe something as on or
off (on being non-zero), and to control state machines. You'll
almost always use (aistate) in a construct similar to:
(select (aistate) (0 blah) (1 other-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".
;;------------------------------------------------------------------------
Object Function: bg
Usage: (bg)
Returns: A pointer to the closest player object
bg stands for BadGuy. It returns a pointer to the _closest_ player
in the game. If you're playing a networked or multi-player game,
this may not always be the same player. For example, you might say
(with_object (bg) (set_hp 100)) to give the closest 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). Great for debugging, though.
;;------------------------------------------------------------------------
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: create_players
Usage: (create_players obj-tag)
Returns: dunno
Creates a player to be controlled by the local PC. The player starts
off in the same location as the START object. If you don't do a
(create_player) BEFORE you enter the editor, you can't to squat (try
commenting out the create_player in abuse.lsp and see what I mean).
;;------------------------------------------------------------------------
Object Functino: current_weapon_type
Usage: (current_weapon_type)
Returns: The currently selected weapon.
Returns the current weapons selected by the local 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 count max)
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). I haven't had a chance to play around with what [count]
and [max] do yet. :(
;;------------------------------------------------------------------------
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 T or nil
Returns whether or not the current object is facing the (bg).
;;------------------------------------------------------------------------
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. Should
always be between 0 and 15 to determine the amount of transparency.
;;------------------------------------------------------------------------
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
Returns the first object in the list of players. Is useful when
you want to do something to all the player objects (when used
with next_focus).
;;------------------------------------------------------------------------
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. Be careful not to change anything
globally based on the frame_panic. Otherwise, machines in a network
game can become out of sync.
;;------------------------------------------------------------------------
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).
;;------------------------------------------------------------------------
Function: gc
Usage: (gc)
Returns: dunno
Turns on garbage collection.
;;------------------------------------------------------------------------
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). You can set the r2 or a light
with the (set_light_r2) function.
;;------------------------------------------------------------------------
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 push)
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.
The [push] parameter is how far to push the offending object.
;;------------------------------------------------------------------------
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). An object's hitpoints cannot
drop below 0.
;;------------------------------------------------------------------------
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))).
WARNING: lower should only be called from the reload_fun.
;;------------------------------------------------------------------------
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.
;;------------------------------------------------------------------------
Object Function: raise
Usage: (raise)
Returns: dunno
Moves the object above 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 (raise))).
WARNING: raise should only be called from the reload_fun.
;;------------------------------------------------------------------------
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
;;------------------------------------------------------------------------
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. The level will be loaded at the _end_ of the current
game tick.
;;------------------------------------------------------------------------
Function: save_game
Usage: (save_game name)
Returns: dunno
Saves the game in the file named [name]. If you don't want to
supply a name, you can always use whatever (next_savegame_name)
returns.
;;------------------------------------------------------------------------
Function: set_ambient_light
Usage: (set_ambient_light player value)
Returns: dunno
Changes the value of the ambient light for [player] only (everyone
else on the network is unaffected). [Value] specifies what you want
the new ambient light to be. For example (set_ambient_light (bg) 10)
;;------------------------------------------------------------------------
Object Function: set_aistate
Usage: (set_aistate n)
Returns: Int
Use the set_aistate function to set the value of aistate in
the current function. It returns the new value of aistate.
;;------------------------------------------------------------------------
Object Function: set_aitype
Usage: (set_aitype n)
Returns: Int
Use the set_aitype function to set the value of aitype in
the current function. It returns the new value of aitype.
;;------------------------------------------------------------------------
Object Function: set_course
Usage: (set_course angle speed)
Returns: dunno
A bit baffling as there's no (course) function that I can find.
Anyway, I think bmove uses the value of course to determine which
direction to move. If this is the case, use this function to set
it.
;;------------------------------------------------------------------------
Object Function: set_current_frame
Usage: (set_current_weapon n)
Returns: dunno
Sets the current frame of this state to [n].
;;------------------------------------------------------------------------
Object Function: set_current_weapon
Usage: (set_current_weapon n)
Returns: dunno
Use the set_current_weapon function to change which weapon
is currently selected. You can also get the value of the
current_weapon with the (current_weapon) function.
;;------------------------------------------------------------------------
Object Function: set_direction
Usage: (set_direction n)
Returns: Int
Use the set_direction function to set the value of direction in
the current function. It returns the new value of direction.
;;------------------------------------------------------------------------
Object Function: set_fade_count
Usage: (set_fade_count n)
Returns: Int
Use the set_fade_count function to set the value of fade_count in
the current function. It returns the new value of fade_count.
I have no idea what the fade_count does.
;;------------------------------------------------------------------------
Object Function: set_fast_time
Usage: (set_fast_time n)
Returns: Int
Use the set_fast_time function to set the value of fast_time in
the current function. It returns the new value of fast_time.
;;------------------------------------------------------------------------
Object Function: set_frame_angle
Usage: (set_frame_angle start stop angle)
Returns: dunno
Is useful for things that like to rotate. Instead of doing all
the division and math yourself, you can call (set_frame_angle) with
the angle of the first and last frames in the series for [start] and
[stop] and the angle you want to display for [angle]. (set_frame_angle)
will do all the math for you and set the current frame to the proper
rotation.
;;------------------------------------------------------------------------
Object Function: set_gravity
Usage: (set_gravity n)
Returns: Int
Use the set_gravity function to set the value of gravity in
the current function. It returns the new value of gravity.
;;------------------------------------------------------------------------
Object Function: set_hp
Usage: (set_hp n)
Returns: Int
Use the set_hp function to set the value of hp in
the current function. It returns the new value of hp.
;;------------------------------------------------------------------------
Object Function: set_light_x
Usage: (set_light_x light x)
Returns: dunno
Moves the light's x position to [x]. Make sure that you call this
function with an actual light object, not a number. That is, use
(set_light_x (get_light 0) 10), NOT (set_light_x 0 10).
;;------------------------------------------------------------------------
Object Function: set_light_y
Usage: (set_light_y light y)
Returns: dunno
Moves the light's y position to [y]. Make sure that you call this
function with an actual light object, not a number. That is, use
(set_light_y (get_light 0) 10), NOT (set_light_y 0 10).
;;------------------------------------------------------------------------
Function: set_lives
Usage: (set_lives player n)
Returns: dunno
Sets the number of lives a player has to [n]. Dunno how you take
away lives or anything like that...
;;------------------------------------------------------------------------
Object Function: set_otype
Usage: (set_otype obj_class)
Returns: dunno
(set_otype) will change the class of the object, I think. I'm
not sure if this will re-map all the member functions or what
not, but it seems pretty dangerous to me.
;;------------------------------------------------------------------------
Object Function: set_rand_on
Usage: (set_rand_on rand)
Returns: dunno
Not a clue. Looks like it might do something like seed a random
number generator, but I really have no clue.
;;------------------------------------------------------------------------
Object Function: set_sneaky_time
Usage: (set_sneaky_time n)
Returns: Int
Use the set_sneaky_time function to set the value of sneaky_time in
the current function. It returns the new value of sneaky_time.
;;------------------------------------------------------------------------
Object Function: set_state
Usage: (set_state n)
Returns: Int
Use the set_state function to set the value of state in
the current function. It returns the new value of state.
;;------------------------------------------------------------------------
Object Function: set_targetable
Usage: (set_targetable T)
Returns: T or nil
Determines whether or not this object can be targeted. I suppose that
only targetable creatures are affected by hurt_radius or the
find_object* functions.
;;------------------------------------------------------------------------
Object Function: set_visor_time
Usage: (set_visor_time n)
Returns: Int
Use the set_visor_time function to set the value of visor_time in
the current function. It returns the new value of visor_time.
;;------------------------------------------------------------------------
Object Function: set_x
Usage: (set_x n)
Returns: Int
Use the set_x function to set the value of x in
the current function. It returns the new value of x.
;;------------------------------------------------------------------------
Object Function: set_xacel
Usage: (set_xacel n)
Returns: Int
Use the set_xacel function to set the value of xacel in
the current function. It returns the new value of xacel.
;;------------------------------------------------------------------------
Object Function: set_xvel
Usage: (set_xvel n)
Returns: Int
Use the set_xvel function to set the value of xvel in
the current function. It returns the new value of xvel.
;;------------------------------------------------------------------------
Object Function: set_y
Usage: (set_y n)
Returns: Int
Use the set_y function to set the value of y in
the current function. It returns the new value of y.
;;------------------------------------------------------------------------
Object Function: set_yacel
Usage: (set_yacel n)
Returns: Int
Use the set_yacel function to set the value of yacel in
the current function. It returns the new value of yacel.
;;------------------------------------------------------------------------
Object Function: set_yvel
Usage: (set_yvel n)
Returns: Int
Use the set_yvel function to set the value of yvel in
the current function. It returns the new value of yvel.
;;------------------------------------------------------------------------
Object Function: shift_rand_table
Usage: (shift_rand_table n)
Returns: T or nil
Not a clue. Again, it looks like something to seed a random
number generator.
;;------------------------------------------------------------------------
Function: show_help
Usage: (show_help string)
Returns: dunno
Displays that little message across the top of the screen.
;;------------------------------------------------------------------------
Object Function: site_angle
Usage: (site_angle object)
Returns: target angle
Determines the angle from the current object to [object]. Essentially,
does the subtraction and atan2 for you, I suppose.
;;------------------------------------------------------------------------
Object Function: state
Usage: (state)
Returns: the object's current state
Picks out the state of the current object. Can be used with (aistate)
to figure out what to do in an ai_fun. For example, you might
say (if (eq (state) stopped) (blah) nil).
;;------------------------------------------------------------------------
Object Function: state_time
Usage: (state_time)
Returns: how long an object has been in this state
Use (state_time) to determine how long the current object has been
in this state. Cool when you want someone to stop for a while, I
guess.
;;------------------------------------------------------------------------
Object Function: tint_palette
Usage: (tint_palette r_ramp g_ramp b_ramp)
Returns: dunno
Tweaks the ENTIRE palette by ramping up the RGB values of all the
entries. What's more, the palette STAYS that way until you
make another call to tint_palette. You can get some neat effects
with this, if you try.
;;------------------------------------------------------------------------
Object Function: total_lights
Usage: (total_lights)
Returns: Number of lights
(total_lights) returns the number of lights linked to this object.
NOT the number of total lights in the world or other such nonsense.
;;------------------------------------------------------------------------
Object Function: total_objects
Usage: (total_objects)
Returns: Number of objects
Returns the total number of objects linked to the current object.
;;------------------------------------------------------------------------
Object Function: touching_bg
Usage: (touching_bg)
Returns: T or nil
Determines whether or not the current object's frame is overlapping
the nearest player's frame. Would be cool for a landmine object or
something.
;;------------------------------------------------------------------------
Object Function: toward
Usage: (toward)
Returns: -1 or +1
(toward) is short for (with_object (bg) (direction)).
;;------------------------------------------------------------------------
Object Function: try_move
Usage: (try_move x y)
Returns: blocked_flags?
I think try_move returns the blocked_flags you would have gotten had you
tried to call (move x y 0). I'm not entirely sure, though.
;;------------------------------------------------------------------------
Object Function: view_push_down
Usage: (view_push_down n)
Returns: dunno
Pushes the offset of the view down by [n] pixels? Is there a
view_push_up? view_push_left?
;;------------------------------------------------------------------------
Object Function: view_*
Usage: (view_x1), (view_y2), etc.
Returns: pixel position
* is either x1, x2, y1, y2. Returns the pixel coordinate of either
the upperleft or lowerright corner of the screen. Useful for dropping
images at absolute screen coordinates instead of game coordinates.
;;------------------------------------------------------------------------
Object Function: weapon_to_type
Usage: (weapon_to_type weapon-type)
Returns: type
Converts [weapon-type] back into the otype of the weapon. Is used
when you need to compare or set the otype based on a weapon's type.
;;------------------------------------------------------------------------
Object Function: with_obj0
Usage: (with_obj0 fun)
Returns: depends
Short for (with_object (get_object 0) fun)
;;------------------------------------------------------------------------
Object Function: with_object
Usage: (with_object obj-ptr fun)
Returns: depends
Performs function [fun] as if [obj-ptr] had called it. Using a C++
analogy, it's like calling obj_ptr->fun(). Used the most with
(get_object n).
;;------------------------------------------------------------------------
Object Function: x
Usage: (x)
Returns: x coordinate
Returns the x coordinate of the current object.
;;------------------------------------------------------------------------
Object Function: xacel
Usage: (xacel
Returns: x acceleration
Returns the xacel of the current object.
;;------------------------------------------------------------------------
Object Function: xvel
Usage: (xvel
Returns: x acceleration
Returns the xvel of the current object.
;;------------------------------------------------------------------------
Object Function: y
Usage: (y)
Returns: y coordinate
Returns the y coordinate of the current object.
;;------------------------------------------------------------------------
Object Function: yacel
Usage: (yacel
Returns: y acceleration
Returns the yacel of the current object.
;;------------------------------------------------------------------------
Object Function: yvel
Usage: (yvel
Returns: y acceleration
Returns the yvel of the current object.