CONQINIT, the Unrated Edition.


CONTENTS:

  ## OVERVIEW
  ## conqinitrc
     ## global
     ## shiptype
     ## planet
  ## texturesrc or user .trc files
     ## texture
     ## animation
     ## animdef
        # istate subsection
        # texanim subsection
        # colanim subsection
        # geoanim subsection
        # toganim subsection
  ## soundrc or user .src files
     ## soundconf 
     ## music
     ## effect
  ## conqinit utility
  ## example of a user overriding a system defined texture.
     # overriding a texture image
     # overriding a texture definition
  ## conquest's texture format


## OVERVIEW

       This document describes the 'conqinit' (CQI)
       parser/configurator used in Conquest as of 8.1.2a (devel), as
       well as the format of the new configuration files (conqinitrc,
       texturesrc, and soundrc).

       CQI is a lex/yacc parser that reads certain configuration files
       and builds up an internal, validated representation of the data
       contained therein.

       This document is intended for developers, or those who want to
       modify the characteristics of their conquest experience :) 

       If you are not interested in any of that, there is probably no
       point in reading further :)

       CQI data is currently used to represent the following
       information in Conquest:

       - planet data (name, size, type, team, etc).  Used for
         initializing the Planets in the common block. 
       - texture data (Well Known Name (WKN)), 
         filename, color).  Used for texture drawing.
       - animation data (WKN, animdef).  Drawing. 
       - animdef data (name, animation characteristics).  Drawing.
       - sound data (name, music/effect configuration, files, limits,
         etc).

       A detailed description of each of these is given below.

       Currently, CQI can be used to parse these types of files:

         - <prefix>/etc/conqinitrc 

           file that decribes certain characteristics of the game,
           such as how many ships can play, detailed descriptions of
           each of the planets, and other related data.  The format of
           the sections in the conqinitrc file will be described
           below.

         - <prefix>/etc/texturesrc
         - ~/.conquest/*.trc

           These files describe the characteristics of textures,
           colors, animations, and animdefs used by conquestgl for
           rendering.


         - <prefix>/etc/soundrc
         - ~/.conquest/*.src

           These files describe the characteristics of sound
           configuration, effect definitions, and music definitions


       The general syntax of a section entry in these files is as
       follows:

           sectionname {
              variable  value
              ...
           }

           Comments are preceded by a '#' character.
           # like this

       The types of <value> depend on the variable being defined.
       Currently, the following types are supported:

              Type   Valid Values
           --------  ------------

           STRING:   "some characters" enclosed in double quotes
           BOOL:     STRING equal to: "yes", "no", "on", or "off"
           NUMBER:   any valid integer value
           RATIONAL: any valid floating point value
           COLOR:    STRING equal to a 32b hex value: "ffabcdef"
                     in AARRGGBB format (8 bits per component).

       In the descriptions below, these types will be referenced.


## conqinitrc

       The conqinitrc file is used to specify the global, shiptype,
       and planet information used in conquest.

       These are the valid sections that can appear in the conqinitrc
       file.

       ## global

          The global section describe the various limits for
          conquest.  Currently, you should never change this, until
          the common block (and therefore compatibility) is changed to
          support them.  For now, leave these alone :).  

          global {
            planetmax 60
            shipmax   20
            usermax   500
            histmax   40
            msgmax    60
          }

          planetmax:  NUMBER
                      specifies the maximum number of planets in the
                      universe. 


          shipmax:    NUMBER
                      specifies the maximum number of ships that can
                      play. 

          usermax:    NUMBER
                      specifies the maximum number of users the game
                      can handle (and store stats for).

          histmax:    NUMBER
                      specifies the maximum number of history entries
                      that can be stored.  Maybe not useful?

          msgmax:     NUMBER
                      The maximum number of message slots available.
          

       ## shiptype

          The shiptype sections are currently ignored.  They could be
          used someday to allow the creation of new shiptypes with
          differing characteristics.

          shiptype {
            name       "Destroyer"
            engfac     1.000000
            weafac     1.000000
            accelfac   1.000000
            torpwarp   12
            warpmax    9
            armymax    9
            shmax      100
            dammax     100
            torpmax    9
            fuelmax    999
          }

          name:       STRING
                      specifies the name of the shiptype.

          engfac:     RATIONAL
                      engine mult factor

          weafac:     RATIONAL
                      weapon mult factor

          accelfac:   RATIONAL
                      acceleration mult factor

          torpwarp:   NUMBER
                      speed of the ship's torpedos

          warpmax:    NUMBER
                      maximum speed of the ship

          armymax:    NUMBER
                      maximum number of armies that can be carried by
                      the ship

          shmax:      NUMBER
                      maximum shield strength

          dammax:     NUMBER
                      maximum damage before exploding

          torpmax:    NUMBER
                      maximum number of torps a ship can carry/fire

          fuelmax:    NUMBER
                      maximum fuel that can be carried


       ## planet

          The planet sections are used to describe all of the planets
          and their characteristics in conquest.  This data is used to
          initialize conquest's planet list on a game reset.  This
          should allow budding universe builders alot of freedom.
          Even more when the common block has been changed (in a
          future release) to support things like colors, size, etc.

          planet {
            name        "Klingus"
            primary     "Kejela"
            angle       136.215891
            velocity    -7.284646
            radius      2600.000000
            ptype       "M"
            pteam       "K"
            armies      50
            visible     "yes"
            core        "yes"
            homeplanet  "yes"
            x          -9655.250220
            y          9577.226313
            size        300
            color       "ffe6e6e6"
            texname     "kling"                  # optional
          }

          name:       STRING
                      the name of the planet

          primary:    STRING
                      The name of the body this planet orbits.  If set
                      to be the same as the planet's name, then the
                      planet is marked as not orbiting anything
                      (stationary).  The default is Murisak.

          angle:      RATIONAL
                      The starting angle of the planet relative to
                      it's primary.  If the angle is negative, a
                      random angle is chosen when the planet is
                      initialized. 

          velocity:   RATIONAL
                      The velocity of the planet in degrees per
                      minute.  A positive number has the planet orbit
                      it's primary counterclockwise, while negative
                      orbits clockwise.

          radius:     RATIONAL
                      The distance of the planet from it's primary (in
                      Conquest Units (CU)).
                      
          ptype:      STRING
                      The planet type.  Valid values are:
                      "M"               Class M (fuel)
                      "D"               Class D (dead)
                      "S"               Sun
                      "m"               Moon
                      "G"               Ghost
                      "A"               Class A
                      "O"               Class O
                      "Z"               Class Z

          pteam:      STRING
                      The planet's team.  Valid values are:
                      "F"               Federation
                      "R"               Romulan
                      "K"               Klingon
                      "O"               Orion
                      "S"               Self Ruled
                      "N"               No Team (non)
                      "G"               God
                      "E"               Empire

          armies:     NUMBER, NUMBER PAIR
                      specifies the number of armies put on the planet
                      at init time.  The value can be a single NUMBER,
                      or a pair of NUMBERs.

                      armies  20     
                              20 armies placed on planet

                      armies  80 180
                              a random number of armies, between 80
                              and 180, placed on the planet.  This
                              form is typically used for suns where
                              you want it's 'damage potential' to vary
                              randomly with each new game.

          visible:    BOOL
                      whether the planet is visible

          core:       BOOL
                      wether the planet must be taken in order to
                      conquer the universe.  This value has no meaning
                      currently, as this is hardcoded into the game.
                      When the common block is reworked, this value
                      will actually mean something :)

          homeplanet: BOOL
                      whether this planet is one of the owner team's
                      homeplanets. This value has no meaning
                      currently, as this is hardcoded into the game.
                      When the common block is reworked, this value
                      will actually mean something.

                      Currently, you must ensure that 3, and only 3
                      planets are marked as a 'homeplanet' for each of
                      the player teams (f, k, r, and o).

          x:          RATIONAL
                      starting x coordinate of the planet's location.
                      This value is ignored if the planet is not
                      stationary. 

          y:          RATIONAL
                      starting y coordinate of the planet's location.
                      This value is ignored if the planet is not
                      stationary. 

          size:       NUMBER
                      size of the planet in CU's.  This only matters
                      to the gl client for now.  In the future, this
                      value will be stored with the planet into the
                      common block, and propagated out to clients.

          color:      COLOR
                      the desired base color of the planet.  This only
                      matters to the gl client for now.  In the
                      future, this value will be stored with the
                      planet into the common block, and propagated out
                      to clients.

          texname:    STRING
                      optional.  Explicitly specifies the texture to
                      be used to draw the planet.  In general this
                      option should not be used for planet definitions.  


       Currently in conquestgl, the following steps are made to
       determine the proper texture to use to display a planet:

       1. see if one was specified in the conqinitrc entry for
          the planet, if so, use it.  This should usually not be done
          except in special cases.

       2. see if a texture exists with the same name (case sensitive)
          as the planet, if so use it.

       3. if all else fails, use the default textures 'classm',
          classd', 'star' etc.

       So in general, you never really need to specify a texture for a
       planet in conqinitrc.  If you want a specific texture to be
       displayed for a planet, just create a texture definition with
       the same name as the planet and add an entry for it in the
       texturesrc (or a user .trc) file.


## texturesrc or user .trc files

       These files contain sections that describe each of the
       texture, animation, and animdef's used in conquestgl.

       A texture section specifies a texture by a Well Known Name (WKN),
       the base filename that contains the image data used to draw the
       texture, and the base color of the texture.  If the filename of
       a texture is equal to "", then this indicates that only a color
       is described therein (no texture image data is used).

       Users can override the system's texture definitions (defined in
       <prefix>/etc/texturesrc).  After conquestgl parses the main
       texturesrc file, it will then load and parse any *.trc files it
       finds in your ~/.conquest/ directory.  These files have the
       same format as texturesrc.  Texture image (TGA) files can be
       provided in a user's ~/.conquest/img/ directory, which will
       also be searched when texture loading starts.  This allows
       users to override the games textures if they wish.

       The ability for a user to create his/her own .trc files and
       supply their own texture images (TGA) allows them to modify or
       override the system entries as they prefer.  Much better than
       having to hack the src code :)

       Most of these sections have a Well Known Name (WKN) that
       'labels' the entry.  These labels are used by conquest to look
       up the information they contain.  For example, to find out the
       texture and color used for the generic 'torpedo' texture,
       conquest will look up the WKN 'torp' in the texture list and
       use it's data to draw one.

       The WKN of an entry should never be changed, as these are
       hard-coded into conquest.  The other data related to a WKN can
       of course be modified. 

       The following provides a detailed description of the valid
       texturesrc sections that can appear in the global texturesrc
       file or a user's ~/.conquest/*.trc files.   

       ## texture

          A texture section specifies the characteristics of a
          texture (or color) to conquest by it's WKN.

          texture {
            name         "conqlogoF"
            filename     "conq-fed"              # optional
            color        "ffe6e6e6"              # optional

            texarea {                            # optional
              name       "somerect_in_texture"
              x          10.0
              y          10.0
              w          10.0
              h          10.0
            }
          }
     
          name:       STRING
                      the WKN of the texture.  In the above example,
                      this texture refers the the conquest logo for
                      Federation players, and is composed of the word
                      'conqlogo' followed by the first (case
                      sensitive) character of the team.  This is what
                      conquestgl will use when looking for the
                      Federation Conquest Logo texture.

          filename:   STRING
                      optional.  This field specifies the base name of
                      the texture file that contains the texture image
                      data (without an extension).  In the above
                      example, conquest will look for and load a
                      texture image file called 'conq-fed.tga' in the
                      texture image directory(s).

                      If the filename is specified as "", then this
                      indicates that there is no image data associated
                      with this texture, and that only a color is
                      stored there.

                      If the filename is not specified at all, then
                      the default is to use the same name as 'name'
                      when loading the texture.

          color:      COLOR
                      optional. Specifies the base color of the
                      texture used when it is rendered.  If not
                      specified, the default depends on how the
                      texture is being used in conquest.

          texarea:    SUBSECTION
                      optional. A texarea subsection is used to
                      describe a named rectangle within the texture.
                      These can be looked up by the gme and used to
                      describe and position areas within a texture.

                      The x, y, w, and h parameters describe a
                      rectangle within the texture.

                      The decal textures use these to describe the
                      locations within the texture of where the fuel
                      gauge scale, for example, is positioned.

                      The above texture section example does not need
                      a texarea section - it is provided for
                      documentation/example purposes.


       ## animation

          An animation section is used to provide a WKN to conquest
          for a given animation, and to specify the 'animdef' to be
          used to render the animation, based on it's current 'state'.
          This provides the ability to have several animations use the
          same 'animdef'.

          animation {
            name         "explosion"
            animdef      "explode"               # optional
          }

          name:       STRING
                      the WKN of the animation.  In the above example,
                      this animation refers to the animation that is
                      used when something is exploding.  

          animdef:    STRING
                      optional. Specifies the name of the animdef
                      section to use for this animation.  In this
                      example, an animdef named 'explode' will be used
                      to modify the animation's state.

                      If 'animdef' is not specified, then the default
                      is to look for an animdef with the same WKN of
                      the animation section.

       ## animdef

          An animdef section is used to describe the specific
          characteristics of how to 'run' an animation.  It is
          composed of base data, and one or more nested animation
          types, for each animation type supported.  

          Animdefs are 'compiled' at parse time and represent a series
          of operations to perform on a programmer specified animation
          'state' within conquest at defined intervals.  Animation
          drawing states are used throughout conquestgl to draw
          explosions, torpedo's, and several other things.

          An animation drawing 'state' in conquest is defined as a
          structure that contains the following variables:

          id                              - current texture id
          s, t                            - texture S and T coordinate
                                            offset (defaults to S=0.0
                                            and T=0.0) 
          color (ARGB)                    - current color
          geometry (size, rotation, x, y) - current geo info
          armed                           - current toggle value (on/off)

          An animdef is soley responsible for defining how these
          values will be modified as the animation is 'executed'.
          Which elements of the animation state that are actually
          modified also depends entirely on the animdef specification.

          Each animdef can contain specifications for up to 4
          different animation types that can be executed to change
          the various components of it's relevant 'state'.  The 4
          types are:

          texanim:     Specifies parameters for a texture
                       animation. Modifies state's 'id' and 'color'
                       values.  If deltas and deltat
                       offsets/incrementors are present, modifies
                       texture's S and T coordinates.

          colanim:     Specifies parameters for a color animation.
                       Modfies the state's 'color' values.
                       colanim's can only run if no texanim is
                       currently executing.  

          geoanim:     Specifies parameters for a geometry animation.
                       Modfies the state's 'geometry' values.
                       geoanim's can only run if no texanim is
                       currently executing.

          toganim:     Specifies parameters for a toggle (on/off)
                       animation.  Modfies the state's 'armed' value.


          When these animations expire, their state is automatically
          removed from the animator's run que.  It's important that
          you ensure that any animations that conquest is expecting to
          expire at some future point, actually do expire at some
          future point :).

          Here is an example of the most complicated animdef currently
          provided.  Although this example incorporates components
          that are not really used for the 'explode' animdef, all
          possible options are listed here anyway for compleness and
          documentation purposes.  


          animdef {
            name         "explode"
            texname      "exp"                   # semi-optional
            timelimit    3000                    # optional

            # initial state
            istate {                             # optional
              size       450         # in CU's   # optional
              angle      -1.0        # random    # optional
            }
    
            texanim {                            # optional
              stages     16 
              loops      1                       # optional
              delayms    100                     
              deltas     0.02                    # optional
              deltat     0.02                    # optional
            }

            # this runs when texanim has expired
            colanim {                            # optional
              stages     10                      
              loops      1                       # optional
              delayms    80
    
              deltaa     -0.1                    # optional
              deltar     0.0                     # optional
              deltag     -0.001                  # optional
              deltab     -0.01                   # optional
            }

            # this runs when texanim has expired
            geoanim {                            # optional
              stages     10
              loops      1                       # optional
              delayms    100

              deltas     10.0                    # optional (in CU's)
            }

            toganim {                            # optional
              delayms    250
            }
          } 

          name:       STRING
                      the name of the animdef, referenced by the WKN
                      of an 'animation' section as described earlier.

          texname:    STRING 
                      semi-optional.  Specifies the WKN of a texture
                      to use in the default anim state (ie: when an
                      animation state is first initialized).  If a
                      texanim section is specified, then this field is
                      required.

                      If the animdef specifies a texanim, then this
                      name is used to look up the textures for each of
                      the stages in the texanim, by concatenating the
                      stage number onto the texname. In the example
                      above, the texanim will look for and use,
                      WKN textures named 'exp0', 'exp1', ..., 'exp15',
                      since there are 16 stages defined for the
                      texanim.

          timelimit   NUMBER 
                      optional.  Specifies the maximum time in
                      milliseconds this animdef should run on a state.
                      When the timelimit expires, all animation types
                      making up the animdef are expired for the state
                      regardless of their own defined parameters.

          # istate subsection

            optional.  This subsection is provided to allow you to
            specify certain 'starting' conditions to be used when an 
            animation state is reset for a run.

            size:       NUMBER
                        optional.  Allows you to specify the initial
                        value of the 'size' anim state variable when the
                        animation is reset for a run.  Value is in
                        CU's.  

            angle:      RATIONAL 
                        optional.  Allows you to specify the initial
                        value of the 'angle' anim state variable when the
                        animation is reset for a run.  

                        If a negative value is specified as the angle,
                        then a random angle will be chosen every time
                        the anim state is reset for a run.

          # texanim subsection

            optional.  This subsection is used to describe the
            charactistics of a texture animation type.  A texture
            animation is a sequence of textures, displayed in
            ascending order at a given time interval. The number of
            textures displayed depends on the 'stages' field of the
            texanim definition.

            stages:     NUMBER
                        a non-zero number specifying the number of
                        individual textures that make up the texanim.

            loops:      NUMBER
                        optional.  defaults to 1.  Specifies how many
                        times to to display all of the textures.  In
                        the above example, the 16 textures are
                        displayed only once, in the sequence 'exp0',
                        'exp1', ..., 'exp15', and then the texanim is
                        expired.

            delayms:    NUMBER
                        The delay, in milliseconds, before advancing
                        onto the next stage.
                    
            deltas:     RATIONAL
                        Specify an offset to be applied to the texture
                        state's S coordinate variable.

            deltat:     RATIONAL
                        Specify an offset to be applied to the texture
                        state's T coordinate variable.


          # colanim subsection

            optional.  This subsection is used to describe a 'color'
            animation type.  A color animation is used to modify 1 or
            more of the Alpha (A), Red (R), Green (G), and/or Blue (B)
            channels of the animdef's color anim state at predefined
            time intervals.  

            If a texanim was specified as part of the animdef, then a
            color anim will not run until it (the texanim) has
            expired. 

            All resulting color channels (ARGB) are clamped to a value
            between 0.0 (black) to 1.0 (white) before being placed in
            the anim's active color state.  For alpha, the values are
            clamped to 0.0 (fully transparent) to 1.0 (fully opaque).

            stages:     NUMBER
                        a number specifying the number of iterations
                        to perform.  If set equal to 0, then the
                        colanim will run forever.  Generally you will
                        never want to do this.

            loops:      NUMBER
                        optional.  defaults to 1.  If equal to 0, loop
                        'stages' forever.  Generally you will never
                        want to do this.

            delayms:    NUMBER
                        The delay, in milliseconds, before advancing
                        onto the next stage.
                    
            deltaa:     RATIONAL
                        optional.  delta to apply to the anim state's
                        alpha color channel per stage iteration.
                    
            deltar:     RATIONAL
                        optional.  delta to apply to the anim state's
                        red color channel per stage iteration.
                    
            deltag:     RATIONAL
                        optional.  delta to apply to the anim state's
                        green color channel per stage iteration.
                    
            deltab:     RATIONAL
                        optional.  delta to apply to the anim state's
                        blue color channel per stage iteration.
                    

          # geoanim subsection

            optional.  This subsection is used to describe a 'geometry'
            animation type.  A geometry animation modifies the
            geometry values in the anim's state by applying a
            specified delta to a geometry component at a specified
            interval.

            If a texanim was specified as part of the animdef, then a
            geometry anim will not run until it (the texanim) has
            expired.

            The current geometry state includes X/Y coordinates,
            rotation, and size.  These state variables are modified
            according to the deltas supplied.

            stages:     NUMBER
                        a number specifying the number of iterations
                        to perform.  If set equal to 0, then the
                        geoanim will run forever.  Generally you will
                        never want to do this.

            loops:      NUMBER
                        optional.  defaults to 1.  If equal to 0, loop
                        'stages' forever.  Generally you will never
                        want to do this.

            delayms:    NUMBER
                        The delay, in milliseconds, before advancing
                        onto the next stage.
                    
            deltax:     RATIONAL
                        optional.  delta to apply to the anim state's
                        X geometry variable per stage iteration.

            deltay:     RATIONAL
                        optional.  delta to apply to the anim state's
                        Y geometry variable per stage iteration.

            deltas:     RATIONAL
                        optional.  In CU's. delta to apply to the anim
                        state's size geometry variable per stage iteration.

            deltar:     RATIONAL
                        optional.  delta to apply to the anim state's
                        rotation geometry variable per stage iteration.


          # toganim subsection

            optional.  This subsection is used to describe a 'toggle'
            animation type.  A toggle animation simply toggles the
            animation state's 'armed' variable on or off at a specified
            time interval.  

            An animdef composed solely of a toganim always runs
            forever (it never expires).  These types of animdefs are
            refered to as 'blinker' anims in conquest, and are used
            for things like blinking the "SELF DESTRUCT IN XX" message
            in conquestgl.

            A toganim combined with another animation type will expire
            as soon as all other specified animation types have expired.

            delayms:    NUMBER
                        The delay, in milliseconds, before toggling
                        the state's 'armed' variable.


## soundrc or user .src files

      These files contain basic sound configuration support (fx
      channels, samplerate, etc), definitions for sound effects
      (phaser firing, explosions, etc), and music definitions. 

      Music definitions and music files are not supplied in the
      conquest src tarball due to their size.  They are supplied in a
      seperate 'music pak' tarball that must be unpacked in your
      ~/.conquest/ directory.  I recommend it for the full experience
      :) 

      Users can override the system's sound definitions (defined in
      <prefix>/etc/soundrc and <prefix>/etc/*.src).  After conquestgl
      parses the main soundrc file, it will then load and parse any
      *.src files it finds in your ~/.conquest/ directory.  These
      files have the same format as soundrc.  Sound files (.wav or
      .ogg) can be provided in a user's ~/.conquest/sound/ directory,
      which will also be searched when sound loading starts.  This
      allows users to override the games sounds if they wish.

      Like textures, sound effects and music are known by a Well
      Known Name (WKN) that is hardcoded into conquest.  The WKN's
      should never be modified, however any data associated with them
      can be overridden by the user or the operator.
      
      So, without further ado, here are the valid sections that can be
      present in a soundrc file.  In each section, all possible
      variables and their values will be shown.

      ## soundconf

         A soundconf section specifies certain parameters for the SDL
         mixer API, which is used to provide sound.  Feel free to
         change these if you'd like, though the defaults should be
         ok on most modern systems. 

         soundconf {
           samplerate   44100
           stereo       "yes"
           fxchannels   16
           chunksize    512        # low latency
         }

         samplerate:  NUMBER
                      The specified the samplerate the mixer will
                      use. If you have a slow processor (but a decent
                      sound card that can resample in hw) try 22050 to
                      reduce CPU requirements somewhat.

         stereo:      BOOL
                      Indicates whether to use stereo or not.

         fxchannels:  NUMBER
                      The number of channels to allocate for the
                      effects pool.  This is a decent number.  I doubt
                      you would need more than this.

         chunksize:   NUMBER 
                      This value determines the chunksize the mixer
                      will use.  A slow CPU might need a larger
                      chunksize, but will intorduce latency.  256 is
                      the minimum, 8192 is the maximum.  512 (the
                      default) is a good balance for low latency.


      ## effect
      ## music

         The effect section describes an effect for conquest.  Effects
         include engine rumble, phasers, explosions, beaming, bombing,
         etc... Effects can be modified or overriden by user in a .src
         file. 

         Effect and Music files have the same information associated
         with them, so we will only use an effect section below to
         describe it's parts.  A music definition look the same,
         though some options probably do not make sense for music.  A
         music section for the intro music is shown below.

         music {
           name         "intro"  
           filename     "TOS-intro"

           fadeinms     0
           fadeoutms    1000
           loops        1
         }

         effect {
           name         "explosion"  
           filename     "explosion"

           volume       45
           fadeinms     0
           fadeoutms    0
           loops        1
           framelimit   2
           delayms      100
         }
         

         name:        STRING
                      This is the WKN of the music of effect.  It
                      should never be changed, since it is hardcoded
                      into conquest.

         filename:    STRING
                      This specifies the filename (basename only, no
                      extension) that contains the audio samples.  The
                      sound loader can handle .WAV or .OGG files
                      only.  Only .OGG files are shipp with conquest. 

         volume:      NUMBER
                      0 to 100. Specifies the volume of the effect or
                      music sample.  This volume is used when the
                      sound is prepared for playing.  It is used to
                      provide the ability to 'equalize' the various
                      sound volumes being used, so they are even.  
      
         pan:         NUMBER
                      -127 to 127. The default pan of the effect when
                      created.  If it is a positional affect
                      (explosion for example), this value will have
                      no effect.

         fadeinms:    NUMBER
                      The number of milliseconds to take to fade in
                      the effect or music.

         fadeoutms:   NUMBER
                      The number of milliseconds to take to fade out
                      the effect or music.  

         loops:       NUMBER
                      Number of loops to play the effect of music.  0
                      means to loop infinitely.

         limit:       NUMBER
                      Specifies the maximum number times this effect
                      can be running concurrently.  Attempts to play
                      this effect after the limit is hit are ignored.
                      Music can never run at the same time as another
                      music file, so this option is only of use will
                      effects.  

         framelimit:  NUMBER
                      Specifies the number of times per frame that
                      this effect can be queued to play.  Attempts to
                      play the effect once the framelimit is exceeded
                      are ignored.  This is useful when there is the
                      potential for a large number of the same effect
                      (like an explosion) being triggered during the
                      same frame.  

         delayms:     NUMBER
                      When specified, indicates the minimum number of
                      milliseconds that must pass before the effect
                      can be played again.


## conqinit utility

      There is a new executable called conqinit provided.  conqinit
      can be used to test the parser, perform syntax checking on
      conqinitrc and texturesrc files, as well as to generate a
      texdata.h file based on texturesrc data, or an initdata.h file
      based on conqinitrc data.

      These (pre-generated) initdata.h and texdata.h files contain
      defaults for the planets and textures, compiled directly into
      conquest, in the event the respective conquestrc and texturesrc
      file could not be found or successfully read on startup.

      If you are modifying the conquestrc or texturesrc system files
      used by conquest, you should at least run conqinit on them to
      check for syntax or other validation errors.  If conquest (or
      conquestd) fails to properly load and parse the file at
      runtime, the built in internal defaults will be used and a warning
      message will be logged.

      examples:

      NOTE: all of these forms support '-v' to enable verbose mode and
            '-d' to enable extremely verbose debugging modes,
            respectively. 

      $ conqinit

        Simply parses the global conqinitrc file and exits, reporting
        any errors, warnings, etc.

      $ conqinit -f <file>

        Does the same thing but parses <file>.

      $ conqinit -t

        parses the default texturesrc file and exits, reporting any
        errors/warnings.

      $ conqinit -t -f <file>

        does the same thing but parses <file> instead, and treats it
        like a file in texturesrc format.

      $ conqinit -f <file> -h >conqinit.h

        parses <file> as a conqinitrc file and generates a conqinit.h
        file on stdout that can be compiled into conquest to specify
        'last-ditch' defaults in case the normal files could not be
        parsed for some reason at runtime.

        Note, you should never have to gen any .h files, the parser
        runs when conquest starts up and will always use the data it
        found if it can.  Valid texdata.h and initdata.h files are
        supplied in the conquest distribution and should not be
        modified by end users.

      $ conqinit -D 

        You must be a conqoper (or have direct read permission on the
        common block) to use this option. 

        This option is sort of a hack.  It loads the current state of
        the universe on the local machine and generates a conqinitrc
        format file on stdout.  This file can be saved and made the
        default conqinitrc for a system.

        If you do this, you will almost certainly want to edit the
        file and at least change the colors of the suns, and the sun's
        randomized army counts.  Since this data is not currently
        stored in the common block, conqinit tries to choose
        reasonable defaults for them.  Make sure it actually did :)

        This capability is useful if you init the universe, then use
        conqoper to edit and or create new planets and arrange them
        just like you want them.  Then, using the above command, dump
        the universe to a conqinitrc file, edit it if neccessary (to
        clean up colors, etc).  

        Then copy that file over the system's conqinitrc file.  From
        then on, whenever the planets are initialized (due to a
        successful conquer, or the actions of an oper in conqoper),
        your definitions will be used as the default planet
        configuration. 


## example of a user overriding a system defined texture.

   Here is an example of how a user can override a a system-wide
   texture image or texture definition.

   For the purposes of this discussion, a 'texture image' represents
   the file (in TGA format) that contains the image data for the
   texture.  A 'texture definition' represents a mapping between a WKN
   texture, and the actual texture's filename/color information.  Texture
   definitions are specified in texturesrc or *.trc files.

   # overriding a texture image

     When loading texture image (TGA) files, a user's ~/.conquest/img/
     directory is searched prior to the system-wide
     (<prefix>/share/img/) image directory.  This allows users to
     trivially substitute a different texture in place of the system
     defined ones.  Just make a texture with the same name as the one
     you want to replace, and put it in your ~/.conquest/img/
     directory.  Fun to play around with :)

   # overriding a texture definition

     You can override one of conquest's WKN texture definitions by
     adding an appropriate entry into a user .trc file.

     After conquestgl parses the main texturesrc file, it will then
     load and parse any *.trc files it finds in your ~/.conquest/
     directory.

     These files have the same format as texturesrc.  They can be used
     to remap a WKN texture to a different texture image filename, or to
     use a different color. 

     So for example, if you absolutely hate the Viewer Backgroud
     texture (it's WKN is 'vbg'), you could make it whatever you want
     by creating a ~/.conquest/vbg.trc file with the following
     contents:

         texture {
           name "vbg"                      # WKN of the vbg texture
           filename "my_better_vbg"
         }

         Then place your 'my_better_vbg.tga' file into your
         ~/.conquest/img/ directory.

         Now when conquest wants to draw the 'vbg' texture, it will
         use your definition instead.  

         NOTE: I just randomly chose the name 'vbg.trc' for this
         example.  You can name the file to whatever you want, just as
         long as it has a .trc extension, and lives in your
         ~/.conquest/ directory.


## conquest's texture format

   ConquestGL currently uses Targa (.tga) image format files to
   represent textures.  This is a simple and easy to use format,
   though not as good as formats like PNG in terms of compression.

   TGA files you use in Conquest must have the following
   characteristics: 

   - uncompressed or RLE compressed TGA
   - 24 bit RGB or 32bit ARGB pixel data
   - be a power of two in their width and height, 256x128 is okay,
     3x27 is not. :)

   I would limit texture sizes to no more than 512x512.
   
   For Conquest's textures, I use The Gimp (www.gimp.org) under linux.
   It can save in compressed ARGB/RGB TGA format.  For the 'Save'
   options dialog, select 'RLE Compressed' and de-select 'Origin in
   lower left'.



$Id: CONQINIT.TXT 700 2007-05-28 04:31:51Z jon $
