--------------------------------------
Advanced Shadow Warrior Mapping Topics
Written By Keith Schuler
(c) 1997 3D Realms Entertainment
--------------------------------------

This briefly documents some of the more advanced topics in Shadow Warrior
mapping. Almost all of these are demonstrated to some degree in EXAMPLE.MAP
(found on your Shadow Warrior CD in the \GOODIES\TOOLS directory).

Refer to these documents in the \GOODIES\DOC directory on your Shadow
Warrior CD for other important information:

ADVANCED.TXT - Brief explanations of room-over-room, sector objects, and
other advanced Shadow Warrior mapping topics.
EDITART.TXT  - Instructions and reference for using the EDITART program.
EXAMPLE.TXT  - Documentation to accompany EXAMPLE.MAP, which includes
demonstrations of almost all of Shadow Warrior's map functionality.
SLABSPRI.TXT - Instructions and reference for using the SLABSPRI program.
SWSOUNDS.TXT - An index of the sound effects and ambient sounds.
SPRITAGS.TXT - Sprite tagging reference. Your guide to all the special
sprites in Shadow Warrior and how to use them.
SWBUILD.TXT  - A tutorial and reference guide to using the BUILD editor.
WALLTAGS.TXT - Wall and sector tagging reference. These are all the wall and
sector tags used in Shadow Warrior.
-----------------------------------------------------------------------------

Timing Vators                                                   1
Room-Over-Room                                                  2
        How It Works                                            2.1
                BOUND_FLOOR_BASE_OFFSET and BOUND_FLOOR_OFFSET  2.1.1
                VIEW_LEVEL1 and VIEW_LEVEL2                     2.1.2
                The Floor Mirror                                2.1.3
        The Rules Of Construction                               2.2
                BOUND_FLOOR_BASE_OFFSET and BOUND_FLOOR_OFFSET  2.2.1
                VIEW_THRU_FLOOR and VIEW_THRU_CEILING           2.2.2
                VIEW_LEVEL1 and VIEW_LEVEL2                     2.2.3
                Raising ceilings and lowering floors            2.2.4
                Z heights and overlap                           2.2.5
Advanced Room-Over-Room                                         3
        Visible Ceilings And Floors                             3.1
        Translucent Water                                       3.2
        Sloping Room-Over-Room                                  3.3
Sector Objects                                                  4
        Rules of construction                                   4.1
                The Wall Loop                                   4.1.1
                The Bounding Box                                4.1.2
                The Center Sector Lotag                         4.1.3
                The Center Sector Hitag                         4.1.4
                Sector Object Limitations                       4.1.5
        What Can You Do With It                                 4.2
                Follow A Track                                  4.2.1
                Auto Turret                                     4.2.2
                Driveables                                      4.2.3
                Bind It Across Floors                           4.2.4
SWSAVE                                                          5

---------------------
1.      Timing Vators
---------------------

Timing vators can be used to time events, cause things to happen after a
pause, or whatever. A timing vator is usually just a small sector somewhere
that the player can't get into. A SECT_VATOR (hitag 92) ST1 in the sector
has a TAG6 match equal to the event you want to trigger. Adjust the speed or
height of the vator to make a longer or shorter timer. Examples of timing
vators exist in almost every map of Shadow Warrior.

----------------------
2.      Room-Over-Room
----------------------

Room-Over-Room is the most significant feature of Shadow Warrior. It allows
for building genuinely 3-dimensional areas by placing one layer of sectors
over another, and allowing players and sprites to pass freely between the
two layers. It is, admittedly, a hack, and as such several rules of
construction must be followed in order for it to work at all. This being
the case, we'll start off by explaining what the heck the BUILD engine is
doing to produce this effect anyway.

2.1     How It Works:

The BUILD engine is sector based, which means every sector must have walls,
a ceiling, and a floor. Sectors can overlap each other, but these
overlapping sectors can never see each other, or the view becomes garbled.

        2.1.1 BOUND_FLOOR_BASE_OFFSET and BOUND_FLOOR_OFFSET

        These two ST1's (hitags 202 and 203, respectively) are used to drag
        groups of sectors over top of each other at premap. The BASE_OFFSET
        serves as an "anchor point." The next OFFSET processed is moved to
        the same x,y location as the BASE_OFFSET, dragging every sector
        connected to it along for the ride.

        2.1.2 VIEW_LEVEL1 and VIEW_LEVEL2

        Let's assume for now that the player will be viewing the lower
        layer (level 1) from within the upper layer (level 2). That's when
        the VIEW_LEVEL1 (hitag 110) ST1 kicks in. Behind the scenes,
        VIEW_LEVEL1 causes Shadow Warrior to draw level 1 as though the
        player were standing in it, but with one difference: the ceiling
        is moved up really, really high. If the player had been instead
        standing in the lower layer (level 1) and looking up at level 2,
        then the VIEW_LEVEL2 (hitag 111) sprite does a similar action.
        Behind the scenes, VIEW_LEVEL2 causes Shadow Warrior to draw level
        2 as though the player were standing in it, but with one
        difference, the floor is moved down really, really low.

        2.1.3 The Floor Mirror

        Okay, so behind the scenes, we've drawn this weird looking area with
        a really high ceiling or low floor. Now Shadow Warrior draws the
        layer that the player is actually standing in, but it doesn't draw
        anything where the floor mirror is. The "floor mirror" (tile #341)
        is a special texture used expressly for this purpose. Because
        Shadow Warrior didn't draw anything where the floor mirror was, the
        scene appears to "see through" it into the other layer. That's the
        image that the player sees on the screen at the next refresh.

2.2     The Rules Of Construction

        2.2.1 BOUND_FLOOR_BASE_OFFSET and BOUND_FLOOR_OFFSET

        As stated above, these are necessary in order to drag one level over
        the other. The lotag is the order in which they are processed, so
        you'd set a BASE_OFFSET first, with a lotag of 0. Then you'd set up
        all the OFFSETS you wanted to align to that BASE_OFFSET.

        2.2.2 VIEW_THRU_FLOOR and VIEW_THRU_CEILING

        One VIEW_THRU_CEILING (hitag 120) ST1 must be placed in a sector in
        level 1 with a floor mirror texture on the ceiling. The lotag is a
        view match tag, and must be the same as the lotag for the
        VIEW_THRU_FLOOR sprite, as well as all the VIEW_LEVEL1 and
        VIEW_LEVEL2 sprites in the room-over-room area. One VIEW_THRU_FLOOR
        (hitag 121) ST1 must be place in a sector in level 2 with a floor
        mirror texture on the floor, again, the lotag must be the same as
        the VIEW_THRU_CEILING sprite. Both of the VIEW_THRU sprites must be
        in the same relative positions in their respective sectors. Any
        sectors in level 1 with a floor mirror texture must be congruent
        to their matching sectors in level 2.

        2.2.3 VIEW_LEVEL1 and VIEW_LEVEL2

        These VIEW sprites are responsible for the actual drawing of room
        over room, so there must be one in every sector where the player
        can see the other level. Remember how the first area is drawn as
        though the player's view were there, with the ceiling pushed up?
        This means that there must be valid player space in level 1
        everywhere the player can view it from level 2. This means that if
        a player is standing anywhere in level 2, he cannot be standing over
        "null space" in level 1. Also note that the VIEW_LEVEL sprites
        should always be angled downward in 2D mode.

        2.2.4 Raising ceilings and lowering floors

        Because Shadow Warrior temporarily alters ceiling and floor heights
        in room over room areas, two side effects will occur. The first is
        that you can never see the ceiling of level 1 from level 2, nor see
        the floor of level 2 from level 1. The second is that wall textures
        will move depending on whether they are oriented to the ceiling or
        floor. Keep this in mind when constructing your room over room areas.

        2.2.5 Z heights and overlap

        Level 1 and level 2 must be constructed with proper Z heights,
        because Shadow Warrior won't do it for you. By this I mean that the
        floor of level 2 must actually be higher than the ceiling of level 1.
        The difference between the two is called the "overlap." At least
        some overlap is necessary for room over room to behave correctly.
        To build overlap correctly, follow these guidelines:

                1> The height of the floor mirror (on the ceiling) in level 1
                   must be the exact same as the height of the -floor- (not
                   the floor mirror) in level 2.
                2> The height of the floor mirror in level 2 must be the
                   same as the height of the -ceiling- (not the floor mirror)
                   in level 1.


-------------------------------
3.      Advanced Room-Over-Room
-------------------------------

Confused by room over room yet? Now let's move on the exceptions and special
cases!

3.1     Visible Ceilings And Floors

        Above, we stated that you can never see the floor of level 2 from
        level 1, and you can never see the ceiling of level 1 from level 2.
        We lied. In $SHRINE.MAP, you can see sloping floors in level 2
        from level 1 out in front of the temple. In $AUTO.MAP you can see
        a car on the floor of level 2 from level 1. This is a special
        trick, and you'll need to look at those maps to see how its done.
        Here are some guidelines:

        1> You must use two sets of VIEW_LEVEL and VIEW_THRU tags. Depending
           on the sector, some VIEW_LEVEL tags will be turned "on" (pointing
           down) and some will be turned "off" (pointing up.)
        2> The player can only see the floor/ceiling from the sector with
           the floor mirror texture, so be sure to construct your area
           accordingly.
        3> The player cannot see the floor/ceiling and see more floor mirror
           on the other side. It just won't work.

3.2     Translucent Water

        To do this, build level 1 like any room over room area, but tag it
        to be water, too, by placing a SECT_UNDERWATER (hitag 8) sprite in
        there. The floor mirror sector is the sector you can enter and
        exit the water from. The floor mirror sector in level 2 should not
        have a DIVE_SECTOR (hitag 7) sprite, but it will need a
        FLOOR_Z_ADJUST (hitag 98) with a lotag of 40. This allows the player
        to wade along the surface without "falling" underwater. Use a
        CEILING_FLOOR_PIC_OVERRIDE (hitag 136) to give the water a texture.

        NOTE: This technique was also used to create reflective or masked
              floors in Shadow Warrior.

3.3     Sloping Room-Over-Room

        Yes, it can be done. Look at $AIRPORT.MAP for an example.


----------------------
4.      Sector Objects
----------------------

A "sector object" is a group of connected sectors that operate as a unit.
Driveables, amoebas, turrets, and numberous other things can be built using
sector objects.

4.1     Rules of construction:

        4.1.1 The Wall Loop

        Any sector object must be entirely surrounded by an unbroken
        "wall loop." This means that no line can connect a vertex on the wall
        loop to a vertex within the sector object. One line of this wall loop
        must have a lotag set to TAG_WALL_LOOP_OUTER (walltag 504).

        4.1.2 The Bounding Box

        Every sector must have two SECT_SO_BOUNDING (hitag 500-600) ST1. One
        sprite (BOUND_SO_UPPER) is placed in the upper left corner of the
        sector object, while the other (BOUND_SO_LOWER) is placed in the
        lower right corner. These two sprites form an imaginary rectangle.
        Place these sprites so that this "imaginary rectangle" is large
        enough to contain the entire outer wall loop plus any sprites you
        want to move with the sector object. For sector object #0, the
        BOUND_SO_UPPER sprite is hitag 500, and the BOUND_SO_LOWER sprite
        is hitag 501. For sector object #1, use 505 and 506, respectively.
        Sector object #2 uses 510 and 511. This continues all the way up
        to sector object #19, which uses hitags 595 and 596.

        4.1.3 The Center Sector Lotag

        Every sector object must contain one and only one sector tagged as
        its "center sector." This determines the center point around which
        the sector object will pivot. The lotag of the center sector will
        always be the same as the hitag of the sector object's
        BOUND_SO_LOWER sprite. So, sector object #0 uses 501, #1 uses 506,
        #2 uses 511, and so on all the way up to sector object #19, which
        has a center sector lotag of 596.

        4.1.4 The Center Sector Hitag

        The sector hitag of the center sector is the track # that the
        sector object will follow. See SPRITAGS.TXT for a description of
        track sprites. If you don't want the sector object to follow a
        track, set the hitag to -1. Other special cases include: 95 for a
        killable sector object, 96 for an auto-turret, and 98 for a
        driveable.

        4.1.5 Sector Object Limitations

        You can have up to twenty (0-19) sector objects in a map. Each
        sector object can contain up to 30 sectors.

4.2     What Can You Do With It?

        4.2.1 Follow A Track

        This is the most common use of a sector object. Set the hitag equal
        to a track # and make the thing wander around. See SPRITAGS.TXT
        to find out what you can do with tracks.

        4.2.2 Auto Turret

        Set the center sector hitag to 96, then put an AUTO_TURRET (hitag 81)
        ST1 in the center sector. Put in a SO_ANGLE (hitag 16) to tell it
        which way is the front, and then the sector object will always turn
        to track the movement of the player. Add a SHOOT_POINT and the
        auto-turret will shoot at the player.

        4.2.3 Driveables

        Set the center sector hitag to 98, then put in a SECT_OPERATIONAL
        (hitag 1) and a SO_ANGLE and your sector object can now be driven
        around by the player. It can never leave the sector surrounding the
        wall loop, though, so keep that in mind.

        4.2.4 Bind It Across Floors

        If you want to place a sector object in water or in room over room
        areas, you're going to want a "bottom" that moves with the top
        half of the SO. This can be done pretty easily with
        BOUND_FLOOR_BASE_OFFSET and BOUND_FLOOR_OFFSET. If the sector object
        finds itself in a BOUND_FLOOR area, it will automatically try to
        find its other half in the matching BOUND_FLOOR area. All the
        secondary part needs is a wall loop tagged with 504 or 508, and
        it will move as a unit. See rooms FB,FC, FE, and FF in EXAMPLE.MAP.

--------------
5.      SWSAVE
--------------

SWSAVE is a powerful and convenient debugging feature of Shadow Warrior. We
found it to be immensely useful for finding stacked sector walls that don't
match up, as well other odd uses. While in the game, press "T" and type in
"SWSAVE" just like a cheat code. The program will save the map in its
current state as SWSAVE.MAP, which you can then load into BUILD.
BOUND_FLOOR_OFFSET dragging will have taken place, so you'll see room over
room area sectors in their actual positions during the game.
