Lvl bkgrd.ini (Config pack)

From PGE Wiki
Jump to navigation Jump to search

lvl_bkgrd.ini - Defines background images for levels


[ background2-main ]
Parameter Allowed values Example value Description
total >=1 total = 58 Allocate number of BACKGROUND-ID's to define background images
config-dir string config-dir = "items/background" Enables split config mode (using a set of background2-*.ini files in the specified directory instead finding sections in the same INI-file)


Note: in the split mode or in the custom level/episode background2-*.ini config file, section name is always background2.

Settings of each background image (Where '*' - should be a BACKGROUND-ID from 1 to total number of background images)
You should define settings for all allocated BACKGROUND-ID range!

[ background2-* ]
Parameter Allowed values Example value Description
Generic
name string name = "Big field" Title of background
fill-color #HexColor or "auto" fill-color = "#E1F502" Default fill color. Fill color applying to the space where background image is not shown on the screen. "auto" keyword (works by default) means color will be automatically captured from left-top pixel of background image (or left-bottom if Y reference point is top). For multi-layer backgrounds "auto" is black color by default.
Multi-layer background (since PGE Engine 0.3-alpha)
legacy boolean legacy = false Turn off multi-layering background mode and use legacy SMBX background style. Most of general properties are ignored in multi-layer backgrounds, and properties for each layer are used. The background2-*-layer-* or background2-layer-* INI sections will be used to declare settings per every layer.
multi-layer-count uint multi-layer-count = 5 Total count of background layers
Legacy background
type string type = double-row Background model type:

single-row - show single horizontal repeating row at bottom or at top (in dependence of "attached" value),
double-row - two-layer background, show second row at top of first row, or at bottom over first,
tiled - fill screen by horizontal and vertical repeating of image

(ignored for multi-layer backgrounds)
First image
image string image = "background2-24.png" Image filename of background (ignored for multi-layer backgrounds)
repeat-h float >=0 repeat-h = 2 Horizontal parallax coefficient. I.e. how slowly will be moved background concerning edge of the camera. If coefficient equal to 0, the background will be static on screen (ignored for multi-layer backgrounds)
repeat-v string repeat-v = ZR Vertical parallax and repeat formula type:

RP - With repeat, vertical parallax equal to horizontal with parallax coefficient equal to 2
RZ - repeat without parallax
NR - Without repeat, parallax is proportional to section height
ZR - Static: without repeat and without parallax

(ignored for multi-layer backgrounds)
attached string attached = bottom Attachment of background image to side of section:

bottom,
top

(ignored for multi-layer backgrounds)
tiled-in-editor [0,1] tiled-in-editor = 1 Show this background tiled in the editor (ignored for multi-layer backgrounds)
magic [0,1] magic = 1 Enable magic multi-parallax of background (cut image into horizontal strips with differenced parallax coefficient) (ignored for multi-layer backgrounds)
magic-strips >=1 magic-strips = 3 Number of magic parallax strips (ignored for multi-layer backgrounds)
magic-splits Array of integer numbers magic-splits = "49,541,850" List of magic strips separators (value in number of pixels from top to separator) (ignored for multi-layer backgrounds)
magic-speeds Array of float numbers magic-speeds = "1.2,2.1,3" List of horizontal parallax coefficients for each magic strip (ignored for multi-layer backgrounds)
animated [0,1] animated = 0 Enables sprite animation for background (ignored for multi-layer backgrounds)
frames >=1 frames = 4 Number of frames which using by this background (ignored for multi-layer backgrounds)
frame-delay >=1 frame-delay = 128 Delay between animation frames in milliseconds (ignored for multi-layer backgrounds)
frame-speed >=1 frame-speed = 128 Alias to frame-delay (ignored for multi-layer backgrounds)
framespeed >=1 framespeed = 8 Delay between animation frames in 1/65 seconds (ignored for multi-layer backgrounds)
display-frame >=0 display-frame = 0 Show specific frame when animation is disabled (ignored for multi-layer backgrounds)
Second image
second-image string second-image = "background2-27.png" Image filename of second row of background (using only by double-row background) (ignored for multi-layer backgrounds)
second-repeat-h float >=1 second-repeat-h = 4 Horizontal parallax coefficient for second row (using only by double-row background) (ignored for multi-layer backgrounds)
second-repeat-v string second-repeat-v = ZR Vertical parallax type and repeat for second row of double-row background:

RP - With repeat, vertical parallax equal to horizontal with parallax coefficient equal to 2
RZ - repeat without parallax
NR - Without repeat, parallax is proportional to section height
ZR - Static: without repeat and without parallax
(ignored for multi-layer backgrounds)

second-attached string second-attached = overfirst Type of second row of double-row background

overfirst - second row will be drawn higher than normal background row
bottom - second row will be attached to top of section, will be drawn as second layer
top - second row will be attached to bottom of section, will be drawn as second layer

(ignored for multi-layer backgrounds)



Definition of each layer for multi-layer backgrounds. Section name means: background2-X-layer-Y. Where X - is an ID of background that owns this layer, and Y is a code of layer (begin of count is from zero!). For custom configs or split mode INI files the section for every layer will be background2-layer-*.

[ background2-*-layer-* ]
Parameter Allowed values Example value Description
name string name = "Sky" Name of the layer. Optional. Can be shown in the editor or be used as accessing alias to control layer from the PGE lua API.
image string image = "sky.png" Image filename (or relative path) of this layer.
z-value long double z-value = "-50" Absolute Z position of background layer. If value is negative, background will be shown as background. If value is positive - layer will be shown as foreground.
z-index long double z-index = "-50" Alias to "z-value"
priority long double priority = "-50" Alias to "z-value"
in-scene-draw boolean in-scene-draw = "false" Draw this layer together with level scene elements. The z-value will declare z position between scene elements.
opacity double opacity = "1.0" Declares transparency level for the layer. Possible floating point values between 1.0 (solid) and 0.0 (transparent).
flip-h bool flip-h = "false" Flip the background layer horizontally.
repeat-x bool repeat-x = "true" Enable horizontal repeating of background image.
repeat-y bool repeat-y = "false" Enable vertical repeating of background image.
parallax-x bool parallax-x = "1.0"
parallax-y bool parallax-y = "1.0"
parallax-coefficient-x double parallax-coefficient-x = "1.0" Declares horizontal parallax coefficient for this layer. Parallax coefficient declares how slower/faster background image will offset relative to camera motion. Allowed positive non-zero values.

Same as 1.0 / parallax-x, has lower priority than parallax-x and will be overridden by by parallax-x if it was defined.
1.0 - don't parallax (for example, wall on the scene);
<1.0 - parallax faster (near), suggested for foregrounds;
>1.0 - parallax slower (far), suggested for backgrounds.

If parallax coefficient is not defined, it will be equal 1.0, or will be automatically calculated from z-value if auto parallax mode is turned on.
parallax-coefficient-y double parallax-coefficient-y = "1.0" Declares vertical parallax coefficient for this layer. Parallax coefficient declares how slower/faster background image will offset relative to camera motion. Allowed positive non-zero values.

Same as 1.0 / parallax-y, has lower priority than parallax-y and will be overridden by parallax-y if it was defined.
1.0 - don't parallax (for example, wall on the scene);
<1.0 - parallax faster (near), suggested for foregrounds;
>1.0 - parallax slower (far), suggested for backgrounds.

If parallax coefficient is not defined, it will be equal 1.0, or will be automatically calculated from z-value if auto parallax mode is turned on.
parallax-mode-x enum: scroll, fit, fixed parallax-mode-x = "scroll" Horizontal parallax mode.

scroll - layer will be scrolled with parallax coefficient in dependence of position difference of camera and reference point.
fit - The image of layer will scroll so that the edges of image are touch the edges of the section in case they are touched by a camera
fixed - The image will be drawn on fixed screen position with no matter where camera is in the section

parallax-mode-y enum: scroll, fit, fixed parallax-mode-y = "scroll" Vertical parallax mode.

scroll - layer will be scrolled with parallax coefficient in dependence of position difference of camera and reference point.
fit - The image of layer will scroll so that the edges of image are touch the edges of the section in case they are touched by a camera
fixed - The image will be drawn on fixed screen position with no matter where camera is in the section

reference-point-x enum: left, right reference-point-x = "left" Horizontal reference point - left side of image to left edge of section, or right side of image to right edge of section.
reference-point-y enum: top, bottom reference-point-y = "bottom" Vertical reference point - top side of image to top edge of section, or bottom side of image to bottom edge of section.
offset-x double offset-x = "0.0" Horizontal offset of reference point.
offset-y double offset-y = "0.0" Vertical offset of reference point.
margin-x-left double margin-x-left = "0.0" Extra spacing at left side of image.
margin-x-right double margin-x-right = "0.0" Extra spacing at right side of image.
margin-y-top double margin-y-top = "0.0" Extra spacing at top side of image.
margin-y-bottom double margin-y-bottom = "0.0" Extra spacing at bottom side of image.
margin-x double margin-x = "0.0" Extra spacing at both left and right sides of image. Has lower priority than padding-x-left and padding-x-right.
margin-y double margin-y = "0.0" Extra spacing at both top and bottom sides of image. Has lower priority than padding-y-top and padding-y-bottom.
speed-x uint speed-x = "0" Pixel-per-second horizontal autoscrolling of reference point. Affected by horizontal parallax coefficient. That can be used, for example, to visualize a river stream with multiple layers on different Z position with auto parallax mode. 0 - autoscroll is disabled. >0 - scroll right, <0 - scroll left.
speed-y uint speed-y = "0" Pixel-per-second horizontal autoscrolling of reference point. Affected by vertical parallax coefficient. 0 - autoscroll is disabled. >0 - scroll down, <0 - scroll up.
auto-scroll-speed-x uint auto-scroll-speed-x = "0" Alias to speed-x.
auto-scroll-speed-y uint auto-scroll-speed-y = "0" Alias to speed-y.
frames uint frames = "1" Count of animation frames (by vertical). If 1, animation is disabled.
frame-delay uint frame-delay = "128" Delay between every frame in milliseconds.
framespeed uint framespeed = "128" Alias to frame-delay.
display-frame uint display-frame = "0" Show specific frame when animation is turned off.
frame-sequence uint-array frame-sequence = "0,2,5,0,0,0,6,7,0" A custom sequence of animation frames.