FAQ 6 - 3D File Formats for ROOMS worlds [build 444]
In order to help third party developers to create exciting new content,
utilities and editors for ROOMS, we publish here the main ROOMS file formats.
This page is organised in three main sections. We suggest you read through each
section in order to fully understand how ROOMS files work.
TIP: Click on "Print-vu" (top right of screen) to re-display this page so you
can print it out to read offline.
September 2002 - this page content is provisional. Please
contact us where tag descriptions are too short to be meaningful. You may find
using ROOMS wizards dialog content helpful in providing parallel explanation.
===========================
1. ROOMS World Architecture
Each standalone ROOMS world is specified by three types of object.
There must be one and only one World Property object.
There must be one or more Sector Property objects.
There must be one or more Item Property objects.
Crudely, a Sector specifies a room and an Item specifies a 3D icon.
More precisely, Sectors can include part-rooms, windows and steps,
while Items include walls, floors, ceilings and doors.
Each Sector belongs to the World. Each Item belongs to one and only one
sector. Items which can move (like draggable 3D icons) can move from
one sector to another during the life of a world.
The user is also an Item in the world and at any time belongs to the Sector
in which he/she appears.
World, Sector and Item properties are stored in a single ROOMS World File [.rwq].
To load a world you load its rwq file.
Some Items make use of ROOMS shape [.rsf] and behavior [.rvc] files. These
files are stored separately from the world file and can be shared by
several Items. Shape and behavior content is cached individually for each
item (because shape and behavior can take on different additional properties
item by item).
Not all combinations of properties can be applied to all worlds, sectors
and items. For example, if you use a predefined sky box texture, then tiling is
ignored. The rules which specify which combinations are legal are
encapsulated in the various wizards which ROOMS supports. So, for example,
the Icon Property Wizard grays out fields when they are inappropriate.
In most cases there are no further checks for legality of combinations,
but breaking the rules which are implicit in the wizard will most likely
crash ROOMS, and will not be supported in future versions.
If you need to clarify or have any doubts about any rules please
and ask. Be aware
that just because an obscure combination of properties works in one
version of ROOMS, if it is not legal via normal wizard activity, there
is no guarantee that it will continue to work in the next ROOMS version.
In what follows you will see that future-proofing (forwards and backwards
compatibility) is an important criterion for our architecture and file
formats. Take-home message "experiment at your peril".
2. File Format Principles
The key requirements for our file formats are forwards and backwards
compatibility.
Forwards compatibility means that if you create a world today and save
it to file (and normalize it), then any future version of ROOMS should
be capable of
reading that world file and displaying the world as you originally
intended.
Backwards compatibility means that if you create a world and save it
to file (and normalize it) and then post it on your Web site, then
anyone downloading that world, but who has an earlier version of ROOMS
should be able to run your world, although they may not be able to do
everything which the later ROOMS version can do.
This Web page describes the file format supported by ROOMS build 444.
Worlds are stored as tag data files. When a tag is not recognised it
is ignored. When a tag is not supplied ROOMS adopts a sensible default
value.
Each version of ROOMS will need some minimum set of tags and will
reject a world if this minimum set is missing, but the idea is to
keep this set small and thereby ensure future-proofing.
Some tags are for ROOMS internal use, from one session to another,
or for internal engine configuration. You should *NOT* amend these tags.
When manipulating a ROOMS file simply copy them from the source file
and re-write them to your target file. If you want to create a completely
new world file, you should seed these tag fields from the most similar
world you can find to that you are tring to create.
In ROOMS files, tags are organised into groups or sections. There
is a tag to indicate the start of a section and another tag to
indicate the end of section. Section tags are 6 characters long,
including square brackets, and occupy a single line in a file.
End-of-section tags contain the same letters as the start-of-section
tag, but in reverse order. E.g. start of world properties is [WORL]
and end of world properties is [LROW].
Data-bearing tags are 5 characters long including square brackets.
Data-bearing tags do not have a terminating tag. Instead each tag
is immediately followed by a number indicating its size on this
occasion. For example:
[MAP][1]0
Means the MAP data field contains one character and its value is zero. whereas:
[RNA][6]Room 1
Means the RNA data field contains six characters and its content is the text
string "Room 1".
In many places ROOMS tries to pack tag data fields into single lines in
a file. But this is not always true. And ROOMS cannot read multiple tag
lines in all places. The only safe way for a third party developer
(i.e. you) to handle this (sad) inconsistency and guarantee always to
work is if your software is capable of reading more than one tag from
any line of a ROOMS world file, but only ever write one tag per line
to a ROOMS world file.
The maximum length of a ROOMS data field which is stored in a tag file
is 256 characters.
Data fields can include characters, numbers and punctuation, but must
not include a newline. All data is ASCII, so there are no "raw" numbers,
and numbers are converted to their text string representation for
storage in a ROOMS file. ROOMS knows from the tag name whether it
is dealing with an integer value or floating point or a text string.
Fields that can contain file names may contain an absolute path to
the file or a normalized path. In normalization, the path is replaced
by a variable name (such as ?ROOMSRWQDIR? which stands for the directory
into which this world and all its files get copied). It is up to you
whether your software supports normalized ROOMS files, but you need
to be aware that this variablisation is what normalization involves.
There are other variables as well:
?ROOMSHOMEDIR? - the ROOMS installation directory e.g. C:\Program Files\Rooms\Rooms3d
?WINDOWSDIR? - the main Windows directory e.g. C:\Windows
?WINDOWSSYSDIR? - the Windows system directory e.g. C:\Windows\System
?WINDOWSPROGDIR? - the Windows program files directory e.g. C:\Program Files
3. Tag definitions, meanings and dependencies
ROOMS World File - .RWQ
The RWQ file contains three kinds of tag sections for properties:
World and Sector and Item.
The World section must appear first in the file. After the world
section the tag section for the first Sector must appear. All
the Items included in the first Sector must follow the first Sector.
Then the tag section for the second Sector appears and all the items
in the second Sector must follow immediately after it. This pattern
continues for as many Sectors as there are in the world.
In outline we get:
[WORL]
...World data tags
[LROW]
[SECT]
...Sector data tags
[TCES]
[ITEM]
...Item data tags
[METI]
[ITEM]
...Item data tags
[METI]
[SECT]
...Sector data tags
[TCES]
[ITEM]
...Item data tags
[METI]
[ITEM]
...Item data tags
[METI]
and so on...
The World Properties Section
[MAP] Is world in immersive or map view?
[ICN] How many items in the world?
[NAM] Name for this world
[BAK] Are we painting back faces on walls?
[FTY] Custom File-Type filename with path
[UUF] User shape file
[MUF] RoomMate shape file
[RWN] This worlds RWQ filename
[DEX] Default texture file name
[DEI] Default texture icon index (index into resources of icon-bearing file if texture is a Windows icon)
[SNO] Current highest sector number
[ACD] Animation click delay
[UBR] reserved, copy if present
[UBS] reserved, copy if present
[UBF] reserved, copy if present
[LIC] reserved, copy if present
[SKX] reserved, copy if present
[SKI] reserved, copy if present
[STL] reserved, copy if present
[SWL] reserved, copy if present
[CLN] reserved, copy if present
New for 444
[WLT] 0 for ambient lighting, 1 for dynamic lighting
[WLM] 0 for sun/moon stationary, 1 for light source moves with user
[LON] 1 for use global lighting with dynamic, 0 for no sun/moon with dynamic
[LCL] sun/moon color
[LAT] sun/moon attenuation
[LUM] sun/moon luminosity
[LSH] sun/moon light source shape
[WLU] sun/moon up/down angle
[WLL] sun/moon left/right angle
[WLF] sun/moon forwards/backwards angle
[FGA] 0 for no fog, 1 for fog
[FGC] fog color, integer
[FGD] fog starts distance
[FGN] fog attenuation
[FGF] clip distance for fog
[WBG] background color, integer
GoTo Markers. Each GoTo marker is specified by the full set here
and must be contained within the World section. There can be zero or
more GoTo markers, limited only by what fits in users popup menu.
[MKJ] start GoTo marker tags for this marker
[MKN] marker name
[MKI] marker index (unique number among markers for this world)
[MKS] sector index (number, which sector is marker in?)
[MKX] position in world x
[MKY] position in world y
[MKZ] position in world z
[MKP] forward vector x
[MKQ] forwrd vector y
[MKR] forward vector z
[MKA] upward vector x
[MKB] upward vector y
[MKC] upward vector z
[MKV] are we in map view? (number zero=no, number one=yes)
[MKO] zoom value for immersive view
[MKF] zoom value for map view
[MKE] end GoTo marker tags for this marker
The Sector Properties Section
[RIX] Room/Sector Index
[PSX] Parent Room/Sector Index
[PIX] Parent Item Index (e.g. wall ID thru which created)
[RNA] Room Name
[WZY] reserved, copy if present
[DNA] Directory Name
[WLN] Next number for a wall name
[NSI] Number of walls
[LSI] Length of each wall
[HSI] Height of each wall
[PHY] Type of physics USER_GRAV_ITEM_FLOAT=0 USER_FLOAT_ITEM_FLOAT=1 USER_GRAV_ITEM_GRAV=2 USER_FLOAT_ITEM_GRAV=3
[CTX] Ceiling texture filename
[CII] Ceiling texture icon-index (index into resources of icon-bearing file if texture is a Windows icon, -1 means off)
[FTX] Floor texture filename
[FII] Floor texture icon-index
[WTX] Wall texture filename
[WII] Wall texture icon-index
[DIX] reserved, copy if present
[HSN] Sound of icon hitting wall
[USN] Sound of user moving
[BSN] Sound in background
[DSN] Background Delay (average delay between background sounds if background sound file named)
[ELH] Default elevation for items
[XCS] XCoord of room origin
[YCS] YCoord
[ZCS] ZCoord
[SFX] Face forward x for room (horizontal perpendicular to wall 1)
[SFY] Face forward y
[SFZ] Face forward z
[SAX] Face up x for room (currently only vertical is supported)
[SAY] Face up y
[SAZ] Face up z
[FPT] reserved, copy if present
[DVA] EVAC for Door
[FVE] Vertex for custom footprint: copy if present
[WTI] Wall tiling
[FTI] Floor tiling
[CTI] Ceiling tiling
[SKY] reserved, copy if present
[ISS] Scene shimmers
[ISB] reserved, copy if present
[TRM] reserved, copy if present
[RST] Frictional resistance (number 0 to 1)
[ADT] reserved, copy if present
[DTX] reserved, copy if present
[JEN] reserved, copy if present
[JIX] reserved, copy if present
[JWL] reserved, copy if present
New for 444
[LWA] 0-1.0 attenuate world lighting when user in this room
[WAD] 0 for world using ambient, 1 for world using dynamic lighting, can warn user
[WSH] filename for shape file which each wall uses as profile when created
[WSE] wall shape file / stencilling is enabled.
This set available for each texture type, wall floor & ceiling
Wall
[DOM] texture decal or light modulated?
[RSI] Image Stream interface, ON or OFF for RSI DLL as texture
[RSN] Image Stream channel ID, integer, -1 for unset
Sampled animation tag set is optional:
[SAA] Sampled animation is enabled, 1 or 0 for enabled or disabled
[SAT] Sampled animation type, enum integer
[SAD] Sampled direction of traversal, angle in degrees 0-360
[SAI] Sampled time interval in frames, integer 0-16k
[SAR] Sampled distance change. 0-1.0 units of S and T
[SAW] Sampled width, 0-1.0
[SAH] Sampled height, 0-1.0
end of sampled animation set
[TLV] Vertical tiling
[ALP] texture transparency, 1 or 0 for enabled or disabled
[ALC] transparency color key
Ceiling
[CDO] texture decal or light modulated?
[CRI] Image Stream interface, ON or OFF for RSI DLL as texture
[CRN] Image Stream channel ID, integer, -1 for unset
Sampled animation tag set is optional:
[CSA] Sampled animation is enabled, 1 or 0 for enabled or disabled
[CST] Sampled animation type, enum integer
[CSD] Sampled direction of traversal, angle in degrees 0-360
[CSI] Sampled time interval in frames, integer 0-16k
[CSR] Sampled distance change. 0-1.0 units of S and T
[CSW] Sampled width, 0-1.0
[CSH] Sampled height, 0-1.0
end of sampled animation set
[CTL] Vertical tiling
[CLP] texture transparency, 1 or 0 for enabled or disabled
[CLC] transparency color key
Floor
[FDO] texture decal or light modulated?
[FRI] Image Stream interface, ON or OFF for RSI DLL as texture
[FRN] Image Stream channel ID, integer, -1 for unset
Sampled animation tag set is optional:
[FSA] Sampled animation is enabled, 1 or 0 for enabled or disabled
[FTS] Sampled animation type, enum integer
[FSD] Sampled direction of traversal, angle in degrees 0-360
[FSI] Sampled time interval in frames, integer 0-16k
[FSR] Sampled distance change. 0-1.0 units of S and T
[FSW] Sampled width, 0-1.0
[FSH] Sampled height, 0-1.0
end of sampled animation set
[FTL] Vertical tiling
[FLP] texture transparency, 1 or 0 for enabled or disabled
[FLC] transparency color key
The Item Properties Section
[INA] Item Name
[TGT] Target File Name
[WDR] Working Directory
[FTY] File Type
[XCO] XCoord
[YCO] YCoord
[ZCO] ZCoord
[CMD] Command Line
[SSS] Selected Shape
[UCL] Upward clearance for collisions
[DCL] Downward clearance for collisions
[PIF] Texture
[PIX] Texture Icon Index
[WAR] reserved, copy if present
[XFL] Un-Selected Shape
[COS] Collision sound file
[SES] Selected sound file
[OPS] Open sound file
[XDS] Deletion sound file
[SPT] Shape Type (integer) CUBE=0 WALL=1 FLOOR=2 CEILING=3 THEUSER=4 THEROOMMATE=5 SHAPE_FILE=9
[WTP] reserved, copy if present
[TLE] Texture Tiling factor (integer)
[DSF] Scale Factor
[RLO] reserved, copy if present
[RVC] EVAC File
[SEL] Selected?
[FFX] Face forward vector x
[FFY] Face forward y
[FFZ] Face forward z
[FAX] Face up vector x
[FAY] Face up y
[FAZ] Face up z
[ITI] Index ID for item
[IPS] Parent Room/Sector Index
[IGP] Group parent item index if a group child
[ISG] Is this item a group parent?
[FPT] reserved, copy if present
[FPD] Collision type FOOTPRINT_OFF=0 BOX_FOOTPRINT=1 FULL_FOOTPRINT=2
[ALA] EVAC is always active
[UZO] User Zoom
[MZO] Map Zoom
[SZO] Standard Zoom
[FUN] Ceiling Sky or Item Door UNSET=-1 DOOR_FUNCTION=1 SKY_FUNCTION=2
[FTF] reserved, copy if present
NEW FOR 444
[WSH] filename for shape file which each wall uses as profile when created
[WSE] wall shape file / stencilling is enabled
Light source tag set is optional:
[LOF] icon is light source, 1 for yes 0 for no
[LCL] light source color, integer
[LAT] light source attenuation, float 0-1.0
[LUM] light luminosity, float
[LSH] light, source shape, string or integer #define?
end of light source tag set
[LCC] item invisible when not in design mode
[DOM] texture decal or light modulated?
[RSI] Image Stream interface, 1 for yes 0 for RSI DLL as texture
[RSN] Image Stream channel ID, integer, -1 for unset
[RSE] Command Stream interface, control is enabled, 1 or 0 for enabled or disabled
[RSX] Command stream channel ID, -1 for unset, (uses target file as DLL)
[RSC] Command ID for target control stream, integer
Sampled animation tag set is optional:
[SAA] Sampled animation is enabled, 1 or 0 for enabled or disabled
[SAT] Sampled animation type, enum integer
[SAD] Sampled direction of traversal, angle in degrees 0-360
[SAI] Sampled time interval in frames, integer 0-16k
[SAR] Sampled distance change. 0-1.0 units of S and T
[SAW] Sampled width, 0-1.0
[SAH] Sampled height, 0-1.0
end of sampled animation set
[ALP] texture transparency, 1 or 0 for enabled or disabled
[ALC] transparency color key
[TLV] Vertical tiling
[SLH] Split wall horizontally, float less than 1 means fraction divide
[SHV] Split wall vertically, float greater than one rounded to number of divisions
[WAD] temporary use only, 0 if ambient lighting in world, 1 if dynamic. Can warn user.
[NSI] number of walls created alongside this wall in room, used to calculate mitre-ing
[]
RAV File Tags
[]
[TG]
[FNM][nn]Texture file name
optional
[IID][nn]Texture icon index
Dynamic texture RSI tags
[DOM] texture decal or light modulated?
[RSI] Image Stream interface, ON or OFF for RSI DLL as texture
[RSN] Image Stream channel ID, integer, -1 for unset
[SAA] Sampled animation is enabled, 1 or 0 for enabled or disabled
[SAT] Sampled animation type, enum integer
[SAD] Sampled direction of traversal, angle in degrees 0-360
[SAI] Sampled time interval in frames, integer 0-16k
[SAR] Sampled distance change. 0-1.0 units of S and T
[SAW] Sampled width, 0-1.0
[SAH] Sampled height, 0-1.0
[TLE] Horizontal tiling (integer)
[TLV] Vertical tiling (integer)
[ALP] texture transparency, 1 or 0 for enabled or disabled
[ALC] transparency color key
end-of-optional
[COL][nn]RRGGBB - Color triple
[PAR][nn]0 or 1 is this parameterised? Can current item prefered texture be used for this texture?
[VAX][nn]A vertex x relative to object origin
[VAY][nn]A vertex y relative to object origin
[VAZ][nn]A vertex z relative to object origin
[VBX][nn]B vertex x relative to object origin
[VBY][nn]B vertex y relative to object origin
[VBZ][nn]B vertex z relative to object origin
[VCX][nn]C vertex x relative to object origin
[VCY][nn]C vertex y relative to object origin
[VCZ][nn]C vertex z relative to object origin
[SXA][nn]S coord x for vertex A relative to texture origin
[SYA][nn]S coord y for vertex A relative to texture origin
[SXB][nn]S coord x for vertex B relative to texture origin
[SYB][nn]S coord y for vertex B relative to texture origin
[SXC][nn]S coord x for vertex C relative to texture origin
[SYC][nn]S coord y for vertex C relative to texture origin
[FAC][nn]Face is visible clockwise or anticlockwise or both: C A or B
[GT]end this triangle info
- end of tag list -
|
