SCASM 2.88

FS5 - FS2002 - dynamic scenery commands

  

command index:
 
back to main index
 
Area15( )
End15
LatRef( )
Pattern( )
Exit
SetColor( )
SetPos( )
Heading( )
Sleep
Awaken( )
Hold( )
Gear( )
Turn( )
Jump( )
conditional jumps: If..( )
Call( )
Return
PitchTo( )
BankTo( )
YawTo( )
MoveX( )
MoveY( )
MoveZ( )
Move..( )
Accelerate..( )
StartTimer
MoveToPos1( )
MoveToPos5( )
MoveToPosN( )
TaxiTo( )
MonitorRwy( ) / IfObjectInBox( )
MonitorPos( ) / RefuelBounds( )
Refuel( )
ACS( )
CallDLibObj( )
LandingAbort( )

Most of this document is based on experiments with FS5.0 and so it might happen that some instruction do not work as expected in newer FS versions.

I've ben often asked how to increase the visibility distance of the FS5 dynamic objects. It seems the maximum visibility distance is "hard coded" in the FS5 internal object definition and cannot be changed by any command.
But FS98 and FS2000 uses dynamic objects defined as library objects (file DYNLIB.BGL) and it is possible now to experiment with self made dynamic objects. See CallDLibObj() in this document and the file sca_objl.htm for more information.

The use of D##() expert commands such as Dbx(05) is allowed in the dynamic scenery area.

TOP 

 

FS5 - FS2002
Area15( maxlat minlat maxlon minlon [&] )
Area15( maxlat minlat maxlon minlon [maxlat2 minlat2 maxlon2 minlon2] )
 

This defines an area for the dynamic scenery section. All commands for this section have to appear within Area15() and End15.
Note: There are two boundaries in this instruction. When the first boundary is entered, the scenery is activated and it is released when leaving the second boundary. Therefore the second boundary has to be larger than the first one. If the second boundary is not defined SCASM will set it equal to the first one. If the '&' character is present, the second boundary is set about 1.5 degrees larger than the first one.

According to the FS2000 scenery SDK the second boundary MUST be larger than the first one. There are also some limitations with dynamic sceneries:

  • FS can handle only ONE dynamic scenery at a time.
  • FS2000 can handle only one dynamic scenery Area per BGL (previous versions could handle up to 5 Area15)
  • FS will load the first dynamic scenery which matches the users aircraft position.
  • FS may not handle dynamic scenery correctly if they overlap each other. For this reason you cannot add dynamic scenery to some places where there already exist one in the default database. In older FS versions it was obseved that the distance of the dynamic scenery areas have to be at least 15 seconds of an arc (for inner boundaries ??).
In the FS5.0 default world you cannot add dynamic scenery to the following areas, since they are already occupied.
San Francisco (FS5):
N35:07:31 - N40:48:21, W124:22:15 - W119:37:29
Chicago (FS5):
N38:14:06 - N44:22:52, W90:22:25 - W85:37:39
For FS95 it is very important to define a correct second (outer) boundary.

TOP 

FS5 - FS2002
End15
 

This command marks the end of an section 15 area block and tells SCASM to do some clean ups and calculate the jump distances.


TOP 

FS5 - FS2002
LatRef( lat )
 

This command defines a reference latitude which should be the center latitude of your Area15() scenery block. It should also be the first command in an Area15(). The reference latitude is needed for the correct scaling in east-west direction.
This command is called SET_LAT_ANCHOR in the FS2000 SDK.


TOP 

FS5 - FS2002
Pattern( :Label objectcode traffic_flags mindense )
 

This command defines an object pattern. It seems these instruction also defines an internal control block for every object. So this is probably something like a object (or pattern) control block. If you want to awaken a sleeping process you have to refere to this instruction. (a :Label just in front of this Pattern() )
DO NOT FORGET to insert the "Exit" command just after the last Pattern() instruction ! It is reported that the number of objects in one Area15() is limited to 60 (for FS95?) and they cannot move all at the same time.
For FS98 and FS2000 objects see also CallDLibObj().

:Label  Starting address for commands related to this object.
objectcode  Hexcode or name to define the object. If you want to enter a hex number don't forget the leading 0!
0FE0B  Cessna
0FE0C  Learjet
0FE0D  bigjet (727)
0FE0E  miljet, F18 (military jet, always light gray)
0FE0F  sailboat
0FE10  truck, always yellow
0FE11  helicopter, FS2000
0FE12  new fuel truck, FS2000
others  may cause a crash

traffic_flags  One hex digit. These bits are corresponding to the dynamic scenery option menu.
air traffic
aircraft ground traffic
airport service traffic
traffic outside airport
Recommended values:
aircrafts
truck (sevice trucks)
ships (other trucks)
NOTE: FS2000 does not longer handle these flags separately.
mindense  minimum scenery density at which this object is shown.
Range 0 ... 4 (4 = maximum density)

TOP 

FS5 - FS2002
Exit
 

This marks the end of the pattern definition table or the end of dynamic scenery initialisation.


TOP 

FS5 - FS2002
SetColor( number colorcode attr )
 

Sets the color of some parts of the selected object. Atention, it was reported that some color codes (high numbers) can cause crashes in FS95 !
Note: Since FS98 uses textured dynamic objects the color setting may be different from the table below, even if the textures are disabled. From the BGL code in FS98 Dynlib.BGL it is known that some objects do not use the color parameter passed to them!
If you create your own dynamic objeect library for FS98 or FS2000 these colors codes are available to the object by using LoadSurfaceColor() with local variables 30, 32, 34, 36, 38 up to 3E.

number 
number of an object detail
0...4 in FS5 (see table)
0...7 in FS2000 the numbers depend on the specific object design
colorcode  2 digit hex code for the color.
attr  color attribute code (hex), normal value = F0

Table of FS5 object details:
  Cessna Learjet bigjet miljet sailboat truck
nose fuselage nose - - -
fus.up wings fuselelage - - -
fus.dn tail wings - - -
tail engine tail - - -
wings - engine - - -

TOP 

FS5 - FS2002
SetPos( Lat Lon alt )
 

Sets the position of an object
In FS5 the maximum total distance an object can be moved is 32767 meters (17,7nm) from this point. It seems that this limit does not longer exists in FS98.

Lat  latitude
Lon  longitude
alt  altitude in meters (above MSL).

If you take the altitude from the FS5 menu, remember that this is the ground level plus gear height. If you forgot this the wheels of your dynamic aircraft may appear somewhere below the ground surface. I calculated the following gear heights by comparing the altitude settings in the different BGL sections:

  FS5-FS95  FS98
Cessna  1.221  1.158
Learjet  1.186  1.138
big jet  2.637  2.544
military jet  1.582  -
sail boat  0.0  0.0
truck  1.102  1.102
Helicopter  0.733

 
TOP 

 

Sets the heading of an object


TOP 

FS5 - FS2002
Sleep
 

Stops any action of this object (pattern process) until it is reactivated (->Awaken ) by an other pattern process. Be very carefull with this command. Misplaced Sleep instructions may crash FS5. Never use this as the last instruction. If in doubt place a jump after the sleep even if you never Awaken() this object.


TOP 

FS5 - FS2002
Awaken( :Label )
 

Reactivates the addressed pattern process. You have to address a label at the required pattern definition entry. Do not try to Awaken() non sleeping objects. Do not place a Sleep() command immediately after this one. This can loock up all dynamics. If your scenery does not need more movements at this point use at least a Hold( 2 ) command before putting this object to sleep.


TOP 

FS5 - FS2002
Hold( time )
 

Stops the action of this object for 'time' (integer value) seconds. No Awaken command is needed. I havn't seen any value greater than 255 in original scenerys but it seems that in FS98 larger values will work.


TOP 

FS5 - FS2002
Gear( up | down | number )
 

Moves the gear up or down.
Ignored for objects with fixed gear (as in FS98 Cessna).


TOP 

FS5 - FS2002
Turn( time heading rad )
 

time  time in seconds, integer
heading  new heading in degrees (floatung point). The turning is done to the shortest direction.
rad  turning radius (meters, integer)

TOP 

FS5 - FS2002
Jump( :Label )
 

The programm execution is continued at :Label.


TOP 

FS5 - FS2002
If..( :Label var dezval )
 

The following four commands are conditional jumps. The content of the variable "var" is compared to "dezval".
Possible values for val are:

air trafic checkbox
ground traffic checbox
aircraft service traffic checkbox
traffic outside airports checkbox
dynamic scenery density checkbox
very sparse
sparse
normal
dense
very dense
extremely dense, FS2000
surface wind direction (0...359)
surface wind speed (knots)
time of day in minutes (0...1439)

TOP 

FS5 - FS2002
Ifeq( :Label var dezval )
Jump2B( :Label var dezval )
 

Execute the following commands if the content of var is equal to dezval, otherwise jump.


TOP 

FS5 - FS2002
Ifne( :Label var dezval )
Jump2C( :Label var dezval )
 

Execute the following commands if the content of var is not equal to dezval, otherwise jump.


TOP 

FS5 - FS2002
Iflt( :Label var dezval )
Jump2D( :Label var dezval )
 

Execute the following commands if the content of var is less than dezval, otherwise jump.


TOP 

FS5 - FS2002
Ifgt( :Label var dezval )
Jump2E( :Label var dezval )
 

Execute the following commands if the content of var is greater than dezval, otherwise jump.


TOP 

FS5 - FS2002
Call( :Label )
 

The subroutine at :Label is called. Programm execution is continued there until a Return command appears. The Return command in the subroutine causes the programm to continue with the next command following the Call() instruction.
Since the call stack in the dynamic scenery engine is only 1 level deep you cannot call another subroutine from a subroutine. (No subroutine nesting allowed in FS5 to FS2000).


TOP 

FS5 - FS2002
Return
 

The programm execution is continued with the instruction immediately following the Call()which calls this subroutine.


TOP 

FS5 - FS2002
PitchTo( angle speed )
 
angle  Pitch angle,
+ = nose down
- = nose up
speed  rotating speed in degrees per second (int)
+ = move nose down
- = move nose up

TOP 

FS5 - FS2002
BankTo( angle speed )
 
angle  Bank angle
+ left wing down, right wing up
- left wing up, right wing down
speed  rotating speed in degrees per second (int)
+ move left wing down, right wing up
- move left wing up, right wing down

TOP 

FS5 - FS2002
YawTo( heading speed )
 
heading  new heading angle
speed  rotating speed in degrees per second (int)
+ rotate to the right side (clockwise)
- rotate to the left side

TOP 

FS5 - FS2002
MoveX( time dist )
 
time  time in seconds for this movement, integer
dist  the distance to move (integer)
+ move east
- move west

TOP 

FS5 - FS2002
MoveY( time dist )
 
time time in seconds for this movement
dist  the distance to move, + north, - south

TOP 

FS5 - FS2002
MoveZ( time dist )
 
time time in seconds for this movement
dist the distance to move, + up, - down

TOP 

FS5 - FS2002
MoveXY( time X_dist Y_dist )
MoveXZ( time X_dist Z_dist )
MoveZY( time Z_dist Y_dist )
Move3D( time X_dist Z_dist Y_dist )
 
time time in seconds for this movement, int
X_dist distance to move, + east, - west
Y_dist distance to move, + north, - south
Z_dist distance to move (int), + up, - down

TOP 

FS5 - FS2002
AccelerateX( time rate X_dist )
AccelerateY( time rate Y_dist )
AccelerateZ( time rate Z_dist )
AccelerateXY( time rate X_dist Y_dist )
AccelerateXZ( time rate X_dist Z_dist )
AccelerateZY( time rate Z_dist Y_dist )
Accelerate3D( time rate X_dist Z_dist Y_dist )
 
time time in seconds for this movement, int
rate  this value controls the acceleration. Range 15.0000 ... 0.0002
Often found values are: 2.0, 1.0, 0.5 !
2.0 increasing speed
1.0 constant speed
0.5 decreasing speed
X_dist distance to move, + east, - west
Y_dist distance to move, + north, - south
Z_dist distance to move, + up, - down

TOP 

Dynamic Scenery Instructions for FS98 / FS2000 +

2.12 | FS98 - FS2002
StartTimer
 

This command must be used just before the first MoveToPos1() or MoveToPos5() command to ensure the correct timing of those commands. It seems that this commant must be repeated when a MoveToPos.. sequence is interrupted by any other timer controled istruction as Move.. (Gear() seem to be allowed).
The traditional systen uses a timed XYZ moving system. This command switches to a timed LatLonAlt system. Unfortunately FS can only handle ONE LatLonAlt command at a time and will execute the next one after this one is finished. In the XYZ system up to 34 commands can be handled simulaneously.


TOP 

2.12 | FS98 - FS2002
MoveToPos1( Lat Lon elev pitch bank heading )
 

This command moves the dynamic object from its current position to this new position within 1 second.

elev  new elevation in meters (integer)
pitch  new pitch angle, - nose up, + nose down
bank  new bank angle (floating point number)
+ left wing down, right wing up
- left wing up, right wing down
heading  new heading angle,

TOP 

FS98 - FS2002
MoveToPos5( Lat Lon elev pitch bank heading )
 

This command moves the dynamic object from its current position to this new position within 5 seconds.


TOP 

2.50 | FS98 - FS2002
MoveToPosN( time Lat Lon elev pitch bank heading )
 

This command moves the dynamic object from its current position to this new position within N = time seconds.

time  time to move to the new position
elev  new elevation in meters (integer)
pitch  new pitch angle, - nose up, + nose down
bank  new bank angle (floating point number)
+ left wing down, right wing up
- left wing up, right wing down
heading  new heading angle

TOP 

FS98 - FS2002
TaxiTo( Lat Lon elev heading )
 

This cammand moves the dynamic object in a smooth curve and with an slow speed to this final parking position. Usually this position is identical to that one defined in the SetPos() command for this object.
In the FS2000 SDK this command is called PARK.

elev final elevation in meters (floating point value)
heading final heading

TOP 

FS98 - FS2002
MonitorRwy( :Label Lat Lon elev hdg len wid )
IfObjectInBox( :Label Lat Lon elev hdg len wid )
 

The specified area is monitored. If no other aircraft is in this area a jump to :Label is performed. This command is usually used to check if the runway is free.

elev  Elevation in meters. Since only integer numbers are accepted chose the nearest lower number which fits the runway elevation.
hdg  runway heading in degrees
len  1/2 runway length in meters (integer)
wid  1/2 runway width in meters (integer)

Example:
    ...
:wait
    MonitorRwy( :free Lat Lon  120  57.3  800  25 )
    Hold( 2 )     ; let's wait before try again
                  ; may help to save some framerate
    Jump( :wait ) ; try again
    ;
:free
    ...           ; ok, lets start operation

TOP 

FS98 - FS2002
MonitorPos( Lat Lon rad :Label val2 )
RefuelBounds( Lat Lon rad :Label val2 )
 

This specific spot is monitored. If your aircraft is not there a jump to :Label is performed. See also the Refuel() command.

rad  radius of the tested area in meters
type  available fuel type:
GA fuel
JET fuel
both

TOP 

FS98 - FS2002
Refuel( rate )
 

Move a fuel truck to a position near your aircraft refuling point and then use this command. The fuel truck then moves to a position in front of your aircraft, stops if your tank is not full, and then continues a circle back to the initial position of this command. This command is often found together with MonitorPos().

rate  refueling speed in gal/minute

Example:
    ...
:LAB1
    SetPos(   00:00:00  00:00:00     181.848 )
    Heading(  90.00 )
:LAB2
    MonitorPos( 00:00:00   00:00:00   16 :LAB3  1 )
    Hold( 2 )      ; check refuling position ..
    Jump( :LAB2 )  ;  ..every 2 seconds

:LAB3
    Hold( 5 )
    MoveX(  12   61 )
    Turn(  3   0.00 10 )
    MoveY(  13  129 )
    Refuel( 60 )
    MoveY(  10 -101 )
    ...

TOP 

FS98 - FS2002
ACS( s )
Dbx( 42 s )
 

The new FS98 dynamic objects has an Anti Collision System. For some purposes this system can be switched off. In the default scenery this ACS is usually switched off after an take off of an aircraft and it is usually enabled again just before touch down or lowering the gear. Usually it is also switched off for service trucks just before the TaxiTo() command is used to put them back to the parking area. If 2 dynamic objects come too close together with ACS on the whole dynamic scenery can change to an 'static' scenery. The default for ACS seem to be permanently ON (if not generally disabled from the menu system). Maybe ASC OFF will result in a higher frame rate. The original name in the SDK is ANTI_COLLISION_OFF with parameters TRUE or FALSE.

state
1 = off
0 = ON

TOP 

FS98 - FS2002
CallDLibObj( :Label X Y id0 id1 id2 id3 )
CallDLibObj( :Label X Y "object description" )
 

This command activates an dynamic object from a library file and passes some FS internal parameters to it. It can be used as a replacement of the Pattern() command. The following ID parameters are examples from the FS98 default dynamic object library named DYNLIB.BGL.
For more information about library objects please see sca_objl.htm.

If the scenery is for FS98 or later and if you use SCASM 2.32 or later, it is possible to select the dynamic objects by their text description. Just replace the id0 to id3 values by the text surounded by quotation marks.
See the LibCat() instruction in the OBJLIBS.DOC document for more information.

The ID's are 32 bit hex numbers. These are used to specify the library file and the wanted object in this file

The following ID's are used in FS98 DYNLIB.BGL:
id0  00C2CdA9  for FS98 DYNLIB.BGL
id1  A9E100AA  for FS98 DYNLIB.BGL
id2  596711D0  for FS98 DYNLIB.BGL
id3  ...   
  B1A18300  Cessna
  B1A18301  Lear45
  B1A18305  Helicopter, color parts 0 ... 7
  B1A18307  G_Truck 1 (gas truck)
  B1A18308  G_Truck 2, color parts 0 .. 7

TOP 

FS98 - FS2002
LandingAbort( Lat Lon elev flag v hdg len wid )
D_40( Lat Lon elev flag v hdg len wid )
 

This command will test the runway area defined by hdg/len/wid for other objects and will enter an traffic pattern if this area is occupied. The runway area is checked again after the pattern is finished.
This instruction is found in the landing pattern of an dynamic object aircraft just before lowering the gear (a few hundered feet before runway threshold). The Lat/Lon position is abt. the middle of the runway and the parameters hdg, len and wid should match runway size.

elev  ground elevation in meters (integer)
flag  0 fly left hand pattern
1 fly right hand pattern
the objects current velocity in meters per second (rounded to integer number) 1 kts = 0.5144 m/s
hdg  heading angle of the monitoring box, usually equal to the true runway heading.
len  1/2 of the length in meters (integer)
wid  1/2 of the width in meters (integer)

Example:
    ...
    MoveXY(   67 -2689  273 )
    PitchTo(     3.84     1.64 )
    Move3D(   73 -2618 -184  266 )
    LandingAbort
        ( 39:17:21 -94:42:24 532  0  36 -85.24 705 25 )
    Gear( 1 )
    Move3D(   18 -655  -46   67 )
    PitchTo(     0.00    -1.64 )
    Move3D(    9 -297  -12   30 )
    AccelerateXY(   37 0.5000 -827   87 )
    Return

TOP 

For the variables used in FS98 / FS2000 dynamic scenery library objects please see "Dynamic object parameter block" at the end of OBJLIBS.DOC.

This is a minimal FS5.0 dynamic scenery file:
 
Header( 1  54:20  54:00  8:20  7:30 )
LatRange(       54:00 54:20 )
Area15(  54:20  54:00  8:20  7:30 )
    LatRef( 54:11:13 )
:Cessna_0
    Pattern( :CS0 Cessna 3 0 )
:Cessna_1
    Pattern( :CS1 Cessna 3 0 )
    Exit                ; Do not forget this command !

:CS0
    ; parking Cessna
    SetColor( 0 7 )
    SetColor( 1 7 )
    SetColor( 2 4 )
    SetColor( 3 4 )
    SetColor( 4 4 )
    SetPos( 54:11:19.7494  7:55:01.1519  4.221 )
    Heading( 20 )
    Sleep               ; sleep forever
    Jump ( :CS0 )

:CS1
    SetColor( 0 5 )
    SetColor( 1 5 )
    SetColor( 2 4 )
    SetColor( 3 4 )
    SetColor( 4 4 )
    SetPos( 54:11:17.2821  7:54:56.1099  4.221 )
    Heading( 33.1 )
    Sleep               ; sleep (parking) forever
    Jump( :CS1 )

End15


 

    
TOP © Manfred Moldenhauer