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.
Grid (Grid)

A container laying its children out across fixed-size cells.
Input (Input)

A text box the reader types into, for filtering a page against what they've typed.

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). In a placed list it anchors the element and `Position` is measured from there.
`VerticalAlignment` optional	`Top` \| `Center` \| `Bottom`	`Top`	Where the element sits within its container's height. Only used in `Background`, `Foreground`, `Underlay` and `Overlay`, since a stacked element takes its vertical position from the elements above it (see Placed elements). Setting it on a stacked element logs an error and does nothing.
`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. Measured from wherever `Alignment` and `VerticalAlignment` anchor the element, so under the default `Left` and `Top` it's a plain coordinate (see Placed elements). 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. Understands tokens.
`Lifetime` optional	`number`	—	Seconds the element stays up once shown. Setting it makes the element a timed one: hidden until a `ShowElement` action names it, so an `Id` is required.
`FadeAfter` optional	`number`	—	Seconds before it starts fading, reaching nothing at the end of `Lifetime`. Needs `Lifetime`, and must be below it.
`IgnoreCursor` optional	`bool`	`false`	Lets the cursor pass straight through the element to whatever sits beneath it, so it can't be hovered or clicked. Its children and its own `Background` and `Foreground` are still reachable (see Passing the cursor through).
`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`. Understands tokens.
`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. Understands tokens.
`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. Understands tokens.
`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. Understands tokens.
`TypedAction` optional	`string`	—	A trigger action run once every typewriter in the element's text has finished. See Typed actions. Understands tokens.
`TypedActions` optional	list of `string`	—	Trigger actions run in order once the element's typewriters have finished. Combined with `TypedAction` rather than replacing it, so an element with both runs `TypedAction` first.
`DisplayName` optional	`string`	—	The bold title of the element's hover tooltip. Works in every list, including a page's `Background` and `Foreground`. Can carry tokens. Any color, effect or link markup is taken out, as a tooltip draws plain text.
`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. Ignored when `IgnoreCursor` is set, which logs a warning. Can carry tokens. Any color, effect or link markup is taken out, as a tooltip draws plain text.
`Tags` optional	list of `string`	—	Free-form markers other mods can read off whatever the cursor is over, such as Lookup Anything support. Tagging an element also makes it reachable by the cursor, since a tag is only useful on something that can be hovered. Ignored when `IgnoreCursor` is set. See Tags.
`ParseTokenizableStrings` optional	`bool`	`true`	Whether the game's `[Token]` tokenizable strings are resolved in this element's `Text`, `DisplayName`, `Description`, `Condition` and actions. Set it to `false` where a square bracket is meant as the character itself. Color, effect and link markup is read either way.

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, Image and Input.

Any element's Text can carry tokens, placeholders replaced with something the book knows as the element is laid out. That covers Parchment's own %Token% forms and the game's [Token] tokenizable strings. Part of it can also be colored with inline color markup, given a text effect, written in one of the game's languages or turned into a link on a Title, Heading, Paragraph or PageNumber.

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. Can carry tokens, both Parchment's `%Token%` forms and the game's tokenizable strings. Leading whitespace is lost once the string also carries a Content Patcher `{{ }}` token (see Content Patcher tokens). Part of it can be colored with `[color=...]` markup (see inline color) given an effect such as `[wave]` (see text effects) or written in a language such as `[dwarvish]` (see languages), on every element but `Input`. On a `Title`, `Heading` or `Paragraph` it can also hold links.
`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 color.
`ShadowColor` optional	`color`	the game's shadow color	The color of the drop shadow drawn behind the text, alpha included. Left off, the shadow follows `TextColor`'s alpha instead. Ignored when `FontType` is `SpriteText`, which draws its own outline.

Sprite fields¶

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

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 color 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.

Animation fields¶

Understood by every element type. On an Image a frame steps through a sprite sheet. Everywhere else it moves the element, times a trigger action, or both.

Property	Type	Default	Description
`Frames` optional	list of `frames`	—	Animation frames. When omitted, the element draws where it was laid out.
`HoverFrames` optional	list of `frames`	—	Animation frames played while the cursor is over the element, replacing `Frames` for as long as it stays there. See Hover frames.
`FrameDuration` optional	`number`	`100`	How long a frame is shown when it doesn't specify its own `Duration`, in milliseconds.

Frame fields¶

Each entry in Frames or HoverFrames:

Property	Type	Default	Description
`Offset` optional	`Point`	`{ X: 0, Y: 0 }`	How far this frame is shifted from where the element sits, in unscaled sprite pixels × the element's `Scale`. Positive moves right and down. See Frame offset.
`Duration` optional	`number`	the element's `FrameDuration`	How long this frame is shown in milliseconds.
`Condition` optional	`string`	—	A game state query deciding whether this frame plays. When omitted the frame always plays. Understands tokens.
`Action` optional	`string`	—	A trigger action run each time this frame starts. Understands tokens. See Frame actions.
`Actions` optional	list of `string`	—	Trigger actions run in order each time this frame starts. Combined with `Action` rather than replacing it. Understands tokens.
`SourcePoint` optional	`Point`	the element's own sprite	Sprite elements only. The coordinate of the art for this frame, inheriting the element's `TextureSourceRectangle` for width and height.
`Scale` optional	`number`	`1`	`Image` only. A multiplier on the element's `Scale` while this frame draws. See Frame scale.

SourcePoint works on anything that draws art, so a Panel, Button, Banner, Divider, Grid or Input can step through a sheet the same way an Image does. It only moves where the art is read from, never how much of it, so a nine-sliced element keeps the border and the inset it was measured with.

Scale is the one field an Image alone can apply, since it's the only element drawn as a single quad with nothing inside it sized against it. Setting either field where it doesn't apply fails validation with a message saying so, rather than being quietly ignored.

Frames loop, and the cycle is timed from the moment the animation starts, so the first frame is the one that draws when it does.

A frame whose Condition fails is skipped, not paused on. The cycle gets shorter and the remaining frames close the gap, the same way a hidden element lets the ones below it close up. Conditions are re-checked while the book is open, so an animation can gain and lose frames as the game state changes.

Gaining or losing a frame starts the animation over. A cycle whose frame list changed isn't the cycle that was playing, so it restarts rather than resuming partway. That's what lets an animation gated behind a condition play properly: gate every frame on PeacefulEnd.Parchment_CurrentPageId <your page> and the whole thing plays from the top when the reader arrives, instead of catching it mid-cycle.

Timing a pause into a loop

Since the animation restarts when it becomes active, a long final frame reads as a delay before the next repeat. A ten-frame flourish followed by a frame of 60000 plays once on arrival then holds still for a minute, over and over, without needing anything to trigger it.

Animating a panel's frame¶

SourcePoint swaps the art without touching the layout, so a nine-sliced border can flicker, pulse or react to the game state. Every frame has to point at a patch laid out the same way and the same size, since the element was measured once against those dimensions:

A panel border that shifts between two patches

{
  "Type": "Panel",
  "TexturePath": "{{ModId}}/frames",
  "TextureSourceRectangle": { "X": 0, "Y": 0, "Width": 18, "Height": 18 },
  "Frames": [
    { "Duration": 400 },
    { "Duration": 400, "SourcePoint": { "X": 18, "Y": 0 } }
  ]
}

Nothing checks that the art fits

A source point aimed at a patch that isn't nine-sliceable, or that has a different border, draws a mangled box rather than raising an error. There's no way to tell intent apart from a mistake here, so the sheet is yours to lay out carefully.

Moving an element¶

Offset is the field that works on every element type, sprite or not. The element is measured once and keeps that space and that hitbox, so it slides over its own footprint rather than pushing the page around:

A panel that drifts up and down

{
  "Type": "Panel",
  "TexturePath": "{{ModId}}/frame",
  "TextureSourceRectangle": { "X": 0, "Y": 0, "Width": 18, "Height": 18 },
  "Frames": [
    { "Duration": 700 },
    { "Duration": 700, "Offset": { "X": 0, "Y": -1 } }
  ],
  "Children": [
    { "Type": "Paragraph", "Text": "Everything in here comes along for the ride." }
  ]
}

A container carries its children and its own Background and Foreground with it, since they are all drawn relative to the rectangle it was given.

Offsets add up

A moving element inside a moving container is shifted by both. Animate the container or its contents, not usually both, or pick offsets that read well together.

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¶

Color fields accept any of:

Form	Example
A color 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 color logs a warning and falls back to the default.

Alpha is optional and full strength when left off. Write the color you want at full strength and let the alpha fade it, the same way the game does elsewhere: "255 0 0 128" is a half-faded red rather than a brighter one. The channels are scaled by the alpha before anything is drawn, so a translucent color fades towards whatever is behind it instead of washing out towards white.

Inline color¶

A text element can color part of its Text by wrapping it in [color=...] and [/color]:

{
  "Type": "Paragraph",
  "Text": "You reeled in a [color=Gold]Legend[/color] at [color=#4A90D9]Mountain Lake[/color]."
}

The value takes any of the color forms above. Everything outside a tag keeps the element's TextColor.

Nesting. Tags nest, so [color=Red]a [color=Blue]b[/color] c[/color] draws c red again.
Tokens. Tokens work inside a run, game tokens included: [color=Gold][ItemName (O)128][/color]. The markup is read from the text as written before any token resolves, so a value a token brings in (such as something the player typed into an Input) is always drawn as it is and can't color anything.
Shadow. A colored run keeps the element's ShadowColor. Left unset, the shadow follows the run's alpha the same way it follows TextColor's.
Case. Tags are case-insensitive, so [Color=Red] works too.
Mistakes. A [color] that is never closed runs to the end of the text. A stray [/color] is dropped. A color that won't parse keeps the color around it. Each logs a warning.

Markup is read on every text element except Input, whatever ParseTokenizableStrings is set to.

Where markup isn't drawn

SpriteText keeps its own color, so [color] and the coloring effects ([rainbow], [gradient], [pulse] and [shimmer]) on an element drawn in it are ignored with a warning. A tooltip's DisplayName and Description draw plain text, so any markup in them is taken out rather than shown.

Links¶

A Title, Heading, Paragraph or PageNumber can turn part of its text into a link by wrapping it in [link=id] and [/link]. The id names an entry in the element's Links:

{
  "Type": "Paragraph",
  "Text": "You reeled in a [link=legend]Legend[/link] at [color=Blue]Mountain Lake[/color].",
  "Links": {
    "legend": {
      "TextColor": "Gold",
      "HoverTextColor": "Orange",
      "DisplayName": "Legend",
      "Description": "Only bites in spring rain.",
      "Action": "PeacefulEnd.Parchment_JumpToPageId legendary-fish"
    }
  }
}

A link behaves like an element of its own: it has its own tooltip, runs its own actions and carries its own tags, all reached through the stretch of text it covers.

Property	Type	Default	Description
`Condition` optional	`string`	—	A game state query deciding whether the link applies wherever it's used. When it fails the text is drawn plain (no color, tooltip or action) and can't be reached. See Tag conditions.
`TextColor` optional	`color`	the color around it	The linked text's color.
`HoverTextColor` optional	`color`	—	The linked text's color while the cursor is over it. Covers any `[color]` markup inside the link.
`DisplayName` optional	`string`	—	The bold title of the link's hover tooltip. Can carry tokens.
`Description` optional	`string`	—	The body of the link's hover tooltip. Can carry tokens.
`Action` optional	`string`	—	A trigger action to run when the link is clicked. Shorthand for a single-entry `Actions` that runs first when both are given.
`Actions` optional	`string[]`	—	Trigger actions to run in order when the link is clicked.
`HoverAction` optional	`string`	—	A trigger action to run when the cursor moves onto the link. Shorthand for a single-entry `HoverActions` that runs first when both are given.
`HoverActions` optional	`string[]`	—	Trigger actions to run in order when the cursor moves onto the link.
`Tags` optional	`string[]`	—	Tags carried by the link, read the same way as an element's own.
`HoverEffect` optional	`string`	—	A text effect applied to the linked text while the cursor is over it. Shorthand for a single-entry `HoverEffects` that applies first when both are given.
`HoverEffects` optional	`string[]`	—	Text effects applied in order to the linked text while the cursor is over it. See Hover effects.

Each occurrence is its own link. The same id used twice gives two links that are hovered, highlighted and reached by a controller separately.
Wrapping. A link that runs onto a second line is reached through its text on both lines, never through the words between them.
Nesting. [color] works inside and around a link. A link inside another link takes over the text it covers. Tags of the two kinds may overlap rather than nest, in which case each closing tag closes the innermost tag of its own kind.
Tokens and actions. A link's tooltip and actions resolve tokens against the link. It follows the element's ParseTokenizableStrings and plays the element's Sound when clicked.
The rest of the text. Text outside every link still shows the element's own tooltip and runs the element's own actions. So does a link that only sets TextColor, since it gives the cursor nothing to do.
Controller. Each link is a stop of its own, placed on the first line it covers.
Hover effects. A link can change effects under the cursor with hover effects.
Mistakes. A [link] naming an id that isn't in the element's Links or the book's is drawn as plain text with a warning. So is a [link] on any other element. Unclosed and stray tags behave as they do for inline color.

Links in SpriteText

A link drawn in SpriteText keeps its tooltip, actions and tags. Its TextColor and HoverTextColor are ignored, as SpriteText keeps its own color.

Shared links¶

A link used in many places can be defined once in the book's own Links rather than on every element that points at it:

{
  "Id": "you.FishingJournal_Book",
  "Links": {
    "legend": {
      "TextColor": "Gold",
      "DisplayName": "Legend",
      "Description": "Only bites in spring rain."
    }
  },
  "Pages": [
    {
      "Id": "catches",
      "Elements": [
        { "Type": "Paragraph", "Text": "You reeled in a [link=legend]Legend[/link]." }
      ]
    }
  ]
}

A [link] looks in the element's own Links first and the book's second. When both define the same id, the element's entry replaces the book's whole for that element rather than filling in around it, so a link's values always come from one place.

Text effects¶

These tags move or recolor each character of the text they wrap, without changing how it's laid out:

Tag	What it does	Value	Default
`[wave]`	Bobs each character up and down a beat behind the one before it.	amplitude and period	`2` and `1000`
`[bounce]`	Hops each character up off the line and back down, a beat behind the one before it.	amplitude and period	`2` and `800`
`[shake]`	Jitters each character to a new spot every period.	amplitude and period	`1` and `80`
`[wobble]`	Rocks each character back and forth about its center, a beat behind the one before it.	angle and period	`8` and `1200`
`[pop]`	Swells each character about its center and settles it back, a beat behind the one before it.	size and period	`0.25` and `800`
`[flicker]`	Dims and brightens each character on its own like a candle, wavering between a lowest strength and full.	lowest strength and period	`0.3` and `120`
`[rainbow]`	Colors each character one step further along the game's rainbow, cycling through every color once per period.	period	`2000`
`[gradient]`	Blends the text from one color to the next across its whole length, without moving.	two or more colors	required
`[pulse]`	Fades the whole stretch towards a color and back once per period.	color and period	a color is required, then `1500`
`[fade]`	Dims the whole stretch towards a lowest strength and back once per period, as though it were breathing.	lowest strength and period	`0.25` and `2000`
`[shimmer]`	Sweeps a band of color across the text like a glint of light, then rests until the next period.	color, period and width	`White`, `2500` and `3`
`[sparkle]`	Twinkles the game's own sparkles over random characters, each playing out over one period. See Sparkle.	color, period and chance	`White`, `400` and `0.2`
`[typewriter]`	Reveals the text one character at a time, the way the game's dialogue box does. See Typewriter.	speed, delay and options	`30` and `0`
`[underline]`	Draws a line under the text. See Decorations.	color	the text's color
`[strike]`	Draws a line through the text.	color	the text's color
`[highlight]`	Draws a marker box behind the text.	color	a soft yellow
`[redact]`	Covers the text with a solid bar, hiding it while keeping its width.	color	the text's color
`[scramble]`	Shows random glyphs in place of the text until its condition stops passing, then locks the real characters into place. See Scramble.	period and options	`80`
`[bold]`	Thickens the text by drawing it a second time, shifted to the right. See Bold.	strength	`1`
`[outline]`	Draws a solid outline around each letter, in place of the text's shadow. See Outline.	color and thickness	`Black` and `2`
`[glow]`	Draws a soft, fading halo behind the text that can breathe in and out. See Glow.	color, radius and period	`255 200 80`, `3` and `0`

{
  "Type": "Paragraph",
  "Text": "A [wave]legendary[/wave] catch! The line [shake=2]snapped[/shake] on a [rainbow]prismatic[/rainbow] fish. [bounce]Hooray![/bounce]"
}

{
  "Type": "Heading",
  "Text": "[gradient=Orange|Gold|255 240 160]Sunset Lake[/gradient] holds a [pulse=Gold|800]secret[/pulse]."
}

{
  "Type": "Heading",
  "Text": "[color=Gold][shimmer]Legendary[/shimmer][/color] Catches"
}

Values. A tag's value is split into parts by |, the same for every effect. Every part except a color is optional. [wave=4] sets only the amplitude and [wave=4|500] sets both. [bounce] and [shake] read their values the same way. So does [wobble], whose amplitude is how far it rocks either way in degrees, so [wobble=15|800] tips further and faster. [pop] reads them the same way too, its amplitude being how much larger a letter grows as a share of its size, so [pop=0.5] swells letters to half again their size and [pop=-0.3] shrinks them instead. [flicker] takes how faint it can get from 0 (vanishing entirely) to 1 (not at all) and then its period, so [flicker=0] gutters out and [flicker=0.7|300] is a slow, gentle waver. [fade] reads its values the same way, so [fade=0|4000] slowly vanishes and returns. A fade dims any decoration on its text along with it, while a flicker leaves them steady. [rainbow] takes only a period, so [rainbow=1000] cycles twice as fast and [rainbow=0] holds still, the way the game draws its own rainbow text.
Colors. A color keeps any spaces of its own, such as 255 215 0, which is why parts aren't split on spaces. [gradient] takes two or more colors, spread evenly from the first character to the last. [pulse] takes one color and then an optional period, such as [pulse=Gold] or [pulse=Gold|800]. [shimmer] takes an optional color, period and width in that order, so changing its period means writing its color first, such as [shimmer=White|1500]. All three take any of the color forms.
Units. An amplitude is in unscaled pixels multiplied by the text's scale (its Scale, which is TextScale on an element with a sprite). A period is in milliseconds: how long one bob or hop takes for a wave or a bounce (or one rock back and forth for a wobble, or one swell and settle for a pop), how long each spot is held for a shake, how long each character takes to drift to its next strength for a flicker, how long a full trip through the colors takes for a rainbow, how long one fade out and back takes for a pulse or a fade and how long from one glint to the next for a shimmer. A shimmer's band crosses in the first half of its period and the text rests for the second. Its width is how many characters the band reaches either side of its center, so [shimmer=White|2500|1] is a thin glint and [shimmer=White|2500|6] a broad sheen.
Layout. An effect only changes the drawing. Lines keep the room they were laid out with, so a large amplitude overlaps the lines around it rather than pushing them apart. A popping letter grows over its neighbours in the same way rather than nudging them aside. A moving link is still reached where its text rests.
Combining. Effects stack, so [shake][rainbow]...[/rainbow][/shake] both jitters and recolors. Any of them can also play for a set time with a duration. They also work inside and around [color] and [link].
Color order. Coloring effects apply from the outside in. A rainbow or a gradient replaces the color around it (any [color] included), while a pulse or a shimmer fades from whatever color is around it, so [rainbow][pulse=White]...[/pulse][/rainbow] pulses the rainbow and [color=Gold][shimmer]...[/shimmer][/color] glints across gold text. A hovered link's HoverTextColor covers the coloring effects in its text so the link still shows it's under the cursor, though its own hover effects start from it.
Continuity. An effect carries on unbroken across a color change or a line break. A gradient spreads over its whole stretch rather than restarting on each line. A shimmer's band also carries on from the end of one line to the start of the next.
Fonts. [wave], [bounce], [shake], [pop], [flicker], [fade] and [sparkle] work in every font, SpriteText included. [rainbow], [gradient], [pulse] and [shimmer] are colors, which SpriteText ignores with a warning. So are [outline] and [glow], as SpriteText outlines its own letters in its own color. SpriteText can't turn its letters either, so [wobble] leaves them upright with a warning.
Cost. Each character under an effect is drawn on its own, so keep effects to a word or a phrase rather than a whole page. [bold], [fade] and the decorations are the exception, as they can draw their text whole.
Mistakes. An amplitude or period that won't parse keeps its default with a warning, as does a flicker or fade strength outside 0 to 1. When it was written with a space rather than |, such as [wave=4 500], the warning shows the corrected tag. A color that won't parse is left out of a gradient. A gradient left with fewer than two colors keeps the color around it with a warning. So does a pulse without a color. A shimmer whose color won't parse shimmers in white with a warning. Unclosed and stray tags behave as they do for inline color.

Decorations¶

[underline], [strike], [highlight] and [redact] draw a line or a box over the stretch of text they wrap rather than changing the characters themselves:

{
  "Type": "Paragraph",
  "Text": "[strike]Catch a carp[/strike] done! Next, the [highlight]Legend[/highlight] in [underline=SkyBlue]Mountain Lake[/underline]."
}

Each takes one optional color, such as [highlight=255 200 200 128] or [underline=Red]. Left off, a highlight is a soft translucent yellow and the rest take the color of the text they decorate.

Steady. A decoration stays where the text was laid out, so [wave][underline]...[/underline][/wave] keeps a straight underline under the moving letters.
Across lines. A decoration that wraps is drawn on each line it reaches, joining up wherever its text continues.
Redacting. [redact] draws only its bar, so nothing of the text underneath shows. A link whose text is fully redacted can't be reached by the cursor or a controller either, so its tooltip can't give away what's hidden. Paired with a tag condition, it hides something until the player has earned it: [redact=condition=!PLAYER_HAS_CAUGHT_FISH Current (O)163]Legend[/redact].
Typewriters. Under a typewriter, a decoration grows along with the text it covers rather than appearing ahead of it.
Hover effects. [underline], [strike] and [highlight] work as a link's hover effects, so "HoverEffect": "underline" underlines a link while the cursor is on it. [redact] doesn't, as it would hide the very text the cursor is on (and neither does [scramble]).
Fonts. Decorations are drawn by Parchment rather than the font, so they work in SpriteText too. Give them a color there, as SpriteText draws its letters in its own color rather than the element's.

Bold¶

[bold] thickens the text it wraps.

{
  "Type": "Paragraph",
  "Text": "Only [bold]one[/bold] legendary fish lives in each spot."
}

Strength. It takes one optional whole number, being how far the second copy is shifted in unscaled pixels multiplied by the text's scale. [bold=2] is heavier than the default of 1. A strength that isn't a positive whole number keeps the default with a warning.
Layout. Bold only changes the drawing. The text keeps the width it was laid out with, so its last letter reaches a pixel or two past it.
Translucent text. The two copies overlap, so text that isn't fully opaque looks more solid than it would on its own. That shows on a translucent color such as 255 0 0 128, on an element fading in or out, on a typewriter that fades its characters in and on a flicker or a fade as it dims. Text at full strength looks as it should.
Combining. Bold works inside and around every other effect. Bolds nested inside one another don't add up, so the strongest applies.
Hover effects. Bold works as a link's hover effect, so "HoverEffect": "bold" thickens a link while the cursor is on it.
Fonts. Bold works in every font, SpriteText included. A SpriteText letter is built from pixels a few screen pixels wide, so it may take a higher strength such as [bold=3] to show.

Outline¶

[outline] draws a solid outline around each letter of the text it wraps, which keeps light text readable over a busy or dark background.

{
  "Type": "Heading",
  "Text": "[color=White][outline]Night Market[/outline][/color] opens at [color=Gold][outline=95 40 10|1]5pm[/outline][/color]"
}

Values. It takes an optional color and then a thickness, such as [outline=Navy] or [outline=Navy|3]. The color takes any of the color forms. The thickness is a whole number of unscaled pixels multiplied by the text's scale, so [outline=Black|1] is a fine line and [outline=Black|3] a heavy one.
Shadow. An outline takes the place of the text's shadow, so outlined text is drawn without one.
Layout. An outline only changes the drawing. The text keeps the room it was laid out with, so a thick outline reaches past it into the lines and letters around it.
Combining. An outline follows its letters through every other effect, so it waves, shakes, fades and flickers with them, wraps [bold] text and takes no color from a rainbow or gradient inside it. Outlines nested inside one another don't add up, so the innermost applies.
Hover effects. Outline works as a link's hover effect, so "HoverEffect": "outline=Gold" outlines a link while the cursor is on it.
Fonts. SpriteText already outlines its own letters and keeps its own color, so [outline] is ignored there with a warning.
Cost. Every letter is drawn eight extra times, so an outline suits a heading or a phrase rather than a whole page.
Mistakes. A color that won't parse gives a black outline, while a thickness that isn't a positive whole number keeps the default. Both log a warning.

Glow¶

[glow] draws a soft halo behind the text it wraps, strongest beside the letters and fading out to its radius.

{
  "Type": "Paragraph",
  "Text": "The [glow]Golden Walnut[/glow] hums with power. A [glow=Cyan|4|2000]spirit[/glow] drifts by while a [glow=40 20 10|2][color=White]shadowy figure[/color][/glow] watches."
}

Values. It takes an optional color, radius and period in that order, so changing its radius means writing its color first, such as [glow=Gold|5]. The color takes any of the color forms. The radius is a whole number of unscaled pixels multiplied by the text's scale. The period is how long one breath out and back takes, in milliseconds, with the default of 0 holding the glow steady.
Breathing. A glow with a period dims to less than half its strength and back, so it never quite goes out.
Background. A glow is translucent, so a light glow shows faintly on a light page. It stands out most on a dark panel or as a dark glow behind light text, where it reads as a soft shadow.
Shadow. A glow sits behind the text's shadow rather than replacing it. Inside an [outline], the glow goes down first, the outline over it and the text over both without its shadow.
Layout. A glow only changes the drawing. The text keeps the room it was laid out with, so a wide glow spills into the lines and letters around it.
Combining. A glow follows its letters through every other effect, so it waves, shakes, fades and flickers with them and wraps [bold] text. Glows nested inside one another don't add up, so the innermost applies.
Hover effects. Glow works as a link's hover effect, so "HoverEffect": "glow=White|3" lights a link up while the cursor is on it.
Fonts. SpriteText keeps its own color, so [glow] is ignored there with a warning.
Cost. A glow is drawn in up to four rings of eight copies each, so it costs more than an outline. Keep it to a word or a short phrase.
Mistakes. A color that won't parse uses the default gold, while a radius or period that won't parse keeps its default. Both log a warning.

Sparkle¶

[sparkle] twinkles sparkles over the text it wraps, using the same sprite as the game's own sparkling text.

{
  "Type": "Paragraph",
  "Text": "A [sparkle]Prismatic Shard[/sparkle] glints in the [sparkle=LightBlue|800|0.4]moonlight[/sparkle]."
}

Values. It takes an optional color, period and chance in that order, so changing its period means writing its color first, such as [sparkle=Gold|800]. The color tints the sparkle and takes any of the color forms, while White leaves it as the game draws it. The period is how long one sparkle takes to play out. The chance, from 0 to 1, is how likely each character is to sparkle in any one period, so 0.05 is a rare twinkle and 1 keeps every letter sparkling.
Placement. Each sparkle lands somewhere new over its letter and follows it, so a waving or shaking word carries its sparkles along. Sparkles come and go at scattered moments rather than all at once. Spaces never sparkle.
Size. A sparkle is drawn at the text's scale, so at a Scale of 1 it's the size the game draws its own.
Combining. A sparkle fades with its letter, so it shows only once a typewriter reaches the letter and dims under a flicker or a fade. Sparkles inside one another don't add up, so the innermost applies.
Hover effects. Sparkle works as a link's hover effect, so "HoverEffect": "sparkle" twinkles a link while the cursor is on it.
Fonts. The sparkle is drawn by Parchment rather than the font, so it works and takes its color in SpriteText too.
Art. The sparkle is the game's own, the six frames from 0, 704 in TileSheets/animations, so a mod that retextures the game's sparkles changes these too.
Mistakes. A color that won't parse keeps the sparkle's own colors, while a period or chance that won't parse keeps its default. Both log a warning.

Scramble¶

[scramble] shows a random glyph in place of each character, picking a new one every period. With a condition, the text stays scrambled while the condition passes and locks into place once it stops:

{
  "Type": "Paragraph",
  "Text": "The legendary [scramble=condition=!PLAYER_HAS_CAUGHT_FISH Current (O)163]Legend[/scramble] lurks in the mountain lake."
}

Without a condition it stays scrambled for good, which suits cipher text that's never meant to be read.

Its value takes a number and then any options, all separated by | and all optional:

Part	What it sets	Default
number	Milliseconds each random glyph shows before the next.	`80`
`glyphs=…`	The characters a scrambled character can show.	capital letters and digits
`settle=milliseconds`	How long each character waits after the one before it to lock into place. `settle=0` shows the real text all at once.	`40`

So [scramble=60|glyphs=0123456789|settle=25|condition=!PeacefulEnd.Parchment_HasFlag decoded] flickers through digits until the decoded flag is set, then settles quickly from left to right.

Glyphs. Every scrambled character picks from glyphs= alone, so glyphs=123456 only ever shows 1 to 6. A character listed more than once is picked more often, a single character gives a steady mask such as #### and a space in the set can blank a character out. Characters the font can't draw are left out with a warning, falling back to capital letters and digits when none are left. |, [ and ] can't go in the set.
Spaces. Spaces stay spaces, so the shape of the words still shows. Everything else, punctuation included, is scrambled.
Widths. Each glyph is drawn centered in the room its real character was laid out with, so the text never shifts when it settles.
Settling. Settling only plays when the condition changes while the text is on screen. One that changed while the page was elsewhere shows the real text straight away the next time it's seen.
Links. A link whose text is fully scrambled can't be reached by the cursor or a controller until it settles, so its tooltip can't give the answer away.
Combining. Under a typewriter, characters type in already scrambled. Decorations still draw at the text's real width. Moving effects move the glyphs. A scramble can't be a link's hover effect, as it would hide the very text the cursor is on.

Typewriter¶

[typewriter] hides the text it wraps and then reveals it a character at a time, at the same pace as the game's dialogue box:

{
  "Type": "Paragraph",
  "Text": "[typewriter]Dear friend, the fish are biting again.[/typewriter]"
}

Its value takes two numbers and then any options, all separated by | and all optional:

Part	What it sets	Default
first number	Milliseconds each character takes to appear.	`30`
second number	Milliseconds to wait before the first character.	`0`
`immediate`	Start as soon as the text is on screen instead of waiting for the typewriters before it.	waits its turn
`fade` or `fade=milliseconds`	Fade each character in instead of showing it at once. A bare `fade` takes 100 milliseconds.	shows at once
`drop` or `drop=milliseconds`	Have each character fall a short way into place as it appears. A bare `drop` takes 200 milliseconds.	appears in place
`pop` or `pop=milliseconds`	Have each character shrink into place from oversized as it appears. A bare `pop` takes 200 milliseconds.	appears at its size
`sound=cue`	Play a sound cue as characters appear, such as `sound=dialogueCharacter` for the game's own typing sound.	no sound
`condition=query`	Type only when a game state query passes, checked once when the typewriter would start. When it fails the text shows in full at once. See Tag conditions.	always types

So [typewriter=20|500|fade|sound=dialogueCharacter] waits half a second, then types quickly with each character fading in to the game's typing sound.

fade, drop and pop can be used together, so [typewriter=40|fade=300|drop=300] has each character fade in as it falls. A typewriter counts as finished once its last character has settled, so whatever waits on it (the typewriters after it and its typed actions) waits for the longest of the three.

When it starts. A typewriter on a page starts once its spread has settled into view, after any page turn. One in an element that's hidden until a Condition passes or a ShowElement names it starts when that element appears instead. One on the book's own Underlay or Overlay starts when the book first settles, open or on its cover.
Order. Typewriters on a spread type one after another in the order they're drawn, left page then right, so the spread reads like it's being written. Each waits for the one before it to finish, plus its own delay. immediate starts one alongside the others instead, without holding up the ones after it. A hidden element doesn't hold the others up either.
Replaying. Each typewriter types once per reading. Turning back to a spread shows its text in full, while closing the book and opening it again types it out afresh.
Skipping. While anything on screen is still typing, a click (or a controller's confirm button) finishes all of it at once and does nothing else, the same as the game's dialogue. It doesn't also press the button it landed on or turn the page. Keybinds are unaffected.
Links. A link in text that hasn't been typed out yet can't be reached by the cursor or a controller until all of its text is showing.
Sound. Only one cue plays at a time however many typewriters are revealing at once. It follows the player's own typing sound option, the same as the game's dialogue.
Layout. The text takes its full space from the start, so lines never reflow as they fill in. A dropping or popping character moves within that space, overlapping its neighbours for a moment rather than nudging them.
Combining. Other effects work inside and around a typewriter, so [typewriter][wave]...[/wave][/typewriter] waves each character as it appears. A typewriter can't be a link's hover effect, as it reveals text once rather than coming and going with the cursor.

Pauses¶

A [pause] inside a typewriter holds the reveal for a moment before carrying on, for pacing a line the way it would be spoken:

{
  "Type": "Paragraph",
  "Text": "[typewriter]Wait…[pause=600] what was that?[/typewriter]"
}

Length. Its value is how many milliseconds it holds. A bare [pause] holds for 500.
No closing tag. Unlike every other tag, [pause] marks a single point in the text rather than wrapping any.
What waits. A pause lengthens its typewriter, so the typewriters after it and the element's typed actions wait for it too. One placed just before [/typewriter] holds whatever comes next without holding any of its own text.
Conditions. [pause=600|condition=...] only holds when its condition passes, checked once when the typewriter starts, the same as a typewriter's own.
Skipping. A click finishes the whole typewriter, pauses included.
Mistakes. A [pause] outside a typewriter has nothing to hold, so it's ignored with a warning.

Typed actions¶

An element's TypedAction and TypedActions run once every typewriter in its text has finished. Pair them with something that should only appear once the text is written, such as a button below a letter:

{
  "Type": "Paragraph",
  "Id": "letter",
  "Text": "[typewriter]Dear friend, the fish are biting again.[/typewriter]",
  "TypedAction": "PeacefulEnd.Parchment_SetFlag letterWritten"
}

Finishing early. They run whether the text typed out or the reader clicked to finish it, so skipping never loses what they do.
Once per reading. They run once each reading, the same as the typing. Turning back to the page doesn't run them again, while closing the book and opening it again does.
Turning away. Typing finished by turning away from the page runs them the next time that page is on screen, so nothing they do lands while the page is turning.
Chaining. A hidden element with its own typewriter starts typing as it appears, so a postscript can follow a letter by giving it a Condition on the flag a typed action sets (or on HasFinishedTyping below).
Without an action. The HasFinishedTyping query lets another element's Condition wait on the typing directly, such as "Condition": "PeacefulEnd.Parchment_HasFinishedTyping letter". Conditions are checked on a short timer, so it can appear a moment after the typing ends.
Mistakes. An element with a typed action but no [typewriter] in its text logs a warning when the book loads, as they could never run.

Hover effects¶

A link's HoverEffect and HoverEffects apply text effects to the linked text only while the cursor (or a controller) is on it. Each entry is written the way its tag is, without the brackets:

"Links": {
  "legend": {
    "TextColor": "Gold",
    "HoverTextColor": "Orange",
    "HoverEffects": [ "wave=3|600", "pulse=White" ]
  }
}

Easing in. The effects start from rest when the cursor arrives and grow to full size over a moment, so a wave never appears mid-cycle. A bold has no size to grow through, so it applies in full straight away. They all stop as soon as the cursor leaves.
Order. Hover effects apply after any effects written in the text itself, so they stack on top. A coloring hover effect starts from the link's HoverTextColor when one is set, so HoverTextColor: White with pulse=Gold fades between white and gold.
Whole link. Each effect covers the whole of the link's text, so a gradient spreads across all of it, even when a link nested inside cuts it in two.
Interactivity. A link with hover effects is reachable by the cursor even when it has no tooltip or action.
Mistakes. An entry naming no effect Parchment knows is skipped with a warning listing the ones it does. Values that won't parse behave as they do in the text.

Languages¶

These tags write the text they wrap in one of the game's own languages until the player has learned it. From then on the text shows as written:

Tag	What it does	Learned from
`[dwarvish]`	Writes the text the way the game writes a dwarf's speech before the player can understand them.	The Dwarvish Translation Guide
`[junimo]`	Writes the text in the Junimo script the game uses for the Community Center's bundle notes. See Junimo script.	The Wizard, the same as the game's own notes

{
  "Type": "Paragraph",
  "Text": "Scratched into the cave wall: [dwarvish]Beware the lower levels.[/dwarvish]"
}

{
  "Type": "Paragraph",
  "Text": "A note tucked behind the bundle: [junimo]Thank you for the gifts[/junimo]"
}

Learning it. Whether the player knows the language is checked whenever the text is laid out. Text already on screen when the player learns it switches over the next time it's laid out.
Conditions. A condition has to pass as well, so [dwarvish=condition=!PLAYER_HAS_SEEN_EVENT Current 123] also shows its text as written once the event has been seen.
Forcing it. A force part keeps the text unreadable whether or not the player knows the language. On its own, [junimo=force] never becomes readable, which suits a cipher or a note the player is never meant to read. With a condition, the condition alone decides, so [dwarvish=force|condition=!PLAYER_HAS_SEEN_EVENT Current 123] becomes readable once the event has been seen, Translation Guide or not. force and a condition are the tag's only parts, so anything else is ignored with a warning.
Tokens. A token inside one resolves first, then its value is written in the language along with the rest.
Combining. Effects and links inside or around one apply to the text as the language writes it, so [dwarvish][shake]Go away![/shake][/dwarvish] shakes the converted letters. One inside another of the same language changes nothing more. The two can also go together, as [junimo][dwarvish]...[/dwarvish][/junimo] writes the converted dwarvish in the Junimo script.
Tooltips. A tooltip draws its text as written, as all markup is taken out of it.

Dwarvish¶

The game's own conversion does the work, so the text reads exactly like a dwarf's untranslated speech. Line breaks stay where they are. The conversion can change how long a word is, so the text is laid out as converted rather than as written. Colors work on it like any other text.

Junimo script¶

[junimo] writes each letter with the Junimo glyphs SpriteText keeps alongside its own (in LooseSprites/font_bold). In a SpriteText element it is drawn at the font's own size, the same as the game's notes. In any other font it is sized to that font's capital letters and set on their baseline, so the script sits among the rest of the text. Both are read from the fonts themselves, so a mod that replaces a font is matched too.

Characters. Spaces stay spaces, so the text still wraps between words. Anything the script has no glyph for (a character outside the printable ASCII range, or ^) stays in the element's font.
Spacing. Outside a SpriteText element, a narrow glyph such as a period, a comma or an apostrophe is pulled in to its own width rather than keeping the room a full letter gets, so it sits close to the letters around it. A glyph counts as narrow when its pixels fill less than half its cell, read from SpriteText's sheet.
Color. It keeps the game's own look unless markup colors it, so an element's TextColor doesn't reach it. A [color], a coloring effect such as [rainbow] or [gradient] and a link's colors recolor its letters, while their drop shadow takes the text's shadow color, the same as the rest of the text. [color=Gold][junimo]Thank you[/junimo][/color] reads as gold Junimo script. It fades with the text either way. In a SpriteText element it keeps its own color, the same as SpriteText's own letters.
Shadows and halos. Each glyph carries its own drop shadow. Uncolored, that shadow keeps the game's orange. Colored, it follows ShadowColor (or the game's shadow color when that's left unset) and is left out under an [outline], the same as plain text. An [outline] or [glow] wraps it like any other letter, except in a SpriteText element.
Effects. Moving effects move it and [bold] thickens it. [wobble] rocks it like any other letter, except in a SpriteText element, which can't turn its letters. A [scramble] over it scrambles through the script, so the random glyphs never give away the plain text.

Tag conditions¶

Any tag can take a condition= part holding a game state query. The tag only applies while the query passes:

{
  "Type": "Paragraph",
  "Text": "The lake is [color=SkyBlue|condition=WEATHER Here Rain]full of rain[/color] and the [link=legend|condition=PLAYER_HAS_SEEN_EVENT Current 123]Legend[/link] stirs.",
  "Links": {
    "legend": { "TextColor": "Gold", "Description": "Only bites in spring rain." }
  }
}

It goes alongside the tag's other parts, separated by | the same way, in any position: [wave=4|500|condition=SEASON spring] or [gradient=Red|Blue|condition=!IS_FESTIVAL_DAY]. On a tag with nothing else to set, the condition is its whole value: [underline=condition=SEASON spring].

When it fails. The tag steps aside and its text is drawn as though the tag weren't there. A failed [color] keeps the color around it, a failed effect leaves its characters still, a failed decoration isn't drawn, a failed [dwarvish] or [junimo] shows its text as written and a failed [link] is plain text that the cursor can't reach. The text itself always shows. A [scramble] settles into its real text rather than snapping, as described under Scramble.
When it's checked. Alongside element conditions, so the text follows the query while the book is open. The query isn't run every time the text is drawn.
Typewriters. A [typewriter]'s condition is checked once, when it would start, so its text can't appear and vanish as the query comes and goes. When it fails the text shows in full at once and the element's typed actions still run.
Links. A link's own Condition switches it off everywhere it's used, while a condition= on a [link] tag switches off just that one use. Both have to pass.
Tokens. Parchment's %Token% forms resolve against the element, the same as in its Condition. ! negation and comma-separated queries work as usual.
Limits. A tag's value can't hold square brackets, so the game's [Token] forms can't go in an inline condition. Nor can a |, which would start the tag's next part. Set a flag or variable elsewhere and check that instead. The element's own Condition can also hold the query.
Hover effects. A link's hover effects don't take a condition, since the link's own Condition already governs them. One given is ignored with a warning.

Effect durations¶

Any text effect can take a duration= part, in milliseconds, to play for a while once its text appears and then settle to rest:

{
  "Type": "Paragraph",
  "Text": "You caught a [bounce=4|400|duration=800]Legend[/bounce]! [shimmer=White|1600|duration=800][color=Gold]Perfect catch[/color][/shimmer] [typewriter=40][rainbow=1000|duration=2000]New record![/rainbow][/typewriter]"
}

It goes alongside the effect's other parts, separated by | the same way and in any position, the same as a condition. On an effect with nothing else to set, the duration is its whole value: [shake=duration=500].

When it starts. An effect inside a typewriter starts as the typewriter reaches its first character, so a word can bounce as it's written. Any other starts when its text comes into view, at the same moment a typewriter in it would: once the spread has settled after a page turn, or when a hidden element appears.
From the top. A timed effect runs on its own clock from the moment it starts, so it always begins at the start of its cycle. [bounce=4|400|duration=800] gives two hops that die down, while [shimmer=White|1600|duration=800] glints across once, since a shimmer crosses in the first half of its period.
Settling. It grows in over its first moment and settles over its last, rather than starting or stopping with a jolt. A moving effect comes to rest where its text was laid out, a coloring effect blends back to the color around it, a fade or flicker returns to full strength and an outline, glow, sparkle or decoration fades away. A [bold] can only be on or off, so it switches off partway through settling.
Once per reading. A timed effect plays once each reading, the same as a typewriter types. Turning back to the page shows its text at rest, while closing the book and opening it again plays it afresh.
Hover effects. A link's hover effects take a duration too, playing it each time the cursor arrives, so "HoverEffect": "pop=0.3|300|duration=300" swells the link once on each hover.
Not every effect. A [typewriter], [redact] or [scramble] already decides how long it shows for, so a duration on one is ignored with a warning, as is one that isn't a positive number.
Where it plays. A timed effect plays in a book's pages and on its own layers. Text drawn anywhere else has nothing to start it, so its timed effects stay at rest.

Rectangles and points¶

Rectangles and points are objects:

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