Set background image for electron-app version (i.e., Desktop Twine)

Authoring Twine
1

Twine Version: 2.10.0

Is there a way to set a background image for the desktop version of Twine. I’m interested in a background for the tool itself, not for the story or individual passages.

2

The Advanced Customization section of the Twine Reference, that is accessible from the Learn Twine section of the Twiney web-site, includes information about how to use CSS Rules in a correctly placed user.css file to styling the look of the Desktop release of the Twine 2.x application.

3

Thank you, Greyelf!

I can set a background color using the code below, but how would I specify in user.css for app Twine to use a background image?

For instance, I have an image file, cogs.png in the same folder with user.css. What would user.css need in order to use that as the background image.

passage-map {
  background: hsl(204, 19%, 26%) !important;
}
4

Did you try the background-image property?
I’ve no time to test right now, but under https://www.w3schools.com/, which is my main reference website about css, this might work. Assumine passage-map really is the element to change this would give something like

passage-map {
background-image: url("mybackgroundimage");
}
5

I had the same thought, souppilouliouma. This doesn’t work:

.passage-map {
  background-image: url("cogs.png") !important;
}
6

Reviewing the source code of the getUserCss() function that is used to access the user.css file shows that it needs to be located in the Twine child-folder of whichever folder the Author’s Operating System has been configured to store its “documents” in.
eg. on Windows that might be the user’s Documents\Twine folder.

Once the user.css file is located in the correct folder, the first of the examples…

.passage-map {
	background: hsl(0, 0%, 75%) !important;
}

…can be used to confirm the file is in the right location.

While the application is open, the Help > Troubleshooting > Show Debug Console toolbar menu items can be used to reveal the HTML structure of any part of the application, and what CSS is being applied to the elements of that structure.
eg. While the Passage Map of a project is being display, the Debug Console can be used to determine that three “background” related properties are being used to apply its default styling…

.passage {
    background-color: var(--faint-blue);
    background-image: url(../../static/media/graph-paper-light.1491480….svg);
    background-size: 100px;
    /* other default assignments. */
}

note: you may notice that the file-path of the default image’s URL includes ../.. at the start of it, which indicates some folder navigation was needed to locate the file. This fact will become important soon.

Based on the above, a minimum rule needed to show a “cogs.png” image might look something like…

.passage-map {
	background-color: transparent !important;
	background-image: url('cogs.png') !important;
}

…however, when the Passage Map of a project is opened that image wont be seen.

Reviewing the above CSS within the Debug Console shows that the application is expecting the image file to be located in a very specific “folder”, that is located within the application’s app.asar resources file. As you’re likely unable to update the contents of that resources file, you will need to some “folder navigation” in your own URL.

If you place a copy of your cogs.png file within same folder you run the Twine application’s execution file from (1), then a URL with a file-path like the following should work…

.passage-map {
	background-color: transparent !important;
	background-image: url('../../../../cogs.png') !important;
}

(1) which ever folder you installed the Twine application into.

So in summary:

  • the user.css file needs to be stored relative to your Documents folder.
  • the image files you’ll be using need to be stored relative to the Twine executable.
  • folder navigation may be needed in the URL to help the application to find the image file.
7

Thank you, GreyElf. I appreciate you taking the time and effort.

I can confirm that my user.css file is in the correct location and produces a light gray background for Twine in place of the usual graph-paper-like background.

My Twine child folder for projects is at C:\OneDrive\Documents\Twine

I have copied cogs.png and pasted it next to the Twine.exe file in the following path:

C:\Program Files\Twine

I believe that to indicate the correct executable directory in my user.css file, I need to go up three directory levels to the root of C:, then down into Program Files\Twine, which is where my Twine.exe lives.

Given the above specified directory paths, I’m thinking the following should specify the path to the image cogs.png:

.passage-map {
	background-color: transparent !important;
	background-image: url('../../../Program Files/Twine/cogs.png') !important;
}

However, this doesn’t appear to work. Here’s my reasoning for the above directory navigation: up one level from child Twine folder into Documents, up another into OneDrive, up another into C:\ – and then down into Program Files/Twine/cogs.png

8

I should add that I first tried this, before trying altering the path to my PNG image:

.passage-map {
	background-color: transparent !important;
	background-image: url('../../../../cogs.png')
}
9

Oops, I re-read your post carefully and am adjusting for path to app.asar folder… I’ll report back…

10

I successfully placed cogs.png in

C:\Program Files\Twine\resources

…the same folder containing app.asar

I modified user.css to the following, but no luck:

.passage-map {
	background-color: transparent !important;
	background-image: url('../../../Program Files/Twine/resources/cogs.png') !important;
}
11

note: while I’m using a jpg file in my test, the following should work with a png file.

I installed a copy of Twine v2.10.0 into a folder named D:\apps\Twine_v2.10.0, and place my test cogs.jpg file in that folder, which is where the Twine.exe file is located.

I place the following CSS Rule in my user.css file…

.passage-map {
	background-color: transparent !important;
	background-image: url('cogs.jpg') !important;
}

…which obviously failed to locate the cogs.jpg file.

I inspected the passage-map classed <div> in the Debug Concole, and determined that the above rule was correctly being applied. And when I hovered my mouse cursor over the cogs.jpg reference in the above URL, the debugger showed it was looking for that file using a URL of…

file:///D:/apps/Twine_v2.10.0/resources/app.asar/electron-build/renderer/cogs.jpg

Which confirms my earlier statement that the application is trying to find the cogs.jpg within a child folder of the app.asar archive file.

So I added folder navigation path of ../../../../ at the start of my modified cogs.jog URL, so that the application would look for the image file in the D:\apps\Twine_v2.10.0 folder instead…

.passage-map {
	background-color: transparent !important;
	background-image: url('../../../../cogs.jpg') !important;
}

…and that image is now displayed as the background of the Passage Map.

note: If you prefer to store your image file within the Twine application’s resources folder, which would have the following path on my drive…

D:\apps\Twine_v2.10.0\resources

…then a folder navigation of ../../../ should result in the application being able to find that image…

.passage-map {
	background-color: transparent !important;
	background-image: url('../../../cogs.jpg') !important;
}

…because that resources folder was included in the original path the application was using when it tried to locate the image file. At least it was on my machine.

1 Like
12

Excellent. I’ll make modifications and report back. Appreciate it!

13

It works! Thanks, Greyelf! It tiles the image. Is there a way to make the image fill the background instead.

14

There are a number of “background” related CSS properties you can use:

  1. The background-repeat property controls the potential “tiling” of the image, both horizontally and vertically, assigning a value of no-repeat will stop tiling in both directions. The !important flag is not needed, as the default CSS for the element doesn’t assign a value for this property.
  2. The background-size property controls the potential “sizing” or “scaling” of the image within the boundaries of the element that it is a background of. Because you want the image to fill the entire background, a value of 100% 100% will likely be needed. This time the !important flag will be needed to override the default sizing of the original background.

The final CSS Rule would look something like…

.passage-map {
	background-color: transparent !important;
	background-image: url('../../../../cogs.jpg') !important;
	background-repeat: no-repeat;
	background-size: 100% 100% !important;
}
15

I actually code in VSCode with Tweego extension, but I’m writing a tutorial game in Desktop Twine to learn the use of that tool better.

I had to fiddle with percentages but managed to get this (very cool, thanks Greyelf!!):

Now I’m thinking about writing a batch file that randomly picks a particular background image from a collection, saves the needed text in user.css, then launches desktop Twine… I might have to ensure the images are in Twine/resources ahead of time: Windows doesn’t seem to appreciate me trying to save files there.

MyAppTwineBackground
MyAppTwineBackground1419×668 127 KB