M.U.G.E.N, (c) Elecbyte 1999-2010
Documentation for version 1.1 (2010)
Updated 28 July 2010
A background in M.U.G.E.N consists of one or more background elements, and zero or more background controllers. These are combined with stage settings to produce the appearance and functionality of a stage for use in M.U.G.E.N.
The stage settings control general parameters such as the size of the stage, movement of the camera, starting position of characters and camera in relation to the stage, shadow intensity, floor reflections, etc. Most fighting games maintain consistent values of these background parameters across their constituent stages, especially in regards to stage size and camera movement.
A background element is an individual unit of graphical data that is displayed on screen. All the visible parts of the stage are formed out of background elements. Each background element has individual settings for its sprite data, transparency, location, tiling, scroll speed with respect to the camera, and animation (if applicable). "Parallaxing" elements add a raster effect when scrolling the camera. Background elements may be of any size, although in practice, backgrounds are usually pieced together from several moderately-sized elements.
A background controller will perform additional manipulations on a background element, such as change its position or velocity, make it invisible or invisible, etc. Applications of background controllers include making characters stroll back and forth in the background, having debris fly across the screen, or creating changes in the background at set times (such entering a cave when the characters are fighting on a ship). In general, background controllers may allow you to create more advanced effects for a stage or optimize certain animations to reduce memory consumption, although many stages will do quite well without any controllers at all.
When creating a stage, you must assure that the visible area on the screen is "covered" by background elements at all times. Leaving holes in the background will cause a hall-of-mirrors effect in that location. Enabling the debugbg parameter will fill all holes with a bright shade of magenta, which should assist you in locating and fixing them.
Besides the obvious use in stages, backgrounds objects are used in M.U.G.E.N for the backgrounds of all system screens such as the title screen and the character select screen, as well as for use in storyboards. These types of backgrounds are referred to as "system backgrounds" and "storyboard backgrounds" respectively. Background objects used for stages are called "stage backgrounds". Besides their intended use, there is essentially no difference between the different types of backgrounds. This document covers stage settings as well as the background object format.
Stage settings define the background's relationship with the stage. The stage settings must be in the same stage file as the background. There are several groups that make up the settings. They are:
(all parameters are required unless specifically marked as "optional")
This parameter sets the target version number of M.U.G.E.N that the stage is designed for. Valid values are 2002,02,14, 1.0 or 1.1. Defaults to 2002,02,14.
A version number of 2002,02,14 restricts camera movement to whole units of the stage coordinate space, whereas 1.0 and higher allows the camera position to assume fractional values.
A background is made up of one [BGDef] group and one or more [BG] groups. The [BG] groups are called background elements.
Exactly one BGDef group is required in the stage's DEF file. An example of the format:
[BGDef] spr = my_stage.sff debugbg = 0
Replace my_stage.sff with the name of the SFF file containing your stage's sprite data. The SFF file should be placed in the same directory as the stage DEF (i.e. stages/). If debugbg is set to 1, the screen is cleared to magenta before the stage is drawn. This makes "holes" in the background more apparent. To improve runtime speed, set debugbg = 0 before releasing a stage for distribution.
Once the BGDef definition is created, everything below it in the DEF file is considered to belong in the BGDef section. In the BGDef section, you should specify one or more background elements. Background elements are drawn in the order they appear in the DEF file (with later elements drawn over earlier elements), so the rearmost elements should be defined first.
An example for specifying a static background element is as follows.
[BG my_element_name] type = normal spriteno = 0,0 start = 0,0 delta = .5, .5 mask = 0
This example displays sprite 0,0 from the background's SFF file at an initial position of 0,0. For each unit of camera movement, the sprite will move .5 stage units.
Every background element is defined by a group starting with a header [BG my_element_name]. my_element_name should be replaced with a distinct and descriptive name, as the group header is what will be displayed in error messages.
Parameters are to be specified in the lines following the group header.
The format for specifying an animated background element is almost exactly the same as for a normal background element. The differences are described below.
[BG my_animated_element] type = anim actionno = 55
All other parameters other than spriteno are the same as for static background elements.
First, for the element to animate, a type of anim must be specified. Second, an "action number" (actionno) must be specified. This replaces the spriteno parameter that would be used for a normal background element. The value of actionno must be for an animation that is defined in the DEF file. In this example, since actionno is 55, Action 55 must be defined in a manner similar to the following:
[Begin Action 55] 0,0,0,0,5 0,1,0,0,5
The format is the same as specifying animations in the AIR file, so details will be omitted here. The Action definition can be placed anywhere below the original [BGDef] group. Typical strategies are either to define the action immediately after the element it belongs to, or else to collect all the stage's actions together at the beginning or end of the [BGDef] group.
Note that each sprite you specify in the animation has its own axis (specified in the SFF file). During animation playback, the axis of each sprite will be lined up to correspond with the axis of the background element itself.
The effect of the tilespacing parameter is different for anim-type elements compared to normal-type elements. For a normal element, the x-value of this parameter specifies the horizontal distance between the right edge of the first tile and the left edge of the second tile. In the case of an anim element, the x-value specifies the horizontal distance between the left edge of the first tile and the left edge of the second tile. This applies similarly for the y-value. The reason for the difference is because the size of an anim is not necessarily constant. tilespacing is required for anim-type elements that use the tile parameter.
Animated elements always have mask = 1 and cannot be set to non-masked.
Parallaxing background elements give the illusion of depth for elements that appear to face upwards or downwards. Parallaxing background elements may consist of a single sprite specified by the spriteno parameter. In Version 1.1 and higher, parallax elements may be animated by specifying actionno like in ordinary animated background elements. Animated parallax may not be used with the xscale parameter.
An example of the format is as follows:
[BG my_parallax_element] type = parallax spriteno = 10, 0 width = 300, 600 scalestart = 1,1 scaledelta = 0,.001
Another example:
[BG my_parallax_element] type = parallax spriteno = 10, 0 xscale = 1,1.5 yscalestart = 100 ;Deprecated! yscaledelta = 1.2 ;Deprecated!
Parameter descriptions follow:
top_xscale and bottom_xscale respectively scale the horizontal delta of the background element's top and bottom edge to create a horizontal shearing effect. For example, delta = .75, .75 amd xscale = 1, 2 specifies the top of the sprite would move at .75 * 1 = .75 stage units per camera unit, and the bottom would move at .75 * 2 = 1.5 stage units per camera unit. This example assumes the sprite axis is at the top of the sprite.
Either xscale or width is required, but not both at the same time. Use xscale if the sprite has already been preprocessed for perspective distortion. Hardware accelerated rendering will have visual artifacts at extreme shear angles.
Animated parallax may not be used when xscale is used.
This deprecated parameter controls the change in vertical scale of the element as the camera moves vertically. Its functionality is replaced by the general-purpose scalestart and scaledelta advanced parameters.
yscalestart is the inverse of the vertical scale of the sprite when the camera is at ground level, represented in percentage. For example, a value of 100 corresponds to a scale factor of 1, and 50 corresponds to a scale factor of 2. The value defaults to 100.
Specifies the amount to add from the inverted scale factor for every camera unit the camera moves down, represented in percentage. The final scale factor is calculated using the following formula:
scale = 1 / (yscalestart/100 + yscaledelta/100 * camera_y)
In the example above, if the camera moves up by one unit, the scale factor will be 1 / (1.00 + .012 * -1) = 1.012, and if it moves up another unit, the scale will be 1 / (1.00 + .012 * -2) = 1.025 and so on.
The unintuitive behavior for the yscalestart and yscaledelta parameters is the reason for deprecating these parameters in favor of the scalestart and scaledelta parameters.
Other parameters for static elements are also valid for parallax elements, with the exception of tilespacing. Additionally, y_tile is ignored and forced to be 0.
The result of specifying an angle in an animated parallax element is undefined.
The software renderer does not support animated parallax.
These optional parameters can be added to any background element.
Specifies the type of transparency blending to perform on the sprite. Transparency modes are default, none, add, sub. Respectivelty, these specify default behavior, no transparency, color addition and color subtraction. default and none both cause non-animated elements to be drawn without any tranparency blending. For animated background elements, default will use anim-specific transparency while other values of trans will override the transparency flags in the anim. If add is specified, the alpha parameter may be used to control the blending. Defaults to default.
Note: If mugenversion is less than 1.0, none will behave the same as default for animated elements.
Besides normal, anim and parallax background types, there is also a dummy type. As its name implies, a dummy-type background has no associated graphics. A dummy element's position is affected just like any other element type. A dummy element with an ID parameter may serve as a placeholder for the effect of the zoffsetlink parameter in the StageInfo group.
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] looptime = GLOBAL_LOOPTIME ctrlID = DEFAULTID_1, DEFAULTID_2, ... [BGCtrl my_controller_1] type = CONTROLLER_TYPE time = START_TIME, END_TIME, LOOPTIME ctrlID = ID_1, ID_2, ... (controller-specific parameters here) [BGCtrl my_controller_2] (etc.)
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.
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.
null
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.
Visible
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).
Enabled
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).
VelSet
Sets the x-velocity of the elements.
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.
VelAdd
Changes the x-velocity of the elements by vel_incr_x.
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.
PosSet
Sets the x-position of the elements.
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.
PosAdd
Displaces the x-coordinate of the elements.
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.
Anim
Changes the animation displayed by the affected elements to the specified animation number.
SinX
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.
SinY
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.
Suppose we want to make a person walk back and forth from (-300,0) to (300,0), right behind the main characters. We'll use background controllers to accomplish this task.
First, define the walking animations. Say that the character's walking sprites are 10,0 through 10,3 and that they face to the right.
; Walk right [Begin Action 10] 10,0,0,0,6 10,1,0,0,6 10,2,0,0,6 10,3,0,0,6 ; Walk left [Begin Action 11] 10,0,0,0,6,H 10,1,0,0,6,H 10,2,0,0,6,H 10,3,0,0,6,H
Now start the character off at the far left edge of his range.
[BGDef] (...) [BG Peregrinator] type = anim actionno = 10 id = 10 start = -300, 0 delta = 1,1
Let's give Peregrinator a comfortable ambling speed of 2 pixels per tick. The one-way distance for his walk is 600 pixels, which will take 300 ticks. In total, it'll take him 600 ticks to make the round trip. Using this knowledge, set up the background controllers appropriately: since the entire situation repeats every 600 ticks, we can set the global looptime to 600.
[BGCtrlDef Peregrinator] ; reset the whole deal every 600 ticks. looptime = 600 ctrlID = 10 ; Set velocity of 2 pixels/sec rightward at time 0. [BGCtrl Walk Right] type = VelSet time = 0 x = 2 ; Set velocity of 2 pixels/sec leftward at time 300. [BGCtrl Walk Left] type = VelSet time = 300 x = -2
And that's it! You can make the walk look better by having Peregrinator slow down and display a turning animation at each end of his walk. This would entail use of the VelAdd and Anim controllers. If you want Peregrinator to stop and start at regular intervals as he goes from one end to the other, you could create more VelSet and Anim controllers with their own individual looptimes (to get the behavior to repeat at regular intervals).