Playnote > Theming > Manifest

For a theme to be valid, it must have a file named theme.kdl in its folder. As the extension suggests, this is a KDL 2.0 document, expecting a specific structure.

This file is called the theme manifest. An example manifest that uses all features looks like this:

theme "foon" format=1 {
    name "Foon Theme"
    description """
        A very foon theme I just made up.
    """
    creator "Tearnote"
    credit "my cat Luna helped a bit"
    credit "and my other cat Niko"
    version "1.0"
    homepage "https://playnote.dev"
    license "MIT"

    extends "default"
    styles "style.pncss"
    scripts "scripts.as"
    views "views.kdl"
}

Caution

Any extraneous nodes or unexpected arguments cause the manifest to be rejected.

Root node

The theme must contain a single root node theme, with an "id" argument, and then format=1.

The id is a string that must be unique among all installed themes. It must be equal to the name of the theme's folder, or the theme is not valid. (The installer ensures this.) This implies the id must not contain any characters which could be problematic on some filesystems.

Metadata

All metadata fields are optional.

• name: Human-readable theme name. This, rather than the id, will be shown in the UI.
• description: Text description of the theme. In the example, KDL multi-line syntax is used; it can be used instead of a normal string anywhere.
• creator: Name of the person who created the bulk of the theme.
• credit: Mentions of any additional work. Unlike the others, there may be multiple credit entries.
• version: A version string. It can be anything, but semver is recommended.
• homepage: A website address associated with the theme.
• license: Terms of distributing and modifying the theme. If missing, “All Rights Reserved” is implied, meaning nobody else can modify or redistribute it. Include the full text of the license with the theme.

Resource links

The manifest must link to resource files that are part of the theme. Only the entry points must be linked; certain resource types have syntax for importing other files. Such imports are traversed recursively, and don't have to be explicitly linked.

The linking requirements are:

• The extension must be correct. That is, styles are .pncss, scripts are .as, and views are .kdl.
• Subfolders may be used, but paths must be relative, and must not contain . or .. components.
• Each line must contain one path.

There may be multiple lines of the same type:

    scripts "decorators.as"
    scripts "playfield.as"

They will behave as if concatenated, in the provided order.

Inheritance

extends declares a theme as extending another theme. The theme is said to be a child of a parent theme. The parent theme must be referenced by its id, and it must be already installed.

The theme will be constructed as if the parent's resource links were loaded first, and then the child's links. Standard concatenation rules apply, with a few extra allowances:

• If a child defines a view that's already present on the parent, this view will be overridden. Normally, this would be an error.
• If a child defines a script with the exact same path as the parent (including any subfolders), the parent's script will not be loaded. Normally, a second class with the same name is an error.

Any metadata present on the child overrides the parent's value. Credits are the exception: they accumulate rather than override. Due to this, using credit metadata is generally recommended.

Note

Add the child theme creator as a credit so that both the original creator and the remixer can be shown.

Example:

theme "child" format=1 {
    extends "default"
    credit "remixed by BMSMaster"
}