Elements

An element is one piece of content on a page: a heading, a picture, a framed callout. Every element has a Type, which decides which other fields it understands.

{
  "Type": "Heading",
  "Text": "Setting up camp",
  "Alignment": "Center"
}

Elements appear in five places, and where they appear changes how they're positioned:

Where	Positioning
Page.Elements	Stacked top to bottom.
Page.Background	Placed by Position, drawn behind the page's elements.
Page.Foreground	Placed by Position, drawn over the page's elements.
Book.Underlay	Placed by Position relative to the book, drawn behind the book sprite.
Book.Overlay	Placed by Position relative to the book, drawn in front of everything.

Where an element appears doesn't change what it can do. A tooltip, an Action or a HoverAction works the same in any of the five. Note that an element in Page.Background or Page.Foreground with none of those is transparent to the cursor, so decorative art doesn't cover the page.

---

Element types

• Title (Title)

  Large heading text.

• Heading (Heading)

  Section heading text.

• Paragraph (Paragraph)

  Body text.

• Image (Image)

  A sprite, an animation or an item's icon, optionally with text drawn on it.

• Divider (Divider)

  A horizontal rule, plain or decorative.

• Panel (Panel)

  A nine-sliced frame containing other elements.

• Banner (Banner)

  A three-sliced strip with text in the middle, a scroll or ribbon.

• Button (Button)

  A nine-sliced frame with a label, for running an action.

• Page number (PageNumber)

  The page's own number, filled in automatically.

An unrecognised Type is skipped with a warning rather than breaking the book.

---

Common fields

Every element understands these, whatever its type.

Property	Type	Default	Description
Type required	element type	—	Which kind of element this is. Determines every other field below.
Id optional	string	—	An optional identifier for this element. Not used for navigation, purely for your own reference.
Alignment optional	Left | Center | Right	Left	Where the element sits within its container's width. Only has an effect when the element is narrower than the space available (see Layout).
Scale optional	number	1	The element's scale. Its meaning depends on the element type: sprite scale for Image, Panel, Banner, Button and Divider. Font scale for Title, Heading and Paragraph. See Units and scale.
SpacingAfter optional	int	8	The gap between this element and the next one, in unscaled sprite pixels × Scale. Not applied after the last visible element, so a trailing gap can't appear at the bottom of a page or panel.
MarginLeft optional	int	0	Space reserved to the element's left, in unscaled sprite pixels × Scale. This narrows the width the element measures against, so text wraps at the indented width rather than overflowing.
MarginRight optional	int	0	Space reserved to the element's right, in unscaled sprite pixels × Scale.
Position optional	Point	{ X: 0, Y: 0 }	The element's position, in screen pixels. Only used in Background, Foreground, Underlay and Overlay, where elements are placed rather than stacked. Unlike every other spacing field this is not multiplied by Scale. Changing an element's scale resizes it in place rather than moving it.
Condition optional	string	—	A game state query. When it evaluates false the element is hidden, and elements below it close the gap. Re-checked several times a second while the book is open.
Action optional	string	—	A trigger action run when the element is clicked. When set, the element becomes interactive: any element type can have one, not just Button.
Actions optional	list of string	—	Trigger actions run in order when the element is clicked. Combined with Action rather than replacing it, so an element with both runs Action first.
Sound optional	string	bigSelect	The cue played when the element is clicked. Only used when Action or Actions is set, and played once however many actions run. Set to null for a silent click.
HoverAction optional	string	—	A trigger action run when the cursor moves onto the element. Runs on entry, not while the cursor rests there. Sound doesn't apply.
HoverActions optional	list of string	—	Trigger actions run in order when the cursor moves onto the element. Combined with HoverAction rather than replacing it, so an element with both runs HoverAction first.
DisplayName optional	string	—	The bold title of the element's hover tooltip. Works in every list, including a page's Background and Foreground.
Description optional	string	—	The body of the element's hover tooltip. Works in every list, including a page's Background and Foreground, where setting it is also what makes an otherwise decorative element reachable by the cursor.

Any element can be clickable

Action lives on every element, not just Button. An Image with an Action is a perfectly good bookmark or tab. Button is just the shorthand for the common case of a framed label.

Text fields

Understood by Title, Heading, Paragraph, Banner, Button and Image.

Property	Type	Default	Description
Text optional	string	—	The text to draw. Wraps automatically to the available width, including breaking words that are too long for a line on their own. \n forces a line break.
FontType optional	font type	varies	Which font to draw with. The default differs per element type.
TextColor optional	color	the book's default	The text colour.

Sprite fields

Understood by Image, Panel, Banner, Button and Divider.

Property	Type	Default	Description
TexturePath optional	string	—	The asset name of the sprite sheet, such as Assets/PeacefulEnd.Parchment/panelFrame2 or a vanilla path like LooseSprites/Cursors. This is a game asset name, not a file path in your content pack. Load your PNG into the game's content with a Content Patcher Load patch first. See Loading your art.
TextureSourceRectangle optional	Rectangle	the whole texture	The area of the sprite sheet to draw. Almost always needed: without it, the whole sheet is used, which for a multi-sprite sheet means a much larger element than you expect.
HoverTextureSourceRectangle optional	Rectangle?	—	An alternate source rectangle drawn while the cursor is over the element. Must be the same size as TextureSourceRectangle. The element's layout is measured from the normal rectangle, so a differently-sized hover sprite will overhang its own bounds. For a moving hover state on an Image, use HoverFrames instead.
TintColor optional	color	white	A colour multiplied into the sprite. Multiplying means it can only darken: red on grey art gives red, red on blue art gives near-black. Best on neutral or greyscale art.
SpriteEffects optional	None | FlipHorizontally | FlipVertically	None	Mirrors the sprite within its own bounds. It does not move the element. If flipping appears to shift the art sideways, the sprite has uneven transparent padding inside its source rectangle. Combine with a comma: "FlipHorizontally, FlipVertically". Ignored by Panel and Button, which are nine-sliced.

---

Font types

Value	What it is
Dialogue	The game's main dialogue font. Large.
Small	The game's small font. The usual choice for body text and labels.
Tiny	The game's tiny font.
SpriteText	The game's bitmap title font, the one vanilla uses for menu headers. Its natural size is large: a dozen characters at TextScale: 1 is around 300 pixels wide.

TextScale: 1 means each font's own natural size, so switching FontType changes the size. On elements that have both a sprite and text (Banner, Button and a text-bearing Image) TextScale sizes the text and Scale sizes the sprite, independently.

Sizing modes

Used by Panel, Banner, Button and Divider to decide how wide they are.

Value	Behaviour
Fill	Take the full width available.
ShrinkToFit	Be exactly as wide as the contents need. The element is then placed by its Alignment.
Fixed	Be exactly Width wide. Requires Width.

In every mode the result is clamped to the space available, so an element can never be wider than its container.

Colors

Colour fields accept any of:

Form	Example
A colour name	"SkyBlue"
RGB hex	"#8B4513"
RGBA hex	"#8B4513FF"
8-bit RGB	"34 139 34"
8-bit RGBA	"34 139 34 255"

Values are space-separated, not comma-separated. An unparsable colour logs a warning and falls back to the default.

Rectangles and points

Rectangles and points are objects:

"TextureSourceRectangle": { "X": 0, "Y": 0, "Width": 16, "Height": 16 },
"Position": { "X": -64, "Y": 192 }