0
///////////////////////////////////////////////////////////////////////////
// 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 ...................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
// 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 ...................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