Add-ons / Theme Tools

A macro to change theme colors dynamically.

Author Zen447
Website https://twine.pier17.cc/addons/theme-tools/
Story format SugarCube 2
Last checked Wed Dec 28 2022
License Unlicense
Download theme-tools.zip

Index

Overview

Use this in combination with any of the themes available in the customizer to easily change the theme colors from within Twine.

⚠️ Warning: This add-on depends on specific CSS variables used in the customizer themes, it won't work on other themes that don't use the same variables, unfortunately. For more general manipulation of styles in non-supported themes check out the CSS Macro.

Installation

Macros

<<theme>>

<<theme>>

Syntax: <<theme target effect value [variable]>>

This macro modifies the different colors available in the themes: background, sidebar and accents (links, buttons, etc.).

Arguments:

Effect Description Value
color Sets the color. Hexadecimal color, e.g. #FF8800.
hue Sets the hue. Integer between 0 and 360.
shift Shifts the hue. Integer between -360 and 360.
lightness Sets the lightness. Percentage between 0% and 100%.
lighten Increases the lightness. Percentage between -100% and 100%.
darken Lowers the lightness. Percentage between -100% and 100%.
saturation Sets the saturation. Percentage between 0% and 100%.
saturate Increases the saturation. Percentage between -100% and 100%.
desaturate Lowers the saturation. Percentage between -100% and 100%.
opacity Sets the opacity. Percentage between 0% and 100%.
thicken Increases the opacity. Percentage between -100% and 100%.
dilute Decreases the opacity. Percentage between -100% and 100%.

Out of range values are clamped to the nearest valid value, only values that can't be parsed will return an error.

Usage:

<<theme background hue 20>>
<<theme background saturation 20%>>
<<theme background darken 8%>>
<<theme background lighten 8%>>
<<theme sidebar thicken 10%>>
<<theme accent shift 60>>

READ: Documentation

Usage notes

How to persist changes

Since CSS is not part of the story state, by default changes made by this macro won't be persisted and will revert to the default when saving or reloading the game.

If you want changes to be persistent, you will need to use variables to keep track of colors. To make this easy, the macro has an optional parameter that you can use to pass a variable name — the resulting color will be saved to that variable.

As an example, let's say you wanted changes to the background color to be persistent.

First, set the inital value in the StoryInit passage:

<<set $bgColor to '#334455'>>

Then, add the following line to the PassageReady passage to make sure it's always applied:

<<theme background color $bgColor>>

Now you can modify the background color anywhere, just make sure to pass the correct variable name (as a quoted string):

<<theme background darken 5% '$bgColor'>>

That's it, now the background color will be preserved when you refresh or load a saved game.

Live demo

Demo Twee code:

:: Start
<<theme background color '#332222' '$bgColor'>>\
Accent: <<link "Shift hue">>
        <<theme accent shift -30>>
    <</link>>
Background: <<link "Darken">>
        <<theme background darken 8>>
    <</link>>, <<link "Lighten">>
        <<theme background lighten 8>>
    <</link>>
Sidebar: <<link "Opaque">>
        <<theme sidebar thicken 10>>
    <</link>>, <<link "Translucent">>
        <<theme sidebar thicken -10>>
    <</link>>
Effects: <<link "Sepia">>
        <<theme background hue 20>>
        <<theme sidebar hue 20>>
        <<theme accent hue 20>>
        <<theme background saturation 10>>
        <<theme sidebar saturation 10>>
        <<theme accent saturation 10>>
    <</link>>