Theme_System.txt

For historical purposes only. Do not edit.

Permalink: https://github.com/caligari87/Oblige/blob/e3dbc44e1649e40a65df8da0cc65d13be592fa03/notes/Theme_System.txt

THEME SYSTEM
============


( FIXME : THIS IS OUT OF DATE )


Theme Definitions
-----------------

Every level has a single "Level Theme", defined in the game-specific
LEVEL_THEMES table.  For example, it is called QUAKE.LEVEL_THEMES in
the games/quake.lua file.  There can be several Level Themes which
belong to a single "User Theme" -- e.g. with DOOM the 'Hell' theme
will randomly select between two Level Themes: doom_hell1 (which is
green marble) and doom_hell2 (which is hot red bricks).

Levels are divided into large "Zones" (usually separated by keyed
doors) and each zone has its own "Zone Theme", defined in the
ZONE_THEMES table.

Zones consist of rooms, and each room has its own "Room Theme",
defined in the ROOM_THEMES table.  That includes hallways too.

The THEME_DEFAULTS table provides info which can be common to
every theme -- and hence that stuff does not need to be duplicated
in all the specific themes.

The most specific theme usually[*] overrides any values from a
more generic one, with the following priorities:

    ROOM_THEMES > ZONE_THEMES > LEVEL_THEMES > THEME_DEFAULTS

Zone Themes can be absent, in which case OBLIGE will create its own
one using the data in the Level Theme.

Room Themes cannot be absent (at least for buildings, see below).


[*] there are exceptions though, for example OBLIGE selects a
single liquid to be used for the whole level, hence any 'liquids'
table in a Zone Theme or Room Theme will be ignored.


Application
-----------

Theming is decided after all the rooms have been connected and the
quest structure is in place (including the zones).

Liquids are easy: there is only one liquid per level (if any) and
this gets decided right at the beginning of the planning stage.

Building facades are fairly easy.  There will be a single facade
used in each zone [perhaps in the future allow two in very large
levels].  It will be chosen using the 'facades' table in the
Zone Theme, if absent then try 'facades' in the Level Theme, but
if all else fails then OBLIGE will use the interior wall from one
of the buildings in the zone.

Each room and hallway will get a 'room_theme' reference.
There are four basic kinds of rooms: Buildings, Caves, Outdoor and
Hallways.  [Note: hallways are not really considered rooms by the
Lua code, but we ignore that distinction here].  For each kind of
room there should be table for choosing the room theme:
 
    buildings = { B1=50, B2=15 }
    caves     = { C1=50 }
    outdoors  = { D1=50 }
    hallways  = { H1=40, H2=10 }

If such a table is absent in the Zone Theme, then the Level Theme
is tried.  It is a fatal error for the 'buildings' table to be
completely absent.  When 'caves' is completely absent, the level will
simply contain no caves, and the same goes for outdoor areas.  When
no 'hallways' table can be found, then OBLIGE will use the Room Theme
of a room which the hallway connects to.


Material Choices
----------------

Parts of a room will use materials (textures) chosen from the
Room Theme.

Buildings and Hallways have three main tables:

    walls = { STARTAN3=50, METAL2=10 }

    floors = { FLOOR4_8=50, FLAT1=30 }

    ceilings = { CEIL1_1=50 }

The special keyword '_FACADE' can be used in the 'walls' table,
which causes the interior texture of a building to match the
exterior (facade) texture.

The 'floors' and 'ceilings' tables can be absent (one or both),
which means they will use the same material as the one chosen
for the walls.


Caves have a single table, the wall and floor are chosen separately
from this table, and the ceiling will match either the wall or the
floor (or can be SKY in places).

    naturals = { ASHWALL4=50, ROCK1=20 }


Outdoor areas have some combination of man-made ("constructed") parts
and natural parts, and hence use these two tables:

    floors = { STONE1=50, WOOD2=10 }

    naturals = { GRASS1=20 }

Outdoor areas generally don't need walls, they are normally bounded
by buildings or caves, or have a fence between a neighboring outdoor
area (or a "sky fence" at the edge of the map).  However if a wall
was absolutely necessary then one of 'floors' or 'naturals' would be
chosen and used appropriately.


The Other Stuff
---------------

Walls, floors and ceilings are very important, but levels are
pretty boring without some other things too :-)

Theme definitions can contain other "choice tables" which refer
to various types of stuff.  For example the 'keys' table refers
to the names of KEY entities, and the 'doors' table refers to the
names of DOOR skins.

Many of these tables are for prefabs.  Prefabs are used to build a
lot of a level's architecture, things like archways, doors, stairs,
pedestals, windows, fences, etc....  A "skin" is a definition for
a prefab, specifying all the materials it needs (among other things,
like line-types etc).  Skins definitions are located in the
game-specific 'SKINS' table (e.g. DOOM.SKINS).

For example, this table in a Theme definition:

    stairs = { Stair_Up1=50, Stair_Down1=50 }

specifies there are two types of stairs to be used in a room,
'Stair_Up1' and 'Stair_Down1', and both are equally likely.
Changing the first 50 --> 5 would cause OBLIGE to create rooms
where he player mostly goes downward from the entrance.