Background controllers operate on an internal timer that starts at 0 when the round starts, and increases by 1 for every game tick. When the timer reaches the controller's start time, then the controller becomes active. When the timer reaches the controller's end time, then the controller deactivates. If a positive looptime is specified for the controller, then the controller's internal timer will reset to 0 when the looptime is reached.
Background controllers must be grouped under a parent BGCtrlDef. You can use multiple BGCtrlDefs to separate the controllers into several groups. Each block of BGCtrlDef and background controllers may be placed anywhere within the [BGDef] section of the DEF file. The general format for these blocks is as follows.
[BGCtrlDef my_controller_name]GLOBAL_LOOPTIME specifies the number of ticks after which the BGCtrlDef should reset its internal timer, as well as the internal timers of all BGCtrls it contains. To disable the looptime, set it to -1 or omit the parameter.
looptime = GLOBAL_LOOPTIME
ctrlID = DEFAULTID_1, DEFAULTID_2, ...
type = CONTROLLER_TYPE
time = START_TIME, END_TIME, LOOPTIME
ctrlID = ID_1, ID_2, ...
(controller-specific parameters here)
DEFAULTID_1, DEFAULTID_2, etc., specify the IDs of background elements to be affected by any BGCtrl that doesn't specify its own list of ctrlIDs. You can list up to 10 ID numbers for this parameter. If the line is omitted, then the default will be to affect all background elements.
START_TIME, END_TIME, and LOOPTIME are the times at which the background controller should start acting, stop acting, and reset its internal timer, respectively. If LOOPTIME is omitted or set to -1, then the background controller will not reset its own timer. (Its timer can still be reset by its parent BGCtrlDef if a GLOBAL_LOOPTIME is specified.) The background controller will be continuously active between START_TIME and END_TIME. START_TIME is required, but if END_TIME is omitted then it will default to the same value as START_TIME (so the controller will be active for 1 tick only).
ID_1, ID_2, etc., specify the IDs of background elements for this controller to act on. This list, if specified, overrides the default list specified in the BGCtrlDef. The maximum number of IDs specifiable is 10.
Below is the list of BGCtrl types and their associated parameters.
As the name implies, this controller does nothing. It is useful mainly for debugging, when you want to quickly disable a controller without commenting the whole thing out. Simply change the type to null and comment out the old type. This controller has no additional parameters.
value = visible_flag Sets the visibility status of the elements.
While active, this controller sets the affected background elements to be invisible (0) or visible (1). Time will still pass for invisible elements (meaning, in the case of animated elements, that the animation will continue to progress even though it can't be seen).
value = enable_flag Sets the enabled status of the elements.
This controller either disables (0) or enables (1) the affected background elements. When an element is disabled, it is invisible and time does not pass for it (so, in the case of animated elements, any animation is paused when it's disabled).
x = vel_x Sets the x-velocity of the elements.
y = vel_y Sets the y-velocity of the elements.
This controller will set the x/y velocity of the affected background elements to the specified values. Velocities are measured in pixels per game tick. You can specify either or both of the x and y parameters. If either is omitted, the element's velocity in that direction will not change.
x = vel_incr_x Changes the x-velocity of the elements by vel_incr_x.
y = vel_incr_y Changes the y-velocity of the elements by vel_incr_y.
This controller will add the specified values to the x/y velocity of the affected background elements. You can specify either or both of the x and y parameters. If either is omitted, the element's velocity in that direction will not change.
x = pos_x Sets the x-position of the elements.
y = pos_y Sets the y-position of the elements.
This controller will set the x/y coordinate of the affected background elements to the specified values. You can specify either or both of the x and y parameters. If either is omitted, the element's coordinate on that axis will not change.
x = x_displacement Displaces the x-coordinate of the elements.
y = y_displacement Displaces the y-coordinate of the elements.
This controller will displace the x/y coordinate of the affected background elements by the specified values. You can specify either or both of the x and y parameters. If either is omitted, the element's coordinate on that axis will not change.
value = action_no Changes the animation displayed by the affected elements to the specified animation number.
value = amplitude, period, offset Changes the amplitude, period, and phase offset for the affected elements' sinusoidal motions in the x-direction.
These values have the same effect as they do for the sin.x background element parameters.
value = amplitude, period, offset Changes the amplitude, period, and phase offset for the affected elements' sinusoidal motions in the y-direction.
These values have the same effect as they do for the sin.y background element parameters.
Notes: Without the ID Placed in the BG, the BGctrl cannot reference the normal, parallax, or anim items.
If PosSet and PosAdd, or VelSet and VelAdd, time= overlap they will be overwriten by the most current, active BGCtrl.
You do not need a BGCtrlDef to add individual BGCtrl items.
Example: None (yet)