SCASM 1.4 dynamic scenery instructions addendum, section 15
-----------------------------------------------------------

Assumptions:
------------
The dynamic scenery section contains several objects which are
active (moving) all the time. There is one process for every object (paralell
processing). The status of every process is stored in the pattern definition
table.
The number of simultaneously moving objects may be limited but I have not
tested the limit.

Credits:
--------
Many thanks to Hermann Lange (CIS 100326.142) who decoded the traffic flags
in the Pattern instruction. He also gave me usefull feedback as a beta tester.


Commands:
---------

Area15( maxlat minlat maxlon minlon  [&] )
Area15( maxlat minlat maxlon minlon  [maxlat2 minlat2 maxlon2 minlon2] )
	-
	Format may be expanded in future versions !
	This defines an area for the dynamic scenery section. All commands
	for this section must appear within Area() and End15.
	This works similar to the visual (sect 9) Area() command.
	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 thre second boundary has to be
	larger (or equal). If the second boundary is not defined both are set
	to the same value. If the '&' character is entered the second boundary
	is set about 1.5 degrees larger than the first. According to some
	user reports it seems FS5 can only handle ONE ACTIVE dynamic area. If
	you have more dynamic areas define the boundaries verry carefully
	otherwise FS5 may not switch to new areas.
	In the FS5 default world you cannot add dynamic scenery to the
	following areas, since they are already occupied.
	San Francisco:	N35:07:31 - N40:48:21, W124:22:15 - W119:37:29
	Chicago:	N38:14:06 - N44:22:52,  W90:22:25 -  W85:37:39

End15
	This command marks the end of an section 15 area block and tells SCASM
	to do some clean up work in some instructions.
	-> Area15()

LatRef( lat )
	-
	This command defines a reference latitude. I think it's a good idea
	to take the same value as for the airport reference point. It seems
	these value is needed for the correct scaling in east-west direction.
	Be sure this value is within the maxlat and minlat boundaries.
	This command should be the first after the Area15 definition.
	ATENTION, this value must be within the latitude boundaries defined in
	the AREA15() command.
	
Pattern( :Label objectcode  traffic_flags  mindense )
	-
	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, (military jet F15, always light gray)
			0FE0F   boat (sailboat)
			0FE10   truck, always yellow
			others  may cause a crash
	traffic_flags   One hex digit. These bits are corresponding to the
			dynamic scenery option menu.
			1 -> air traffic
			2 -> aircraft ground traffic
			4 -> airport service traffic
			8 -> traffic outside airport
			Recommended values:
			3 -> aircrafts
			4 -> truck (sevice trucks)
			8 -> ships (other trucks)
	mindense        minimum scenery density at which this object is
			shown. Range 0 ... 4 (4 = maximum density)

	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 !

Exit
	This marks the end of the pattern definition table.
	Maybe this tells FS5 that there are no more pattern processes in
	this area to start.

SetColor( number colorcode [x] )
	-
	number          number of an object detail (0...4), see table
	colorcode       2 digit hex code for the color.
	x               color attributes (hex), default value -> F0

	Sets the color of some parts of the selected object
	------------------------------------------------------------
		Cessna  Learjet  bigjet     miljet  sailboat   truck
	------------------------------------------------------------
	0       nose    fuselage nose       ---     ---        ---
	1       fus.up  wings    fuselelage ---     ---        ---
	2       fus.dn  tail     wings      ---     ---        ---
	3       tail    jet      tail       ---     ---        ---
	4       wings   ---      jet        ---     ---        ---

SetPos( Lat Lon alt )
	Lat     latitude
	Lon     longitude
	alt     altitude (meters/float)
		The altitude setting is always above MSL. It seems the
		altitude definition point of an object is its bottom. That
		means you have to add the height of the gear to the ground
		level (above MSL). If you forgot this your dynamic object may
		appear somewhere below the ground surface. You can check the
		correct settings by viewing the shadow.
		I calculated the following gear heights by comparing the
		altitude settings in the different BGL sections:
		Cessna          1.221
		Learjet         1.186
		big jet         2.637
		military jet    1.582
		sail boat       0.0
		truck           1.102


Heading( degrees )
	Sets the heading of an object i.e. 22.75

Sleep
	Stops any action of this object (pattern process) until it is
	reactivated (->Awaken ) by an other pattern process.
	ATENTION! 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. -> See example.

Hold( time )
	Stops the action of this object for 'time' (integer value) seconds.
	No Awaken command is needed.
	Note: I hav'nt seen any value greater than 255 in original scenerys.

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.
	-> Sleep, -> Pattern()

Gear( up|down|number )
	Moves the gear up or down.

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

Jump( :Label )
	The programm execution is continued at :Label.

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
	after the Call() instruction.
	-> Return

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

Jump..( :Label var/hex val/dez )
	-
	all preliminary! Maybe renamed in future versions.
	These are conditional jumps to :Label.
	The variable(?) number 4 contains the dynamic scenery density code.
	I had no luck when trying to test variables from the normal visual
	area.
	found variable number(s): 4
	found values: 0, 1, 2, 3, 4
	Some/all? of these jumps may have a 2nd jump condition. In the german
	version of FS5.0 it seems the time of day and the air traffic control
	do not influence the jump conditions.

Jump2B( :Label var/hex val/dez )
	-
	condition unknown, probably jump_if_greater_than, GT

Jump2C( :Label var/hex val/dez )
	-
	condition unknown, probably jump_if_less_or_equal, LE

Jump2D( :Label var/hex val/dez )
	-
	This is a guess !
	Not found in any BGL file but accepted by FS5. In my test scenery I
	found the jump was always performed.
	condition unknown

Jump2E( :Label var/hex val/dez )
	-
	condition unknown, probably jump_if_less_or_equal, LE


PitchTo( angle speed )
	angle   Pitch angle (fp)
		+ -> nose down
		- -> nose up
	speed   rotating speed in degrees per second (int)
		+ -> move nose down
		- -> move nose up

BankTo( angle speed )
	angle   Bank angle (fp)
		+ 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

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

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

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

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

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, + up, - down
		int

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
		int


D..()
	You can also use the D##() binary commands. See -> scadoc.txt

; =============================================
;
;       This is a minimal dynamic scenery file. 
;       Helgoland / Duene
;
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

: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
