Background image Entry INI config (Config pack)
background2-*.ini - the settings file which declares single entry of background images. When this file is a part of the config pack, almost all parameters are required. The default location of these files is specified in the main lvl_bkgrd.ini file by "config-dir" field of "[background2-main]" section.
When this file is created inside level or episode, all parameters are optional: the role of episode/level side configuration is overriding default properties are declared on the side of the config pack.
Note: Some of the multi-layer background parameters can be used for SMBX2, however, SMBX2 has a different config format, partially incompatible with this. Pay attention while making background configs for SMBX2.
| [ 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 (single-list config type only: If you have the separate background2-*.ini file per every background type, this field is useless. This field is required when all type entries were declared inside of "lvl_bkgrd.ini" file) |
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), |
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 |
| attached | string | attached = bottom | Attachment of background image to side of section: bottom, |
| 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 |
| 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 |
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!).
Tip: For custom configs or split mode INI files (when every background type was declared as the separate background2-*.ini file) the section for every layer may have any bud unique text as a section name. For example "SkyLayer", "Rain clouds", and even with special symbols and non-latin characters "Деревья и растительность", "B@d-ro0d", "美しい植物", etc.
WARNING: You may NOT use the "General" and "background2" because they are reserved names for the INI file header.
|
[ background2-*-layer-* or <any unique text> ] | |||
|---|---|---|---|
| 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 |
| 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 |
| parallax-mode-x | enum: scroll, fit, fixed | parallax-mode-x = "scroll" | Horizontal parallax mode. scroll - layer will be scrolled with parallax coefficient that depends on a position difference of camera and reference point. |
| parallax-mode-y | enum: scroll, fit, fixed | parallax-mode-y = "scroll" | Vertical parallax mode. scroll - layer will be scrolled with parallax coefficient that depends on a position difference of camera and reference point. |
| 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 - auto-scroll 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. |