how do I use different color schemes for my dialogue boxes in Ren’Py

This information is valid for Ren’Py 7.3.x. I believe it should work all the way back to Ren’Py 7.x. The names and values I use for the variables do not need to be yours.

Some readers prefer reading light text on a dark background. Some prefer the opposite. You can make this a user setting, or Preference, in your Ren’Py game.

Ren’Py gives you several baked in Preferences in the default project that you can use, or not. There are a heck of a lot more that are native to Ren’Py. However, they don’t cover everything, and you may want to make some of your own.

Preferences are a kind of persistent variable. A persistent variable is a game setting that stays constant when a player exits a game, and even stays the same across playthroughs. To make your custom settings, you’ll need to define and set a persistent variable.

Open up your scripting files in your code editor of choice.

options file

Here’s a “blank” game created by Ren’Py 7.2.3. I’ve opened the options.rpy file. You can put persistent variables many places in your scripts. You can make a file just for them! In this case, though, I put my custom persistent variables in the options file because it makes sense to me.

# additional persistent variables begin here
define persistent.colorscheme = "lightondark"
# end extra variables

The comments (# lines) are for my own convenience so I can locate the preferences in my files later.

With this statement I’ve added a persistent variable called colorscheme and given it the default value of lightondark (with quotes, so the computer reads it as a text string). In order to make a variable persistent, you need to have “persistent.” in front of it.

Next, we want to add the option to our Preferences screen. Open up screens.rpy and find the screen preferences() function.

This is an example of the default Preferences screen. It makes a layout with vboxes and hboxes. You may have already changed some code in here, and that is fine.

n.b. I have word wrap enabled in my editor. Make sure you put what’s in line 874 all on one line. Same with line 875.

Figure out where you want to position your new option. In this case I decided to stick the custom preference in a new column.

style_prefix radio

style_prefix "radio"
label _("Dialogue box")
textbutton _("Light on Dark") action SetVariable("style.say_dialogue.color","#fff"), SetVariable("style.window.background", "gui/textbox.png"), SetVariable('persistent.colorscheme','lightondark'), style.rebuild
textbutton _("Dark on Light") action SetVariable("style.say_dialogue.color","#000"), SetVariable("style.window.background", "gui/game_menu.png"), SetVariable('persistent.colorscheme', 'darkonlight'), style.rebuild

radio means the user can only select one of the options. The label’s what you want the preference to be called. Here we add two options which display as Light on Dark and Dark on Light.

action tells Ren’Py to do something when that text is clicked. On these lines we’re telling Ren’Py to set some variables and then refresh the look and feel.


This will make the text color in the dialogue box white. You can sub in any hex color for #fff.

SetVariable("style.window.background", "gui/textbox.png")

Surprisingly window.background only seems to apply to the dialogue window in a blank project. If you have other windows defined in your UI, though, this line will change the background for them too. Anyway, we’re setting the dialogue box background to be the textbox.png file stored in the gui folder. It’s a dark image, but you can use whatever you want. I don’t think you can define a color for window.background.


Here’s the variable we defined in options.rpy. Note that this is the same value, lightondark, as the default. That means the Preferences screen will render this as selected.


We want to make Ren’py refresh the colors/images now according to what the user has just set.

The next line of code lets you define an additional possible background and text color for your dialogue box.

Further notes

You do not need to use these two color schemes. You can have as many as you like. You can also change the font itself, or spacing. However, the more tweaks you want to make, the more you may want to define your own style.

I didn’t suggest defining a style above because we’re just trying to get things to work. That’s something for another day.

Leave a Reply

Your email address will not be published. Required fields are marked *