Changelog¶

v2.1.1 Release | Oct 23, 2026¶

A mod's own guide book item shows its cover.

🐛 Fixes¶

• A mod's own guide book item (a GuideBookItem made for one book) shows its book's cover text and colours on every stack, not only on stacks given with the book in their folios:guide_book component: from the creative tab, /give or a recipe, it no longer has blank plates and Folios's own colours. GuideBooks.bookOf now gives such an item's own book when the stack names none.

v2.1 Release | Oct 23, 2026¶

Books make better use of the screen at small GUI scales, and what is on their pages keeps clear of the page frame.

✨ New Features¶

• At a GUI scale smaller than Auto, a book keeps its size on the screen and its pages grow, so more fits on each: what is on them is drawn a step larger than the rest of the GUI (in whole pixels, so the print stays sharp), and the pages take the rest, as much as 2.5 times the default page. GUI scale 1 fits more than 2. A handheld book's pages grow too, as far as keeps its print easy to read. Pages of every kind lay themselves out to the page's size: text, recipes, scenes (which keep their shape), pictures, links and quests.

🐛 Fixes¶

• A screen book no longer shrinks at GUI scale 1 and 2: it is drawn as large as at Auto, and so are its tooltips.
• What is on a page keeps 4 pixels clear of the page frame on every side, and the turn buttons and page numbers sit clear of its corners (turn_buttons now defaults to 10, 21, page_numbers to 0, 19).
• The page frame keeps its corners and ornaments their size on a larger page.
• A book's subtitle on its front page shows whole: made a little smaller when it doesn't fit, rather than cut short.

v2.0 Release | Oct 22, 2026¶

Pages hold elements, structures and builds join multiblocks, and a book chooses how it celebrates and what colours its panels take.

✨ New Features¶

• Multiblock mappings (and builds, and build spreads) can name a tag in place of a block, "#minecraft:logs", with properties set on each block that has them ("#minecraft:logs[axis=y]"): any block of it will do, the window and the blocks-needed list show its blocks in turn, and the build guide in the world takes any of them.
• structure pages: structures from data packs (data/<namespace>/structure/<path>.nbt; structures/ on 1.20.1), asked of the server the first time they're shown. "structure" names one, "structures" several (ids, or {"id": ..., "name": ...}).
• build pages: builds designed in the book's own builds/<name>.json files, from a pattern and mapping as a multiblock's and/or blocks: single blocks ("pos") and boxes ("from"/"to", "hollow"), in order, air clearing. "build" names one, "builds" several.
• A guide book's tooltip says who it is from, under its name: the mod its namespace belongs to, or the book's own "author" in book.json (raw text or a translation key).
• A structure or build page with several to show picks between them under its window: clasps stepping back and on with the name between them ("selector": "arrows", the default), or a numbered clasp each ("numbers"). They are for showing, not building: no blocks-needed list, nor an eye clasp to build them in the world.
• A multiblock's blocks needed no longer take room under its window: a clasp in the window's bottom-left corner lays a requirement list over the window: "Requirement list:" over the blocks in rows from the left, scrolled with the mouse wheel when there are more than fit, with a clasp to close it.
• Pages hold elements: a page is a title and its "elements" (text, recipes, multiblocks, structures, builds, entities, pictures, spotlights, links, quests), in any order, one under another. Each is written as its type is ({"type": "recipe", "recipe": ...}; a plain string is text), with its own title and text if it has them; one that doesn't fit starts the next page, and text runs on. A page written the old way, as one type, is a page of that one element, so existing books read as before. A mod's own element type works in a page's elements when it lays itself out through GuideLayout.flow.
• A handheld book's bar has the light/dark button too, and its pages go dark in dark mode (a book's "colors" › "dark" applies to them as to a screen book's).
• Bars with more to them: a category's completion bar is notched between its entries (a quest's between its objectives) with a rounded rim, a sunken groove and a light that sweeps across it once full; the front page shows "Mastery" with its trophy and "Progression:" with a percentage under it, over a gilt bar in the build guide's look; the build guide's bar has a rounded rim, a shadow, a shaded fill and marks at each tenth; and the requirement list's scroll bar has arrows lit while there is more that way and a raised thumb with grip lines.
• An entry's first page has the entry's icon before its title, over a mark of the book's colour heading the line under it; any page can name its own with "icon" (or "none" on the first page for none). A title without an icon has a plain line under it.
• The page's content stops 2 pixels short of the turn buttons, so nothing sits against them.
• Celebrations are a book's choice, and off unless it says so: "celebrations" in book.json, true for all of them, or an object turning parts ("toast", "sound", "particles", "fireworks") and events ("objective", "entry", "category", "quest", "mastery", each false, true or an object of its own parts) off. Each objective of a quest done and each entry read can now be celebrated too, beside a category read through, a quest done and the book mastered; fireworks are for mastery alone.
• Toasts in the book's own look for what is celebrated: its panel ground and frame, the quest's, entry's or category's icon in a slot, a small heading over the name, and a line along its foot running down while it shows; mastery's shows the trophy.
• The panel colour scheme: "panel" in book.json (background, frame, title, detail) colours what a book shows off its pages: its tooltips, its toasts and the build guide's panel. "colors" › "tooltip", as it was, is still read.
• The mastery heading on the front page: the trophy and "Mastery" over "Progression:" and a percentage, over a gilt bar split into quarters. Once the book is mastered the trophy glints with a rainbow running across it diagonally, a sheen sweeping over it now and then.

🐛 Fixes¶

• A long trail on a book's bar ("Why Can't I Sleep? › Sleep Quality") no longer gets cut short: it shrinks on its line a little, then goes onto two smaller lines, the book or category over the rest, and is cut only if it still doesn't fit.
• Blocks needed are counted by the items they take: a door's top half and a bed's head no longer count as another door or bed (nor a tall flower's top), and a double slab counts as two slabs. The same in the build guide's panel.

v1.0 Release | Oct 21, 2026¶

Folios's guide books were first made inside CoolCatLib; this is them as a mod of their own, built on CoolCatLib.

✨ New Features¶

• Guide books (net.ixdarklord.folios: api.GuideBooks, api.client.Guides): in-game manuals written as JSON in a resource pack, so packs can add, translate and replace them, and F3 + T reloads them while you write.
• A book is a folder, assets/<namespace>/folios/<book>/: book.json (name, subtitle, the first page's text, style, colours, icon: an item or a texture, the book's own item if it names none), categories/*.json and entries/**/*.json. Every text can be a translation key.
• Two styles, any page showing in either: screen, a flat book in the middle of the screen with the world dimmed around it, a bar like its cover for where you are, a bookmark star, search (a glass that opens into a field while you type), light or dark paper and folding it away, swallowtail ribbon tabs coming out of the leaves' fore-edge, each a little deeper than the one above it and the open one risen to the top, for the front and its categories, with the bookmarks and an index of every entry A to Z at the foot (springing out under the pointer and knocked in when pressed), and leaves that fold across the spine; and handheld, the book held open in your hands in the world, raised from below and opened, its leaves turning with a shadow under them, its pages pressed with the pointer; the book sets how far it leans back ("tilt", degrees, 6 by default), how far it is held from the eyes ("distance", blocks, 0.64) and how its leaves turn ("page_turn": "bend", the default, curls each leaf as it goes, its writing following the curve; "flat" swings it stiffly). The reader's hands hold it, following its lean and distance ("models"/"hands"), and once it lies fully open the same bar grows out over its head, in the world with it, so a turning leaf passes in front of it; its close button shuts the book. No crosshair or block outline shows over it. Picked up, it is raised shut and opened with a click on its cover (or → / Enter / Space); the bar's close button shuts it again in the reader's hands, and Esc puts it away (and a click off the book does too: on by default for a handheld book, off for a screen one, set either way with "close_on_click_outside").
• Both styles are drawn from texture layers, grey or white and tinted by the book's colours: page, frame, cover, tab (a stitched swallowtail ribbon), tab_plate (the rounded plate each tab's icon sits on) and, for screen books, an optional backdrop. Folios's own are at folios:textures/book/, so a resource pack can restyle every book, and a book can name its own under "textures". A category can give its tab its own "color". Page numbers and turn arrows are printed on their pages, so they turn with them. Where the tabs, turn buttons and page numbers sit is the book's "layout" (tabs, turn_buttons, page_numbers and close_button, for a page close clasp where one is drawn, each with x and y; tabs also spacing). Back, previous, next and close are small eight-sided clasps with pixel icons that lift under the pointer. GuideStyles.register adds more.
• Text is a small Markdown: headings, bullet and numbered lists, notes, rules, bold, italic, underline, strikethrough, code, colours, key names, and links to entries, anchors, categories and web pages. Long text runs on over as many pages as it needs by itself.
• Pages: text, spotlight (an item shown large; pressing that item anywhere in the book comes back to it), image (several shown in turn), recipe (crafting, smelting, stonecutting and smithing, the block each is made at hung under it on a tag, asked of the server as clients aren't sent recipes), spread (one thing over both pages of the open book, across the fold: a wide picture, a build to drag round with its eye clasp, or a map of places linked to entries and joined by dotted paths; it starts on a left page and is laid out as one page over both: one frame joined across the fold, its title and text centred, one page number at the fold, and its window framed like a print laid on the page, running unbroken over the spine; GuidePage.spread() lets a mod's page do the same), entity and multiblock (turning scenes on a ground of grid lines, entities with their shadow; drag one to turn it yourself, and a clasp puts it back; what a build takes is listed). A build's eye clasp shows it in the world to be built: ghost blocks stand where you look, turned the way you face, until a right-click sets them down; the layer to build now is clearest, wrong blocks show red, and a panel on the HUD tracks the build's progress and what is still needed, until it is done (a toast says so), you walk away, or sneak + right-click puts it away, links and empty. GuidePageTypes.register adds a mod's own; pages draw through a GuidePainter, so one page works on both styles.
• Reveal effects: a page's content shows once its leaf is down, by an effect that tells everything drawn on it how faded and how far moved it is by where it is on the page, so every page type, a mod's own too, takes part. folios:rise (the default), fade, ink, sweep, scatter, burn (each thing is burnt in turn down the page and along each line, flaring white-hot, flames licking up off it, charring and settling, with sparks and smoke) and runes (parts show as glowing runes that flicker and settle into their words, under drifting runes and a shimmer of light) come with it, and GuideReveals.register adds a mod's own (GuideReveal: a look per thing drawn, its fade, move, tint and how much of its text shows as runes, an overlay drawn over the page while it plays, and around, drawn about each letter, item or picture as it is revealed). Items and scenes take part too, fading, tinting and moving with the effect in both styles (GuidePainter.item and scene take a colour for a page's own drawing). A spread's pages reveal together, across the fold; other pages one after the other. A book chooses one in book.json and an entry may choose its own: "reveal": "folios:ink", or {"effect": ..., "seconds": 0.6, "once": true} to play only the first time each spread is seen this game (pages of entries read in an earlier game count as seen), "unread": true to play only on spreads the reader has never been shown in full (kept with their reading progress, so not again after a restart or on another computer), or "none".
• What a reveal effect draws over a page (sparks, smoke, light, runes, and what it draws about each thing) fades out towards the page's edges and its fold, melting into the paper rather than stopping at its border; addon effects get this too.
• Scenes on pages (entities, builds) are drawn sharp at four texture pixels to a page pixel, zoom with the mouse wheel and turn by dragging, and a clasp puts them back. A build lists the blocks it needs under it, most needed first in framed slots, with a heading and clasps to page through long lists; build spreads list them across the fold.
• The front page shows a mastery bar, how many of all the book's quest objectives are done, with a trophy; every bar in the book is drawn as pixel art.
• On a screen book a turning leaf bends as it goes ("page_turn": "flat" swings it stiffly), what is on it bending with it.
• Tooltips in the books take on the book's colours: a ground from its cover and a gilt frame warmed by its accent, a name, and a quieter line under it saying more. A book sets its whole colour scheme with "colors": the page's colours by name (paper, text, muted, heading, accent, link, panel, line), the same under "dark" for a screen book in dark mode, and "tooltip" (background, frame, title, detail); any left out keep the style's own.
• Quests and progress: a quest page lists objectives with progress bars, followed live: advancements, entries or categories read, the whole book, flags, items carried, and values a mod reports (GuideObjectives.register). A quest's entry shows how far along it is on its row, categories show how much of them has been read as bars, and a toast says when a quest is done.
• Finishing part of a book is celebrated, once each: every entry of a category read brings a toast, a chime and sparkles round the player; mastery (every quest done) a toast, the challenge fanfare and fireworks in the book's colours.
• Categories, entries and pages can be locked behind advancements (the server says which the player has) or flags set in code (Guides.setFlag), and hidden until they open (secret). What has been read, the spreads shown, bookmarks and where you left off are kept on the server, so they follow the player to any computer: with each player by default, or, with "progress": "book" in book.json, on each copy of the book, which carries its own like a notebook (entries read in it still count for the player's quests). Unread entries are marked with a blinking sparkle and progress is shown.
• folios:guide_book is an item for any book (GuideBooks.createStack(id), or createStack(item, id) for a mod's own GuideBookItem, or /give @s folios:guide_book[folios:guide_book="mymod:handbook"]), named after its book; GuideBookItem makes a mod's own. GuideBooks.open(player, book, entry) opens one from the server.
• Its look: a bound book in three dimensions in the hand, on the ground and in frames (leather in the book's cover colour, gilt corners, a strap and clasp, its name and subtitle printed on the cover), and a flat icon in inventory slots unless the book asks for its model there too ("models"/"gui": "model"). A book's "models" can name its own item model ("item"; "item_model" still works), its own open book ("open") and what sits on a handheld book's boards ("cover": a model in the block and item model format, laid on each board, its tinted faces taking the cover colour; "none" for nothing). Item models can use the folios:guide_cover tint (the book's cover colour) and the folios:guide_cover_text special model (its name and subtitle, placed with x, title_y, subtitle_y, z and width).
• Others see a handheld book being read: the reader holds it up open in both hands. It is the folios:guide_reading component on the book in hand, put on and taken off by the server; a mannequin given a book with it is shown reading.
• Reading together: players within 16 blocks of someone reading a book see it in the reader's hands, held part open by its bottom corners at chest height: a handheld book at the spread they have open, its leaves turning as they turn them, so they can read along; a screen book as a likeness of its pages. The reader faces their book.
• A handheld book put away lying open opens again by itself where it was left (an entry's page, the front, a category, the index or the bookmarks); put away shut, it is raised shut. Its pages' content reveals once the cover lies open, not while it swings.
• The bar over a book is a ribbon banner: a cloth band in the cover's colour with swallowtail ends folded behind it, stitched in gilt, its buttons on small brass plates.
• When a handheld book opens, a hint over its bar (Minecraft's right-click icon, framed as the book's tooltips are) says the right button held looks about; it fades after a few seconds and isn't shown again once you have looked about.
• While a handheld book is open the reader can look about, holding the right mouse button, and walk, jump, sneak and sprint with the movement keys (the arrow keys still turn the leaves); a book turns either off with "handheld": {"look_around": false, "walk": false}. Put away, it goes back into the hand just as the held item lies there.
• The perspective key works while a handheld book is open: from outside, you see yourself holding it open, and the mouse turns the view freely (as the book's look_around allows); back in first person, the pointer reads the pages again.
• A handheld book is held steady: it doesn't sway as the view turns or bob as the reader walks, and its cover swings open in one smooth sweep. The bar folds away from a pocket in the middle of its foot, an arrow in it, where its pull is once it is folded.
• Pages have a rough-cut head and foot, and the leaves at their sides are uneven, some a hair short.
• A screen book used from the hand is raised out of it and opened part way in 3D first, its halves leaning up from the spine and its pages a pixel-art likeness of pages (a heading, a rule, lines of scribbled writing); others see it held part open too (folios:guide_book_half_open), and its screen comes up once it lies open; closed, the book shuts and goes back into the hand.
• Held shut, a handheld book's tooltip over its cover's name plate shows the name and subtitle, and over its lower plate the summary (or subtitle), above "Click to open".
• A handheld book held shut is the book item: the item's leather on its boards, its title, emblem and subtitle laid out as on the item's cover. In the bar, the book's icon sits in a slot. A cover model's box can show hold the book shut (#shut in its name, as the strap and clasp do: as the book opens they unlatch first, swinging out about the board's fore-edge before the cover moves, and are carried off behind the boards, gone once it lies open) or only once it lies open (#open), or be wrapped round the spine, bending with it as the cover opens (#spine, as the bands across it are), and can sit on one board only ("board": "front" or "back"), and boxes turn in the board's own proportions, so a square stays square.
• A book model marks where its lettering goes: an element named with #title or #subtitle (a plate, or an invisible box) has the line centred on its face, sized to it; folios:guide_cover_text reads them with "markers": "<model>".
• A new look for the default book: leather with a tooled frame, the name and subtitle large on gold-rimmed plates, engraved gold corner brackets with rivets, a gem in the book's accent colour set in a gold lozenge, an engraved clasp with a keyhole, ridged bands over the spine, cleaner page edges, and a matching flat icon tinted with the cover. Shown as a model in slots, it leaves out the lettering, too small to read there. The folios:guide_cover tint takes "part": "accent" for the book's own colour, and cover models tint faces with "tintindex": 1 the same way. A book places its lettering with "cover_text": title and subtitle, each x, y, size and width.
• A book can have a "summary": then its name and its subtitle (smaller, under it) share the cover's upper plate and the summary, up to two lines set to fit, has the lower one. A cover model marks where it goes with #summary, and "cover_text" takes summary as it does title and subtitle.
• A build shown in the world is drawn as its own blocks, see-through (CoolCatLib's GhostBlocks), the layer to build now clearer; its panel on the HUD takes the book's tooltip look and colours, and is as wide as what it holds, longer lines shrinking or wrapping to fit. Which corner of the screen it sits in and how far in from it are client settings (buildPanel: corner, x, y).
• A template resource pack with a complete example book, every kind of page and a README of the keys, is in templates/folios-book-template.