images:
This is a config file reference. Click for instructions.
This page is reference material which explains every setting and option for this section of an MPF yaml config file. See the instructions for config files for formatting and other details. See our guide to config file examples for more examples of real configs in action.
| Valid in | |
|---|---|
| machine config files | YES  |
| mode config files | YES |
The images: section of your config is where you configure non-default
parameter values for any image assets you want to use in your game.
Note: You do not have to have an entry for every single image you want
to use, rather, you only need to add individual assets to your config
file that have settings which are different from other assets in that
asset's folder. (This section is part of the MPF media controller and
only available if you're using MPF-MC for your media controller.)
More information on working with assets is in the Assets section of the documentation.
Each sub-entry in your image: section is the name that MPF will use to
refer to that asset. (In other words it's how you specify that asset in
other areas of your config files.) The asset manager works by first
scanning the file system to build up a list of asset files it finds.
Then it looks at the config to see if there are any additional settings
specified for each asset.
For example:
images:
insert_coin:
load: preload
hello_face:
file: hello_face_300.jpg
load: None
So in the example above, if the asset manager found a file called
insert_coin.jpg on disk, then it will also see the insert_coin entry
in the config file and know that those two match. (The "match" is just
based on the part of the file name without the extension, so the
settings entry for insert_coin: would match insert_coin.jpg and
insert_coin.png. In other words, don't name two files with the same
name if you want to keep them straight.)
Optional settings
The following sections are optional in the images: section of your
config. (If you don't include them, the default will be used).
file:
Single value, type: string. Defaults to empty.
Sometimes you might want to name a file one thing on disk but refer to
it as another thing in your game and config files. In this case, you can
create an file: setting in an asset entry. (Note the file:
hello_face_300.jpg setting in the example above, and note that it
includes the file extension.) In this example, you would refer to that
image asset as hello_face even though the file is hello_face_300.
You might be wondering why this exists? Why not just change the file
name to be whatever you want and/or who cares what the name is? The
reason this function exists is because it allows for the separation of
the actual file on disk from the way it's called in the game. For
example, you could use this to create two sets of assets---one for a
traditional DMD and one for a color DMD---and then you could refer to
the asset by its generic name throughout your configs. (In other words,
you could swap out assets for different physical machine types without
having to update your display code.) That said, we expect that 99% of
people won't use this file: setting, which is fine.
frame_skips:
List of one (or more) values, each is a type: images_frame_skips:. Defaults to empty.
Help us write it!
This section is unwritten or needs an update or edit. Can you help write it? Get your name in lights and geeky pinball bragging rights! Hit the magic sparkly wand to the right of the title to see this page source on GitHub. Then add/edit and submit your change. It's easy!
image_template:
Single value, type: images:. Defaults to empty.
Help us write it!
This section is unwritten or needs an update or edit. Can you help write it? Get your name in lights and geeky pinball bragging rights! Hit the magic sparkly wand to the right of the title to see this page source on GitHub. Then add/edit and submit your change. It's easy!
load:
Single value, type: string. Defaults to empty.
Specifies when this asset should be loaded. (See the Assets documentation for an explanation on loading.)
- preload (The asset is loaded when MPF boots and stays in memory as long as MPF is running.)
- mode_start (The asset is loaded when the mode starts and is unloaded when the mode ends. This option is only valid for asset files that are in mode folders, not machine-wide assets.)
- Anything else (or nothing at all) means that the asset it loaded "on demand" when it's first called for. (At this point, assets loaded on demand stay in memory forever, but at some point we'll change that so they get unloaded on demand too.)
Note that you can configure load: options in the
assets: section of your config
files. It's nice to be able to override those on an asset-by-asset
basis. For example, you might configure your assets for a mode to all
load when the mode starts, but you could also create a few entries in
your config files with load: preload for the assets that are needed
for the intro show of the mode. That way that show can play while the
other assets are loading in the background. (Of course you could also
create a subfolder for the assets that you want to preload and specific
an assets: entry for that folder rather than specifying entries in
your config for specific assets. The choice is up to you.)
Related How To guides
Something missing or wrong? You can fix it!
This website is edited by people like you! Is something wrong or missing? Is something out of date, or can you explain it better?
Please help us! You can fix it yourself and be an official "open source" contributor!
It's easy! See our Beginner's guide to editing the docs.
Page navigation via the keyboard: < >
You can navigate this site via the keyboard. There are two modes:
General navigation, when search is not focused:
- F , S , / : open search dialog
- P , , : go to previous page
- N , . : go to next page
While using the search function:
- Down , Up : select next / previous result
- Esc , Tab : close search
- Enter : go to highlighted page in the results