Difference between revisions of "M.U.G.E.N Documentation:Background Documentation"

From mugen-net
Jump to navigation Jump to search
(→‎Reflection Group: Added undocumented intensity for reflections)
(Replaced content with "; Definition of new stage ; *** You need create & select sff file before test. ; This default values can be edited in EmptyStage.def. ;-------------------------------------------------------- [Info] name = "Stage00" displayname = "Stage00" versiondate = 09,30,2009 mugenversion = 1.0 author = "Elecbyte" ;------------------------------------- [BGdef] spr = debugbg =0 ;-------------------------------------------------------- [Music] bgmusic = bgmvolume = 100 ;----...")
Tags: Replaced Reverted
Line 1: Line 1:
[[Category:M.U.G.E.N Documentation]]
; Definition of new stage
<div class="document">
; *** You need create & select sff file before test.
; This default values can be edited in EmptyStage.def.


<div id="background-stage-documentation" class="section">
;--------------------------------------------------------
[Info]
name = "Stage00"
displayname = "Stage00"
versiondate = 09,30,2009
mugenversion = 1.0
author = "Elecbyte"


= [[#id1|Background / Stage Documentation]] =
;-------------------------------------
[BGdef]
spr =
debugbg =0


M.U.G.E.N, (c) Elecbyte 1999-2010
;--------------------------------------------------------
[Music]
bgmusic =
bgmvolume = 100


Documentation for version 1.1 (2010)
;--------------------------------------------------------
[Camera]
startx = 0
starty = 0
boundleft = -125
boundright = 125
boundhigh = -25
boundlow = 0
verticalfollow = .2
floortension = 0
tension = 50
overdrawhigh = 0
overdrawlow = 0
cuthigh = 35
cutlow = 25


Updated 28 July 2010
;--------------------------------------------------------
[PlayerInfo]
;--- Player 1 ---
p1startx = -70
p1starty = 0
p1facing = 1
;--- Player 2 ---
p2startx = 70
p2starty = 0
p2facing = -1
;--- Common ---
;Don't change these values.
leftbound  = -1000 ;Left bound (x-movement)
rightbound =  1000 ;Right bound


</div>
;--------------------------------------------------------
<div id="overview" class="section">
[Bound]
screenleft = 15    ;Dist from left of screen that player can move to
screenright = 15  ;Right edge


= [[#id2|Overview]] =
;--------------------------------------------------------
[StageInfo]
zoffset = 190
autoturn = 1
resetBG = 1
localcoord = 320, 240
xscale = 1
yscale = 1


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.
;--------------------------------------------------------
[Shadow]
intensity = 96
color = 0,0,0
yscale = .3
fade.range = 0,0


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.
;--------------------------------------------------------
[Reflection]
intensity = 0


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). &quot;Parallaxing&quot; 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.
;----------
[BG 0]
type  = normal
spriteno = 0, 0
layerno = 0
start = 0, 0
delta = 1, 1
trans = none
mask  = 0
tile  = 1, 0
tilespacing = 0,0


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.
;----------
 
[BG 1]
When creating a stage, you must assure that the visible area on the screen is &quot;covered&quot; by background elements at all times. Leaving holes in the background will cause a hall-of-mirrors effect in that location. Enabling the <code>debugbg</code> parameter will fill all holes with a bright shade of magenta, which should assist you in locating and fixing them.
type = normal
 
spriteno = 0, 1
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 &quot;system backgrounds&quot; and &quot;storyboard backgrounds&quot; respectively. Background objects used for stages are called &quot;stage backgrounds&quot;. 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.
start = 0, 185
 
delta = 1, 1
 
mask = 0
</div>
velocity = 0, 0
<div id="description-of-stage-settings" class="section">
tile = 1, 0
 
tilespacing = 0, 0
= [[#id3|Description of stage settings]] =
 
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 &quot;optional&quot;)
 
<div id="info-group" class="section">
 
== [[#id4|<code>Info</code> Group]] ==
 
<dl>
<dt><code>name</code> = ''stage_name''</dt>
<dd>This parameter sets the name of the stage. The parameter must be enclosed in double-quotes.</dd>
<dt><code>displayname</code> = ''display_name''</dt>
<dd>This parameter sets the name to display in the stage select list. The parameter must be enclosed in double-quotes. If omitted, defaults to ''stage_name''.</dd>
<dt><code>versiondate</code> = ''version''</dt>
<dd>This parameter sets the version of the stage. The formats accepted are either a date (MM,DD,YYYY) or a x.xx version number, e.g. 1.23. This parameter is for informational purposes and is currently not used by the engine.</dd>
<dt><code>mugenversion</code> = ''mugen_version''</dt>
<dd><p>This parameter sets the target version number of M.U.G.E.N that the stage is designed for. Valid values are <code>2002,02,14</code>, <code>1.0</code> or <code>1.1</code>. Defaults to <code>2002,02,14</code>.</p>
<p>A version number of <code>2002,02,14</code> restricts camera movement to whole units of the stage coordinate space, whereas <code>1.0</code> and higher allows the camera position to assume fractional values.</p></dd>
<dt><code>author</code> = ''author_name''</dt>
<dd>This parameter sets the name of the author of the stage. The parameter must be enclosed in double-quotes. This parameter is for informational purposes and is currently not used by the engine.</dd></dl>
 
 
</div>
<div id="camera-group" class="section">
 
== [[#id5|<code>Camera</code> Group]] ==
 
; <code>startx</code> = ''pos_x''
: Sets the camera's starting <code>x</code>-position. Should be set to 0.
; <code>starty</code> = ''pos_y''
: Sets the camera's starting <code>y</code>-position. Should be set to 0.
; <code>boundleft</code> = ''min_x''
: This is the minimum <code>x</code>-value that the camera can move to. It must be negative. Adjust this value to limit how far left the camera can scroll.
; <code>boundright</code> = ''max_x''
: This is the maximum <code>x</code>-value that the camera can move to. It must be positive. Adjust this value to limit how far right the camera can scroll.
; <code>boundhigh</code> = ''min_y''
: Controls the minimum <code>y</code>-value that the camera can move to. It must be negative. Adjust this value to limit how far up the camera can scroll.
; <code>boundlow</code> = ''max_y''
: Controls the maximum <code>y</code>-value that the camera can move to. It must always be set to 0.
; <code>tension</code> = ''h_dist''
: This is the horizontal distance a player can get from the left and right edges before the camera starts to follow.
; <code>tensionhigh</code> = ''top_dist'' ; (Version 1.1 and higher)
: This is the vertical distance a player can get from the top edge before the camera starts to follow. The use of the <code>tensionhigh</code> and <code>tensionlow</code> parameters activates a method of vertical scrolling based on edge tension introduced in Version 1.1. If <code>tensionhigh</code> and <code>tensionlow</code> are specified, <code>verticalfollow</code> and <code>floortension</code> will be ignored.
; <code>tensionlow</code> = ''bottom_dist'' ; (Version 1.1 and higher)
: This is the vertical distance a player can get from the bottom edge before the camera starts to follow.
; <code>verticalfollow</code> = ''closeness''
: This value affects the vertical movement of the camera to follow the highest player. It should be set between 0 and 1. A value of 0 means the camera does not move up at all. A higher value makes the camera track the higher player closer. A value of 1 makes the camera track the player as close as possible. This parameter is ignored if <code>tensionhigh</code> and <code>tensionlow</code> are used.
; <code>floortension</code> = ''v_dist''
: This is the minimum vertical distance the highest player has to be from the floor (given as a positive value), before the camera starts to move up to follow him. This parameter is used only with the <code>verticalfollow</code> camera scrolling mode. This parameter is ignored if <code>tensionhigh</code> and <code>tensionlow</code> are used.
; <code>overdrawhigh</code> = ''top_pixels'' ; (Version 1.0 and higher)
: See below.
; <code>overdrawlow</code> = ''bottom_pixels'' ; (Version 1.0 and higher)
: Number of pixels beyond the top and bottom of the screen that may be drawn. Overdraw specifies the how much can be seen during an EnvShake. Overdraw pixels will also be used when the screen aspect is taller than the stage aspect.
; <code>cuthigh</code> = ''top_pixels'' ; (Version 1.0 and higher)
: See below.
; <code>cutlow</code> = ''bottom_pixels'' ; (Version 1.0 and higher)
: Number of pixels into the top and bottom of the screen that may be cut from drawing when the screen aspect is shorter than the stage aspect. These parameters suggest a guideline, and the actual number of pixels cut depends on the difference in aspect. If <code>cuthigh</code> and <code>cutlow</code> are omitted, the engine will attempt to guess a reasonable set of values.
; <code>startzoom</code> = ''start_zoom_scale'' ; (Version 1.1 and higher)
: This specifies the initial scale factor for the stage. The effect of this parameter is most visible if there are no characters that affect the camera. Defaults to 1.
; <code>zoomout</code> = ''zoom_out_scale'' ; (Version 1.1 and higher)
: This specifies the scale factor for the stage when the camera is fully zoomed out. Note that a smaller number allows the camera to zoom out more, e.g. <code>zoomout = .5</code> specifies that the camera can zoom outwards by a factor of 2. Defaults to 1.
; <code>zoomin</code> = ''zoom_in_scale'' ; (Version 1.1 and higher)
: This specifies the scale factor for the stage when the camera is fully zoomed in. Defaults to 1.
 
 
</div>
<div id="playerinfo-group" class="section">
 
== [[#id6|<code>PlayerInfo</code> Group]] ==
 
; <code>p1startx</code> = ''x_start''
: Sets the starting <code>x</code>-position for Player 1.
; <code>p1starty</code> = ''y_start''
: Sets the starting <code>y</code>-position for Player 1.
; <code>p2startx</code> = ''x_start''
: Sets the starting <code>x</code>-position for Player 2.
; <code>p2starty</code> = ''y_start''
: Sets the starting <code>y</code>-position for Player 2.
; <code>p1facing</code> = ''facing_flag''
: Controls which way Player 1 faces at the start. Set to 1 to face right, or -1 to face left.
; <code>p2facing</code> = ''facing_flag''
: Controls which way Player 2 faces at the start. Set to 1 to face right, or -1 to face left.
; <code>leftbound</code> = ''x_min''
: Sets the minimum allowable <code>x</code>-position for all players.
; <code>rightbound</code> = ''x_max''
: Sets the maximum allowable <code>x</code>-position for all players.
 
 
</div>
<div id="bound-group" class="section">
 
== [[#id7|<code>Bound</code> Group]] ==
 
; <code>screenleft</code> = ''min_dist_left''
: Minimum allowable distance between players and the left edge of the screen. Must be positive.
; <code>screenright</code> = ''min_dist_right''
: Minimum allowable distance between players and the right edge of the screen. Must be positive.
 
 
</div>
<div id="stageinfo-group" class="section">
 
== [[#id8|<code>StageInfo</code> Group]] ==
 
; <code>zoffset</code> = ''v_dist''
: ''v_dist'' is the vertical distance of the ground level from the top of the screen, given in pixels. The <code>zoffset</code> parameter is inappropriately named, but has been left unchanged for compatibility purposes.
; <code>zoffsetlink</code> = ''elem_ID''
: If this parameter is specified, it links the <code>zoffset</code> value to the <code>y</code>-position of a background element with the specified ID number. For example, you can link the value to a dummy element (see [[#other-background-element-types|Other background element types]]) with a <code>sin.y</code> parameter to make the characters bob up and down in a sinusoidal fashion.
; <code>autoturn</code> = ''turn_flag''
: Leave this parameter to 1 to make characters automatically turn to face each other. Setting this to another value will cause undesirable behavior.
; <code>resetBG</code> = ''reset_flag''
: If set to 1, backgrounds will be reset between rounds. If set to 0, backgrounds will continue playing.
; <code>localcoord</code> = ''width'', ''height''
: Dimensions of the coordinate space of the stage. Defaults to 320, 240 if omitted.
; <code>xscale</code> = ''xscale''
: Horizontal scaling factor of offsets, velocities, sprites and animations.
; <code>yscale</code> = ''yscale''
: Vertical scaling factor of offsets, velocities, sprites and animations.
 
 
</div>
<div id="shadow-group" class="section">
 
== [[#id9|<code>Shadow</code> Group]] ==
 
; <code>intensity</code> = ''darkness_val'' ;(optional) (int)
: This controls how dark the shadow is. Valid values range from 0 (lightest) to 256 (darkest). Defaults to 128 if omitted.
; <code>color</code> = ''r,g,b'' ;(optional) (deprecated)
: This parameter is no longer supported as of M.U.G.E.N 1.1 and will be ignored.
; <code>yscale</code> = ''scale_y'' ;(optional) (float)
: This is the vertical scale factor of the shadow. Use a larger ''scale_y'' to make the shadow longer. You can use a negative ''scale_y'' to make the shadow fall on the other side of the players. Defaults to <code>0.4</code> if omitted.
; <code>fade.range</code> = ''top_y, bot_y'' ;(optional) (int, int)
: This parameter lets you set the range over which the shadow is visible. It is used to create an effect of the shadow fading as the player gets farther away from the ground. The first value is the high level, and the second is the middle level. Both represent y-coordinates of the player. A shadow is invisible if the player is above the high level, and fully visible if below the middle level. The shadow is faded in between the two levels. If omitted, defaults to no effect (shadow is always fully visible). Take note that y-coordinate values are negative, and TOP_Y should be less than BOT_Y.
; <code>xshear</code> = ''shear'' ;(optional) (float)
: Specifies the amount of horizontal shearing to apply to the shadow. A positive value shears the shadow to the left of the screen. Defaults to <code>0</code>.
 
 
</div>
<div id="reflection-group" class="section">
 
== [[#id10|<code>Reflection</code> Group]] ==
 
; <code>reflect</code> = ''reflect_flag'' ;(optional)
: Set <code>reflect</code> to 1 to enable reflection shadows, 0 to disable them. Reflection shadows create a &quot;shiny floor&quot; effect. Defaults to 0 if omitted.
; <code>intensity</code> = ''opacity_val'' ;(optional, undocumented) (int)
: This controls how opaque the reflection is. Valid values range from 0 (invisible) to 256 (fully opaque). Defaults to 128 if omitted.
 
 
</div>
<div id="music-group" class="section">
 
== [[#id11|<code>Music</code> Group]] ==
 
; <code>bgmusic</code> = ''bgm_filename'' ;(optional)
: ''bgm_filename'' is the name of the music file to play in the stage. Music files are usually put in the <code>sound/</code> directory. Leaving ''bgm_filename'' blank will result in no music being played. If the music file does not exist, no music will be played. To play CD audio, put the track number followed by &quot;.da&quot;. Using a track number of 0 will play a random audio track. For example, to play track 3 from a music CD, use <code>bgmusic = 3.da</code>. If omitted, defaults to no music.
; <code>bgvolume</code> = ''volume_offset'' ;(optional)
: This parameter adjusts the volume of the BGM being played. 0 is normal, negative for softer, and positive for louder (only for mp3, mods and CDA). Valid values are from -255 to 255. If omitted, defaults to 0.
 
 
</div>
 
</div>
<div id="description-of-background-elements" class="section">
 
= [[#id12|Description of background elements]] =
 
A background is made up of one [BGDef] group and one or more [BG] groups. The [BG] groups are called background elements.
 
Exactly one <code>BGDef</code> group is required in the stage's <code>DEF</code> file. An example of the format:
 
<pre class="literal-block">[BGDef]
spr = my_stage.sff
debugbg = 0</pre>
Replace <code>my_stage.sff</code> with the name of the <code>SFF</code> file containing your stage's sprite data. The <code>SFF</code> file should be placed in the same directory as the stage <code>DEF</code> (i.e. <code>stages/</code>). If <code>debugbg</code> is set to 1, the screen is cleared to magenta before the stage is drawn. This makes &quot;holes&quot; in the background more apparent. To improve runtime speed, set <code>debugbg = 0</code> before releasing a stage for distribution.
 
Once the <code>BGDef</code> definition is created, everything below it in the <code>DEF</code> file is considered to belong in the <code>BGDef</code> section. In the <code>BGDef</code> section, you should specify one or more background elements. Background elements are drawn in the order they appear in the <code>DEF</code> file (with later elements drawn over earlier elements), so the rearmost elements should be defined first.
 
<div id="format-of-background-elements" class="section">
 
== [[#id13|Format of background elements]] ==
 
An example for specifying a static background element is as follows.
 
<pre class="literal-block">[BG my_element_name]
type = normal
spriteno = 0,0
start = 0,0
delta = .5, .5
mask = 0</pre>
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 <code>[BG my_element_name]</code>. <code>my_element_name</code> 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.
 
 
</div>
<div id="static-background-element-parameters" class="section">
 
== [[#id14|Static background element parameters]] ==
 
; <code>type</code> = ''normal'' ; (required) (string)
: This specifies that this background element is a static sprite.
; <code>spriteno</code> = ''groupno, imageno'' ; (required) (int, int)
: ''groupno, imageno'' specifies the sprite in the SFF to display for this background element.
; <code>layerno</code> = ''layer'' ; (optional) (int)
: If ''layer'' is 0, the background element will be drawn behind the characters. If ''layer'' is 1, the element will be drawn in front of the characters. Within each layer, background elements are drawn back-to-front in the order they appear in the <code>DEF</code> file. Defaults to <code>0</code>.
; <code>start</code> = ''x,y'' ; (optional) (float, float)
: Specifies the background element's starting position with respect to the top center of the screen. Positive ''x'' values go right; positive ''y'' values go down. The values are given in stage units, which correspond to pixel units in typical use. Defaults to <code>0,0</code>.
; <code>delta</code> = ''dx,dy'' ; (optional) (float, float)
: Specifies how many pixels the background element should scroll for each pixel of camera movement in the horizontal and vertical directions, respectively. Setting <code>delta=1,1</code> will cause the background element to move at the same speed as the camera. 1,1 is an appropriate value for the ground under the characters' feet. For elements off in the distance, use smaller values of <code>delta</code> to create the illusion of depth. Similarly, elements in the foreground (<code>layerno = 1</code>) should usually be given <code>delta</code>s larger than 1. Defaults to <code>1,1</code>.
; <code>mask</code> = ''mask'' ; (optional) (boolean)
: If ''mask'' is set to <code>1</code>, color 0 of the sprite will not be drawn. This is used in drawing objects which are not rectangular in shape. For performance reasons, <code>mask</code> should be set to 0 when not needed. This parameter is ignored for RGB sprites. Defaults to <code>0</code> normally. For historical reasons, ''mask'' will default to <code>1</code> if the <code>trans</code> parameter is set to <code>add</code> or <code>sub</code>.
; <code>tile</code> = ''x_tile,y_tile'' ; (optional) (int, int)
: Specifies if the background element is to be repeated (&quot;tiled&quot;) in the horizontal and/or vertical directions, respectively. A value of 0 specifies no tiling, a value of 1 specifies infinite tiling, and any value greater than 1 will cause the element to tile that number of times. If this line is omitted, no tiling will be performed.
; <code>tilespacing</code> = ''x_spacing,y_spacing'' ; (optional) (int, int)
: If tiling is enabled, this line specifies the space to put between separate instances of the tile in the horizontal and vertical directions, respectively. There is no effect if tiling is not enabled. <code>tilespacing</code> defaults to <code>0,0</code>.
 
 
</div>
<div id="animated-background-elements" class="section">
 
== [[#id15|Animated background elements]] ==
 
The format for specifying an animated background element is almost exactly the same as for a normal background element. The differences are described below.
 
<pre class="literal-block">[BG my_animated_element]
type = anim
actionno = 55</pre>
All other parameters other than <code>spriteno</code> are the same as for static background elements.
 
First, for the element to animate, a type of <code>anim</code> must be specified. Second, an &quot;action number&quot; (<code>actionno</code>) must be specified. This replaces the <code>spriteno</code> parameter that would be used for a normal background element. The value of <code>actionno</code> must be for an animation that is defined in the <code>DEF</code> file. In this example, since <code>actionno</code> is 55, Action 55 must be defined in a manner similar to the following:
 
<pre class="literal-block">[Begin Action 55]
0,0,0,0,5
0,1,0,0,5</pre>
The format is the same as specifying animations in the <code>AIR</code> file, so details will be omitted here. The <code>Action</code> definition can be placed anywhere below the original <code>[BGDef]</code> 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 <code>[BGDef]</code> group.
 
Note that each sprite you specify in the animation has its own axis (specified in the <code>SFF</code> 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 <code>tilespacing</code> parameter is different for <code>anim</code>-type elements compared to <code>normal</code>-type elements. For a <code>normal</code> 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 <code>anim</code> 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. <code>tilespacing</code> is required for <code>anim</code>-type elements that use the <code>tile</code> parameter.
 
Animated elements always have <code>mask = 1</code> and cannot be set to non-masked.
 
 
</div>
<div id="parallaxing-background-elements" class="section">
 
== [[#id16|Parallaxing background elements]] ==
 
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 <code>spriteno</code> parameter. In Version 1.1 and higher, parallax elements may be animated by specifying <code>actionno</code> like in ordinary animated background elements. Animated parallax may not be used with the <code>xscale</code> parameter.
 
An example of the format is as follows:
 
<pre class="literal-block">[BG my_parallax_element]
type = parallax
spriteno = 10, 0
width = 300, 600
scalestart = 1,1
scaledelta = 0,.001</pre>
Another example:
 
<pre class="literal-block">[BG my_parallax_element]
type = parallax
spriteno = 10, 0
xscale = 1,1.5
yscalestart = 100 ;Deprecated!
yscaledelta = 1.2 ;Deprecated!</pre>
Parameter descriptions follow:
 
<dl>
<dt><code>width</code> = ''top_width, bottom_width'' ; (int, int)</dt>
<dd>''top_width'' and ''bottom_width'' respectively specify the top and bottom widths of a trapezoid that has the same height as the sprite used. The sprite will be distorted to match the shape and size of the trapezoid. The ratio of ''top_width'' to ''bottom_width'' affects the amount of shearing as the camera moves horizontally. Use <code>width</code> if the sprite is not preprocessed for perspective distortion. For historical reasons, the x-axis specified in the SFF is ignored. The horizontal center of the sprite is used as the x-axis instead.</dd>
<dt><code>xscale</code> = ''top_xscale, bottom_xscale'' ; (float, float) (deprecated)</dt>
<dd><p>''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, <code>delta = .75, .75</code> amd <code>xscale = 1, 2</code> specifies the top of the sprite would move at .75 * 1 = <code>.75</code> stage units per camera unit, and the bottom would move at .75 * 2 = <code>1.5</code> stage units per camera unit. This example assumes the sprite axis is at the top of the sprite.</p>
<p>Either <code>xscale</code> or <code>width</code> is required, but not both at the same time. Use <code>xscale</code> if the sprite has already been preprocessed for perspective distortion. Hardware accelerated rendering will have visual artifacts at extreme shear angles.</p>
<p>Animated parallax may not be used when <code>xscale</code> is used.</p></dd>
<dt><code>yscalestart</code> = ''yscalestart'' ; (float) (deprecated)</dt>
<dd><p>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 <code>scalestart</code> and <code>scaledelta</code> advanced parameters.</p>
<p>''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.</p></dd>
<dt><code>yscaledelta</code> = ''yscaledelta'' ; (float) (deprecated)</dt>
<dd><p>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:</p>
<pre class="literal-block">scale = 1 / (yscalestart/100 + yscaledelta/100 * camera_y)</pre>
<p>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.</p>
<p>The unintuitive behavior for the <code>yscalestart</code> and <code>yscaledelta</code> parameters is the reason for deprecating these parameters in favor of the <code>scalestart</code> and <code>scaledelta</code> parameters.</p></dd>
<dt>Notes:</dt>
<dd><p>Other parameters for static elements are also valid for parallax elements, with the exception of <code>tilespacing</code>. Additionally, ''y_tile'' is ignored and forced to be 0.</p>
<p>The result of specifying an angle in an animated parallax element is undefined.</p>
<p>The software renderer does not support animated parallax.</p></dd></dl>
 
 
</div>
<div id="advanced-parameters" class="section">
 
== [[#id17|Advanced Parameters]] ==
 
These optional parameters can be added to any background element.
 
<dl>
<dt><code>trans</code> = ''trans'' ; (optional) (string)</dt>
<dd><p>Specifies the type of transparency blending to perform on the sprite. Transparency modes are <code>default</code>, <code>none</code>, <code>add</code>, <code>sub</code>. Respectivelty, these specify default behavior, no transparency, color addition and color subtraction. <code>default</code> and <code>none</code> both cause non-animated elements to be drawn without any tranparency blending. For animated background elements, <code>default</code> will use anim-specific transparency while other values of ''trans'' will override the transparency flags in the anim. If <code>add</code> is specified, the <code>alpha</code> parameter may be used to control the blending. Defaults to <code>default</code>.</p>
<p>Note: If <code>mugenversion</code> is less than 1.0, <code>none</code> will behave the same as <code>default</code> for animated elements.</p></dd>
<dt><code>alpha</code> = ''src_alpha,dst_alpha'' ; (optional) (int, int)</dt>
<dd>Specifies the source and destination blend contributions when <code>trans = add</code>. Acceptable values are from <code>0</code> to <code>256</code>. Defaults to <code>256,256</code>.</dd>
<dt><code>id</code> = ''id_number'' ; (int)</dt>
<dd>This specifies an ID number for the background element. Multiple elements can share the same ID number. The purpose of the ID number is to allow background controllers to specify which elements they are operating on. Defaults to 0.</dd>
<dt><code>positionlink</code> = ''link_flag'' ; (boolean)</dt>
<dd>Set <code>positionlink</code> to 1 to lock this element's position to the position of the element immediately preceding it in the <code>DEF</code> file. If set to 1, the values of the <code>start</code> parameter for the current element are treated as an offset from the previous element's position. The <code>delta</code> parameter will have no effect in this case. This is useful for getting large groups of elements to move in unison; if you edit the <code>start</code> and <code>delta</code> values of the first element in the positionlink chain, the effects will be seen throughout all elements the chain. Defaults to 0.</dd>
<dt><code>maskwindow</code> = ''x1,y1,x2,y2'' ; (int, int, int, int) (Version 1.1 and higher)</dt>
<dd>Specifies a masking window for the background element. A masking window is conceptually a rectangular box on the screen in which the sprite is contained. Any part of the sprite that lies outside of the box will not be drawn. ''x1,y1'' specifies the coordinates of the top-left corner of the window, and ''x2,y2'' specifies the coordinates of the bottom-right corner of the window. These coordinates are relative to the stage origin (top-middle of screen). These coordinates are &quot;endpoint exclusive&quot;, i.e. the pixels along the bottom and right edges of the window will not be drawn. If omitted, window masking will not performed.</dd>
<dt><code>window</code> = ''x1,y1,x2,y2'' ; (int, int, int, int) (deprecated)</dt>
<dd>This deprecated parameter is included for compatibility and the use of it is not guaranteed to work correctly under all cases of zooming. It specifies a masking window with coordinates relative to the top-right corner of the screen. The coordinates are endpoint inclusive.</dd>
<dt><code>windowdelta</code> = ''window_dx,window_dy'' ; (float, float)</dt>
<dd>Specifies the movement delta of the masking window. It works similarly to the <code>delta</code> parameter for the background element itself. Defaults to <code>0,0</code>.</dd>
<dt><code>velocity</code> = ''vel_x, vel_y'' ; (float, float)</dt>
<dd>Specifies initial <code>x</code>- and <code>y</code>-velocities for the background element (these default to 0). This functionality is also subsumed by the <code>VelSet</code> background controller.</dd>
<dt><code>scalestart</code> = ''scale_x, scale_y'' ; (float, float)</dt>
<dd>Starting scale. Defaults to <code>1,1</code>.</dd>
<dt><code>scaledelta</code> = ''scale_dx, scale_dy'' ; (float, float)</dt>
<dd>Similar to the <code>delta</code> parameter, this is the amount to change the scale of the element for each unit of camera movement. Defaults to <code>0,0</code>.</dd>
<dt><code>zoomdelta</code> = ''dzoom'' ; (float)</dt>
<dd>Specifies the amount that the camera zoom affects the scale of the element. A value of 0 is means the element will not change size during zoom, and a value of 1 will scale the element by the same factor of camera zoom. Defaults to <code>1</code>.</dd>
<dt><code>sin.x</code> = ''amplitude, period, phase'' ; (float, float, float)</dt>
<dd>Specifies sinusoidal movement for the element in the <code>x</code>-direction. The first parameter is the amplitude, the second parameter is the period of the motion in game ticks, and the third parameter specifies the initial phase shift of the sinusoidal motion (defaults to 0, i.e., the element will start in the exact middle of its sinusoidal range). This parameter is basically superseded by the <code>SinX</code> background controller.</dd>
<dt><code>sin.y</code> = ''amplitude, period, phase'' ; (float, float, float)</dt>
<dd>Works the same as the <code>sin.x</code> parameter, but in the <code>y</code>-direction.</dd></dl>
 
 
</div>
<div id="other-background-element-types" class="section">
 
== [[#id18|Other background element types]] ==
 
Besides <code>normal</code>, <code>anim</code> and <code>parallax</code> background types, there is also a <code>dummy</code> type. As its name implies, a <code>dummy</code>-type background has no associated graphics. A dummy element's position is affected just like any other element type. A dummy element with an <code>ID</code> parameter may serve as a placeholder for the effect of the <code>zoffsetlink</code> parameter in the <code>StageInfo</code> group.
 
 
</div>
 
</div>
<div id="background-controllers" class="section">
 
= [[#id19|Background controllers]] =
 
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 <code>BGCtrlDef</code>. You can use multiple <code>BGCtrlDef</code>s to separate the controllers into several groups. Each block of <code>BGCtrlDef</code> and background controllers may be placed anywhere within the <code>[BGDef]</code> section of the <code>DEF</code> file. The general format for these blocks is as follows.
 
<pre class="literal-block">[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.)</pre>
<code>GLOBAL_LOOPTIME</code> specifies the number of ticks after which the <code>BGCtrlDef</code> should reset its internal timer, as well as the internal timers of all <code>BGCtrls</code> it contains. To disable the looptime, set it to -1 or omit the parameter.
 
<code>DEFAULTID_1</code>, <code>DEFAULTID_2</code>, etc., specify the IDs of background elements to be affected by any <code>BGCtrl</code> that doesn't specify its own list of <code>ctrlID</code>s. 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.
 
<code>START_TIME</code>, <code>END_TIME</code>, and <code>LOOPTIME</code> are the times at which the background controller should start acting, stop acting, and reset its internal timer, respectively. If <code>LOOPTIME</code> 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 <code>BGCtrlDef</code> if a <code>GLOBAL_LOOPTIME</code> is specified.) The background controller will be continuously active between <code>START_TIME</code> and <code>END_TIME</code>. <code>START_TIME</code> is required, but if <code>END_TIME</code> is omitted then it will default to the same value as <code>START_TIME</code> (so the controller will be active for 1 tick only).
 
<code>ID_1</code>, <code>ID_2</code>, etc., specify the IDs of background elements for this controller to act on. This list, if specified, overrides the default list specified in the <code>BGCtrlDef</code>. The maximum number of IDs specifiable is 10.
 
Below is the list of <code>BGCtrl</code> types and their associated parameters.
 
<ul>
<li><p><code>null</code></p>
<p>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 <code>null</code> and comment out the old type. This controller has no additional parameters.</p></li>
<li><p><code>Visible</code></p>
<dl>
<dt><code>value</code> = ''visible_flag''</dt>
<dd><p>Sets the visibility status of the elements.</p></dd></dl>
 
<p>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).</p></li>
<li><p><code>Enabled</code></p>
<dl>
<dt><code>value</code> = ''enabled_flag''</dt>
<dd><p>Sets the enabled status of the elements.</p></dd></dl>
 
<p>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).</p></li>
<li><p><code>VelSet</code></p>
<dl>
<dt><code>x</code> = ''vel_x''</dt>
<dd><p>Sets the <code>x</code>-velocity of the elements.</p></dd>
<dt><code>y</code> = ''vel_y''</dt>
<dd><p>Sets the <code>y</code>-velocity of the elements.</p></dd></dl>
 
<p>This controller will set the <code>x</code>/<code>y</code> 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 <code>x</code> and <code>y</code> parameters. If either is omitted, the element's velocity in that direction will not change.</p></li>
<li><p><code>VelAdd</code></p>
<dl>
<dt><code>x</code> = ''vel_incr_x''</dt>
<dd><p>Changes the <code>x</code>-velocity of the elements by ''vel_incr_x''.</p></dd>
<dt><code>y</code> = ''vel_incr_y''</dt>
<dd><p>Changes the <code>y</code>-velocity of the elements by ''vel_incr_y''.</p></dd></dl>
 
<p>This controller will add the specified values to the <code>x</code>/<code>y</code> velocity of the affected background elements. You can specify either or both of the <code>x</code> and <code>y</code> parameters. If either is omitted, the element's velocity in that direction will not change.</p></li>
<li><p><code>PosSet</code></p>
<dl>
<dt><code>x</code> = ''pos_x''</dt>
<dd><p>Sets the <code>x</code>-position of the elements.</p></dd>
<dt><code>y</code> = ''pos_y''</dt>
<dd><p>Sets the <code>y</code>-position of the elements.</p></dd></dl>
 
<p>This controller will set the <code>x</code>/<code>y</code> coordinate of the affected background elements to the specified values. You can specify either or both of the <code>x</code> and <code>y</code> parameters. If either is omitted, the element's coordinate on that axis will not change.</p></li>
<li><p><code>PosAdd</code></p>
<dl>
<dt><code>x</code> = ''x_displacement''</dt>
<dd><p>Displaces the <code>x</code>-coordinate of the elements.</p></dd>
<dt><code>y</code> = ''y_displacement''</dt>
<dd><p>Displaces the <code>y</code>-coordinate of the elements.</p></dd></dl>
 
<p>This controller will displace the <code>x</code>/<code>y</code> coordinate of the affected background elements by the specified values. You can specify either or both of the <code>x</code> and <code>y</code> parameters. If either is omitted, the element's coordinate on that axis will not change.</p></li>
<li><p><code>Anim</code></p>
<dl>
<dt><code>value</code> = ''action_no''</dt>
<dd><p>Changes the animation displayed by the affected elements to the specified animation number.</p></dd></dl>
</li>
<li><p><code>SinX</code></p>
<dl>
<dt><code>value</code> = ''amplitude, period, offset''</dt>
<dd><p>Changes the amplitude, period, and phase offset for the affected elements' sinusoidal motions in the <code>x</code>-direction. These values have the same effect as they do for the <code>sin.x</code> background element parameters.</p></dd></dl>
</li>
<li><p><code>SinY</code></p>
<dl>
<dt><code>value</code> = ''amplitude, period, offset''</dt>
<dd><p>Changes the amplitude, period, and phase offset for the affected elements' sinusoidal motions in the <code>y</code>-direction. These values have the same effect as they do for the <code>sin.y</code> background element parameters.</p></dd></dl>
</li></ul>
 
 
</div>
<div id="simple-example" class="section">
 
= [[#id20|Simple Example]] =
 
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.
 
<pre class="literal-block">; 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</pre>
Now start the character off at the far left edge of his range.
 
<pre class="literal-block">[BGDef]
(...)
 
[BG Peregrinator]
type = anim
actionno = 10
id = 10
start = -300, 0
delta = 1,1</pre>
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.
 
<pre class="literal-block">[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</pre>
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 <code>VelAdd</code> and <code>Anim</code> 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 <code>VelSet</code> and <code>Anim</code> controllers with their own individual looptimes (to get the behavior to repeat at regular intervals).
 
 
</div>
 
</div>

Revision as of 11:14, 4 March 2025

Definition of new stage
*** You need create & select sff file before test.
This default values can be edited in EmptyStage.def.
--------------------------------------------------------

[Info] name = "Stage00" displayname = "Stage00" versiondate = 09,30,2009 mugenversion = 1.0 author = "Elecbyte"

-------------------------------------

[BGdef] spr = debugbg =0

--------------------------------------------------------

[Music] bgmusic = bgmvolume = 100

--------------------------------------------------------

[Camera] startx = 0 starty = 0 boundleft = -125 boundright = 125 boundhigh = -25 boundlow = 0 verticalfollow = .2 floortension = 0 tension = 50 overdrawhigh = 0 overdrawlow = 0 cuthigh = 35 cutlow = 25

--------------------------------------------------------

[PlayerInfo]

--- Player 1 ---

p1startx = -70 p1starty = 0 p1facing = 1

--- Player 2 ---

p2startx = 70 p2starty = 0 p2facing = -1

--- Common ---
Don't change these values.

leftbound = -1000 ;Left bound (x-movement) rightbound = 1000 ;Right bound

--------------------------------------------------------

[Bound] screenleft = 15 ;Dist from left of screen that player can move to screenright = 15 ;Right edge

--------------------------------------------------------

[StageInfo] zoffset = 190 autoturn = 1 resetBG = 1 localcoord = 320, 240 xscale = 1 yscale = 1

--------------------------------------------------------

[Shadow] intensity = 96 color = 0,0,0 yscale = .3 fade.range = 0,0

--------------------------------------------------------

[Reflection] intensity = 0

----------

[BG 0] type = normal spriteno = 0, 0 layerno = 0 start = 0, 0 delta = 1, 1 trans = none mask = 0 tile = 1, 0 tilespacing = 0,0

----------

[BG 1] type = normal spriteno = 0, 1 start = 0, 185 delta = 1, 1 mask = 0 velocity = 0, 0 tile = 1, 0 tilespacing = 0, 0

Retrieved from "https://mugen-net.work/wiki/index.php?title=M.U.G.E.N_Documentation:Background_Documentation&oldid=38469"