Playnote > Theming > Reference

This page is the index of schemas exposed to themes. It records which names may be used in stylesheets, views and scripts, and which properties each name accepts. Here you can check the variety of customizations you can apply.

Important

As the game is currently in its early stages, the less generic content types are in constant flux. Widgets in Playnote/src/comp, views, default decorators, and widget script APIs are omitted until the interfaces settle. Consult the source code and the default theme for reference to these types of content.

Property types

Properties of widgets, decorators, constants, and primitives use the shared value vocabulary below. The same semantic types are also exposed to theme scripts, with the conversions documented in the script value types section.

Integer

A whole number.

z-index: 5;
z-index: -1;

Bool

Can be true or false.

wrap: true;

Offset

A one-dimensional signed value, in screen units.

gutter: 5;
gutter: -8;
gutter: 0.4;

Length

A one-dimensional non-negative value, in screen units.

size: 12;
size: 0.1;
size: 0;

Ratio

A unitless fraction. Can be written as a percentage.

scale: 0.5;
scale: 120%;
scale: 400%;
scale: -2;

Normalized

A unitless fraction between 0 and 1, inclusive. Can be written as a percentage.

opacity: 0;
opacity: 100%;
opacity: 0.5;

Angle

A measure of rotation. Must use either a deg (degrees) or a rad (radians) suffix.

rotation: 0rad;
rotation: 90deg;
rotation: -180deg;
rotation: 720deg;
rotation: 3.14rad;

Duration

A length of time, non-negative. Must use either an s (seconds) or ms (milliseconds) suffix.

fadeout: 1s;
fadeout: 0s;
fadeout: 1.2s;
fadeout: 1600ms;

Point

A two-dimensional signed value, in screen units. Has a shorthand for equal values.

position: 20 10;
position: -5 0;
position: 0.2 0.1;
position: 64;

Size

A two-dimensional non-negative value, in screen units. Has a shorthand for equal values.

size: 200 150;
size: 8.5 4.5;
size: 16.1 0;
size: 2;

Anchor

A two-dimensional unitless fraction between 0 and 1, inclusive. Can be written as percentages. Has a shorthand for equal values.

align: 0.5 0.5;
align: 1 0;
align: 0.2 50%;
align: 50% 20%;
align: 0;

Edges

A four-dimensional signed value, representing four cardinal directions in screen units, with a number of shorthands you may know from CSS.

inset: 8 10 8 0; /* top right bottom left */
inset: 5 -5;     /* vertical (top and bottom), horizontal (left and right) */
inset: 0.5;      /* all four */

Color

A color value, including the optional alpha channel. Must be written via either the rgb() or oklch() function.

rgb() specifies the color as a RGB triplet, each channel itself a Normalized value. It is interpreted in the sRGB colorspace, and is therefore most useful for copying colors from image editors or color pickers.

oklch() uses the Oklab colorspace via the LCh cylindrical model. Since it's based on human perception, it's most useful for authoring colors directly in the stylesheet in a more natural, predictable way. The arguments are lightness (Normalized), chroma (Normalized), and hue (Angle). To discover it, you can play with the color picker at https://oklch.com/.

Both functions can optionally specify an alpha value. It is separated from the argument list with a /, and is itself a Normalized value.

Regardless of the function used, animation always happens in Oklab.

Please note that oklch() is capable of expressing colors outside of sRGB. In fact, it is possible for an animation between two colors that are both inside sRGB to have a midpoint that lies outside. If this happens, the out-of-gamut color will be projected back into sRGB, and a warning will be printed to let you know to fix your theme.

color: rgb(0 0 0);                  /* black */
color: rgb(1 1 1 / 0.5);            /* a semitransparent white */
color: rgb(25% 0 0);                /* a dark red */
color: rgb(0 0 0 / 10%);             /* barely visible black */
color: oklch(0.7 0.1 51deg);         /* cream */
color: oklch(70% 23% 142deg / 0.4);  /* a semitransparent green */

Convenience syntax is available for changing the alpha of color constants:

@const colors {
    red: rgb(1 0 0); /* alpha implicitly 100% */
}

text.red {
    color: rgb(colors.red / 70%); /* overridden to 70% */
}

text.also-red {
    color: oklch(colors.red / 70%); /* equivalent; color function is irrelevant in this shorthand */
}

Enum

The value is one from a set of identifiers. The list of valid identifiers is different for each property, and may even be different between runs of the game.

expand: width;       /* or "height", or "both" */
style: Sans-Regular; /* values are the font styles loaded by the game */

Script value types

Theme scripts expose the same semantic vocabulary as stylesheets, in addition to AngelScript's built-in types.

Additional generic types are available for floating-point and integer vectors:

• Floating-point: float2, float3, float4,
• Integer: int2, int3, int4.

Their x, y, z (3-component only), and w (4-component only) components are available as properties. They support basic arithmetic operators.

The semantic types are:

• 1-component: Offset, Length, Ratio, Normalized, Angle, Duration,
• 2-component: Point, Size, Anchor,
• 3-component: Color (with optional alpha),
• 4-component: Edges.

Most semantic types convert to and from their corresponding generic vector type, with the same construction shorthands. They also support unit-aware arithmetic. Length, Offset, Normalized, and Ratio construct from a float.

Color script syntax

Color rgb(Normalized, Normalized, Normalized, Normalized = 1.0)
Color rgb(float3)
Color rgb(float4)
Color linear(Normalized, Normalized, Normalized, Normalized = 1.0)
Color linear(float3)
Color linear(float4)
Color oklch(Normalized, Normalized, Angle, Normalized = 1.0)
float4 Color::srgb()
float4 Color::linear()

rgb() expects sRGB components. linear() expects linear-RGB components. oklch() uses the Oklab LCh model, equivalent to the oklch() stylesheet value. Color arithmetic always happens componentwise on linear-RGB channels, including color arithmetic in stylesheet calc(). Color animation always happens in Oklab. There's no real need to remember this; for the most part, color operations will simply behave as intuitively expected.

Angle script syntax

Angle deg(float)
Angle rad(float)
float Angle::deg()
float Angle::rad()

Duration script syntax

Duration sec(float)
Duration msec(float)
float Duration::sec()
float Duration::msec()

Script APIs

Shape@ syntax

Shape@ is a reference to a stateful, drawable shape created by a Drawlist@. Its shape-wide properties are:

Point position;
Ratio scale;
Angle rotation;
Point scissor_origin;
Size scissor_size;

The following methods are available:

void restart()
void set_text(Text@)
void set(const string &in, Length)
void set(const string &in, Offset)
void set(const string &in, Angle)
void set(const string &in, Size)
void set(const string &in, Point)
void set(const string &in, Color)

restart() restarts every animation in the shape. set_text() supplies host-composed text to the shape's first text primitive; passing null clears it. The set() overloads drive stylesheet hooks by name. An unknown hook name is ignored, while a value of the wrong type raises an error.

Drawlist@ syntax

Drawlist@ is an application-managed collection of shapes. It exposes:

Shape@ spawn(const string &in)
void detach(Shape@)

spawn() creates a shape from a stylesheet recipe and adds it to the drawlist. An unknown recipe produces an empty but valid shape. detach() removes a shape from the drawlist and marks it for expiry after its finite animations finish.

Theme@ syntax

Theme@ provides access to static stylesheet constants. Each method takes the constant's qualified name, such as "palette.accent":

Color color(const string &in) const
Length length(const string &in) const
Offset offset(const string &in) const
Normalized normalized(const string &in) const
Ratio ratio(const string &in) const
Angle angle(const string &in) const
Duration duration(const string &in) const
bool boolean(const string &in) const
int integer(const string &in) const
Point point(const string &in) const
Anchor anchor(const string &in) const
Size size(const string &in) const
Edges edges(const string &in) const

Only non-animated constants can be retrieved through Theme@.

Widget properties

These properties are available for styling on each of the basic widgets. A widget can also use properties defined on any of its parents. Properties of the widget type, as the base of every other type, can be used universally.

widget properties

Parent: none. Usable in a view: yes.

Property	Type	Description
desired-size	Size	The maximum size the widget will take.
desired-inner-size	Size	The maximum size the widget's content will take.
expand	Enum	Which axes fill the space made available by its parent: none, width, height, or both.
align	Anchor	Aligns the widget's content within the widget's size: 0 0 is top-left and 1 1 is bottom-right.
offset	Point	Position offset relative to the parent.
inset	Edges	Padding between the widget boundary and its content.
scale	Ratio	Local scale multiplier.
rotation	Angle	Clockwise local rotation.
origin	Point	Local pivot point for scale and rotation.
depth	Integer	Additive drawing depth. Smaller values are drawn in front. Total computed value cannot be lower than 0.
opacity	Normalized	Multiplies the opacity of the widget and its descendants.
visible	Bool	Whether the widget is drawn. Invisible widgets still participate in layout.
enabled	Bool	Whether the widget participates in layout and other widget phases.
overflow	Enum	Child overflow behavior: ignore or clip.

inf may be used for an unbounded size. The desired-size and desired-inner-size values constrain measurement; they do not force a widget to occupy that size unless the relevant axis is also included in expand.

text properties

Parent: widget. Usable in a view: no; text widgets are normally supplied through view slots or game code.

Property	Type	Description
size	Length	Point-size of each line.
line-height	Ratio	Spacing between lines, relative to the text size.
wrap	Bool	Whether text wraps to the available width.
hinting	Bool	Aligns text position and size to the pixel grid. Disable this for rotated or animated text.
color	Color	Text color.
style	Enum	A dynamically supplied font style. The available identifiers are the styles loaded by the game.

text-input properties

Parent: widget. Usable in a view: no.

Property	Type	Description
size	Length	Point-size of the text.
line-height	Ratio	Spacing between lines, relative to the text size.
color	Color	Input text color.
cursor-color	Color	Visible cursor color.
cursor-width	Length	Cursor width in logical screen units, independent of text size.
style	Enum	A dynamically supplied font style. The available identifiers are the styles loaded by the game.

list properties

Parent: widget. Usable in a view: yes. Direct children may use the list layout parameters.

Property	Type	Description
orientation	Enum	Child stacking axis: vertical or horizontal.
gutter	Offset	Default space between children along the stacking axis.

scroll-list properties

Parent: widget. Usable in a view: no. In addition to self, it provides the selection decorator attachment point, which is drawn around the currently selected item.

Property	Type	Description
orientation	Enum	Scrolling axis: vertical or horizontal.
gutter	Offset	Space between items along the scrolling axis.
item-extent	Length	Fixed length of every item along the scrolling axis.
selection-ratio	Normalized	Proportion of the available main-axis space before the selected item.
selection-snap	Enum	Whether the selection ratio should be rounded to the nearest item extent: none, before, or after.

column-grid properties

Parent: widget. Usable in a view: yes; columns is a required constructor argument. Direct children may use the column-grid layout parameters.

Property	Type	Description
gutter	Offset	Default space between columns along the main axis.

modular-grid properties

Parent: widget. Usable in a view: yes; columns and rows are required constructor arguments. Direct children may use the modular-grid layout parameters.

Property	Type	Description
gutter	Point	Space between cells along the horizontal and vertical axes.

knob properties

Parent: widget. Usable in a view: no.

Property	Type	Description
empty-color	Color	Color of the unfilled part of the knob curve.
accent-color	Color	Color of the stem and filled part of the curve.
radius	Length	Radius of the knob curve.
thickness	Length	Stroke width of the curve and stem.
label-size	Length	Point-size of the optional attached value label.
glow-color	Color	Color of the glow.
glow-width	Length	Glow width on each side.

stepped-knob properties

Parent: widget. Usable in a view: no.

Property	Type	Description
empty-color	Color	Color of the unfilled part of the knob curve.
accent-color	Color	Color of the stem and filled part of the curve.
radius	Length	Radius of the knob curve.
thickness	Length	Stroke width of the curve and stem.
label-size	Length	Point-size of the optional attached value label.
glow-color	Color	Color of the glow.
glow-width	Length	Glow width on each side.
dot-radius	Length	Radius of the circle representing each step.

Decorator properties

Every decorator has a number of built-in properties which control how it is positioned within the attachment point.

Property	Type	Description
fit-width	Enum	Width supplied to the decorator: inner for the content area excluding inset, padded for the widget's natural content area including inset, or outer for the full widget area including expansion. Defaults to outer.
fit-height	Enum	Height supplied to the decorator, using the same inner, padded, and outer meanings. Defaults to outer.

For inner and padded, the decorator origin follows the widget's aligned content. inner also begins after the top and left inset. Decorators are drawn behind the widget.

Primitives

All shape primitives share a basic set of properties. Each primitive type also has its own properties that define its unique shape.

Common primitive properties

Property	Type	Description
position	Point	Primitive position in the containing shape's local coordinates.
rotation	Angle	Clockwise primitive rotation.
scissor-origin	Point	Top-left of the primitive's local clipping rectangle.
scissor-size	Size	Size of the primitive's local clipping rectangle.
scissor-rotation	Angle	Additional clockwise rotation of the clipping rectangle.
color	Color	Fill color.
opacity	Normalized	Multiplier applied to the alpha of the primitive's colors.
depth	Integer	Drawing depth. Smaller values are drawn in front.
outline-width	Length	Total outline width.
outline-color	Color	Outline color.
glow-width	Length	Glow width on each side.
glow-color	Color	Glow color.

circle primitive

A circle centered at position.

Property	Type	Description
radius	Length	Circle radius.

rect primitive

An axis-aligned rectangle centered at position.

Property	Type	Description
size	Size	Total width and height.
rounding	Length	Corner radius.

rect-tl primitive

An axis-aligned rectangle with its top-left corner (and its origin) at position.

Property	Type	Description
size	Size	Total width and height.
rounding	Length	Corner radius.

line primitive

A line positioned using offsets from position.

Property	Type	Description
start	Point	Start-point offset from position.
end	Point	End-point offset from position.
width	Length	Total line width.
cap	Enum	End-cap style: butt, square, or round.

capsule primitive

A horizontal capsule centered at position.

Property	Type	Description
width	Length	Distance between the centers of the two rounded ends.
radius	Length	Radius of each rounded end.

pie primitive

A filled circular sector centered at position.

Property	Type	Description
radius	Length	Outer radius of the sector.
start-angle	Angle	Clockwise angle at which the sector starts.
end-angle	Angle	Clockwise angle at which the sector ends.

arc primitive

A circular arc centered at position.

Property	Type	Description
radius	Length	Radius of the arc's centerline.
start-angle	Angle	Clockwise angle at which the arc starts.
end-angle	Angle	Clockwise angle at which the arc ends.
width	Length	Total stroke width.
rounded	Bool	Whether the arc ends are rounded instead of butt-ended.

polygon primitive

A polygon made of any number of vertices >= 3. Vertices are declared as nested vertex blocks:

polygon {
    vertex { at: 0 -8; }
    vertex { at: 8 8; }
    vertex { at: -8 8; }
}

Each vertex has one required Point property, at, relative to polygon position.

text primitive

A line of text. The text contents are supplied by script through the shape API; it cannot be set from within the stylesheet.

Property	Type	Description
size	Length	Em-height of the text.
line-height	Ratio	Line spacing in size-scaled ems.
align	Normalized	Horizontal alignment: 0 is left, 0.5 is centered, and 1 is right.
style	Enum	A dynamically supplied font style.

group primitive

A group has no properties, but rather is used to merge several primitives into one for the purposes of glow, outline, or transparency. See usage.

Layout parameters

A subset of widgets that are usable in views have layout parameters, which control how children are positioned within them.

list layout parameters

Parameter	Type	Presence	Description
leading-gutter	Number	Optional; defaults to 0	Replaces the list's gutter before this child. It is ignored for the first child.

column-grid layout parameters

Parameter	Type	Presence	Description
column-width	Integer	Optional; defaults to 1	Number of columns occupied by the child.

modular-grid layout parameters

Parameter	Type	Presence	Description
column	Integer	Optional; defaults to 0	Zero-based column of the child's top-left cell.
row	Integer	Optional; defaults to 0	Zero-based row of the child's top-left cell.
column-width	Integer	Optional; defaults to 1	Number of columns occupied by the child.
row-height	Integer	Optional	Number of rows occupied by the child. If omitted, there is no height limit.