Tearnote/Playnote
Watch
1
0
Fork
You've already forked Playnote
 0
Code Issues 22 Pull requests Releases 3 Wiki Activity Actions
Page: Theming
Pages
Building By Example Command Line Config Contributing Design Development Home IPC Input Manifest Reference Scripts Stylesheets Theming Views
9 Theming
Tearnote edited this page 2026-09-05 00:09:03 +01:00
Table of contents

Playnote > Theming

Playnote is built on top of a bespoke 2D layout engine. Every distinct screen element is a widget, and these widgets are nested to construct responsive layouts. A theme customizes the layout in several ways:

  • Views define structure: the widget hierarchy of every screen in the game.
  • Stylesheets define styles: visual properties of widgets.
  • Scripts define visuals: arbitrary drawing logic, when a style isn't enough.

These three components reference each other's resources, working together in a way that's superficially similar to the HTML+CSS+JavaScript trio of web development. Indeed, many of the concepts are borrowed for familiarity's sake. However, every feature has been designed fundamentally from scratch for Playnote's purposes, and the similarities are often superficial. I ask any theme author to keep an open mind when learning this system, since prior webdev knowledge may be misleading.

Caution

The theme system is not yet battle-tested. Please report anything that is broken, unintuitive, or limiting.

Location

Themes are located at:

  • Linux: ~/.config/playnote/themes/
  • Windows and portable mode: [executable folder]/config/themes

Each theme is contained in a separate folder at this location. If you started the game at least once, you should see the default theme in this location. It is automatically installed at start-up if missing, or if the game was updated. It can be useful as a reference, and can be safely inherited from.

Installation

A theme is distributed as a .pntheme file. It can be installed in either of these ways:

  • Drag and drop: Drag the file onto the window of the running game. If installation succeeds, Playnote switches to the theme automatically. Failures are printed to the logs.
  • Command line: Use the import command with the theme path.

Caution

Installing a theme with the same id overwrites the existing theme, including any local changes.

Distribution

If your awesome theme is finished, you can share it with others by creating a ZIP archive with theme files, and then changing the .zip extension to .pntheme. You may archive the theme folder, or the files inside directly; the theme location within the archive is autodetected as the first found folder that contains the manifest.

Hot reload

Any successfully loaded theme is active for hot reload. All of the theme's files, as well as the files of any theme it extends, are watched for changes. A change (such as saving a file in your text editor) triggers a full reload, which causes the following to happen:

  • New views will apply to newly opened screens,
  • New styles are reapplied to existing and future widgets, restarting any animations,
  • New scripts will be used by newly created widgets.

If the reload fails for any reason, the game continues to use the previous version and logs the error(s).

Caution

Fix or revert the mistake before restarting Playnote. A theme load failure during start-up causes Playnote to fall back to the default theme.

Since all diagnostics are printed into the logs, I suggest configuring the game to display the console window.

Next steps

If you're not so technical, or are looking to tweak small parts of the game, hop on to theming by example.

To fully understand the system and push Playnote to its limits, have a look at the detail pages:

Usage:

Project: