Skip to content

The Deco Framework for Backgrounds

Jump to bottom Edit New page
multimokia edited this page Oct 29, 2021 · 10 revisions

Version 0.11.7 introduced the image tag-based decoration framework, which allows for an image tag to automatically be hidden/shown in different locations depending on the current background.

Version 0.12.3 introduced image tag replacement, which allows a different image tag entirely to be used in different backgrounds.

This guide is written for custom background creators, and does not do a deep dive into the technical aspects of the framework. See Usage to skip over background explanations.

TOC

Components

MASImageTagDecoration

This is an object representation of a decoration that corresponds to an image tag. It's primary purpose is to allow for additional data to be associated with a decoration, like ex_props for example.

Generally, you will not need to construct these objects.

MASAdvancedDecoFrame

Stores attributes that would be passed into renpy.show. Similar to curried functions. This should only be used with MASImageTagDecoration objects

You will likely need to construct these objects to determine positioning for a decoration. The constructor takes the same parameters as renpy.show, excluding name.

MASImageTagDecoDefinition

Ties image tags (MASImageTagDecoration objects) with MASAdvancedDecoFrame objects for specific backgrounds. Every image tag-based decoration must have one of these for the deco framework to consider the tag as a decoration.

Generally, you will not need to construct these objects.

System Behavior (simplified)

When we want to show a decoration, we request the system to show a decoration via the show tag function. This sets up a decoration to be shown if the decoration has an entry in its MASImageTagDecoDefinition for the current background. However, the actual image is only shown when the background changes or a scene change occurs, which allows for the image to dissolve into the picture neatly.

The system handles both hiding and showing decorations automatically based on the MASImageTagDecoDefinition objects. If a decoration does not have a mapping to a MASAdvancedDecoFrame object in its MASImageTagDecoDefinition, the decoration is hidden. Otherwise, MASAdvancedDecoFrame objects allow for decorations to be shown in other locations in different backgrounds.

Usage

Step 1 - determine which decoration objects work for your background

You will need to look at each decoration image and determine if the image can be shown at all for their background. If it can, they will need to specify a MASAdvancedDecoFrame object (or use the existing one) to determine the best position for the background.

If a different image should be shown, then you can associate a different image tag (and optionally, frame) with the decoration for your background.

For a list of current decoration objects, see here (link)

Step 2 - register those decoration objects for your background

You will need to write a line for each decoration object that should be allowed on your background. This should be placed after the code that creates the background object.

There are 2 APIs that can be used here:

MASImageTagDecoDefinition.register_img

Params:

  • tag - (REQUIRED) image tag of the decoration object to register with
  • bg_id - (REQUIRED) ID of the background object to register (this should be your background's ID)
  • adv_deco_frame - (REQUIRED) MASAdvancedDecoFrame object to use when showing this decoration on your background
  • replace_tag - (optional) - NEW in 0.12.3+ - image tag to use instead of the standard decoration image

Use this function when the decoration object can be shown on your background but in a location other than the default.

Here is an example that registers the Christmas tree to your background using a zorder of 7. (The default is 6)

MASImageTagDecoDefinition.register_img(
    "mas_d25_tree",
    "your_custom_background_id",
    MASAdvancedDecoFrame(zorder=7)
)

Here is an example that registers a custom tree to your background.

MASImageTagDecoDefinition.register_img(
    "mas_d25_tree",
    "your_custom_background_id",
    MASAdvancedDecoFrame(),
    replace_tag="your_custom_d25_tree"
)

MASImageTagDecoDefinition.register_img_same

Params:

  • tag - (REQUIRED) image tag of the deoration object to register with
  • bg_id_src - (REQUIRED) ID of the background object to copy MASAdvancedDecoFrame from
  • bg_id_dest - (REQUIRED) ID of the background object to register (this should be your background's ID)

Use this function if the decoration object can be shown on your background in the same position as it is shown on another background. For example, if the default location of a decoration is fine for your background, then you would pass store.mas_background.MBG_DEF here.

Here is an example that registers the Christmas tree to your background using the default position.

MASImageTagDecoDefinition.register_img_same(
    "mas_d25_tree",
    store.mas_background.MBG_DEF,
    "your_custom_background_id"
)

Step 3 - complete

And that's it! Once you've registered the images, the Deco framework should take care of the rest.

Standard Decoration objects

To test how these look/default positioning, use the show deco API with show_now as True. NOTE: all composite images probably won't work on other backgrounds. Our apologies.

player-bday

  • coming soon

o31

  • mas_o31_wall_candle - candle in a cage held by a demonik(a) hand
  • mas_o31_cat_frame - a cat picture on the wall behind Monika which is a little more than it seems
  • mas_o31_wall_bats - bat decals for the wall below calendar
  • mas_o31_window_ghost - paper ghost that hangs in the window
  • mas_o31_cobwebs - cobwebs + spider that hang around corners in the room
  • mas_o31_candles - a table holding a 2 prong candelabra
  • mas_o31_jack_o_lantern - a jack 'o lantern which sits in the back left of the room
  • mas_o31_garlands - a string of o31 banners which I guess we're calling garlands
  • mas_o31_ceiling_lights - light bulbs that hang from the ceiling
  • mas_o31_ceiling_deco - deco that hangs from the ceiling
  • mas_o31_vignette - special o31 specific vignette

d25

  • mas_d25_banners - wreath and stocking composite.
  • mas_d25_garlands - green thing that I guess are called garlands
  • mas_d25_gifts - gifts that go under the Christmas tree
  • mas_d25_lights - the lights that go around the room
  • mas_d25_tree - the Christmas tree

APIs

mas_showDecoTag

Params:

  • tag - (REQUIRED) image tag of the decoration to show
  • show_now - [optional] pass True to show a decoration immediately, False will wait until next background change or scene change.

This is the primary way to show a decoration. show_now is only recommended in testing, as it will not dissolve images into the picture.

mas_hideDecoTag

Params:

  • tag - (REQUIRED) image tag of the decoration to hide
  • hide_now - [optional] pass True to hide a decoration immediately, False will wait until next background change or scene change.

This is the primary way to hide a decoration. hide_now is only recommended in testing, as it will not dissolve images from the picture.

mas_isDecoTagEnabled

(NEW in 0.12.3+)

Params:

  • tag - (REQUIRED) image tag of the decoration to check is enabled

RETURNS True if the deco is enabled, False if not

This does not mean that the decoration is actually visible in the picture. This checks if the decoration is set to be shown, but given the system behavior, the actual decoration may not be visible to the user.

mas_isDecoTagVisible

Params:

  • tag - (REQUIRED) image tag of the decoration to check is visible

RETURNS True if the deco is visible, False if not

This actually checks if the decoration is visible in the picture.

Add a custom footer
Add a custom sidebar
Clone this wiki locally