*** empty log message ***

panda/src/doc/howto.MultiGenModelFlags

@@ -0,0 +1,211 @@
+                                                               9/16/97
+
+
+                           MULTIGEN MODEL FLAGS
+
+
+This document describes the different kinds of model flags one can place in
+the comment field of MultiGen group beads.  The general format for a model
+flag is: 
+                       <egg> { <FLAGNAME> {value} }
+
+The most up-to-date version of this document can be found in:
+
+                     $DWD/doc/howto.MultiGenModelFlags
+
+***************************************************************************
+                                 QUICKREF
+***************************************************************************
+
+            FLAG                                DESCRIPTION
+-------------------------------     ----------------------------------------
+
+<egg> { <Model>      {1} }          Handle to show/hide, color, etc. a chunk
+<egg> { <DCS>        {1} }          Handle to move, rotate, scale a chunk
+<egg> { <TexList>    {1} }          Handle to manage texture for a chunk
+<egg> { <ObjectType> {barrier} }    Invisible collision surface
+<egg> { <ObjectType> {turnstile} }  Invisible 1-way collision surface
+<egg> { <ObjectType> {ghost} }      Visible object, no collisions
+<egg> { <ObjectType> {bubble} }     Collision sphere around geometry
+<egg> { <ObjectType> {missile} }    Collision sphere with "missile" event
+<egg> { <ObjectType> {trigger} }    Invisible trigger polygon
+<egg> { <ObjectType> {eye-trigger}} Trigger which collides with avatar center
+<egg> { <ObjectType> {backstage} }  Modeling reference object
+<egg> { <Normal>     { 0 1 0 } }    Override and set normal for all verticies 
+<egg> { <Scalar> fps { # } }        Set rate of animation for a pfSequence
+<egg> { <Scalar> no-fog {1} }       Immune to the effects of fog
+
+
+
+***************************************************************************
+                                  DETAILS
+***************************************************************************
+
+The player uses several different types of model flags: HANDLES, BEHAVIORS,
+and PROPERTIES.  The following sections give examples of some of the most
+common flag/value pairs and describes what they are used for.
+
+
+                       ********** HANDLES **********
+
+   These flags give the programmers handles which they can use to
+   show/hide, move around, control the texture, etc. of selected segments
+   (chunks) of the model.  The handle is the name of the object bead in
+   which one places the flag (so names like red-hut are more useful than
+   names like o34).
+
+<egg> { <Model> {1} }   
+
+   Used to show/hide, change the color, or change the collision properties 
+   of a chunk.
+
+<egg> { <DCS> {1} }     
+
+   Used to move, rotate, or scale a chunk of the model.  Also can be used
+   (like the <Model> flag) to show/hide, change the color, and change the
+   collision properties of a chunk.
+
+<egg> { <TexList> {1} }
+
+   Used to manage the textures of a chunk.
+
+
+                      ********** BEHAVIORS **********
+
+   These flags are used to control collision properties, visibility and
+   behavior of selected chunks.  An "X" in the associated column means:
+
+      VISIBLE  the object can be seen (see NOTE below for invisible objects)
+      SOLID    avatars can not pass through the object
+      EVENT    an event is thrown whenever an avatar collides with the object
+
+                                       VISIBLE      SOLID       EVENT
+                                       -------     -------     -------
+<egg> { <ObjectType> {barrier} }                      X           X
+
+<egg> { <ObjectType> {turnstile} }                    X           X
+
+<egg> { <ObjectType> {ghost} }            X                       X
+
+<egg> { <ObjectType> {bubble} }           X           X           X
+
+<egg> { <ObjectType> {missile} }          X           X           X
+
+<egg> { <ObjectType> {trigger} }                                  X
+
+<egg> { <ObjectType> {eye-trigger} }                              X
+
+<egg> { <ObjectType> {backstage} }
+
+   Descriptions:
+
+      -  BARRIERS are invisible objects that block the avatars.  Use these
+         to funnel avatars through doorways, keep them from falling off
+         bridges, and so on.
+      -  TURNSTILES are also invisible objects that block the avatars.
+         Unlike barriers, however, avatars approaching from behind the
+         turnstile will smoothly pass through, instead of being forcefully
+         yanked to the front.  These are intended to implement a one-way
+         wall, through which the avatar can go forward but not back (to
+         create a one-way hallway or alley, for example)
+      -  GHOSTS are visible objects that the avatars can move through.  Any
+         objects that have been surrounded by barriers should use this flag
+         to avoid unnecessary collision calculations.
+      -  BUBBLES and MISSILES surround a specified chunk with a collision
+         sphere whose center is at the average of all the vertices.
+         Missiles throw an event called "missile"
+      -  TRIGGERS can be used to signal when avatars have entered a certain
+         area of the model.  One could place a trigger polygon in front of
+         a door, for example, so the player can tell when the avatar has
+         moved through the door.
+      -  EYE-TRIGGERS check for collisions with the *center* of the mover
+         (and not its bounding sphere).  This is useful for visibility
+         calculations. 
+      -  BACKSTAGE objects are not translated over to the player.  Modelers
+         should use this flag on reference objects that they include to help 
+         in the modeling task (such as scale references)
+
+   IMPORTANT NOTE:
+
+   It is not necessary, and in fact some cases it will actually cause
+   problems if you set the transparency value for the invisible objects
+   above (barrier, trigger, eye-trigger) to 0.0.  These objects will
+   automatically be invisible in the player if they have been flagged as
+   one of these three invisible types.  If you wish to make it clear in
+   MultiGen that these objects are invisible objects, set the transparency
+   value to some intermediate level (0.5).  Again, do not set the
+   transparency value to 0.0.
+
+
+                     ********** PROPERTIES **********
+
+These are used to control properties of selected chunks. 
+
+<egg> { <Normal> { 0 1 0 } }
+
+   Sets the normal of all vertices in a chunk to the specified value.
+   { 0 1 0 } is the value used for ramps which the avatars need to walk
+   up.  NOTE: You must have a space between values (i.e. 010 is not valid)
+
+<egg> { <Scalar> fps { frame-rate } }
+
+   This specifies the rate of animation for a pfSequence node
+
+<egg> { <Scalar> no-fog { 1 } }
+
+   This specifies that the geometry will be immune to the effects of fog
+
+***************************************************************************
+                                   NOTES
+***************************************************************************
+
+1) Combinations
+
+   Multiple Flag/value pairs can be combined within an single <egg> field.
+   For example:
+
+   <egg> { <Model> {1}  
+           <ObjectType> {barrier} }
+
+   Generally, the <Model> flag can be combined with most other flags
+   (except DCS).  Each bead, however, can only have *one* <ObjectType> flag.
+
+2) Newlines, spaces, and case (usually) do not matter.  This above entry
+   could also be written as:
+
+   <egg>{<model>{1}<objecttype>{barrier}}
+
+   A notable exception to the space rules is with the values of the
+   <Normal> flag.  There must be a space between the three components of
+   the normal
+
+                       <egg> { <Normal> { 0 1 0 } }
+
+   is valid
+
+                        <egg> { <Normal> { 010 } }
+
+   is *not*
+         
+3) Where to place the flags
+
+   All model flags except <Normal> flags are generally placed in the
+   topmost group bead of the geometry to which the flag applies.
+
+         GROUP  <- place flags here, except <Normal>
+           |
+           ---------------------------
+           |            |            |
+        OBJECT1      OBJECT2      OBJECT3 .....
+           |            |            |
+        polygons     polygons     polygons  <- place <Normal> flag here
+
+   Flags can also be placed in object beads, though for consistency sake
+   its better to place them in the group beads.
+
+4) Flags at different levels in the model
+
+   Flags in lower level beads generally override flags in upper level
+   beads. 
+
+5) For more detailed information see $DWD/doc/eggSyntax