Book¶

BookData

A book is one entry in Parchment's book data. It owns the physical book (its sprite, its animations, the geometry of its pages) plus the pages themselves and any decoration drawn outside them.

{
  "Format": "1.0.0",
  "Id": "PeacefulEnd.Parchment_CampingGuide",
  "Appearance": {
    "TintColor": "165 42 42"
  },
  "Pages": [ ... ]
}

Fields¶

Property	Type	Default	Description
`Format` optional	`string`	`1.0.0`	The schema version this book was written against.
`Id` required	`string`	—	A unique string ID for the book, conventionally `{ModId}_{Name}`. This is how actions and items refer to it, and it's the name Parchment uses in log messages.
`SpritePath` optional	`string`	—	The sprite used for the book's item.
`Pages` optional	list of `pages`	empty list	The book's pages, in order. Two consecutive pages make a spread.
`Underlay` optional	list of `elements`	empty list	Elements drawn behind the book sprite, positioned by their `Position` relative to the book's top-left. Negative coordinates place them outside the book's edges. This is how you make a bookmark that sticks out of the side, with the part that overlaps the book hidden behind it. Drawn during the open and close animations, so they ride in with the book.
`Overlay` optional	list of `elements`	empty list	Elements drawn in front of the book sprite and its pages, positioned by their `Position` relative to the book's top-left. Only drawn once the book is open.
`Appearance` optional	`Appearance`	the default book	The book's sprite and animation frames.
`PageCurl` optional	`PageCurl`	the default corners	The corner curl sprite and its clickable areas.
`Animation` optional	`Animation`	see below	Animation timings and sounds.
`Layout` optional	`Layout`	see below	The page margins.

Underlay and overlay elements always take the cursor

Unlike a page's Background and Foreground, a decorative element here is hit-tested whether or not it has a tooltip or an action, and the overlay is tested before the pages. Keep overlay art to the area it actually covers rather than stretching a transparent sheet over the whole book.

The book's name and description live on the item

A book has no Title or Description of its own. What the player sees comes from the item that opens it, its DisplayName and Description in Data/Objects. That also means those are localisable through the usual [LocalizedText ...] tokens.

Appearance¶

Everything about how the book itself is drawn. All defaults describe Parchment's built-in book, so you only need this block if you're making your own book art, and if you are, you'll want to set all of it, since the frame counts and offsets are facts about a specific sprite sheet.

Property	Type	Default	Description
`TexturePath` optional	`string`	the built-in book	The book's sprite sheet. Frames run horizontally, each `FrameWidth` × `FrameHeight`: first the open frames (index 0 fully closed, the last fully open), then the page-turn frames. The close animation is the open frames played backwards, so you don't supply those separately.
`GrayscaleTexturePath` optional	`string?`	the built-in book	An optional greyscale layer drawn beneath `TexturePath` and tinted by the book's `TintColor`. Multiplying a colour into greyscale art gives you that colour. Set to `null` to skip the recoloring.
`TintColor` optional	`color`	white	A colour multiplied into the book's greyscale layer.
`FrameWidth` optional	`int`	`219`	The width of one frame, in unscaled sprite pixels.
`FrameHeight` optional	`int`	`158`	The height of one frame, in unscaled sprite pixels.
`OpenFrameCount` optional	`int`	`4`	How many open frames the sheet starts with.
`TurnFrameCount` optional	`int`	`6`	How many page-turn frames follow the open frames.
`Scale` optional	`number`	`5`	How much the book sprite is magnified. Everything measured against the book art (the page margins, the curl offsets) scales with this.
`Offset` optional	`Point`	`{ X: 0, Y: 0 }`	A nudge applied to the book's centred position, in unscaled sprite pixels. The book is centred on its frame, so if your frame has empty space around the art it won't look centred.

Page curl¶

The corner you click to turn a page. The offsets are relative to the book frame, so they follow the book when it moves or changes scale.

Property	Type	Default	Description
`TexturePath` optional	`string`	the built-in corner	The curl sprite sheet. Frames run horizontally: frame 0 is flat, the last is fully curled. Hovering plays forward, un-hovering plays back.
`FrameWidth` optional	`int`	`32`	The width of one frame, in unscaled sprite pixels.
`FrameHeight` optional	`int`	`32`	The height of one frame, in unscaled sprite pixels.
`FrameCount` optional	`int`	`7`	How many frames the curl animation has.
`Scale` optional	`number`	`5`	How much the curl sprite is magnified.
`PreviousPageOffset` optional	`Point`	`{ X: 1, Y: 113 }`	The top-left of the back-turn corner, in unscaled sprite pixels relative to the book frame's top-left.
`NextPageOffset` optional	`Point`	`{ X: 186, Y: 112 }`	The top-left of the forward-turn corner, in unscaled sprite pixels relative to the book frame's top-left.

The corner and its hotspot are the same rectangle

Each corner's clickable area is exactly the sprite you see: the offset above, sized FrameWidth × FrameHeight × Scale. There's no separate hotspot to keep in sync.

The left corner is drawn mirrored, so one piece of art serves both sides.

Animation¶

Property	Type	Default	Description
`SlideDuration` optional	`number`	`350`	How long the closed book takes to slide up from the bottom of the screen, in milliseconds. Eased, so it starts fast and lands softly.
`OpenDuration` optional	`number`	`250`	How long the open animation takes, in milliseconds. The open frames are spread evenly across it.
`CloseDuration` optional	`number`	`400`	How long the close animation takes, in milliseconds.
`TurnDuration` optional	`number`	`500`	How long a page turn takes, in milliseconds.
`CurlDuration` optional	`number`	`250`	How long the corner curl takes to play through all its frames, in milliseconds.
`ContentSwapProgress` optional	`number`	`0.5`	The point in a page turn at which the page content changes over, from 0 to 1. Tune this so the swap happens while the turning page hides it.
`OpenSound` optional	`string`	`shwip`	Played when the book lands and again when it finishes opening. `null` for silence.
`TurnSound` optional	`string`	`shwip`	Played when a page turn starts.
`CloseSound` optional	`string?`	—	Played when the book starts closing.

Layout¶

Where the page content sits within the book art, in unscaled sprite pixels, so these scale with Appearance.Scale. Measure them off your book PNG: find where the paper starts relative to the frame's top-left.

Property	Type	Default	Description
`MarginOuter` optional	`int`	`12`	The gap between the book frame's left or right edge and the page content.
`MarginSpine` optional	`int`	`6`	The gap between the spine and the page content, on each side.
`MarginTop` optional	`int`	`27`	The gap between the book frame's top edge and the page content.
`MarginBottom` optional	`int`	`28`	The gap between the book frame's bottom edge and the page content.

Together these define each page's content area, which is what every element's width is measured against and what Fill fills.