SCASM - FS2002 and FS2004 terrain data

SCASM 2.91

FS2002 & FS2004 terrain data

command index:: back to main index; VTPFileHeader( ); VTPEnd; VTPArea( ); VTPLayer( ); VTPTexID( ); VTPPolyCount( ); VTPPoly( ); VTPWPoint( ); VTPCPoint( ); VTPPointXY( ); VTPPointXYUV( ); VTPIndexList( ); VTPTextureList( ); LWMFileHeader( ); LWMEnd; LWMIndexList( ); LWMAreaFill( ); LWMAreaDrawPoly( ); LWMPoly( ); LWMPoly3( ); Examples

The following instructions generate FS2002 and FS2004 terrain data.
This document only describes the format of the SCASM instructions. You will also need the Microsoft® FS2002 terrain SDK for information about how to use the instructions. In most cases the SCASM instruction names are similar to the names used in the SDK.
Dwx() type instructions are allowed in the terrain data area.
You must use labels from the type ":cell00" to indicate the begin of a data cell, where "00" is the SCASM internal cell counter.

For the FS terrain database the world is divided into columns and rows of different sizes. The size depent on the LOD (Level of Detail) factor. The VTP/LWM section uses LOD8 which is 768 colums and 512 rows. The first cell is located at 90 deg. North and 180 deg West. To calculate the cell position use the following formula:

col = int((Lon + 180) * 768 /360)
row = int((90 - Lat) * 512 / 180)

Now the undocumented FS2002 ChildPoints and the new FS2004 LWL structures are added. Unfortunately I had to expand the format of the VTPFileHeader and LWMFileHeader instructions.

2.91 - FS2002/4

VTPFileHeader( version )

This command indicates the begin of the ground texture data section. This instruction creates references to the labels ":Index" and ":TextureList" which are resolved by the instructions VTPIndexList and VTPTextureList.

version

The version number of this header.
0x100 for both FS versions

2.90 - FS2002

VTPEnd

This command indicates the end of the ground texture data section. This command is SCASM specific.

2.90 - FS2002

VTPArea( layercnt m u v )

Called VTPDataArea in the FS2002 SDK.

layercnt	Number of layers in this area (max 32).
m	Polygon method according to the SDK: 0 = method "1" 1 = method "2"
u	Column location relative to the cell.
v	Row location relative to the cell.

The FS2002 scenery SDK says that the u and v value should be set to "0" when using data storing method 2. But when you are using the undocumented child points VTPCPoint(), these parameters define the LOD8 position within the LOD3 grid and you have to set it or FS will not show your elements. In adition to this, it is observed that the MS program "TMFViewer" will show your elements only if the u and v values are set!
Since LOD8 is 1/32 LOD3 we can use the lower 5 bits of the corresponding Cell-ID column and row values.
There are 2 ways to calculate these values:
using bit operators: u = collumn AND 31
using normal math operators: u = collumn MOD 32

2.90 - FS2002/4

VTPLayer( lyr rep txcnt res )

This command is a combination of the SDK structures VTPLayer and VTPTexturesInLayer.

lyr

Layer ID 0...63 (100 ?)

Layer numbers, overview:

Water Texture	0 - 3
Land Texture	4 - 7
General	8 - 100

Layer numbers used:

	FS2002	FS2004
Rivers / Streams	16	4
Elecricity pylons	n/a	4
Railroads	n/a	5
Dirt and Minor Roads	31	6
Major Roads	32	6
Aiport Skirtings and Parks	4	7
VTP bridges	n/a	7
Shorelines	8	8

rep

Replace flag.
0 = coexist with existing data in the same layer.
1 = replace existing data in this layer.

txcnt

Texture count (1...127). Textures in this layer.

res

Reserved, must be 0.

2.90 - FS2002

VTPTexID( id r )

This command selects a texture from the texture list.

id	Texture ID (0...127)
r	Reserved, must be 0.

2.91 - FS2002/4

VTPPolyCount( cnt )

This command specifies the number of polygons to be drawn with the selected texture.
Note: There are 2 changes in this instruction:
The reserve parameter (r) used in previous versions has been removed.
The number of polygons is not longer limited to 127.

cnt	Number of the following polygons

2.90 - FS2002

VTPPoly( m pcnt flag )

This command is a combination of the SDK structures VTPPollyMethod1, VTPPolyMethod2 and their extension fields. The parameter pcnt must match with the number of following point commands.
If method 1 is selected only VTPPointXYUV() can be used.

m

Method, "1" or "2"

pcnt

Point counter

flag

Method 1:	0 = Fan, 1 = Strip
Method 2:	0 = Fan, 1 = Line

2.90 - FS2002/4

VTPWPoint( x y c [w] )

VTPWidePoint for method 2 lines. These points have optional width information.

x	Column offset in the area
y	Row offset in the area
c	ChildPoint counter. If this value is not 0 it indicates the number of the following child points. The maximum of the following child points is 7. If more points are needed an VTPWPoint() has to be inserted.
w	Optional width parameter. Use it for every first point in a line and whenever you want to change the width.

2.91 - FS2002/4

VTPCPoint( x y [w] )

VTPChildPoint for method 2 lines.
These points can have an optional width information.
Child points must be announced by a leading VTPWPoint() with the correct child point counter set. In adition to this you also need to set u and v parameters in the VTPArea() command though the FS2002 SDK says these should be 0!. See the note in VTPArea() for details.

x	Relative column offset from the previous specified point in the area (+1023...-1023).
y	Relative row offset from the previous specified point in the area (+1023...-1023).
w	Optional width parameter. Use it whenever you want to change the width.

2.90 - FS2002

VTPPointXY( x y )

Point command to use with method 2 polygon fans.

x	Column offset in the area
y	Row offset in the area

2.90 - FS2002

VTPPointXYUV( x y u v )

Point command with explicite U and V values for use with method 1 polygons.

x	Column offset in the area (0 ... 255)
y	Row offset in the area (0 ... 255)
u	Column offset in the texture
v	Row offset in the texture

2.90 - FS2002

VTPIndexList( n u v r ... )

This command is a combination of the SDK stuctures VTPIndexHeader, VTPIndexEntry and VTPCellID. To make this command work correctly you have to specify labels in your source text to mark the begin of every data cell. The first label must be ":cell00" where 00 is the start value of the cell counter. This command builds an index table to your cell data.
This command also generates the label ":Index" for internal use with the VTPFileHeader command.

n	Number of entries in this list (u-v-r groups).
u	Column (0 ... 767) in the 768*512 world grid.
v	Row (0 ... 511)
r	Reserved, dummy value, must be 0.

2.91 - FS2002/4

VTPTextureList( n "t_name" fmt effect res size ["e_name"]... )

This command is a combination of all SDK structures needed to generate the texture list.
This command also defines the label ":TextureList" which is needed by the VTPFileHeader command.
Note: SCASM 2.90 does not handle effect names.

n	Number of texture entries in this list.
t_name	Texture name string.
fmt	Texture format ... please see FS2002 SDK for details.
effect	Effect flag. Indicates that an effect is used and the name on the effect will follow. 0 = no effect, 1 = use effect with this texture
res	Reserved, must be 0
size	Meters per pixel
e_name	Name of an effect associated with this texture. You also have to set the "effect" flag.

Land / Water Mask data

2.91 - FS2002/4

LWMFileHeader( version )

This command indicates the begin of the Land/Water Mask data section. This instruction creates a reference to the label ":Index" which is resolved by the command LWMIndexList.

version

The version number of this header.
0x100 for CFS2 (not tested)
0x201 for FS2002
0x300 for FS2004

2.90 - FS2002

LWMEnd

This command indicates the end of the LWM data section. This command is SCASM specific.

2.90 - FS2002

LWMIndexList( n u v atr f cnt ... )

This command is a combination of the SDK stuctures LWMIndexHeader, LWMIndexEntry and LWMCellID. To make this command work correctly you have to specify labels in your source text to mark the begin of every data cell. The first label must be ":cell00" where 00 is the start value of the cell counter. This command builds an index table to your cell data.
This command also generates the label ":Index" which is needed by the LWMFileHeader command.

n	Number of entries in this list (u-v-atr-f-cnt groups).
u	Column (0 ... 767) in the 768*512 world grid.
v	Row (0 ... 511)
atr	Fill attribute 0 = water 1 = land 2 = flatten 3 = transparent
f	This flag indicates that the run counter is used. When using this feature no cell data are used. But the SCASM internal index and label counter is incremented. You must take this into account when mixing index entries with and without explicite cell data.
cnt	Run counter.

2.90 - FS2002

LWMAreaFill( size type col row [height] )

Fills a subsection of a cell.
This command combines the 5 LWMDataAreaFill?x? commands described in the FS2002 SDK. row and col define the upper left corner of the fill area.
Note: it is reported that the use of this instruction can crash FS2004. Maybe FS2004 does not allow to replace/overwrite this part of its database.

size

Area size to fill, covering area

size:	covering:	column/row range:
1	1x1	0 - 31
2	2x2	0 - 15
4	4x4	0 - 7
8	8x8	0 - 3
16	16x16	0 - 1

type

Fill attribute
0 = water
1 = land
2 = flatten
3 = transparent

col

Column of the fill area

row

Row of the fill area
Note, the column and row range depend on the cell covering area.

height

Area height value in meters, only used if type is water or flatten.

2.90 - FS2002

LWMAreaDrawPoly( n t col row )

Every polygon sequence in a data cell must start with this command.

n	Number of the following polygons.
t	Area type. Should be 3 = transparent according to the SDK but I also found "flatten".
col	Column (0 ... 31)
row	Row (0 ... 31)

2.90 - FS2002

LWMPoly( n t height x y ... x y )

Polygon data. This command is a combination of the SDK structures LWMPoly2, LWMPoly2Ex, and LWMPoint. This is for FS2002 so do not use this command for FS2004 if you have set the LWMFileHeader version to 0x300 !

n	Number of points in this polygon, up to 317.
t	Fill attribute. Only 0 or 1 are allowed! 0 = water 1 = land
height	Height in meters
x	Column (0 ... 255)
y	Row (0 ... 255)

2.91 - FS2004

LWMPoly3( n t MinHeight MaxHeight x y z ... x y z )

FS2004 LWM Polygon data (version 3). Use this command only for FS2004 (and later) and only if you have set the LWMFileHeader version to 0x300 !

n	Number of points in this polygon, up to 317.
t	Fill attribute. Only 0 or 1 are allowed! 0 = water 1 = land
MinHeight	Minimum height (bottom) in meters.
MaxHeight	Maximum height (top) in meters. Set it to the same value than max_height if tilted polygons are not used.
x	Column (0 ... 255)
y	Row (0 ... 255)
z	Fractional altitude difference between min and max height in steps 0 ... 255. Set it to 0 if not used.

2.90 - FS2002

Examples

Example source for adding road lines.

Header( 1  55  53  9  7 )
VTPFileHeader    , version number can be omitted for FS2002

:cell00    ; marks the first data cell
  VTPArea( 1 1 0 0 )
  VTPLayer( 32 0 1 0 )
  VTPTexID( 0 0 )
  VTPPolyCount( 1 )
  VTPPoly( 2 50 1 )  ; Method 2, 50 points, line
    VTPWPoint( 8107  8981 0 1 )
    VTPWPoint( 8107  8981 0 10 )
    VTPWPoint( 8107  8981 0 )
    ...
    VTPWPoint( 8884  8679 0 )
    VTPWPoint( 8922  8649 0  0 )

  VTPIndexList( 1
    402 101 0
  )
  VTPTextureList( 5
    "1162"  2 0 0 4
    "1158"  2 0 0 4
    "1160"  2 0 0 4
    "1052"  2 0 0 4
    "1059"  2 0 0 4
  )
VTPEnd

Example source for adding an FS2002 "flatten" polygon.

Header( 1 ... )
LWMFileHeader( 0x201 ) ; for FS2002

:cell00    ; marks the begin of the first data cell
  LWMAreaDrawPoly( 1 2 22 17 ) ; 1 poly, flatten, col=22 row=17
  LWMPoly ( 3 2 22.5  ; 3 polygon points, flatten, height=22.5m
    255 241
    255 255
    203 255
  )

; add more cells if needed...
; :cell01
; ...

  LWMIndexList ( 1 ; one entry follows
    106 364 3 0 0  ; col, row, transparent
  )

LWMEnd

© Manfred Moldenhauer