Ren’Py Sprite Customizer

Documentation for the Sprite Customizer (SC) framework.

This document is a work in progress.

Topics

Sprite State

To keep sprite customization options stored in game save files, the internal selection state for the sprites is stored in a runtime variable of type SCState.

This state should be created via a runtime variable in a python line, or, preferrably, a default statement.

default my_sprite_state_1 = SCState()
default my_sprite_state_2 = SCState()

label start:
    $ my_sprite_1.set_state(my_sprite_state_1)
    $ my_sprite_2.set_state(my_sprite_state_2)

label after_load:
    $ my_sprite_1.set_state(my_sprite_state_1)
    $ my_sprite_2.set_state(my_sprite_state_2)

This state is then loaded into a target CustomizedSprite instance to configure all the option selections show the correct combination of options. Each separate CustomizedSprite instance should have it’s own state instance. This means that for every unique sprite, you will need a unique default declaring a new SCState object. Additionally, for every separate CustomizedSprite instance, that state value must be loaded at start and after_load times.

This state value MUST be passed to the relevant sprite instance via the set_state method in both the start and after_load labels. If this is not done, the sprites will reset to their default state.

Additional State

In addition to the sprite customization option selection values, the SCState object may be used to store arbitrary user-defined variables that will then be passed through to the Layer Callbacks attached to the sprite that uses the target SCState object.

Example

The following code snippets attempt to demonstrate a use case for the use of additional user-defined state to augment the CustomizedSprite's behavior so as to make use of a non-option variable to control how the sprite gets rendered.

In this particular case, we have a set of sprite "base" images that represent different player moods. It wouldn’t make sense to have the player mood be a customization option, but it is something that does have options we wish to control during gameplay.

config.rpy

init python:
    def base_lcb(**kwargs):
        return "sprite_base_{}".format(kwargs["mood"])

define my_sprite = CustomizedSprite("player", SCLayer("base", base_lcb))

script.rpy

default my_sprite_state = SCState()

label start:
    $ my_sprite_state.set_state("mood", "happy")
    $ my_sprite.set_state(my_sprite_state)

    show player

Sprite vs. Factory

The CustomizedSprite class may be constructed directly or via the CustomizedSpriteFactory type. Deciding whether to construct the type directly or via the factory comes down to whether you want to create multiple sprites from the same set of layers and options.

If you only wish to create a single sprite out of a given set of layers and options, then it is fine to construct a new CustomizedSprite instance directly.

If you wish to create more than one sprite out of a set of layers and options, then it is best to create a CustomizedSpriteFactory from those layers and options and use that factory instance to produce new CustomizedSprite instances.

Constructing a Single Sprite

my_sprite = CustomizedSprite(
    "protagonist",
    SCLayer("skin", ...),
    SCLayer("clothes", ...),
    SCLayer("hair", ...),
    SCLayer("eyes", ...)
)

Constructing Multiple Sprites from the Same Options

sprite_fac = CustomizedSpriteFactory(
    SCLayer("skin", ...),
    SCLayer("clothes", ...),
    SCLayer("hair", ...),
    SCLayer("eyes", ...)
)

my_sprite_1 = sprite_fac.new_sprite("protagonist")
my_sprite_2 = sprite_fac.new_sprite("antagonist")

Layer Callbacks

Layer callbacks are functions that are used by SCLayer instances to generate Displayables that can be used as components of the overall CusomizedSprite image. These functions are one of the two ways that the Sprite Customizer is able to make use of your project’s assets.

Defining Layer Callbacks

Before we can talk more about layer callbacks, we need to talk a little bit about layers, more specifically, SCLayers and how they are constructed.

When constructing a new SCLayer instance, you may pass it a layer name, a layer callback, and zero or more customization option groups via keyword arguments. Those keyword arguments are very important to the definition of the given layer callback; they name the same arguments that will be passed to the layer callback when it is eventually (and repeatedly) executed.

For example, given the following SCLayer definition:

SCLayer(
    "hair",
    hair_lcb,
    hair_style=("Hair Style", [ "afro", "bob", "buns" ]),
    hair_color=("Hair Color", [
        "#3D2314",
        "#100C07",
        "#DA680F",
        "#FFCC47",
        "#9A9E9F",
        "#FAFAFA",
        "#801818",
        "#580271",
        "#1592CA",
        "#11694E",
        "#FF87C5"
    ]),
)

we would expect the defined layer callback function (hair_lcb) to accept 2 arguments, hair_style and hair_color. We would then expect that function to perform some work with those arguments to produce a Displayable. The values passed on those arguments will be one of the options in the relevant option list. In our example demonstration’s case, we use the hair_style value (one of "afro", "bob", or "bun") to create a path to the specific image we wish to display; then we use the hair_color value (one of the listed hex color codes) to apply a tint matrix to that image.

def hair_lcb(hair_style, hair_color, **kwargs):
    return Transform(f"images/ccp/hair/{hair_style}.png", matrixcolor=TintMatrix(hair_color))

A layer callback may also be as simple as returning a static string for a case where there are no customization options.

def mic_stand_lcb(**kwargs):
    return "images/something/mic_stand.png"

...

SCLayer("mic_stand", mic_stand_lcb)

Animating Layers

As the whole Sprite Customization framework is built on DynamicDisplayables, it may be desirable to put those Displayables to work with animations. Luckily, the same values passed to a DynamicDisplayable’s callback are accessible from an SC layer callback as well.

In addition to the customization options, the typical st-at pair are passed to layer callbacks and can be accessed by declaring those parameters as positional arguments or by accessing them from the **kwargs argument. This means both of the following example functions are correct:

# Alternate eye image every second for some reason
init python:
    def my_lcb_1(eye_color, **kwargs):
        if int(kwargs["st"]) % 2 == 1:
            return f"images/sprite/eyes/{eye-color}_1.png"
        else:
            return f"images/sprite/eyes/{eye-color}_0.png"

    def my_lcb_2(st, eye_color, **kwargs):
        if int(st) % 2 == 1:
            return f"images/sprite/eyes/{eye-color}_1.png"
        else:
            return f"images/sprite/eyes/{eye-color}_0.png"

Those of you that are already familiar with DynamicDisplayables and their callbacks may be wondering how and where a redraw time may be defined. Luckily, if needed, that may also be returned from SC layer callbacks:

init python:
    def my_lcb_1(eye_color, **kwargs):
        if int(kwargs["st"]) % 2 == 1:
            return (f"images/sprite/eyes/{eye-color}_1.png", 1.0)
        else:
            return (f"images/sprite/eyes/{eye-color}_0.png", 1.0)

If a redraw time is not returned by the layer callback, a default value of 0.0 is used.

Advanced Animations

The following example demonstrates an advanced animation where a character sprite blinks their eyes at a semi-random interval. This is also a demonstration of where the Customized Sprite frameworks starts to break down; at this point it may be worthwhile to consider assembling the DynamicDisplayables and LayeredImages manually unless you are comfortable writing animations in Python.

init python:

    def cs_base(**kwargs):
        return "sprite_base"

    class cs_eyes:
        def __init__(self):
            self.cur_frame = "sprite_openeyes"
            self.next_frame = "sprite_halfclosedeyes"
            self.next_animate = 0.0
            self.last_frame = 0.0
            self.opening = False

        def __call__(self, st, at, **kwargs):
            # If the next_animate time has not yet elapsed, return the current
            # frame.
            if st - self.last_frame < self.next_animate:
                return self.cur_frame

            # The next_animate time has elapsed, set the current frame to the
            # previous next_frame value to queue it up for rendering.
            self.cur_frame = self.next_frame

            # Determine what the new next sprite should be.
            if self.next_frame == "sprite_halfclosedeyes":
                if self.opening:
                    self.next_frame = "sprite_openeyes"
                else:
                    self.next_frame = "sprite_closedeyes"
                self.next_animate = 0.1
            elif self.next_frame == "sprite_closedeyes":
                self.next_frame = "sprite_halfclosedeyes"
                self.opening = True
                self.next_animate = 0.1
            else: # self.next_frame == "sprite_openeyes"
                self.next_frame = "sprite_halfclosedeyes"
                self.opening = False
                self.next_animate = max(0.5, renpy.random.random()) * 5

            self.last_frame = st

            return (self.cur_frame, self.next_animate)

define cs = CustomizedSprite(
    "sprite",
    SCLayer("base", cs_base),
    SCLayer("eyes", cs_eyes()),
    transform = lambda x : Transform(x, zoom=0.75),
)

Type Reference

CustomizedSprite

Represents a multi-layered sprite image composed of customizable layers.

This type provides methods for manipulating the layers by changing their customizations between each layer’s configured customization options.

Properties

`layers`

SCLayer[]

The list of layers attached to this CustomizedSprite instance.

`option_keys`

str[]

A list of the keys for all the options attached to this CustomizedSprite instance.

`option_count`

int

The total number of registered options.

Methods

`init`

Initializes the new CustomizedSprite instance with the given arguments.

Arguments

`image_name`	`str`	Name of the image that will be created for this sprite. This name is the value that will be used when referencing the sprite elsewhere in scripts via `show`, `add`, etc..
`*layers`	`SCLayer[]`	A list of one or more layers from which the sprite should be created. The layers are stacked on top of one another in the passed order. This means the first given layer will be at the "back" of the sprite, where the last given layer will be the "front".
`transform`	`callable`	An optional transform function that will be applied to the created image.

image_name

str

Name of the image that will be created for this sprite. This name is the value that will be used when referencing the sprite elsewhere in scripts via show, add, etc..

*layers

SCLayer[]

A list of one or more layers from which the sprite should be created. The layers are stacked on top of one another in the passed order. This means the first given layer will be at the "back" of the sprite, where the last given layer will be the "front".

transform

callable

An optional transform function that will be applied to the created image.

`set_state`

Sets the internal state object of this CustomizedSprite instance to the given SCState instance.

define my_sprite = CustomizedSprte("sprite", ...)
default my_sprite_state = SCState()

label start:
    $ my_sprite.set_state(my_sprite_state)

label after_load:
    $ my_sprite.set_state(my_sprite_state)

Arguments

`state`	`SCState`	State object to use for storing customization option selections.

state

SCState

State object to use for storing customization option selections.

`get_options`

Gets a list of the options attached to this CustomizedSprite instance.

Returns

SCOption[]

List of the options attached to this CustomizedSprite instance.

`get_options_by_key`

Gets a dict of option keys mapped to SCOption instances for all the options attached to this CustomizedSprite.

Returns

dict

Dict of option keys mapped to SCOption instances.

`get_options_by_group`

Returns an index of options and display names grouped by layer group name. This index may optionally be ordered by providing a list of the desired group order.

Options that do not have a group name declared on them, their display name will be used as the group name.

sprite.get_options_by_group()

sprite.get_options_by_group(["Body", "Face", "Hair"])

Arguments

`group_order`	`str[]`	Optional list of option group names by which the output dict will be ordered. This list MUST contain all of the groups declared in the SCLayer definitions, and ONLY those groups.

group_order

str[]

Optional list of option group names by which the output dict will be ordered. This list MUST contain all of the groups declared in the SCLayer definitions, and ONLY those groups.

Returns

dict

An index of the declared sprite customization options grouped by the configured option groups.

{
    "Body": {
        "skin_color": <SCOption>,
        "clothes": <SCOption>,
    },
    "Face": {
        "eyes": <SCOption>
    }
    "Hair": {
        "hair_style": <SCOption>,
        "hair_color": <SCOption>,
        "accessory": <SCOption>
    },
}

`randomize`

Randomizes the selections for all the randomizable options on this CustomizedSprite instance.

CustomizedSpriteFactory

A factory that can be used to generate multiple CustomizedSprite instances with the same set of base options.

define sprite_factory = CustomizedSpriteFactory(
    SCLayer(...),
    SCLayer(...),
    SCLayer(...),
)

define sprite = sprite_factory.new_sprite("my_image")

Methods

`init`

Initializes a new CustomizedSpriteFactory instance with the given arguments.

Arguments

`layers`	`SCLayer[]`	A list of one or more layers from which CustomizedSprite instances should be created. The layers are stacked on top of one another in the passed order. This means the first given layer will be at the "back" of the sprite, where the last given layer will be the "front".
`transform`	`callable`	An optional transform function that will be applied to images created by this factory.

layers

SCLayer[]

A list of one or more layers from which CustomizedSprite instances should be created. The layers are stacked on top of one another in the passed order. This means the first given layer will be at the "back" of the sprite, where the last given layer will be the "front".

transform

callable

An optional transform function that will be applied to images created by this factory.

`new_sprite`

Constructs a new CustomizedSprite instance with the given name.

Arguments

`image_name`	`str`	Name of the image that will be created for the returned sprite. This name is the value that will be used when referencing the sprite elsewhere in scripts via `show`, `add`, etc..
`transform`	`callable`	An optional transform function that will be applied to the image created by this method.

image_name

str

Name of the image that will be created for the returned sprite. This name is the value that will be used when referencing the sprite elsewhere in scripts via show, add, etc..

transform

callable

An optional transform function that will be applied to the image created by this method.

SCLayer

Represents a single layer in a customizable sprite.

This layer has zero or more customization options provided at construction time via named layer option keyword args. The user’s selections of those options are then passed to the given layer_provider to construct the underlying Displayable for the layer.

SCLayer("name", callback, option=("Option", [ "some", "choices" ]))

# OR

SCLayer("name", "my_image_{option}", option=("Option", [ "some", "choices" ]))

Properties

`name`

str

Name of the layer.

`options`

SCOption[]

List of options attached to this layer.

`options_by_key`

dict

Dict of option keys mapped to SCOption instances for all the options attached to this layer.

SCOption

Base type for Sprite Customizer option types.

Properties

`key`

str

Option keyword.

`display_name`

str

Display name for the option.

`group`

str

Group display name for the option.

`option_type`

int

Option type indicator.

SCState

This class defines an object that is used to hold sprite customization option selections. This is used to persist the selected options as part of the game saves and reload those selections when loading the game from a save.

my_sprite_state = SCState()
my_sprite.set_state(my_sprite_state)

Methods

`init`

Initializes the new, blank SCState instance.

Arguments

`selections`	`dict`	A dict of option keys to selections. May be used to set a custom starting state for a CustomizedSprite.
`user_state`	`dict`	A dict of option keys to values. May be used to set a custom starting user state.

selections

dict

A dict of option keys to selections. May be used to set a custom starting state for a CustomizedSprite.

user_state

dict

A dict of option keys to values. May be used to set a custom starting user state.

`set_variable`

Store arbitrary user variable that will be passed to all layer callbacks.

This method cannot be used to override option selections. If a user state item key conflicts with a sprite customization option, the sprite customization option will take priority.

default sprite_state = SCState()

label start:
    $ sprite_state.set_variable("mood", "happy")
    $ sprite.set_state(my_state)
    ...
    ...
    ...
    $ sprite_state.set_variable("mood", "angry")

Arguments

`key`	`str`	Key for the user state item.
`value`	`any`	Value to store.

key

str

Key for the user state item.

value

any

Value to store.

`get_variable`

Retrieve user variable from the SCState store by key.

Arguments

`key`	`str`	Key for the user state item.

key

str

Key for the user state item.

Returns

any

User state value.

`has_variable`

Tests whether the state contains a user variable value with the given key.

Arguments

`key`	`str`	Key of the user variable to test for.

key

str

Key of the user variable to test for.

Returns

bool

Whether the target user state item exists in the SCState instance.

`set_selection`

Sets the target selection value.

Arguments

`key`	`str`	Key of the selection to set.
`value`	`any`	Value to set

key

str

Key of the selection to set.

value

any

Value to set

`get_selection`

Looks up the target selection value.

Arguments

`key`	`str`	Key of the selection to look up.

key

str

Key of the selection to look up.

Returns

any

Target selection value (or None if no such value is set).

`has_selection`

Tests whether the state contains a selection value with the given key.

Arguments

`key`	`str`	Key of the selection value to test for.

key

str

Key of the selection value to test for.

Returns

bool

Whether the target selection item exists in the SCState instance.

SCValueListOption

Extends SCOption

Represents an option group that is a list or set of option choices that are navigated via an index that can be incremented or decremented.

SCValueListOption("my_option", "My Option", "My Group", [ "some", "choices" ])

This option type is state dependent and cannot be used on its own, it MUST be registered to an SCLayer instance to be in any way useful.

Properties

Includes SCOption Properties

`values`

any[]

The list of values that are part of this option group.

`value_count`

int

The number of options in this option group.

`selection_index`

int

The current selection index for this option group.

`selection_value`

any

The currently selected value for this option group.

Methods

`init`

def __init__(self, key, name, group, values, display_digits=2, **kwargs):

Initializes the new SCValueListOption instance with the given arguments.

Arguments

`key`	`str`	Keyword for this option.
`name`	`str`	Display name for this option.
`group`	`str`	Group name for this option.
`values`	`any[]`	List of values for this option.
`display_digits`	`int`	Number of digits to display when rendering the selection index as a string. The index will be left padded with zeros to reach this digit count. For example, given the `display_digits` value `3`, when rendering the first index as a string, the returned string would be "001".

key

str

Keyword for this option.

name

str

Display name for this option.

group

str

Group name for this option.

values

any[]

List of values for this option.

display_digits

int

Number of digits to display when rendering the selection index as a string. The index will be left padded with zeros to reach this digit count. For example, given the display_digits value 3, when rendering the first index as a string, the returned string would be "001".