Integrated skin options - skin-defined options to personalize a skin

[Corne2Plum3]

TL;DR

The possibility to change some parts of a skin in-game without altering any skin file through a menu in Options. The possible changes are defined by the skin author.

Below there are some details and the description of an implementation of this feature.

Summary

Some skins have a folder called "Extras" where there are several variations of a specific element, for example different hitcircles, cursor, etc. It would be nice to be able to access them without having to change the skin files.

It would be also nice for players who wants to use the same skin under different configurations (for example one with differents hitcircles ("NM" and "DT"), or different cursor colors) without having several times the same skin with just a few different files.

Here's an idea I have is to allow players to change some elements through the in-game options at will. In a couple of clicks, be able to change the cursor color, the hitsounds, enable/disable the anime girls and more, the options available being chosen by the skin author (meaning the options would varies between skins, and in some skins not having any options at all).

It would not only applies on skin sprites but also on audio files and skin.ini values (for example to change the combo colors).

In the example above, it is possible to change the cursor color, the hitcircles and the hitsounds.

Example

We're going to focus on a skin with an option to change the hitcircles. There are 4 possible choices: ring (default), black, filled and ring RGB. The skin has the files for the hitcircles a Extras folder:

A copy of the files within the "Extras/Hit circles/ring (default)" directory is on the skin's root folder, meaning, it's the one in use.

What you would do for example to use the filled hitcircles is to copy all images from Extras/Hit circles/ring (default)/filled folder then paste it at the skin's root folder, replacing the already existing ones, so the game will use those instead.

With the idea described above, there's a dropdown in the osu! lazer option, inside the skin section where the player can choose between ring (default), black, filled and ring RGB, then select filled.

It would tell lazer to use those hitcircles instead of the default one.

Implementation suggestion (with another example)

But how the skinner add an option? How to be able to choose between 2, 3 or even 99 cursors? Here's an example on how to do that.

The core idea is to have a json file (let's call it config.json) in the skin's root folder which lists the options and the changes they applies over what the game would use. This can be:

• Using a different file (sprite, audio)
• Change a value in the skin.ini.

Note that this doesn't alter the skin files, just tell the game what games to use.

Example

For example we're considering a skin with the following options (in parenthesis = default):

• Cursors (green):

  

• Hitcircles fonts (Figtree):

  

• Hitcircles styles (NM):

  

The needed sprites are stored in a folder called customizable_assets with inside the following files (it's possible to use 0 subdirectories, but I think it's a good practice to have subfolders for each option and choice):

To avoid duplicate files, there isn't any of these files in the skin's root folder (meaning if this skin was imported as is, the default assets would be used as they're not defined in the skin)

Then, the config.json would be this:

{
    "defaults": {
        "Cursor": "green",
        "Hitcircles font": "Figtree",
        "Hitcircles style": "NM"
    },
    "options": {
        "Cursor": {
            "blue": {
                "cursor": "customizable_assets/cursors/blue/cursor.png",
                "cursormiddle": null,
                "cursortrail": "customizable_assets/cursors/blue/cursortrail.png"
            },
            "green": {
                "cursor": "customizable_assets/cursors/green/cursor.png",
                "cursormiddle": null,
                "cursortrail": "customizable_assets/cursors/green/cursortrail.png"
            },
            "long trail yellow": {
                "cursor": "customizable_assets/cursors/longtrail yellow/cursor.png",
                "cursormiddle": "customizable_assets/cursors/longtrail yellow/cursormiddle.png",
                "cursortrail": "customizable_assets/cursors/longtrail yellow/cursortrail.png"
            }
        },
        "Hitcircles font": {
            "Figtree": {
                "skin.ini": {
                    "Fonts": {
                        "HitCirclePrefix": "customizable_assets/default_fonts/Figtree/default",
                        "HitCircleOverlap": 5
                    }
                }
            },
            "Manrope": {
                "skin.ini": {
                    "Fonts": {
                        "HitCirclePrefix": "customizable_assets/default_fonts/Manrope/default",
                        "HitCircleOverlap": 2
                    }
                }
            }
        },
        "Hitcircles style": {
            "DT": {
                "hitcircle": "customizable_assets/hitcircles/DT/hitcircle.png",
                "hitcircleoverlay": "customizable_assets/hitcircles/DT/hitcircleoverlay.png",
                "skin.ini": {
                    "Colours": {
                        "Combo1": "255,255,255",
                        "Combo2": "255,255,255",
                        "Combo3": "255,255,255",
                        "Combo4": "255,255,255"
                    }
                }
            },
            "NM": {
                "hitcircle": "customizable_assets/hitcircles/NM/hitcircle.png",
                "hitcircleoverlay": "customizable_assets/hitcircles/NM/hitcircleoverlay.png",
                "skin.ini": {
                    "Colours": {
                        "Combo1": "0,194,175",
                        "Combo2": "0,136,146",
                        "Combo3": "0,194,175",
                        "Combo4": "0,136,146"
                    }
                }
            }
        }
    }
}

The config.json

The config.json defines the options shown in-game and what they do. This is at the toppest level a dict with only 2 elements, containing dicts themselves (details below):

• defaults: defaults options values
• options: description of the options

It's possible to use spaces in options names and values.

The config.json must be located in the skin's root folder (aka in the same folder than skin.ini), otherwise the file is ignored.

This file must be read by the game when launched or when loading a skin, because even with default it's possible to have a sprite that isn't in the root folder (or has a different name) and can be accessed only through the options (see example above, where there isn't any moment where the default 2015 hitcircle, which is used when there are no hitcircle.png in the skin's root folder is used.)

If the JSON file can't be read (for example syntax error), the whole file is ignored and the skin will have no options.

The existence of this file is optional for a skin, note that the skin will have no options (it's like this feature isn't implemented).

The defaults section

The defaults has the following format:

"defaults": {
    "option_1": "default_choice_for_option_1",
    "option_2": "default_choice_for_option_2",
    ...
}

The list of options available and the possible values for each of them are defined in the options values.

• If an option that doesn't exist is found (invalie option), it is ignored.
• If the option exists but is set to a value that isn't an available choice (invalid choice): use the topmost possible value defined in options section.
• If the option has been already set before (duplicate): ignore the duplicate and keep the topmost line, regardless if it's valid or not.

It is possible to show a notification if one of the 3 problems occurs when reading the config.json (note for skinners that these shouldn't show up on a released skin, obviously, because it means there's a bug with your skin).

The options section

The options is a dict containing options, and for each option, there's a dict with the different values, and for each values a dict representing what they change.

"options": {
    "option_1": {
        "value_1": {},
        "value_2": {},
        ...
    },
    "option_2": {
        "value_1": {},
        "value_2": {},
        ...
    },
    ...
}

The options and the values are displayed in the order they appears in config.json. If an option has 0 values, it is ignored by the game.

Each values from an option may have differents lines (I don't recommend doing this tho). When a line is missing, it means: "using the default skin setting" or if not defined, from the default skin.

But what contains the dict for each value? They contains 2 types of entries: a file (to change that file) or skin.ini (for changes inside the skin.ini).

"value_1":
    "file_name_1": "path/to/file_name_1",
    "file_name_2": "path/to/file_name_2",
    ...
    "skin.ini": {
        "section_1": {
            "entry_1": "value_for_entry_1",
            "entry_2": "value_for_entry_2",
            ...
        },
        "section_2": {
            "entry_3": "value_for_entry_3",
            ...
        }
    }

File replacement

When this isn't skin.ini, this is the name of a file (sprite or audio), without extension and without "@2x".

For example, with the line "hitcircle": "hitcircle_alt.png", the game uses hitcircle_alt.png instead of hitcircle.png to display hitcircles.

It's possible to use subdirectories. All paths are relative to the skin root folder. It's possible to use the directory and files names we want, even if it doesn't match the original sprite name or the name of another sprite.

It's also possible to use the value null to use no file, forcing to use the sprites from the default skin. Useful when you don't want to include files that would change the behaviour of the element, such as the HP bar, the cursor or the spinner. This does NOT means that this is a transparant.

Although not recommended, it's possible to have the same file being changed by several options (for example, an option "Hitcircle preset" and "Hitcircle font"). Then the change from the lowest in the options list should be used (in the example above: use the font from "Hitcircle fonts" while using the style of circles from "Hitcircle preset").

There is no need to add an entry for \@2x files, this is implicitly done with the entry without the \@2x. In fact the game should behave like this:

• If the file name doesn't exists (invalid filename), the line is simply ignored.
• If the file name exists but the value leads to a file that doesn't exists (replacement file not found), the game will have the behaviour of the default skin.
• If the file can't be loaded, has the wrong format or extension (invalid file), the game will have the behaviour of the default skin.
• It shouldn't be possible to load sprites from outside of the skin folder. Is there's something like ../another_directory or C:/Windows/..., the game must not attempt to get the file, and just have the same behaviour as the file isn't found.

skin.ini change

When inside a value there's skin.ini. Instead of replacing skin.ini, which would force to have tons of ini files and wouldn't allow multiples options to change the skin.ini, the value is a dict, which the section we wants to change, without brakets (General, Colours, Fonts, CatchTheBeat, Mania*), and for each sections, the lines we wants to change with the new value, in the same way we do in skin.ini.

* Important note for Mania: As there are several section labelled Mania in the skin.ini, the number of keys must be specified inside the config.json, inside brakets to know each one to change. For example, to change the properties for 7K, Mania[7] must be used. If in a Mania section in the skin.ini doesn't have a Keys entry, it can't be accessed, but isn't your skin.ini just invalid in this situation?

It is possible to use integers, floats, booleans, strings. Thus arrays and colors must be given as a strings (see example below):

"skin.ini": {
    "Colours": {
        "Combo1": "255,0,0"
    },
    "Mania[4]": {
        "ColumnWidth": "60,60,60,60"
    }
}

Displaying the option in-game and integration with osu!lazer

As shown in the fake screenshot from the Summary, these options can be accessed from the options menu, under the skin selection, in a "Integrated skin options".

For each option available, a dropdown is added, with the same of the option, and below the choices possible. Not very useful, but it's also possible to display with only 1 choice. Options with 0 choice shouldn't be shown (it's an issue from the skinner). The name of the options and the choice are displayed as is in inside the config.json.

If the skin has no option, either the "Integrated skin options" isn't shown at all or the text "No integrated skin options" is shown (imo the 2nd option is the best.)

The options are seperated from each other skins (as they may have differents or no options at all).

The game must remember what options are selected for each skin, and thus even when the user quits the game (= do not reset the options on start up).

Last word

This took me 3 hours to write this.

While not being a huge priority of the game at the moment, I'm sure this feature would be appreciated from both skinners and players, giving an easy way to personalize a skin without complicated manipulations.

[peppy]

All skinning going forward will be focused on the UI, not config files. The hard part is making this work in a way which users can understand. I've had working proof-of-concepts with skin layers in the past, and I believe we'll try and make this work, but it won't be via users/skinners editing text files.

Also what you are asking for is a new layer of configuration, when we're still struggling to make the base layer of configuration work well. The ideas are appreciated but it's a bit further away. We don't want to add on new systems haphazardly to recreate the absolute mess that stable skinning is.

[peppy]

All of those are the same as stable.

[Czuczekowaty]

Okay but in this case, where is the folder that holds all skins in their "raw" format for lazer?

[peppy]

There is none. If you want to update a texture you can drag a replacement into the skin editor and then delete the sprite from the layout screen.

[Czuczekowaty]

Yeah so I guess I'm really dumb and I still don't know what to do. I want to change hitcircles let's say.
When I drag file named hitcircle@2x it shows up as "SkinnableSprite" and I can change what object I want it to be. I can drag it around playfield but can't do anything else with it. I tried doing it with hp bar and I see that hp bar from skin is called "LegacyHealthDisplay" but then how do I apply my own hp bar so it would be recognized as hp? Do I need to change name of the file to "legacyhealthdisplay.png"? Currently when I put it in, it still appears as "SkinnableSprite" and is not recognized as hp. This is way too complicated for what it used to be man :/

[Taneta-nemausernames]

Is a skin equivalent of the editors teased open in file feature potentially coming?