

  
                             3D Foundation Classes



                       *** TXE Language Specification ***



     -------------------
      Table of Contents
     -------------------



           What is?

           Blocks

           Specification



     ----------
      What is?
     ----------



           TXE is the 3DFC script linguage used to describe
           
           the scenery. Read doc/3dfc.txt for one overview
           
           about 3DFC.

           
           Now, you can define using TXE:

              - textures that polys can use

              - palette

              - vertexes for a mesh

              - polygons for a mesh

              - polygons attributes

              - portals for the polygons

              - scenery sectors

              - view cameras

              - object templates (defines), for instanciation

              - object instances

              - object components

              - colored lights

              - set message system


           Complementar information can be found in the example
           
           files at directory EX. The files have extension .TXE
           


      --------
       Blocks
      --------


           
           To separate each word, number or simbol can be

           used the characters: ENTER, TAB, END-OF-LINE.

           The class that implement the read of a TXE file is

           CFileTXE.


           TXE use the "/" as directory and file separator.

          
           The linguage delimit data with blocks, each block
           
           define one type of data. Above follow the blocks
           
           and their use.


           * blocks where general data files are loaded:

                Read           read other TXE files

                Textures       load textures bit-maps from PCX files

                Palette        load palette from a PCX file

                LightTables    load light table files

           
           * blocks where scenery elements are declared:

                Define         declare one definition (a DEFINE)

                Objects        declare an object instance

                Sector         declare an sector


           * blocks where basic mesh data are declared:

                Polygons       define a mesh polygons

                Vertexes       define a mesh vertexes


           * blocks where polygons attributes are declared:

                Portal         define what polygons are portals and your destins

                PolygonsLight  define polygons light parameters

                SolidState     define if polygon is crossable or solid

                Surface        define the a polygon surface (what texture)


           * blocks for configuration:

                Start          define some engine initial parameters

                SetLightLevel  set the light level, used when creating
                
                               new vertexes

                SetLightTable  set the light table, used when creating
                               
                               new vertexes


           * commands for objects components manipulation and messages:

                CreateComponent     add one component to the define

                ActivateComponent   run one component

                DestroyComponent    remove one component from the define

                InitMessages        initial set of messages to send


           Some blocks only can be declared inside others. For example,

           Vertexes, only can be placed inside an Define or Sector block.



      ---------------
       Specification
      ---------------



          ----
          Read
          ----


             Syntax:
             ------


                Read { file1 [file2 ...] }


             Remarks:
             -------


                Read a TXE file.
                
                
                file1 - the TXE to read
                
                
                After read continue processing

                the original TXE file. If inside file1 or

                file2, ... exists a reference to other files, the path

                of the other files, is relative to location of

                file1 or file2, respectively (see example below).

                A Read block can be placed only outside all other blocks.


             Example:
             -------


                Read {
                  data/textures.txe
                  data/opera.txe
                  data/room.txe
                }


                Read the files data/textures.txe, data/room.txe and

                data/opera.txe.

                If in room.txe you refer the file room100.txe

                automaticaly will be append to file room100.txe

                the path of file room.txe: data/room100.txe

                The same happens when loading other files (textures,...)



          --------
          Textures
          --------



             Syntax:
             ------


                Textures { ID file1 [...] }


             Remarks:
             -------


                Load a texture from a PCX file.

                
                ID     - the texture ID for internal identification

                file1  - the PCX where the texture is


                The macro TEXTURE_SIZE in defs.h define 3DFC internal
                
                texture sizes. Loaded textures are scaled to fit
                
                TEXTURE_SIZE.

                A Textures block can be placed only outside all other blocks.
                

             Example:
             -------


                Textures {
                   1 marble.pcx
                  23 data/rock.pcx
                }



          -------
          Palette
          -------



             Syntax:
             ------


                Palette file


             Remarks:
             -------


                Load a 256 colors palette from a PCX file.

                
                file - the PCX where the palette is


                The palette can be used to reprogramm the VGA palette.

                A Palette block can be placed only outside all other blocks.
                

             Example:
             -------


                Palette rock.pcx



          --------
          Vertexes
          --------



             Syntax:
             ------


                Vertexes { x1 y1 z1  [x2 y2 z2 [...]] }


             Remarks:
             -------


                Declare a vertex.

                
                x1, y1, z1 - are the components of the vertex


                Vertexes only can be declared inside a sector or define

                block. The coordenates are relative to the parent reference

                system.

                A Vertexes block can be placed only inside an Define or
                
                Sector block.

                The vertex order must be anti-clowise.

                Before this block is needed create a mesh component
                
                (if not exist), adding the command:
                
                        CreateComponent 5 2 ;  /* add mesh */


             Example:
             -------


                Vertexes {
                   -10 70 30
                     4 10  0
                   -90 63 12
                }


             If the mesh not exist:

                
                CreateComponent 5 2 ;  /* add mesh */

                Vertexes {
                   -10 70 30
                     4 10  0
                   -90 63 12
                }



          --------
          Polygons
          --------



             Syntax:
             ------


                Polygons { v1 v2 v3 [...] ; [...] }


             Remarks:
             -------


                Declare a polygon, defining what vertexes compose it.

                
                v1, v2, v3 - vertex indexes


                In 3DFC v0.0.2, each polygon can have up to 8 vertexes.

                The ";" is used to separate distinct polygons.

                Polygons only can be declared inside a sector or define

                block. The vertex indexes are acording the position in

                the Vertexes declaration block (the indexing start
                
                in zero).

                A Polygons block can be placed only inside an Define or
                
                Sector block.

                The vertex order must be anti-clowise.

                Before this block is needed create a mesh component
                
                (if not exist), adding the command:
                
                        CreateComponent 5 2 ;  /* add mesh */
                

             Example:
             -------


                Polygons {
                   3 4 2 ;
                   6 5 4 3 5 ;
                }


                Declare two polygons: one with 3 vertexes and other with

                5 vertexes.


             If the mesh not exist:

                
                CreateComponent 5 2 ;

                Polygons {
                   3 4 2 ;
                   6 5 4 3 5 ;
                }



          -------
          Portals
          -------



             Syntax:
             ------


                Portals { c se ndx1 [<;>|<.. ndx2>] [...] }


             Remarks:
             -------


                Define the destin sector for a portal.

                
                c    - a polygon code
                       
                       0 - polygon is not a portal

                       1 - polygon is a portal to a sector inside the

                           object: adjacent sectors inside the same
                           
                           object or a portal from external object mesh

                           to an internal sector.

                       2 - polygon is a portal to exterior: the sector

                           where the object is inside.

                se   - destin sector ID (used if polygon code is 1).

                       In other cases this value is ignored.

                ndx1 - index of the first polygon to aplly the state

                ndx2 - index of the last polygon to aplly the state


                Before the Portals block the polygons must be declared.

                A Portal block can be placed only inside an Define or
                
                Sector block.


             Example:
             -------


                Portal {
                   1 3 43 ; /* polygon 43 has as destin: sector 3,
                               sector 3 is inside the same object where
                               current sector is: the first value is 1 */
                }



          -------
          Surface
          -------



             Syntax:
             ------


                Surface { tID ndx1 [<;>|<.. ndx2>] [...] }


             Remarks:
             -------


                Define the texture to be used for a polygon.

                
                tID  - the texture ID, the ID is the same found in
                
                       Textures block. If -1 the polygon does not

                       has texture.

                ndx1 - index of the first polygon to aplly the state

                ndx2 - index of the last polygon to aplly the state


                Before the Surface block the polygons must be declared.

                A Surface block can be placed only inside an Define or
                
                Sector block.


             Example:
             -------


                Surface {
                   1 22 ; /* polygon 22 has texture 1 */
                }



          ----------
          SolidState
          ----------



             Syntax:
             ------


                SolidState { c t ndx1 [<;>|<.. ndx2> [...] }


             Remarks:
             -------


                Define polygon attributes.

                
                c    - collision detection type of test:
                       
                           0 - polygon is crossable,
                           
                               only plan collision detection;

                           1 - polygon is solid, collision detection test
                           
                               only polygon plan;

                           2 - polygon is solid, collision detection test
                           
                               poly plan and if intersection point is
                               
                               inside the polygon;

                           3 - polygon is crossable, make plan and

                               intersection point test.


                t    - texture ID, -1 if no texture

                ndx1 - index of the first polygon to aplly the state

                ndx2 - index of the last polygon to aplly the state


                The collision detection type can be made with:
                
                "plan collision detection" (type 1), the collision detection

                test only the distance between the object and the polygon

                plan. The problem is, for example, with exist a portal

                sharing the same plan with a solid poly, the collision
                
                would be detected if the object collide with the solid
                
                polygon or with the portal.


                "Polygon collision detection" (type 2), is more slow than
                
                the other test, but the collision is detected with polygon
                
                precision, not only plan precission. Is tested
                
                "plan collision detection" and if the intercestion

                point between the poly plan and the object sphere is
                
                inside the poly edges.

                
                If the attribute correspond only of one polygon use:

                ndx1 and follow by ";".

                If the attribute correspond of a range of polygons use:
                
                ndx1, follow by ".." and than ndx2.

                Before the SolidState the polygons must be declared.

                An SolidState block can be placed only inside an Define or
                
                Sector block.
                

             Example:
             -------


                SolidState Attributes {
                   2 13 .. 19 /* polys 13 to 19:
                                 the collision detection is with polygon
                                 precision */
                   0 22 ;     /* poly 22 is crossable */
                }



          -------------
          PolygonsLight
          -------------



             Syntax:
             ------


                PolygonsLight { ID l ndx1 [<;>|<.. ndx2>] [...] }


             Remarks:
             -------


                Define polygon light intensity (called light level).

                
                l    - the polygon light level, between 0 (dark) and
                
                       1 (lighted). The values are in float range.
                       
                       If you compile using colored light sources the
                       
                       default is 1, else 0.5

                ID   - light table ID. The ID for the light table to be
                
                       used to shade the polygons. Combining parameters

                       "l" and ID many colors combinations can be used.

                       Default is 0.

                ndx1 - index of the first polygon to aplly

                ndx2 - index of the last polygon to aplly


                If the light info correspond only of one polygon use:

                ndx1 and follow by ";".

                If the light info correspond of a range of polygons use:
                
                ndx1, follow by ".." and than ndx2.

                Before the PolygonsLight block the polygons must be declared.

                A PolygonsLight block can be placed only inside an Define or
                
                Sector block.
                

             Example:
             -------


                PolygonsLight {
                   0 0.5 3..59  /* polys 3 to 59: have half light power,
                                   use light table 0 */
                   1 0.9 2 ;    /* poly 2 has 90% light power,
                                   use light table 1 */
                }



          -------
          Objects
          -------



             Syntax:
             ------


                Objects { i o s
                
                          d1 [...] ;

                          [...]
                        }


             Remarks:
             -------


                Create an object instance.


                i - the instance ID (must be unique between all instances)

                o - object instance where the instance is inside

                s - the sector where the instance is inside

                d1, [...] - a list of defines IDs, the defines will
                
                            compose the object
                

                Before the Objects block the object Defines used must
                
                be declared.

                An Objects block can be placed only outside all other
                
                blocks.


             Example:
             -------


                Objects {
                   10 4 15  /* create object 10, place it inside object */
                   1 3 ;    /* 4, sector 15. The defines used for this */
                            /* object are: 1 and 3 */
                   
                   3 5 3   /* create the object 3 */
                   9 ;
                }



          -----
          Start
          -----



             Syntax:
             ------


                Start cam b


             Remarks:
             -------


                Define some initial parameters.


                cam - the object ID that would be the current camera
                
                      (viewer)

                b   - background color, value between 0 and 255 defining
                 
                      the palette color to be used for frame buffer clear or
                      
                      -1 if don't need clear frame buffer. If the scenery is

                      completely rounded by polygons it's not necessary

                      clear the frame buffer.
                

                Before define the Start block the object instances
                
                must be declared.

                A Start block can be placed only outside all other blocks.


             Example:
             -------


                Start 7 -1



          -----------
          LightTables
          -----------



             Syntax:
             ------


                LightTables { ID file levels r g b [...] }


             Remarks:
             -------


                Define the light table. Load it for a file, if impossible

                create it using the given parameters: levels, r, g, b.


                ID     - the light table scenery ID (used to identify

                         what ligth table use in colored shades). Each

                         light table has the shade of one specific color.

                file   - the light table file (recomend extension LTB)

                levels - number of light levels. If file can't be loaded

                         a new one is created using "levels" light levels.

                         The created light table is automaticaly saved with

                         the "file" as name.

                r g b  - the light table color to be used to create the
                
                         shading levels. Is the color to be shaded for
                         
                         the light table. The values are between 0 and 1.


                Is recomendable create light tables only for the colors
                
                more frequent in palette.

                Is better place this block after the Palette declaration.

                A LightTables block can be placed only outside all other blocks.



             Example:
             -------


                LightTables {
                
                   0 demo.tbl 16 1.0 1.0 1.0
                                 /* try load demo.tbl, if can't create
                                    a light table with 16 levels of the 
                                    color 1,1,1 combined with the palette
                                    colors and save it at file demo.tbl */
                
                   4 yellow.tbl 16 1.0 0.5 0.0
                                 /* try load yellow.tbl, if can't create
                                    a light table with 16 levels of the 
                                    color yellow: 1,0.5,0 combined with
                                    the palette colors and save it at file
                                    yellow.tbl */
                }



          ------
          Define
          ------



             Syntax:
             ------


                Define ID { [...] }


             Remarks:
             -------


                Define a possible object component.


                ID - Define ID (must be unique between all defines)


                The define must be instanciated in an Objects block.

                A define block can be placed only outside all other blocks.
                

             Example:
             -------


                Define 7 {
                   Vertexes {
                      -10 10 10
                       10 10 10
                       10 20 10
                   }

                   Polygons {
                       0 1 2 ;
                   }

                   Surface {
                       7 0 ;
                   }
                }



          ------
          Sector
          ------



             Syntax:
             ------


                Sector ID { [...] }


             Remarks:
             -------


                Define a sector model.


                ID - sector ID (must be unique between all sectors inside the
                
                     define)

                
                A Sector block can be placed only inside an Define block.
                

             Example:
             -------


                Define 5 {
                
                   Sector 2 {
                      Vertexes {
                         -10 10 10
                          10 10 10
                          10 20 10
                      }

                      Polygons {
                          0 1 2 ;
                      }

                      Surface {
                          2 0 ;
                      }
                   }
                }



          ---------------
          CreateComponent
          ---------------



             Syntax:
             ------


                CreateComponent slot comp p1 p2 [ d1 ... dn ] ;


             Remarks:
             -------


                Add one component to the define.


                slot    - the slot ID to add (a list of slots IDs is
                
                          in src/defs.h)

                comp    - the component ID to add (a list of
                        
                          components IDs is in src/defs.h)

                p1, p2 -  2 mandatory parameters passed to the component.

                          If the component doesn't need then, use zeros.

                d1...dn - optional, a list of float values used for the
                
                          component.

                          The parameters and the list has specific

                          use acording the component (the
                          
                          components parameters are described in the
                          
                          source files at directory src/comp).

                
                A CreateComponent block can be placed only inside an
                
                Define block. See doc/3dfc.txt for more info about

                components.
                

             Example:
             -------


                Define 5 {
                
                   CreateComponent 4 2 1 3 2.3 -2 ;
                                    /* add component 2 in slot 4,
                                       creation parameters is 1, 3 and
                                       a list of 2.3 and -2. */
                
                   CreateComponent 3 1 0 0 ; /* if the component does not
                                                use some extra parameter
                                                use 0 in mandatory
                                                parameters */
                }



          -----------------
          ActivateComponent
          -----------------



             Syntax:
             ------


                ActivateComponent slot p1 p2 [ d1 ... dn ] ;


             Remarks:
             -------


                Activate, run, one component.


                slot    - the slot ID where the compoent is
                
                          (a list of slots IDs is in src/defs.h)

                p1, p2 -  2 mandatory parameters passed to the component.

                          If the component doesn't need then, use zeros.

                d1...dn - optional, a list of float values used for the
                
                          component.

                          The parameters and the list has specific

                          use acording the component (the
                          
                          components parameters are described in the
                          
                          source files at directory src/comp).

                
                Is necessary, first create the component using
                
                CreateComponent.

                
                A ActivateComponent block can be placed only inside an
                
                Define block. See doc/3dfc.txt for more info about

                components.
                

             Example:
             -------


                Define 5 {
                
                   CreateComponent 2 4 1 3 2.3 -2 ;

                   ActivateComponent 2 0 1 ;
                                   /* run the component in slot 2,
                                      parameters are: 0 and 1 */
                }



          ----------------
          DestroyComponent
          ----------------



             Syntax:
             ------


                DestroyComponent slot p1 p2 [ d1 ... dn ] ;


             Remarks:
             -------


                Remove one component from the define.


                slot    - the slot ID to where the component to be
                
                          removed are (a list of slots IDs is
                
                          in src/defs.h)

                p1, p2 -  2 mandatory parameters passed to the component.

                          If the component doesn't need then, use zeros.

                d1...dn - optional, a list of float values used for the
                
                          component.

                          The parameters and the list has specific

                          use acording the component (the
                          
                          components parameters are described in the
                          
                          source files at directory src/comp).

                
                Is necessary, first create the component using
                
                CreateComponent.

                
                A DestroyComponent block can be placed only inside an
                
                Define block. See doc/3dfc.txt for more info about

                components.
                

             Example:
             -------


                Define 5 {
                
                   CreateComponent 2 4 1 3 2.3 -2 ;

                   DestroyComponent 2 5 0 ;
                                   /* remove the component in slot 2,
                                      the parameters is 5, is necessary
                                      pass the 2 parameters, because
                                      this exist the 0 */
                }



          ------------
          InitMessages
          ------------



             Syntax:
             ------


                InitMessages { objID slot p1 p2 ; ... }


             Remarks:
             -------


                Define the initial set of messages that would be
                
                generated for each engine interaction. Messages would

                be send until they are removed from the message table.
 

                objID   - the ID of the object to send the message
                
                slot    - the slot ID to where the component to receive
                
                          the message is (a list of slots IDs is
                
                          in src/defs.h)

                p1, p2 -  2 mandatory parameters passed to the component.

                          If the component doesn't need then, use zeros.


                The messages send, in true, just activate the specific
                
                object slot passing to it the parameters p1, p2. The

                third activation parameter is allways 0, and you can

                set it in this declaration block.

                
                Is necessary, first create the receivers object
                
                instances.
                

             Example:
             -------


                InitMessages {
                
                   0 1 0 0 ;   /* in each engine interaction is activate
                                  object 0, slot 1, passing 0 and 0.
                                  This line is specialy usefull if you
                                  want to control your camera object
                                  (in this case object 0) with the
                                  keyboard (activating slot 1). */

                   1 2 3 -2 ;  /* another activation */
                }



          -------------
          SetLightLevel
          -------------



             Syntax:
             ------


                SetLightLevel level


             Remarks:
             -------


                Define the light level for the next declared vertexes.

                Light level define light intensity over some

                vertex or polygon.

                This light level is assigned as the "ambient", default

                light level for the vertex. If a light source is close

                to the vertex the result light level is the sun of

                the "ambient" light and light source light.

                The value is used for all vertexes declaraded from the

                point where SetLightLevel is to the end of the system

                running.
 

                level   - the normalized light level (between
                
                          0 - dark - and 1 - whitest )

                          if -1 is used engine default value in macro

                          DEFAULT_LIGHT_LEVEL.

                
                This block can be placed outside all blocks, inside a
                
                Define or a Sector block.
                

             Example:
             -------


                SetLightLevel 0.3       /* a bit dark */

                Define 3 {

                   Vertexes {

                      0 +100 +100
                      0 -100 +100
                   }

                   SetLightLevel 0.5    /* half poly is a bit dark and
                                           the other half  more
                                           lighted */

                   Vertexes {

                      0 -100 -100 
                      0 +100 -100
                   }

                   Polygons { 0 1 2 3 ; }
                }

                SetLightLevel -1        /* set to engine default */



          -------------
          SetLightTable
          -------------



             Syntax:
             ------


                SetLightTable ID


             Remarks:
             -------


                Define the light table for the next declared polygons.

                The light table is used to define the color for the
                
                light sources (and ambient light) over the polygon

                surface.

                The value is used for all polygons declaraded from the

                point where SetLightTable is to the end of the system

                running.
 

                ID      - the light table ID (to define light tables
                
                          see LightTables)

                          if -1 is used engine default value in macro

                          DEFAULT_LIGHT_TABLE.

                
                This block can be placed outside all blocks, inside a
                
                Define or a Sector block.
                

             Example:
             -------


                LightTables {
                  0 white.ltb 32 1.0 1.0 1.0
                  1 red.ltb   32 1.0 0.5 0.0
                }
                
                SetLightTable 1      /* set red.ltb for the polygon,
                                        if the poly receive ambient light
                                        or light from a light source
                                        their color would be red. */
                Define 3 {

                   Vertexes {

                      0 +100 +100
                      0 -100 +100
                      0 -100 -100 
                      0 +100 -100
                   }

                   Polygons { 0 1 2 3 ; }
                }

                SetLightTable 0        /* set white light table */
