PC/CD Gamer UK 16/PCGAMER16.bin/text/abuse.txt

Text File | 1995-11-29 | 18KB | 437 lines

Abuse Levels and the Abuse Engine


This document has been sabotaged by Ted at PC Gamer.
All acknowlegments to the author, and, of course, to Ruari, the ant
with attitude in Crack Dot Com's wunderfull game.

T O'Neill 29/11/95


Note : these docs are far from finished, have not been edit for spelling/correctness,
but I hope it's enough to get a few people started.  More docs/better will follow
later, but I'm busy with net code right now....

            - Jonathan Clark


  I would like to give a quick over-view of making games with the abuse engine.
  First reasons why you might want to give it a try.

    - You can get the shareware version for free and develop at no cost.

    - Any code you write is portable and needs no compilation to run on
        other systems.   Currently the engine has been ported to DOS, LINUX!,
        and SGI.  Other UNIX ports are expected and Mac and WIN '95 are being
        considered.
    - Network code which can be a big pain is already built in.  You can
        make a simple working network game in a day or two.  The engine
        currently supports IPX and TCPIP but will soon have support for modem
        and other network drivers.
    - If the game is fair Crack dot com will include it on their next data
        pack CD and pay you according to it's quality,  but If it 'great' to
        'cool' Crack will market and distribute it individually and pay you
        a percentage of the profits.
    - It's fun, why else?

  Getting started :

      Firstly you should get a copy of Satan Paint, a free program which
    can be found at ftp.island.net (I think).  If you do not
    have internet access then you are currently out of luck.  Satan Paint
    was used in the making of Abuse mainly as a conversion utility, but
    also has some features to assist in graphics creation.  There are
    several data types the abuse engine supports, all outlined in spaint
    docs.

    Spaint is capable of creating all of these except WAV files and
    particle animations.


      Images
    spaint name : image
        simple bitmaps with no other data.
    loaded with (def_image "filename" "image_name")
    displayed with (put_image screen_x screen_y image_id)
    see also : image_width, image_height

      Background tiles
    spaint name : backtile
    loaded with (load_tiles "filename")
    all data items in filename with of type 'backtile' will be loaded
        these tiles should be named with a number prefixing the name
         i.e.  20 red brick
        abuse takes the number and inserts the tile into an array at this offset.
    (bg_tile x_map_location y_map_location) returns this number
        (set_bg_tile x_loc y_loc value) sets this value

      Foreground tiles
    spaint name : foretile
    loaded with (load_tiles "filename")
    all data items in filename with of type 'foretile' will be loaded
        these tiles should be named with a number prefixing the name
         i.e.  25 my foretile
    foretiles can have a 'frame' (as referred to in spaint) which blocks.
    The player and other objects in the game will not be able to pass through
        this area with calls like tick, move, bmove, & can_see.

      Character frames
    spaint name : character (displayed as character2)
    loaded with def_char (explained later)
    characters frames have
           - x center of gravity     (spaint name xcfg)
           - frame advancement       (spaint name advance)
           - attack polygon          (spaint name attack)
           - damage polygon.         (spaint name damage)


      The x center of gravity
        is used to for the object's X position in the game.  i.e. The
        character's X position will correspond with the center of gravity
        line. The character's Y position is always taken from then bottom
        of the character.  Frame advancement indicates how many pixels
        the character will move after the frame is played.  If the character's
    direction>0
        the character will move right according to the frame advancement,
        and if the direction<0 then the character will move left.  The
        attack polygon will incur damage on any other character's damage
        polygon if the other character has the hurtable flags set in it's
        character definition.  When damage occurs the character just hurt will
        have it's damage_fun called (see def_char).

      Particle animation
     can only be made with a particle animator that has not yet been released.
     (perhaps some-day... it's not finished)
     loaded with def_particle

      WAV files
    should be sampled at 11025 Hz mono.  We may add support for
        stereo and variable sample speed later.
    loaded with (def_sound "filename")
    played with (play_sound sound_id volume x y)
    The x & y are used for distance queuing and if we add stereo or
        support for 3d sound cards these numbers will also be used.

      Palettes
    are simply the typical 768 bytes stored RGB RGB...  Spaint
        will do this automatically save one with every file.
    loaded with (load_palette "filename"), only one per game

    palettes can also be loaded as tints in abuse,  the abuse engine
        takes each color of the new palette and finds the closest color
        in the abuse palette to create a remapping filter.
    loaded with (def_tint "filename")
    see also : draw_tint, draw_double_tint

      Color filters
        5 bit RGB lookup tables.  This will be saved in
        a file with spaint if the calc_filter command is executed before saving.
    This filter is need to do effects like transparency and give the LISP
    programmer virtualized RGB access via (find_rgb r g b).
        loaded with (load_color_filter "filename"),  if you use your own custom
        palette you will need to calculate a new color filter with spaint.
        One one color (and exactly one) color filter should be loaded per game.






def_char reference
  def_char is the most complicated function in abuse, and also the most used.

  here's a simple example of def_char

  (def_char CONC
    (funs (ai_fun  mine_ai))
    (fields  ("xvel" "flash [1=on]"))
    (states "art/chars/mine.spe"
        (running   (seq "mine" 1 8))
            (stopped    '("mine0001.pcx" "mine_off"))))


  The first parameter of def_char should be the symbol name of the object.
  This name will be used by the level editor in the objects list.  This value of
  this symbol will also be assigned a character_handle.


  Lisp> (print CONC)
  25


  the next parameter to def_char is arbitrary, but it must be a list and the
  first object in the list must be one of the following :

    funs, abilities,  flags, range, draw_range, fields, logo, vars, or states,


  I. funs
     Following funs should be a list o function types and function
  value pairs.  The following function types are currently defined :

    ai_fun - this is called with no parameter for every object for each
             game tick.  Order of object ai_fun execution goes from back to
             front (as does order for draw_fun).
             This function must return nil or non-nil.  Nil means *delete me*
             and non-nil means keep going.  An object's ai_fun will not be executed
             unless it is in range of a player view (see range).


    move_fun - this is called for player object and has three parameters
             (xv yv but) which indicate the status of the player's input
             but is a bit mask of buttons and you should call bit-and to
         see if a specific button is being pressed.

    constructor - this is called whenever an object is created for the
             first time.  It is a good place to initialize object variable.
             This is not called upon loading and object from disk.
         no parameters are passed to the constructor.

    draw_fun - this is called when and object to displayed on screen.
             it can call things like
                draw, draw_above, draw_line, draw_transparent, draw_tint,
            draw_double_tint, draw_predator, scatter_line, ascatter_line,
            put_image or even play_sound.
         Since a draw_fun for an object may be executed on one computer in
             a networked game and not on others, it is very important that it
             does not change any variables or the state of the game at all.  i.e.
             it can only do drawling stuff, but cannot create new characters,
         set global variables, or even do a (next_picture).

    next_state_fun - this is called when an object animation sequence ends
             from within (next_picture), this function takes no parameters
         and it's return is ignored.


    user_fun - this function is not called by abuse but reserved for the user.
             it can be used to achieve a minimal OOP system for objects.  This
             function is invoked by (user_fun) and the number of parameters must
         match your definition of this function.


    reload_fun - this is called when an object is loaded from disk.
             this can be used to correct general traits of a character.
         this is the only place where (lower) and (raise) may be called.
         If you created an object which you want always to be under all other
             characters, you should give it a reload_fun which calls (lower).
         this function has no parameters and return is ignored.


    get_cache_list_fun - this function is also called while a level is loading,
         but the return must be in a specific format.  specifically this return
         should be :
              (list (list character_id1 character_id2) (list other_id1 other_id2))
         the character_id list should be the id's of characters that are likely to
         accessed within the level.  i.e. (CLOUD SPRAY_GUN)
         The other_id's applies to any other data object which will be needed during
         the level.  This includes sound effects, tints, images & particle animations.

           The game will load as much of these as it can before starting the level.
         To improve game performance even more you should use the Cache profile options
             from the edit menu in the game.


    type_change_fun - this function is called whenever the objects "aitype" variable
             is changed.  This change can occur because a) (set_aitype) is called, or
             b) it is edited by the level designer.  The b option allows a simple, but
         usefull interface between the object and the level editor since on all objects
         pressing the keys 0..9, SHIFT 0..9 will change the objects aitype and thus
         call type_change_fun if it exist.  This is how AMBIENT_SOUND works.




 II. abilities
    these are character type variables that can be accessed via
    (get_ability)

      start_hp - used to set an objects (hp) when it is first created

      walk_top_speed - looked at by the (move) function to determine how
    far to move the character every frame.

      ** these are not useful or not used, but I'll list them for fun :) **
      start_accel, stop_accel, jump_xvel, jump_yvel, run_top_speed,
      jump_top_speed, tint_color, push_xrange,
      example : (abilities (start_hp 200))


  III. flags
     all flags default to false, if a flag is not listed then it is assumed false


     is_weapon - indicates this object should be allocated a spot on the status bar
     hurtable - if an obect can be hurt by other objects
     unlistable - if an object will appear in the object listing window.
     add_front - when an object is created it will place in front of other object
     unactive_shield - if object is hit by shotgun bullet and this flag is set and
       the object is not actiavted, it will not be hurt.
     example : (flags (unlistable T) (add_front T))


  IV. range
     (X_range Y_range)
     specifies how far off-screen an object can be and still be processed.
     example : (range 50 50)


  V, draw_range
     (X_range Y_range)
     specifies how far off-screen an object can be and still be drawn.
     example : (draw_range 50 50)

  VI. fields
      following this should follow a list of (actual_name show_name)
    where actual_name can be one of the following :
                        "fade_dir",
                "frame_dir",
                "direction",
                "gravity_on",
                "fade_count",
                "fade_max",
                "active",
                "flags",
                "aitype",
                "xvel",
                "fxvel",
                "yvel",
                "fyvel",
                "xacel",
                "fxacel",
                "yacel",
                "fyacel",
                "x",
                "fx",
                "y",
                "fy",
                "hp",
                "mp",
                "fmp",
                "cur_frame",
                "aistate",
                "aistate_time",
                "targetable"
          or any of the variables declared in vars

        show_name can be any string and is what will be displayed
        in the level editor under the ai window.
    example : (fields ("hp" "health points")
                      ("fade_count" "faded amount (0-15)"))


  VII. vars
      a list of variable names that get allocated to each object of this
      type, these variables are also loaded and saved with each level.
      The variables are restricted to integers however.
         You may get some complaints from the compiler if different classes
      have the same variable names.  To fix this reorder the compilitation
      order of the objects or rename the variables.

      example : (var time1 time2)


  VIII. states
      An object is always in one animation state.  This section defines
      the animation states for an object.  Each animation state listed
      will be assigned a state number.  The first object of the state list
      must be the file name where the animations are located.  Following
      that should be a list of (state (frame_list)) pairs.

      example :
        (states "art/cop.spe"
            (stopped            (seq "stopped" 1 6))
        (running            (seq "4wlk" 1 10)))

      The seq command creates a list of names such as
        "4wlk0001.pcx" "4wlk0002.pcx" ....

      The seq command is defined in lisp/common.lsp

      An object can set it's animation state with (set_state), and
      once in a animation state it can change animation frames with
      (next_picture) or access the current_frame variable directly with
      (current_frame) and (set_current_frame).  An object can ask what
      animation state it is in with (state).

      Every object must have a 'stopped' state defined.  This is the
      state it will be placed in when it is first created.

      States need not use the seq command, but frames can be listed manually.

      example (states "art/cop.spe"
                 (stopped   '("frame1" "frame2" "frame3" "frame4"))
                 (running   '("rframe1" "rframe2" "rframe3" "rframe4")))

      A frame may be referenced from another file than the one listed after "states".

      example (states "art/cop.spe"
             (stopped   '(  ("art/newfile.spe" . "frame1") "frame2" "frame3")))

      All animation frames of a character are automatically cached in when a level
      containing the character is loaded or the character was refrenced via a get_cache_list
      function.


Ok. I've covered most of def_char, let's do an example of actually making a character for
  abuse.  This example will show how to make a DIFFICULTY_SENSOR.  The difficulty sensor
  turns on if the player is playing on a set difficulty.  In general object use the "aistate"
  variable to indicate weither they are on or off.  aistate==0 means off, aistate<>0 means on.

;; this addon must be loaded by other addons by
;; (if (not (load "addon/diffsens/diffsens.lsp"))
;;    (progn (print ("This package requires the diffsens addon"))
;;           (quit)))

(def_char DIFFICULTY_SENSOR         ; name of objetc
  (funs (ai_fun diff_sensor_ai)    ; name of function listed below
    (draw_fun dev_draw))       ; dev_draw only draws when in edit mode
                                      ; this makes the object invisible while playing

  ; this section provides the interface to the level editor
  (fields ("xvel"  "easy on?    (1=yes, 0=no)") ; recycle variables already defined
      ("yvel"  "meduim on?  (1=yes, 0=no)")
      ("xacel" "hard on?    (1=yes, 0=no)")
      ("yacel" "extreme on? (1=yes, 0=no)"))


  ; this section defines the "visible" part of the object
  ; we define two states to aid the level designer in telling if the object is on or off
  (states "addon/diffsens/diffsens.spe"  ; filename where state artwork is located
     (stopped "off")                        ; we will use this as the off state
     (on_state "on")))


(defun diff_sensor_ai ()            ; no parameters to this function

  (set_state stopped)              ; set animation state to off
  (set_aistate 0)                  ; set aistate to off

  (select difficulty               ; this is set by abuse
      ('easy (if (eq (xvel) 1)
             (progn
               (set_aistate 1)           ; set aistate to on
               (set_state on_state))))   ; set animation state to on
      ('medium (if (eq (yvel) 1)
               (progn
             (set_aistate 1)
             (set_state on_state))))
      ('hard (if (eq (xacel) 1)
             (progn
               (set_aistate 1)
               (set_state on_state))))
      ('extreme (if (eq (yacel) 1)
            (progn
              (set_aistate 1)
              (set_state on_state)))))

  T)    ; return true so that we are not deleted