GitHub Lua Daily Trending Repositories

LandSandBoat/server

⛵ LandSandBoat - a server emulator for Final Fantasy XI

https://landsandboat.github.io/server/

LandSandBoat

An open-source server emulator for FFXI.

Getting Started

A quick start guide, the frequently asked questions, and a table of "what works" are all available on our wiki.

Interacting with LandSandBoat

Crashes, warnings, errors, bugs, gameplay issues, visual issues, questions, documentation issues, build problems, etc.

Please create a new issue in the issues tab after searching to see if your issue is already logged.

If you are encountering an issue, please open an issue! It's easier for us to track and you're more likely to get resolution through an issue than any other means.

AI Agents and their use

If you're a human using AI agents or an AI agent you should go read ./docs/ai_agents/README.md.

LICENSE

LandSandBoat is licensed under GNU GPL v3

Thanks

Thanks to all contributors past and present, we wouldn't be here without you!

Thanks to GitHub for hosting us, and for all the CI minutes we use!

koreader/koreader

An ebook reader application supporting PDF, DjVu, EPUB, FB2 and many more formats, running on Cervantes, Kindle, Kobo, PocketBook and Android devices

http://koreader.rocks/

KOReader is a document viewer primarily aimed at e-ink readers.

Download • User guide • Wiki • Developer docs

Main features

portable: runs on embedded devices (Cervantes, Kindle, Kobo, PocketBook, reMarkable), Android and Linux computers. Developers can run a KOReader emulator in Linux and MacOS.
multi-format documents: supports fixed page formats (PDF, DjVu, CBT, CBZ) and reflowable e-book formats (EPUB, FB2, Mobi, DOC, RTF, HTML, CHM, TXT). Scanned PDF/DjVu documents can also be reflowed with the built-in K2pdfopt library. ZIP files are also supported for some formats.
full-featured reading: multi-lingual user interface with a highly customizable reader view and many typesetting options. You can set arbitrary page margins, override line spacing and choose external fonts and styles. It has multi-lingual hyphenation dictionaries bundled into the application.
integrated with calibre (search metadata, receive ebooks wirelessly, browse library via OPDS), Wallabag, Wikipedia, Google Translate and other content providers.
optimized for e-ink devices: custom UI without animation, with paginated menus, adjustable text contrast, and easy zoom to fit content or page in paged media.
extensible: via plugins
fast: on some older devices, it has been measured to have less than half the page-turn delay as the built in reading software.
and much more: look up words with StarDict dictionaries / Wikipedia, add your own online OPDS catalogs and RSS feeds, over-the-air software updates, an FTP client, an SSH server, …

Please check the user guide and the wiki to discover more features and to help us document them.

Screenshots

Installation

Please follow the model specific steps for your device:

Android • Cervantes • Kindle • Kobo • Linux • Pocketbook • reMarkable

Development

Setting up a build environment • Collaborating with Git • Building targets • Porting • Developer docs

Support

KOReader is developed and supported by volunteers all around the world. There are many ways you can help:

fix bugs and implement new features
translate the program into your language or improve an existing translation
document lesser-known features on the wiki
help others with your knowledge on the forum

Right now we only support liberapay donations.

Contributors

AndyHazz/bookshelf.koplugin

A nice looking home screen for KOReader. Lets you pick a book from your shelf and read it, with some customisation around the book preview info that's shown.

Bookshelf

A friendly home screen for KOReader. Browse your library by series, author, genre, collection, or anything you like; pick a book, glance at its cover, blurb, rating, and progress, and start reading. Browse online catalogues (Project Gutenberg, Standard Ebooks, and friends) the same way and download straight to your shelf. A build-your-own start menu puts your shortcuts, folders, and live panels a tap away in the corner. Shelves draw three ways: a grid of covers, a text list, or spines standing edge-on like a real bookcase.

Install

Download the latest bookshelf.koplugin.zip from Releases.

Unzip it onto your device's KOReader plugins folder:

Device	Plugins folder
Kindle	`/mnt/us/koreader/plugins/`
Kobo	`/mnt/onboard/.adds/koreader/plugins/`
Android	`<koreader-dir>/plugins/`

Restart KOReader.
Open KOReader's menu and set Start with -> Bookshelf. Without this, KOReader opens its standard file browser on launch; you can still open Bookshelf manually from the menu.

The Start with setting only appears in the menu of KOReader's File Manager screen, not while a book is open. If you can't find it, close the book first (or launch KOReader without one open), then open the menu from the file browser.

Bookshelf needs KOReader's Cover browser plugin. It is switched on in a stock KOReader, so this is usually nothing to do. You only need to check it if you have turned it off yourself, which some other plugins ask you to do. To look: open the KOReader menu, then More tools -> Plugin management -> Built-in plugins, and make sure Cover browser is ticked. Cover browser supplies the covers and metadata Bookshelf reads; without it, Bookshelf shows a one-time notice and steps aside to KOReader's standard file browser.

Once it's running, the top menu has a Bookshelf section with everything else: shelf size, shelves, Hardcover, updates, and settings.

"menu" below always means Bookshelf's own menu: the Bookshelf tab in KOReader's top menu, marked with an open-book icon and usually second from the left. Not to be confused with the start menu, the hamburger in the bottom-left corner of the shelf, which is a launcher you build yourself (though it does carry a Bookshelf menu shortcut to the same place by default). Anywhere these instructions mean a different menu, they say so.

A quick tour

The shelf menu (top of the screen)

Each shelf is one slice of your library. Tap one to switch to it. Out of the box you get Home, Recent, Series, and Favorites, but you can rename, reorder, hide, or delete any of them and add as many of your own as you like.

A shelf can point at:

Home -- your library as folders, or as a flat list of every book.
Recent or Latest -- books you read recently, or books added recently.
A stack of series, authors, genres, collections, formats, ratings, or reading statuses. Tap a stack to drill into one of its members.
A specific series, author, genre, collection, format, rating, folder, or reading status -- a shelf showing just that one slice of your library.
Favorites -- the built-in starred shelf.
An OPDS catalogue -- an online book catalogue browsed as a shelf, with downloads. See OPDS catalogues.
Your Kindle library -- on a Kindle, the books in the Kindle's own library. See Kindle library.

Each shelf remembers its own filters (reading status, genre, language, format, rating, collection, or folder -- see Shelf sources, filters, and sorts), sort priority (up to three levels deep, e.g. surname, then series, then series number), label, icon, colour, and whether it's enabled.

To edit a shelf: long-press it. The footer of the editor has + Add new shelf if you'd like to start a fresh one.

The same menu (menu -> Bookshelf shelves…) also has Shelf menu font size for adjusting how big the shelves render across the top of the screen.

When you have more shelves than fit across the screen, the bar splits into pages: tap the > / < chevrons at the end of the row, or swipe left/right on the bar, to move between them (the active shelf's page shows first). On e-ink the change plays as a wipe -- see Animations.

Searching

Tap the search icon at the right of the shelf menu. Search looks across authors, series, genres, collections, and book titles in one go, and groups the results by category. Tapping a result drills into it; back-swipe to return to whichever shelf you were on.

Folder names aren't searched by default: in most libraries the folders mirror the author/series/genre stacks, so matching a folder just duplicates the metadata result of the same name. If you navigate by folder, turn on Settings -> Library & search -> Include folder names in search results.

On an OPDS catalogue shelf, the same search icon searches the catalogue itself (when the catalogue supports search), so you can look up a title or author across the whole catalogue rather than just the page on screen.

The hero card (top of the shelf area)

The big card at the top of the screen previews the focused book. Tap a cover on the grid to focus it; the card refreshes with its title, author, description, rating, and progress. Tap the hero card cover to open the book.

The hero card has eight sections you can show, hide, or restyle:

Status line -- top right; defaults to disk space, battery, frontlight, Wi-Fi, and time.
Rating -- five tappable stars (off by default; tap a star to set or clear).
Title
Author
Metadata -- a free-form line; the default shows the series and series number for books in a series.
Description -- the book blurb. Tap to read the full text in a scrollable viewer.
Tags (interactive) -- a strip of tappable pills for the book's author, series, genres, collections, and parent folder. Tap a pill to jump straight to that shelf. Off by default.
Progress -- bottom-anchored line with an inline progress bar.

To edit them, open menu -> Settings -> Edit book detail view (see Customising the hero card below).

Micro-modules on the home screen

The home screen can show a grid of micro-modules -- small live panels like a clock, a quote from your highlights, your reading goal, the weather, or a launcher button. They're the same kinds of panels you can add to the start menu.

Micro-modules can appear in three independent places, each its own on/off checkbox under Bookshelf settings -> Micro modules:

In hero area -- a grid entry at the right of the shelf menu swaps the book preview at the top of the screen for the grid (tap it to toggle between the two).
Full-screen button -- a grid button sits in the footer opposite the start menu; tapping it opens the modules full-screen as a dashboard, with the status line across the top. Close it with the X, a tap on empty space, or Back. The usual KOReader gestures (top-edge menu, edge swipes for brightness, corner actions) still work over it.
In start menu -- module cards appear in the start menu launcher alongside your other items.

You can run any combination. The hero and full-screen views keep separate module lists, so you can show different modules in each -- the full-screen list starts as a copy of your hero modules and then the two diverge as you edit them. Turning all three off disables micro-modules entirely (a quick way to rule them out when troubleshooting).

In either grid:

Long-press a module to move it, make it wider or narrower (- / +), add another from the picker (+), or remove it. In the hero grid you can also send a module to one of four pages; the full-screen view shows everything at once, so it has no pages.
Swipe left/right on the hero grid, or tap the in-grid arrows, to flip between pages.
Long-press the grid shelf to reset the hero grid to its defaults, or to remove micro-modules from the hero area.
On physical-button (D-pad) devices, move the cursor across the grid with the arrow keys, open a module with the centre key, and long-press to edit it.

The grid packs square modules (clocks, launcher icons) tightly and lets text modules fill the rest of the row. Set the number of columns and rows under menu -> Edit shelf size. Hero micro-modules have their own entry under menu -> Settings -> Text size so you can scale the grid independently of the book hero.

The shelf grid (the books)

Each cover on the grid is either a book or a stack of books (for series, authors, etc.).

Tap a book to preview it in the hero card.
Tap the hero card cover to actually open the book.
Long-press a book to open the book menu (see below).
Long-press a stack to pin it to the shelf menu as its own shelf.
Swipe up to collapse the hero and show more books at once.
Swipe down on the hero to restore it; swipe down on the shelf area to refresh the library after adding new books over USB or Calibre.

Every shelf shows a line of text under each cover -- the title by default. One setting drives it everywhere: menu -> Settings -> Cover display -> Show text below covers picks Title, Author, Series, or None (covers then use the full row). Its text size is Cover labels under Settings -> Text size. Books without covers already show their title and author on the placeholder itself, so those skip the extra label.

The full gesture reference is in Gestures cheatsheet below; physical-key devices have their own reference in Keyboard and D-pad.

List view

Any shelf can be a text list instead of covers. Long-press the shelf and pick List under Show as, or hold the page range in the footer to cycle whichever shelf you are looking at through covers, list and spines. Every shelf shows Covers until you change it; the third option, Auto, switches that shelf to a list whenever it is expanded or drilled into a folder or stack, and back to covers on the two rows under the hero. The same dialog sets how many rows (1 to 12) and columns (1 to 3) the list uses, and pinching the shelf fits one more or one fewer row.

Search results keep their own view -- covers unless you say otherwise. Long-press the Search results pill (or hold the page number) while viewing results to pick Covers, List or Auto for them.

Rows are built from the same editable lines as the hero card: up to six per row, each with its own template, font, size, weight, slant, case and alignment, edited under menu > Settings > List view. Tokens work in every line, so a row can carry a progress bar (%bar, or %bar{rel} to make its length reflect how long the book is), file size, dates, or anything else from the Token cheatsheet. As rows get shorter, lines drop from the bottom up, so the title and author are the last to go.

Series, authors and folders draw as a fan of their members' covers; OPDS subcatalogues become full-width buttons. The list's text size lives under Settings > Text size.

Spines

The third style. Books stand edge-on on a wooden plank, the way they do on a real shelf, so a lot of them fit at once and the shelf reads as an object rather than a grid.

Each book is drawn from what Bookshelf already knows about it:

Width comes from the page count, so a doorstop is visibly fatter than a novella. This is the one that benefits most from Extract page counts below.
Height comes from the cover's aspect ratio, so a tall paperback and a squat hardback differ.
Colour is sampled from the cover art, darkened enough to keep the title legible along the spine.

Long-press a shelf and pick Spines under Show as, or hold the page range in the footer to cycle to it. The same dialog has the settings below it.

Face out. Some books turn to show their cover, the way a shop dresses a shelf. Choose which: favourites, the first in each series, what you are currently reading, all books, or none.

Grouping. On a grouped shelf (series, authors, genres) there are no folders to drill into -- the groups are flattened onto the shelf and each run gets a label at the shelf's edge. Everything is out where you can see it.

Ornaments. Drop SVG files into KOReader's icons/bookshelf.ornaments folder and they turn up now and then in the gaps, standing on the plank like the books. A potted plant and a cactus are seeded there to start you off; delete them if you would rather not see them and they stay deleted. template.svg carries the conventions in its comments: the bottom of the viewBox is the plank surface, bookshelf:overhang=N lets part of the shape hang over the front edge, and the renderer is small, so bold solid shapes work and text, filters and masks do not.

Shelf plank colour is under Settings -> Colours. The lit top surface and the shaded front edge are both tinted from that one colour; the default is light oak.

Spines are not available for OPDS catalogues, which have no local page counts or cover art to measure.

Folder styles (how groups look)

Anything that stands for several books -- a series, an author, a folder, a collection -- is drawn as a group tile, and you choose how those look. menu -> Settings -> Cover display -> Default folder style sets it for the whole library:

Divider card -- a cardboard tab with the group's name on it. The default.
Ribbon -- the first book's cover with the name on a band across the bottom.
Book stack -- a small pile of the covers inside.
Collage -- a grid of several covers from the group.
Text -- the name alone, no artwork.
None -- the first book's cover, unadorned.

Individual shelves can differ. Long-press a shelf -> Folder style gives that one shelf its own look, and the list leads with Default setting to put it back to following the library. The picker stays open while you try styles and the shelf redraws behind it, so you can compare them rather than guessing. (OPDS catalogue shelves have no such row -- their category tiles are always text; see OPDS catalogues.)

You can also give a specific folder or stack a picture of your own -- see Custom images for folders and stacks.

Folder shortcuts and jump-to-folder gestures

If a KOReader folder shortcut, the "go to parent folder" or "go home" gesture, or any plugin points the file browser at a folder while Bookshelf is open, Bookshelf follows into that folder rather than leaving you on the previous shelf. The folder is added to the breadcrumb trail, so a back-swipe returns you to where you were. Opening an actual book still goes straight to the reader as usual.

The start menu

Tap the menu button in the bottom corner of the shelf, in line with the page arrows, to open a popup launcher you build yourself. Think of it as a Start menu for your home screen.

Each item can be:

A KOReader action -- history, the reading calendar, Wi-Fi, night mode, sleep, frontlight, and anything else from KOReader's action list.
A menu action -- capture any item from KOReader's own menus and replay it with one tap. Browse to the item, tap Add as shortcut, and it becomes a menu entry; toggle items (like Wi-Fi) show their current on/off state.
Another plugin -- launch any installed plugin that has a menu entry (games included).
A Bookshelf action -- the full Bookshelf menu (settings, the book detail editor, collections, and the rest), or exit Bookshelf.
A folder -- group items together; it flies out to the side when you tap it.
A micro-module -- a small live panel (see below).

Building and editing it. Long-press any item for rename, change icon, move up / down, move into / out of a folder, show in (home screen, reader, or both), delete, and add new menu item. Adding walks you through the categories above; the icon picker is a built-in glyph grid (no extra plugins needed). Folders open downward from the row you tapped, overlapping the menu so they read as connected.

Position. Under Bookshelf settings -> Start menu you can put the button on the left, the right, or turn it off, and set a Minimum start menu width if the popup feels cramped. It works with touch and with physical-button (D-pad) devices.

While reading. Under menu -> Settings -> Advanced -> While reading, turn on Show menu button to keep a small launcher button in the reader's bottom corner. Tapping it opens the same start menu over your book, so you can jump to a shelf, a collection, or another plugin and tap straight back in. Show micro-modules button adds the full-screen grid button to the reader too. Launcher button position and size… opens a live canvas for placing them: pick the side, the screen edge they sit against, how far along it, and how big -- so they can hide in whichever corner your books' margins leave free. The start menu and module view open from wherever the buttons actually are. By default each menu item shows both on the home screen and while reading; use show in (above) to limit one to the reader or the home screen -- handy for keeping the reading menu short.

By gesture (no button needed). Prefer not to show a button? KOReader's Gesture manager (wrench -> Taps and gestures -> Gesture manager) lists Bookshelf's assignable actions, including Bookshelf: open start menu, Bookshelf: open micro-modules, and Bookshelf: go to home screen (drop whatever you're doing and land on your home shelf). Bind any of them to a gesture -- a corner tap, a swipe, a multiswipe -- and it works in the reader (or the library) whether or not the launcher buttons are shown. Because a bound gesture is a deliberate request, the start-menu and micro-module actions work even when those features are set to Off.

Micro-modules

Micro-modules are small live panels. Add them to the start menu through Add new menu item -> Bookshelf micro-module…, or to the home-screen grid. The ones that ship with Bookshelf:

Clock -- digital (12- or 24-hour) or analogue.
Quote of the day -- a highlight drawn from your own books, refreshed daily or on every open. Tapping it can roll a new quote, open that book's bookmark list, or open the book at the highlight.
Reading goal -- progress towards a daily reading target.
Reading stats -- time and pages read today and this week (needs the statistics plugin).
Reading streak -- your current and best reading streak, in days and weeks (needs the statistics plugin).
Random book -- rolls an unread book from the current shelf (or your whole library) into the hero card; tap the dice for another.
Shelf count -- how many books are on the current shelf.
Countdown -- "N days until " for a date you pick; counts up ("N days since…") once the date has passed. Add it more than once for several dates, each with its own label.
Weather, On this day, Trivia, Daily fun (jokes, facts and riddles) -- live content from the internet.
Action -- a launcher card that runs a plugin, a KOReader action, or a Bookshelf action, with your own icon and an optional label.

Each module can carry its own settings (reached via Module settings… when you long-press it). Modules that need the internet show their data source in the picker rather than fetching while you browse. Modules are a small self-contained format: if you write a little Lua you can add your own by dropping a file into the plugin's micromodules/ folder, or into koreader/settings/bookshelf/micromodules/ to have it survive plugin updates. A bad one is skipped rather than breaking the menu. See micromodules/README.md for the contract.

The book menu (long-press a cover)

Long-press any cover on the shelf or in the hero card -- or tap a book's +N tags pill -- to open the book detail popup, a tabbed window with everything about the book. The header shows a cover thumbnail, the title and author, and (when the book has bookmarks or highlights) a N bookmarks › link in the top-right corner; tap it to open KOReader's bookmark browser for that book and jump into it. Along the bottom sit Close, two zoom buttons (magnifier icons) for text size, and Open.

There are five tabs:

Description -- the book's blurb. When a Hardcover description is cached, a shelf menu switches between the embedded and Hardcover text.
Reviews -- spoiler-free Hardcover reviews for a linked book, cached so they reopen offline once fetched (see Hardcover enrichment). Only shown for linked books.
Tags -- navigation pills grouped into Author, Series, Collections, Genres, and Folder. Tap any pill to drill into that shelf; each section has an Edit… button for changing membership (this is where you add or remove the book from collections, edit genres, and so on).
Edit -- the book's actions:

Button	What it does
Unopened / Reading / On hold / Finished	Reading status. Tap to change. Unopened clears progress and drops the book from Recent without touching highlights or bookmarks.
Favorite	Toggle the book in and out of Favorites.
Your rating	Set a 1-to-5 star rating, or clear it.
Show info	KOReader's built-in book info dialog.
Refresh metadata	Re-read the cover and metadata from the file (useful after editing metadata externally).
Move…	Move the file to another folder on the device, via a folder picker. Reading progress, bookmarks, highlights, custom covers, and Hardcover links all follow the book. (Disabled while the book is open in the reader.)
Remove from history	Drop the book from Recent without changing anything else on disk.
Reset book data…	A wider purge with checkboxes for progress, bookmarks, highlights, notes, custom cover, and custom metadata.
Delete	Permanently remove the file from disk (with a confirmation).
Link… / Edit… (Hardcover)	Shown only when `hardcoverapp.koplugin` is enabled. Link the book to a Hardcover edition, or edit an existing link. See Hardcover enrichment.

If another plugin adds its own entries to KOReader's file long-press menu (for example "Open Incognito", or an AI assistant's "About this book"), those appear in the Edit tab too, so you can use them straight from Bookshelf.

Cover (last tab) -- pick the book's cover from a paginated grid of candidates: covers already stored for the book, an image from your device (Choose from device), or an online search (Google Books, Open Library, and Hardcover for a linked book). Each candidate shows its source and resolution. Tap one to set it as the cover -- the shelf updates and the chosen image is saved as KOReader's standard custom cover, so its file browser shows it too. The book's own embedded cover appears in the grid as well, so you can revert by tapping it; a cover you'd set yourself is preserved.

Text size. The footer's zoom buttons resize the current tab's text, and each tab remembers its own size -- so you can enlarge a long Description or the Reviews without also inflating the Edit tab's buttons or the Tags pills. To resize the tab labels themselves (handy if Description/Reviews/Tags/Edit wrap onto a second row on a small screen), use menu -> Settings -> Text size -> Modal tabs. (With Reviews present that's up to five tabs -- Description, Reviews, Tags, Edit, Cover -- so this helps most on a small screen.)

Long-pressing a series, author, genre, collection, format, rating, or folder stack instead opens a small group menu: Pin to shelf menu (the fastest way to turn a stack you've drilled into into a permanent shelf), Set … image… / Clear … image (see Custom images), Select N to start a bulk selection of the group's books, and -- for real folders -- Move folder… and Rename folder…, which relocate or rename the folder on disk with every book's progress, bookmarks, and covers following along.

With a bulk selection active (from a group menu's Select N, or Select in a book's Edit tab), tapping covers adds or removes them, and the selection bar offers batch actions including Move to folder… for moving several books at once. The bulk menu also has Select all in this shelf, which takes every book the current shelf holds across all its pages -- the way to select a shelf built from filters, which has no folder or stack tile to long-press. There's an assignable gesture for it too (Bookshelf: select all books in this shelf).

Collections

Collections are named lists of books, and Bookshelf uses KOReader's built-in collection system, so anything you collect in Bookshelf shows up in KOReader's collection menu (and vice versa). Two collections come ready:

Favorites -- the built-in starred shelf. Always present; can't be renamed or deleted.
To Be Read -- a reading pile for things you haven't started yet.

Open menu -> Settings -> Library & search -> Manage collections… to add new collections, rename or delete existing ones, and pin any collection to your shelf menu as a dedicated shelf.

To put a book into a collection, open its popup (long-press the cover), go to the Tags tab and tap Edit… in the Collections section. Tick the collections you want, then Save. The Collections pills update immediately to reflect what's changed.

OPDS catalogues

Bookshelf can browse online book catalogues (OPDS) as ordinary shelves -- Project Gutenberg, Standard Ebooks, Internet Archive, and any other catalogue you point it at -- so you can find and download books without leaving your home screen.

Setting up. Add a shelf (long-press any shelf -> + Add new shelf) and pick OPDS catalog… as its source. The picker lists the standard public catalogues out of the box, and it's also where you manage the list: Add catalog… sits in the footer, and a long-press on any catalogue offers Edit and Delete. A catalogue is just a name and a URL, plus an optional username and password for ones that need a login. If you also use KOReader's own OPDS plugin the two share one catalogue list, so anything added in either place appears in both -- but Bookshelf works fine with that plugin disabled.

Browsing. A catalogue renders like any other shelf. Its categories appear as folder tiles -- tap to drill in, back-swipe to come back out -- and some catalogues offer extra filters (language, category) as tiles at the start of the shelf. Category tiles always use the plain text style, whatever folder style the rest of your shelves are set to: they're places to go rather than piles of books you own, and a catalogue's own artwork rides along on them where it sends any.

Covers download in the background as you browse, a few at a time, and appear as they land; until one arrives its book shows a placeholder with the title and author. Nothing is fetched for pages you never look at.

Previewing and downloading. Tap a book to preview it in the hero card -- the description comes straight from the catalogue, and the cover is fetched in the background and appears in the hero and on the shelf as it lands. Tap the same cover again (or the hero) for the download view: available formats are grouped under Recommended and Alternatives, with the best format for KOReader listed first, and Read now opens the book as soon as it arrives. Downloads are saved into your library folder -- by default wherever KOReader's own download folder points, or your home folder if that isn't set. Each catalogue shelf can file its downloads somewhere of its own instead: long-press the shelf to edit it and use Saves to, so (say) Gutenberg classics and your own server's books land in different folders. The folder has to sit inside your home folder, otherwise the books would never appear on your shelves. The catalogue's description stays with the book after download, so the hero and book menu keep showing it.

Big catalogues, and finding the end. Large catalogues load as you go: the page indicator reads "page N of M+", where the + means nobody knows yet how far it goes, and paging forward pulls the next batch. Catalogues are not reliable about their own size -- most don't say, and at least one advertises a round number it never actually serves -- so the count is what's loaded rather than a promise.

To find the real end, tap the last-page chevron. It walks the whole category, counting as it goes, and lands you on the last page with books on it. It can run for a while on a big category, so it tells you where it's up to and a tap stops it -- and stopping keeps everything already loaded, landing you on the last page of that.

Offline, and coming back. Everything a catalogue has shown you is kept on the device, so a catalogue you've browsed opens straight away and keeps working with no connection. By default it only goes back to the server when you ask it to, with a swipe down -- so paging deep into a category is work you keep. If you'd rather a catalogue went stale on its own, long-press its shelf and use Catalog settings -> Refresh to pick an age (five minutes through a week, or every time you open it). The same dialog has Saves to for where that catalogue's downloads land.

Where you were is remembered: restart KOReader inside a drilled category and you come back to it, on the page you left, provided it's still cached. If it isn't, you land on the catalogue's front page rather than on an empty shelf -- getting there would mean a download you didn't ask for.

Catalogues that only lend DRM-protected books (library loans) can't be used -- KOReader has no DRM support -- so lending-only categories show "No downloadable titles" rather than books that wouldn't open.

Kindle library

On a Kindle, Bookshelf can show the books in your Kindle's own library as an ordinary shelf, alongside the books you side-load yourself. It needs the Kindle Virtual Library plugin (kindle.koplugin) installed: a Kindle book has to be converted before KOReader can read it, and that plugin is what does the converting. Without it the source isn't offered at all.

Setting up. Add a shelf (long-press any shelf -> + Add new shelf) and pick Kindle Virtual Library as its source. The option only appears on a Kindle that has the plugin installed, so it stays out of the way everywhere else.

What you get. Your Kindle books with their own cover art, sorted however you like -- title, author, progress, when you last opened them, or anything else the sort picker offers. Titles that the Kindle derived from filenames (01. The Colour of Magic - Terry Pratchett) are tidied up, with a trailing or leading author name removed only where the Kindle's own records confirm that is who wrote it; an unrecognised name is left alone rather than guessed at. Series numbering is kept, so a numbered series still reads in order. A book with no cover art gets Bookshelf's own placeholder, showing title and author, rather than the blank "No image available" card the Kindle stores for it.

Reading progress. The progress shown on a cover comes from the Kindle's own record until you have read the book in KOReader, after which KOReader's is used. That is what the shelf displays, not where the book opens: the Kindle's percentage is never handed to KOReader as a position, so opening a Kindle book for the first time starts at the beginning however far through it you were on the Kindle. The status marker follows the display rule, which means a book you finished on the Kindle is marked finished even though KOReader has never opened it, while long-pressing it still reports its reading status as unopened -- that dialog sets KOReader's status, and KOReader has not read it. All of which is to say the Kindle's record and KOReader's are kept apart rather than merged.

The first open. The first time you open a Kindle book it has to be converted. That takes a few minutes, the screen will not respond while it works, and it cannot be stopped once started -- so Bookshelf asks first, and only asks once per book. Every open after that is immediate, because the converted copy is kept.

Books that will not open. Older MOBI and AZW purchases are protected in a way no KOReader plugin can undo, and .azw3 files cannot be read by KOReader at all, protected or not. Both say so when you tap them, naming the format, rather than dropping you into the file browser. KFX books -- most of a modern Kindle library -- are unaffected.

Filters and sorts. A Kindle shelf takes filters and sort priorities like any other, and its filter pickers describe its books: the genres, formats, languages and collections offered are the ones your Kindle library actually has, so nothing on the list matches nothing on the shelf. A new Kindle shelf starts with the formats KOReader cannot open already filtered out, so the shelf is not padded with books that can only refuse; if you would rather see them, clear that under the shelf's Filters -> Format.

Counted with everything else. Your Kindle books are part of your library, so they count towards the Shelf size module and the %books_read token, and a book you finished on the Kindle counts as finished.

Hardcover. Kindle books can be linked to Hardcover like any other, individually or through Auto-link all books, which picks up covers, ratings and genres for them. Genres matter twice over here: once linked, a Kindle book's genres work in genre filters and on genre shelves, which the Kindle's own records cannot supply.

Searching. Once you have a Kindle shelf, searching your library searches your Kindle books too. And searching from an OPDS catalogue now offers both: Search my library alongside the catalogue's own search, so browsing a catalogue no longer means leaving it to check whether you already own something.

Read-only. The book menu leaves out Move, Delete and Reset for these books. The files belong to your Kindle's library rather than being files you put on the device, and deleting one would really remove the book.

Kobo library (beta)

The Kobo equivalent of the Kindle shelf above: your Kobo's own virtual library, the books managed by the Kobo store, shown as an ordinary shelf. Turn it on under menu -> Settings -> Advanced -> BETA: Kobo library shelf and a Kobo shelf appears.

It needs OGKevin's kobo.koplugin, which is what actually holds that library, and it only appears on a Kobo. If the plugin is missing or its internals have moved, the shelf simply does not show rather than erroring.

The shelf is read-only: covers and opening the books are the other plugin's job, so Bookshelf shows what it finds and hands taps straight back. Filters, sort priorities and the filter pickers work as they do on any other shelf, and as with the Kindle shelf the pickers describe the Kobo library's own books.

It is marked beta for an honest reason: it was built without a Kobo to hand, against unit tests and one Kobo-owning reporter. It should behave, but if something looks wrong, that is worth an issue.

Hardcover enrichment

If you also use hardcoverapp.koplugin, Bookshelf can link books to Hardcover and cache a small amount of Hardcover metadata for display. Everything Hardcover follows that plugin's state: it all appears only while the plugin is installed and enabled, so it stays out of the way if you don't use Hardcover. Disable or remove the plugin and the Hardcover enrichment menu (in the bookshelf menu, above Settings) disappears and linked books revert to their own ratings, covers, metadata and descriptions. Nothing is lost -- the cached data stays on disk and comes back if you re-enable the plugin.

Linking a book. Open a book's popup (long-press its cover) and go to the Edit tab; with the plugin enabled, a Hardcover row sits below File & metadata. Link… (or Edit… once linked) opens the link menu:

Auto link -- links without searching, using identifiers embedded in the EPUB (an ISBN, or a Hardcover id/edition baked into the file). The most specific identifier wins (a Hardcover edition, then ISBN, then a Hardcover book/slug). If the file carries no usable identifier, Auto link falls back to a best-guess search by title and author.
Manual link… -- searches Hardcover by title and author and lets you pick the right book.
Select edition… -- once linked, choose a specific edition (e.g. to get the right cover or page count).
Use Hardcover image / Use Hardcover description -- per-book toggles (shown once linked) that override the book's own cover or description with Hardcover's. See below for how these are set automatically.
Clear link -- remove the Hardcover link.

When a book is linked, its popup gains a Reviews tab (and the hero rating row's "N reviews" opens the popup straight to it). Reviews are filtered to spoiler-free ones, and cached, so they reopen offline once fetched.

Linking the whole library at once. Hardcover enrichment -> Auto-link all books links every unlinked book in one pass, fetching each match's details (description, cover, rating) as it goes. You pick how to match:

Exact match -- uses an embedded ISBN or Hardcover id. Fast, and only links books that carry one.
Best guess -- searches by title and author and picks the most confident match. Slower, but catches books with no embedded id.

It contacts Hardcover at about one book per second with cancellable progress, and shows a report at the end listing what was linked, what wasn't matched, and what had no identifier to try.

Choosing covers and descriptions. Each linked book has its own Use Hardcover image and Use Hardcover description toggles. When you link a book, Bookshelf sets sensible defaults once: it adopts the Hardcover description if the book has none of its own, and the Hardcover cover if the book has no embedded cover or its cover is lower resolution than Hardcover's. After that the per-book toggle is yours -- it's never changed again by a later refresh. Turning Use Hardcover image on saves the Hardcover cover into the book's sidecar (.sdr) folder as a custom cover, so KOReader's own file browser shows it too; turning it off restores whatever was there before -- a cover you'd set yourself is preserved, never overwritten.

Ratings and metadata. Two more options sit in the Hardcover enrichment menu:

Show Hardcover ratings in hero -- the hero rating row shows the cached public Hardcover rating instead of KOReader's local one (and turns the rating row on).
Use Hardcover metadata -- for linked books, shows Hardcover's title, author, series and genres in place of the book's own (a clean switch, no merging). This feeds sorting, search and series grouping for those books; non-linked books are untouched. Hardcover genres used caps how many of a book's genres become tag pills and genre stacks. Covers and descriptions stay under their per-book toggles. The metadata is always cached, so this only decides whether it's used.

Managing the cache. Hardcover enrichment -> Manage Hardcover data holds Refresh ratings only, Refresh linked book details, Clear cache (keeps links), and Remove all Hardcover data (unlinks everything and restores any covers Bookshelf installed).

The two refreshes differ in cost. Refresh ratings only fetches every linked book's rating in one batched request, so it takes seconds even on a large library, and ratings are the thing that actually drifts day to day. Refresh linked book details re-fetches the rarely-changing fields as well -- author, genres, series, description, page count -- one rate-limited request per book, so minutes rather than seconds, and cancellable. Reach for it after an upgrade asks for it, or when cached data looks stale.

Bookshelf does not rewrite EPUB files. Descriptions, ratings and the other cached metadata live in Bookshelf's own cache; a chosen Hardcover cover is stored as KOReader's standard custom cover in the book's .sdr folder. Network calls only happen from explicit actions (linking, refreshing ratings, fetching reviews); normal shelf rendering reads only the local cache.

Layout

Open menu -> Edit shelf size… for a live overlay that resizes the grid without leaving the home screen. Two nudge rows:

Columns -- how many covers fit across, which also sets how large they render.
Rows -- how many rows of them the shelf gets.

Together they decide how the screen is divided: the shelf takes what these two ask for and the hero card above fills whatever is left. List and spine shelves use that same space with their own row counts, which is why the shelf previews as covers while the overlay is open.

The layout auto-fits your screen and orientation, so the same settings adapt between portrait and landscape. Changes preview in real time behind the overlay; Accept keeps them, Cancel reverts. Pinching the shelf itself is the quicker way to the same thing, and on list and spine shelves it moves in half steps, so four rows can become three rather than jumping to two.

Animations

On e-ink, Bookshelf can play a brief page-wipe animation on transitions so they read as motion rather than an abrupt refresh. Two independent settings under menu -> Settings -> Behavior control them:

Page turn animation -- shelf page turns (the new page sweeps in from the side) and shelf-bar paging (the shelf row wipes across as you move between pages).
Start menu animation -- the start menu reveals upward as it opens and wipes back down as it closes. It repaints a taller area than the page wipe and can look choppy on some panels, particularly while reading, so it's kept separate: keep one and turn the other off if you like.

Each is set to Off, Fast, Medium, or Slow on its own -- slower is smoother but takes a little longer on older panels. The effect is e-ink only: on LCD/OLED screens the refreshes complete instantly, so nothing is shown and the setting has no visible effect there.

A separate Cover opening effect toggle (under Settings -> Cover display) briefly flexes a book's cover open as it launches. It's purely cosmetic and on by default; turn it off for an instant, plain open.

Instant book close

Leaving a book drops you back to Bookshelf straight away, without waiting for the book to close. The actual close happens at the next quiet moment -- when you open another book, after about half a minute of inactivity, or when you leave Bookshelf -- so browsing never has to wait for it. Until then, going straight back into the same book is instant too.

This works however you leave a book: the reader's top-menu File browser button, a File browser gesture, or the quick menu.

It's on by default. Turn it off under menu -> Settings -> Advanced -> Performance tweaks -> Instant book close to close books fully before Bookshelf appears, as before. (Leaving a book you read in a different orientation to the shelf always closes fully, so the shelf returns to its own orientation.)

Cover indicators

Each cover can show small badges and bars at the corners. Configure them under menu -> Settings -> Cover display:

Show reading bookmarks -- a bookmark mark on books you're partway through.
Show completed book badge -- a check-mark pill at the bottom-left of finished books.
Show progress bars -- a thin progress bar above the bottom edge for in-progress books.
Show page count -- a page-count pill in the bottom-right ("123 p"). (For EPUBs it works once you've opened the book at least once.)
Show series # -- a "#3" badge on covers in a series. Tri-state: Always, Within series folder (so mixed shelves stay clean), or Never.

The colours of these elements are set separately under Settings -> Colors (see below).

The same Cover display menu also has True cover aspect ratio. Off by default, Bookshelf fits every cover to a uniform book rectangle; turn this on to show each cover at its real shape instead. Covers keep the same width but vary in height -- on the shelf they sit along the bottom shelf line, in the hero area they align to the top -- so wide or square covers stop being cropped or stretched.

Two more rows in that menu change how a cover is drawn rather than how it is sized. Square cover corners replaces the rounded card shape with square ones, and No cover drop shadow draws covers flat against the page rather than raised off it, giving their reserved pixels back to the cover so it grows slightly. They are independent, so a flatter grid can keep the shadow or lose it separately. Both are off by default, and list view's cover column is unaffected either way -- a table cell has never had the chrome.

Colours

Open menu -> Settings -> Colors to recolour the cover chrome. Bookshelf keeps independent day-mode and night-mode palettes -- the top row of the menu shows which one you're editing ("Editing day-mode colours" / "Editing night-mode colours") and tapping it flips night mode so you can set each theme. Anything you leave unset uses a sensible default for that mode.

Each colour is chosen as a "% black on screen" value (so it reads the same way in both modes), and long-pressing a row resets just that colour. The pickers:

Progress bar / Progress bar track -- the filled and unfilled parts of the cover progress bar.
Bookmark color / Finished bookmark color -- the in-progress bookmark glyph and the finished-book check.
Favorite star color -- the star on favourited covers.
Badge foreground / Badge background -- the text and fill of the "#N" series and "123 p" page-count pills.
Border color -- one shared colour for cover frames, badge borders, the bookmark/star halos, the cardboard edge on folder and stack cards, and placeholder (no-image) covers.
Folder overlay background -- the cardboard fill behind folder and stack cards.
Folder text color -- the label text on those cards (the card outline follows Border colour).
Reset to default colors -- restore the whole palette for the current mode.

On colour e-ink panels (Kaleido), a separate Color panel dithering toggle under Advanced -> Performance tweaks keeps covers at full saturation when the shelf redraws; it's on by default, and the row only appears on colour devices.

Custom images for folders and stacks

Bookshelf can replace the default folder cover (cardboard card with the first book peeking above) and the stack covers (Authors / Series / Genres / Collections) with your own images. Three ways to set one:

Long-press the card -> Set folder image… / Set author image… / etc. -> pick an image file. The image renders as that folder's or stack's cover with the cardboard tab + label staying on top so the group identity is still visible.
Drop cover.jpg, cover.png, folder.jpg, or folder.png into a folder and Bookshelf picks it up automatically. The hidden dot-file variants (.cover.jpg, .cover.png, .folder.jpg, .folder.png) work too, for keeping the image out of the visible file listing; a visible file wins if both are present. The image follows the folder when you move it.
Drop named images into an image library for authors, series, genres, and collections. The default location is <your-library>/.bookshelf-images/ with subfolders authors/, series/, genres/, and collections/. Name each file after the exact stack name (e.g. authors/Asimov, Isaac.jpg) or use a slugified form as a fallback. The slug lowercases the name and turns runs of punctuation / whitespace into single dashes, preserving the original order -- so Asimov, Isaac matches asimov-isaac.jpg, and Isaac Asimov matches isaac-asimov.jpg. Extensions tried in order: jpg, jpeg, png, gif, bmp, webp, tiff.

Pick a different image-library location under menu -> Settings -> Library & search -> Image library.

Long-press an image-set folder or stack and tap Clear … image to revert to the cardboard default.

Calibre metadata (beta)

For libraries managed by Calibre. Turn on menu > Settings > Advanced > BETA: Read calibre metadata.calibre and Bookshelf reads the metadata.calibre file Calibre writes when it syncs books to a device or manages a folder. The file must sit directly in your KOReader home folder (the folder Bookshelf scans for books), so point Calibre's device sync at that folder, or set your home folder to wherever Calibre already syncs. Its fields are read alongside each book's embedded metadata.

What it adds:

Calibre's title, authors, series, tags, language and description win over the values embedded in the book file, so edits made in Calibre show up without reconverting books
Calibre's author sort ("Le Guin, Ursula K.") orders author shelves, including hand-edited sort values
A custom column of the Series type gives its books a second series shelf alongside the primary one
Any custom column you create in Calibre can be shown in a token line via %calibre{name}, using the column's lookup name: a column #mood renders with %calibre{mood} (the # is optional). Text, fixed-value lists, numbers, dates, yes/no and multi-value columns all work; the one exception is long-text ("Comments"-type) columns, which are too big for a one-line token. This works anywhere tokens do -- hero card sections, list view lines, and conditionals like [if:calibre{mood}="cosy"]
Three standard Calibre fields are exposed the same way: %calibre{pubdate} (publication year), %calibre{publisher} and %calibre{rating}. Date columns -- standard or custom -- show as the year

What can be shelved, and what can only be shown. Calibre's tags become genres, so they drive genre shelves, the genre filter and %genres exactly like tags read from the book file. A custom column of the Series type gets its own series shelf, as above. Every other custom column is display-only: it can be printed in a token line and tested in a conditional, but you cannot yet build a shelf per column or filter by one.

Bookshelf looks for metadata.calibre or .metadata.calibre (the hidden form Calibre writes for some device setups), so either name works.

Two things worth knowing:

KOReader's own wireless Calibre connection rewrites metadata.calibre after a sync and permanently drops author sort and custom columns from it. Bookshelf works around this automatically: whenever it reads a Calibre-written file it saves those fields into a small calibre.bookshelf.json beside it, and merges them back after KOReader's rewrite. No setup needed -- but the library must have been written by Calibre itself (USB sync, or a Calibre-managed folder) at least once, since a wireless-only library never has those fields on disk to save. That file is plain JSON keyed by each book's lpath (the same path Calibre writes into metadata.calibre), so if you ever need to supply columns Bookshelf cannot get at any other way, you can write it yourself and it will be merged in; anything present in metadata.calibre wins.
A metadata.calibre over 64 MB is read with a slimmer parser that skips custom columns. Below that the file is read in full, and above about 16 MB Bookshelf shows an "Importing calibre metadata" message while it works: a 64 MB file takes around 6 seconds to read and is held in about 24 MB of memory. That happens when Bookshelf starts and again after a Calibre sync changes the file, not on every screen. Custom columns are what make these files big: Calibre repeats each column's whole definition on every book, roughly 400 bytes per column per book, so trimming the columns you do not need is the quickest way to bring a large file down.

Author names

By default Bookshelf shows author names however each book stores them, so the same person can appear two ways (e.g. Richard Osman and Osman, Richard). Under menu -> Settings -> Library & search -> Author name formatting you can pick:

Auto -- leave names as stored (the original behaviour; first form found wins).
First Last -- always Forename Surname.
Last, First -- always Surname, Forename.

Whichever you choose, variant spellings of the same author are merged into one entry on the Authors shelf, and the alpha-jump / surname sort uses the surname -- including names with particles like de Maupassant, which sort under M.

Customising the hero card

Open menu -> Settings -> Edit book detail view to toggle each of the book's sections on or off; tap a section's row to open its line editor. The status line (the strip of device and reading info at the very top) is configured the same way from its own Status line entry just above, and the hero card's overall text size lives under Settings -> Text size -> Hero card.

Show status line. Bookshelf can put this same line across the top of the reader, so it does not change as you move between the shelf and a book. The switch lives under menu -> Settings -> Advanced -> While reading, alongside the other things Bookshelf can draw into the reader; the line itself is still edited here, and the reader follows. It is drawn by the same code that draws it on the shelf, so the two are identical by construction. This works on its own; if you also use Bookends, its top row and any top-anchored progress bar move down to make space.

The Tags section is an interactive pill strip rather than a line of text, so instead of the line editor its row opens a small submenu: turn the line on or off, choose which pill categories to show (Author, Series, Collections, Genres, Folder), and set the Font size and Alignment. Turning off Author and Series, for instance, leaves a line of just the real tags. The Rating section is interactive too and is a simple on/off toggle.

The line editor lets you change the text and styling of one section. You'll see these controls:

Button	What it does
Bold	Toggle bold weight.
Size	A nudge dialog (-5 / -1 / +1 / +5) over the font size, range 8 to 48 pixels.
Font	Pick a font family. Shows previews when Bookends is installed.
Aa / AA	Toggle uppercase (hidden on the Description section).
L / C / R	Cycle alignment (left, centre, right).
Bar style	(Progress only) Cycle the inline progress bar's visual style.
+ Bar / - Bar	(Progress only) Add or remove the `%bar` placeholder.
Bar height	(Progress only) Nudge the inline bar's height as a percentage.
Tokens…	Pick from a categorised list of placeholders (see below).
Icons…	Insert icon glyphs from the built-in icon library (a searchable, categorised glyph grid).
Default	Reset this section's text and styling to its defaults.
Cancel	Revert and close.
Save	Persist and close.

Edits update the hero card behind the editor in real time.

Tokens (placeholders)

Any text in a hero section can include tokens -- placeholders that get replaced with live data. For example, %title becomes the book title; %book_pct becomes the percentage read.

You can wrap things in [if:...]...[/if] to show them only when the relevant data exists. For instance, [if:series]%series_name #%series_num[/if] only renders when the book is in a series.

The full token list is in the Token cheatsheet below.

Bundled fonts

Bookshelf ships three open-licensed fonts (see fonts/CREDITS.md):

Roboto Condensed (Apache 2.0) -- the default Bookshelf UI font on new installs.
Inter ExtraBold (OFL) -- default hero title.
Caveat (OFL) -- default hero author.

Set the interface font under Bookshelf settings -> Bookshelf UI font (defaults to Follow KOReader UI font for existing users). The fonts are also copied into your font folder so they're selectable in the hero card's font picker after a restart. Existing users can adopt the new detail look via Reset book detail area to defaults.

Updates

Open menu -> Updates to keep Bookshelf current. Once any check has found a newer release, the menu entry itself reads Update available so you don't have to open it to find out.

Check for updates -- the installed version is shown in brackets. Tap to check GitHub for a newer release, read its notes, and choose Update and restart.
View changelog -- browse this and past releases' notes, newest first. Notes are cached, so anything fetched once stays readable offline; Refresh pulls the latest.
Notify on wake when update available -- opt-in. Once an hour after a Wi-Fi-connected wake, Bookshelf checks the GitHub releases page and posts a quiet notification if a new version is out. Off by default; nothing is ever fetched without your permission.
Developer updates (advanced) -- type a development branch name (e.g. feat/foo) to install the tip of that branch. Use Reset to latest stable release to clear the dev branch and pull the latest published release.

The whole download, unpack, and restart sequence runs over Wi-Fi only and needs no extra plugins. If Wi-Fi is off, Bookshelf offers to turn it on and carries on once it connects; if it's already connected, it just proceeds, including on networks where a connectivity check would fail (a Pi-hole blocking Microsoft's test domain, for instance).

Library refresh

After adding new books over USB, Calibre, Syncthing, or KOReader's network downloads:

Automatically -- Bookshelf watches your library folder in the background and picks up newly added books on its own, with no interaction needed.
Tap a shelf -- it also checks for filesystem changes on shelf taps.
Swipe down on the shelf area for an immediate, full refresh; a brief "Refreshing library" notice appears.

Page counts

Reflowable formats like EPUB have no fixed page count until something paginates them, so a book you have never opened usually has none. That is fine for most of Bookshelf, but it matters in two places: spine widths have nothing to vary by, and the page tokens have nothing to show.

menu -> Settings -> Library & search -> Extract page counts fills them in. It works down a ladder, cheapest first, and only falls back to the slow option for what is left:

a p(123) marker in the filename, which costs nothing to read
a linked book's page count from Hardcover
a publisher page count embedded in the book itself
failing all of those, it offers to paginate the rest with KOReader's own engine, one book at a time in the background

You get a report at the end saying where each count came from. The slow step is optional, cancellable, and the one worth thinking about on a large library.

Two things worth knowing about the numbers:

The scan paginates at the engine's default font settings, not yours. That keeps counts comparable between books, which is what spine widths want, rather than shifting every spine whenever you change font size. It is an approximation, and it is replaced by the real count as soon as you open the book, since KOReader works that out at your own settings and Bookshelf prefers it.
The counts live in Bookshelf's own store, not in the book's sidecar. Writing them to a sidecar would make KOReader treat an untouched book as one you had opened, which would quietly change your Recent shelf and reading statistics.

Once found, the counts feed spine widths, %page_count, %pages_left, and %bar{rel} (the progress bar whose length reflects how long the book is).

Reference

Everything beyond this point is the full feature reference. Expand any section you need.

Gestures cheatsheet

Gesture	Where	What it does
Tap	Shelf cover (normal mode)	Preview the book in the hero card
Tap	Shelf cover (expanded mode)	Open the book directly
Tap	Hero card cover	Open the previewed book
Tap	OPDS catalogue cover (already previewed)	Open the download view
Tap	OPDS folder tile	Drill into the category
Tap	Hero card description	Open the full description in a scrollable viewer
Tap	Hero card star	Set / clear the book's rating
Tap	Shelf	Switch shelf
Tap	Search icon	Open the library search
Tap	"9-16 of 247" footer	Open the go-to dialog: jump by page number, jump to the first item starting with a letter, or search the library
Tap	First / prev / next / last chevrons	Page navigation
Long-press	Shelf	Open the shelf editor
Long-press	Shelf book cover	Open the per-book menu
Long-press	Shelf stack cover (series, author, etc.)	Pin the stack to the shelf menu
Long-press	Prev / next chevron	Skip 10 pages back / forward (clamped to first / last)
Long-press	Hero card	Open the per-book menu for the previewed book
Swipe west (<-)	Hero card	Cycle preview to the next book in the active shelf
Swipe west (<-)	Anywhere else	Next page; on the last page, drills out or switches shelf
Swipe east (->)	Hero card	Cycle preview to the previous book
Swipe east (->)	Anywhere else	Previous page / drill back out / previous shelf
Swipe north (up)	Anywhere	Collapse hero to a thin status strip; expand the grid
Swipe south (down)	Hero	Restore the full hero from expanded mode
Swipe south (down)	Shelf area	Refresh the library walk
Back (physical key)	Drilled into a stack	Pop one drill level back out to the parent shelf

The pagination row uses wide tap zones across the middle 75% of the screen. The outer 12.5% on each side is left free so KOReader's bottom-corner gestures (gestures.koplugin profiles for brightness, night mode, etc.) still register.

Keyboard and D-pad (non-touch devices)

Everything on the shelf is reachable with physical keys.

Key	What it does
Arrow keys	Move the cursor. Focus moves between the shelf menu, the hero card, the shelf grid and the footer as you run out of room in each.
Press (centre)	Act on whatever has focus: open the focused book, switch to the focused shelf, press the focused footer button.
ScreenKB + Press	The context menu -- the equivalent of a long-press. See below.
Shift + Press	Same, for external and desktop keyboards.
Sym + AA	Same, for other key layouts.
Page forward / back	Page the shelf, wherever the cursor is.
Back	Pop one level back out of a drilled-into folder or stack.

The context-menu chord is the important one. It is how a non-touch device reaches anything a touch device gets by long-pressing:

On the hero card or a shelf book, it opens the book menu -- description, tags, reviews, rating, reading status, and the rest.
On a shelf, it opens the shelf editor.
On a stack (series, author, etc.), it opens the pin / add / remove menu.

The chords are KOReader's own (they match FocusManager's hold gestures), so they are the same ones the rest of KOReader uses. The Menu key is deliberately left alone -- it belongs to KOReader's own menu on devices that have one.

Within the hero card the cover is a single focus target: the rating stars, description and tag pills alongside it are not separately focusable, so use the context-menu chord to reach them.

Back in the reader. Pressing Back after opening a book is KOReader's setting, not Bookshelf's: it defaults to walking your position history inside the book, which is empty in a freshly opened one, so it falls through to "Exit KOReader?". If you would rather Back returned you to the shelf, set menu -> Navigation -> Back in reader -> Go to file browser. Bookshelf picks that up and shows the shelf, the same as the Home action does.

Shelf sources, filters, and sorts

Sources

Each shelf points at one of:

Home (folders) -- your library as a folder tree.
Home (flat) -- every book in one list, no folders.
Recent -- books you've opened, newest-read first.
Latest added -- new files on disk, newest-added first (scan depth set under Settings -> Advanced -> Performance tweaks -> "Latest" walk depth).
Favorites
Series, Authors, Genres, Collections, Formats, Ratings, Languages -- a stack of all the values; drill into one to see its books.
Specific series / author / genre / collection / format / rating / language / folder / reading status -- a shelf scoped to a single chosen value.
Folder (flattened) -- a single folder shown as every book beneath it in one list, no sub-folder cards (vs. the plain folder source, which keeps the sub-folder tree).
OPDS catalog -- an online catalogue browsed as a shelf (see OPDS catalogues). The feed's own order is authoritative, so these shelves have no sort priority, and the local filters don't apply -- some catalogues offer their own filters as tiles instead.
Kindle Virtual Library -- on a Kindle, the books in the Kindle's own library, shown as a sortable shelf with their own covers. Needs the Kindle Virtual Library plugin, and is offered only where it is installed. See Kindle library.

Filters

Each shelf can narrow its shelf with any combination of filters, set from Filters… in the shelf editor:

Reading status -- Unread, Reading, On hold, Finished.
Genre, Language, Format, Collection -- pick any number of values.
Rating -- one to five stars, or Unrated.
Folder -- include and/or exclude folders (an exclude wins over an include, and both apply to sub-folders).

Picks within one filter match any of them, so two chosen genres show books in either. Picks across different filters must all match, so adding a 5-star rating then limits those to 5-star books only. Each choice shows how many books currently match given the other selected filters. All filters are off by default (everything visible).

Sort priority

Up to three levels per shelf. Available sort keys:

Title, Filename
Author surname, Author (given name)
Series name, Series index, Series + index (series name then number, in one pick)
Last opened (most-recent-first by default)
Date added (most-recent-first by default)
Percent read (most progress first by default)
Rating (highest first by default; unrated last)
Unread/Reading/Finished or Reading/Unread/Finished (status orderings)
File size
Page count
Book count (for stacks)

Defaults adjust to the source (e.g. Recent defaults to Last opened; Latest added defaults to Date added). The first-level sort decides the order of stacks for grouped sources; subsequent levels order books within each stack.

Hero card line editor

The book detail card has eight editable sections: Status, Rating, Title, Author, Metadata, Description, Tags (interactive), and Progress. The Tags section shows tappable pills rather than a text template, so it has no line editor; toggle it on or off like the others.

Open menu -> Edit book detail view to toggle each section on or off. Tap a section's row (when its toggle is on) to open the line editor.

Edits live-update the hero behind the editor on every keystroke; only the right column of the card is rebuilt, so the cover stays untouched.

Editor buttons

Button	What it does
Bold	Toggle bold weight
Size	-5 / -1 / +1 / +5 nudge over the font size (range 8-48 px)
Font	Font family picker
Aa / AA	Case toggle (hidden on Description)
L / C / R	Alignment cycle (left / centre / right)
Bar style	(Progress only) Cycle inline progress-bar styles
+ Bar / - Bar	(Progress only) Insert or remove the `%bar` token in the template
Bar height	(Progress only) Nudge the inline bar's height (% of text height)
Tokens…	Categorised token catalogue with live preview
Icons…	Insert icon glyphs from the built-in icon library (searchable glyph grid)
Default	Reset this section's template and styling to defaults
Cancel	Revert and close
Save	Persist and close

Bookends extras

Several editor surfaces use the Bookends plugin when it's installed. Everything degrades gracefully when it isn't:

Surface	With Bookends	Without
Token picker	Modal with shelves, search, live preview	Plain Menu over the token catalogue
Font picker	Each family rendered in its own typeface, weight variants deduped	Plain Menu over the system font list
Progress-bar styles	7 styles (`bordered`, `solid`, `rounded`, `metro`, `wavy`, `radial`, `radial_hollow`)	2 styles (`bordered`, `solid`)

The icon picker is built in and needs no extra plugins.

Token cheatsheet

Tokens are placeholders prefixed with %. Conditional logic uses [if:cond]…[/if] (with optional [else]).

Book metadata

Token	Example
`%title`	The Great Gatsby
`%author`	F. Scott Fitzgerald (first author)
`%author_2` / `%author_3`	second / third author (empty if absent)
`%authors`	Neil Gaiman, Terry Pratchett (all authors)
`%author_count`	2 (number of authors)
`%authors_short`	first author, or A and B, or A, B, et al. for three or more
`%genres`	Science Fiction, Classics (all genres, what calibre calls tags)
`%genre`	Science Fiction (first genre)
`%series` / `%series_name`	Dune
`%series_num`	1
`%rating`	★★★☆☆ (empty when unrated)
`%rating_number`	3 (1-5, empty when unrated)
`%hardcover_rating`	4.5 (cached Hardcover rating, empty when unavailable)
`%hardcover_stars`	Cached Hardcover rating as star glyphs
`%status`	reading (unread / reading / on_hold / finished)
`%status_label`	Reading (the status as a readable label)
`%favourite`	Favourite icon (empty when not a favourite)
`%size`	2.2 MB (file size)
`%added`	Date the file was added to the library
`%opened`	Date the book was last opened
`%calibre{name}`	Any Calibre column by lookup name -- custom columns included: a column `#mood` renders with `%calibre{mood}`. Also `%calibre{pubdate}` (publication year) and `%calibre{publisher}`. Needs the calibre metadata beta; dates show as the year; long-text columns excluded.
`%filename`	The_Great_Gatsby
`%format`	EPUB
`%lang`	en
`%description`	Book blurb (HTML stripped, entities decoded)
`%total_read_time`	Lifetime reading time across every book
`%books_finished`	Books finished; the same count as `%books_read`, under bookends' name
`%pages_today` / `%time_today`	Pages and time read today, across all books (needs the statistics plugin)
`%avg_page_time`	Average time per page for this book
`%highlights` / `%notes` / `%bookmarks`	Counts from the book's own annotations
`%annotations`	All three added together
`%quote`	A random highlight from this book, in quotation marks (a fresh one each time you select the book; empty if the book has no highlights). Handy in the Description section in place of the blurb.
`%quote_source`	The book and author for `%quote`

Position and progress

Token	Example
`%page_num` / `%page_count`	42 / 218
`%pages_left`	176
`%book_pct` / `%book_pct_left`	19% / 81%
`%book_pct_read`	44% (how much you have actually read, not where you are)
`%bar`	Inline progress-bar widget (Progress section only)
`%bar{rel}`	Same bar, but its length reflects how long the book is
`%spacer`	Elastic gap that pushes content left/right. `Reading%spacer47%` renders Reading on the left and 47% on the right.

Statistics (requires the `statistics` plugin)

Token	Example
`%book_time_left`	3h 45m
`%book_read_time`	2h 30m
`%book_pages_read`	142
`%days_reading_book`	7
`%pages_per_day`	12
`%speed`	42 (pages per hour)

Statistics tokens auto-hide when the plugin is absent or the book has no recorded reading time.

Library

Token	Example
`%books_read`	13 (books in your whole library marked Finished)
`%books_started`	Books with any reading time recorded by the statistics plugin

These are library-wide rather than per-book, so they suit the hero status line and micro-modules.

Time and date

Token	Example
`%time` / `%time_24h`	14:35
`%time_12h`	2:35 pm
`%date` / `%date_long` / `%date_numeric`	3 May / 3 May 2026 / 03/05/2026
`%weekday` / `%weekday_short`	Monday / Mon
`%datetime{%H:%M}`	Custom `os.date` format

Device

Token	Example
`%batt` / `%batt_icon`	73% / charge-aware glyph
`%wifi_icon`	Wi-Fi icon (connected / disconnected)
`%light` / `%light_pct` / `%light_icon`	18 (or OFF) / 75% / lightbulb glyph
`%warmth`	Frontlight warmth on the device's own scale, 12 (0-24 on Kindle, varies by device; natural-light only)
`%warmth_pct` / `%warmth_icon`	50% / thermometer glyph, three steps (natural-light only)
`%nightmode`	Moon glyph when night mode is on, sun otherwise
`%mem` / `%ram`	System memory (%) / KOReader RSS, 84M
`%sysused`	System memory used (MiB)
`%disk`	Free space on the books partition (GB)

Conditionals

[if:book_time_left]%book_time_left LEFT[else]Open to start reading[/if]
[if:lang!=en]Lang: %lang\n[/if]%description
[if:batt<20]LOW BATTERY %batt[/if]
[if:not series]Standalone[/if]
[if:connected]%wifi_icon[/if]
%time_12h[if:full_width]   ·   %date[/if]

Comparisons: = != < > <= >=. Boolean: and, or, not. Numeric tokens compare numerically; string tokens compare by string equality. The connected condition is true only while actually online, so [if:connected]%wifi_icon[/if] shows the Wi-Fi glyph just when connected. The full_width condition is true only in the wide status line of the micro-module and full-screen views (not the narrow cover-view status), so you can surface extra content -- a date, say -- only where there's room for it.

Delimited tokens

A token name runs until the next non-letter, so text placed straight after it is read as part of the name -- %author followed by an s becomes %authors and prints every author. Wrap the name in angle brackets to butt text directly against it:

%<author>s book        ->  Frank Herberts book
%<page_num>/%<page_count>  ->  42/500

This matches Bookends, so a line written for one works in the other.

Settings file (advanced)

Bookshelf stores its settings in a dedicated file alongside KOReader's other plugin data, separate from settings.reader.lua:

Platform	Path
Linux / dev	`~/.config/koreader/settings/bookshelf.lua`
Kindle	`/mnt/us/koreader/settings/bookshelf.lua`
Kobo	`/mnt/onboard/.adds/koreader/settings/bookshelf.lua`
Android	`<koreader-dir>/settings/bookshelf.lua`

Existing v1 settings migrate automatically on first launch -- legacy keys are read from settings.reader.lua, copied across with the bookshelf_ prefix stripped, and removed from the global file.

Selected keys

Key	Shape
`tabs`	Ordered list of shelf records (id, label, icon, source, filter, sort_priority, enabled).
`hero_regions`	Per-section overrides (sparse). One entry per section (status / rating / title / author / metadata / description / tags / progress) with any subset of template, font_face, font_size, bold, uppercase, alignment, disabled, bar_style, bar_height. The interactive tags section also takes per-category toggles (show_author / show_series / show_collections / show_genres / show_folder) plus font_size and alignment.
`font_scale`	Global zoom for hero text (50-200%).
`chip_font_scale`	Shelf menu font size (50-300%).
`chip_flex_widths`	Boolean. When true, longer-labelled shelves get more horizontal space than icon-only ones.
`active_chip` / `active_page` / `drill_path`	Persisted navigation state, restored on KOReader restart.
`progress_bar_enabled` / `progress_bookmark_enabled` / `progress_badge_enabled` / `progress_page_count_enabled`	Cover indicator toggles.
`show_series_num`	"always" / "in_series" / "never".
`progress_fill` / `progress_track` / `bookmark_color` / `complete_bookmark_color` / `favorite_star_color` / `badge_fg` / `badge_bg` / `border_color` / `folder_overlay_bg` / `folder_overlay_fg`	Cover-chrome colours (% black). Each also has a `_night` variant for the night-mode palette; unset keys fall back to per-mode defaults.
`author_format`	`"auto"` / `"first_last"` / `"last_first"` -- author name display.
`bookshelf_ui_font`	Chosen Bookshelf interface font (a resolvable font face). Absent = follow KOReader's UI font.
`cover_cache_mb`	Memory budget (MB) for the scaled-cover cache (default 24). The legacy `cover_cache_size` count key is discarded on first load.
`hardcover_links` / `hardcover_enrichment` / `hardcover_ratings` / `hardcover_reviews`	Optional Hardcover link and cached description/cover/rating/review metadata used by the Hardcover enrichment menu.
`hardcover_hero_rating`	Show cached Hardcover ratings in the hero rating row instead of KOReader's local rating.
`hardcover_use_metadata`	Use Hardcover's title/author/series/genres for linked books in place of their own.
`hardcover_max_genres`	How many of a linked book's Hardcover genres to use (when `hardcover_use_metadata` is on).
`calibre_metadata`	BETA. Read metadata from `metadata.calibre` if present.
`search_view_mode`	How search results display: absent = covers, `"list"`, or `"auto"`. Set by long-pressing the Search results pill.
`latest_walk_depth`	How deep the Latest source scans your library.
`show_close_msg`	Show the centred "Closing book…" toast when exiting a book.
`hot_park`	Instant book close: leave the book open in the background and finish closing it at the next quiet moment. Default on.
`open_cover_effect`	Play the cover-opening flex when launching a book. Default on.
`shelf_page_animation` / `start_menu_animation`	Wipe-animation speed (`off` / `fast` / `medium` / `slow`) for shelf/shelf paging and for the start menu, set independently. E-ink only.
`true_cover_aspect`	Render covers at their real shape instead of a uniform rectangle. Default off.
`dev_branch` / `last_install_source` / `check_updates`	Updater state.
`start_menu_items`	The start menu tree: an ordered list of entries (actions, plugin launchers, folders with children, and micro-modules).
`start_menu_position`	`"left"` / `"right"` / `"off"` -- where the start-menu button sits in the footer.
`start_menu_seeded` / `start_menu_next_id`	One-shot seed flag for the default menu, and the counter behind generated entry ids.
`micromodule_<key>_*`	Per-micro-module settings (e.g. `micromodule_clock_format`, `micromodule_random_unread_source`). Each module owns its own keys.
`migrated`	One-shot flag; presence indicates v1 -> v2 migration has run.

Known limitations

%bar styling lives in the Progress section. Inserting %bar in another section still renders the widget, but uses the bordered default style and 100% height since the Bar style / Bar height buttons only appear in the Progress section's editor.
Italic is reachable only via the font picker (by selecting an italic family). The line editor has no italic toggle because TextBoxWidget doesn't synthesise italic from upright fonts.
Inline format tags render in list view lines only: [b], [i], [font=NAME] and [size=N] (also [size=+N] / [size=-N], relative to the enclosing run). [u] is accepted but draws nothing. Hero card sections strip all of them, so use that section's own Bold button there.
Page count for EPUBs requires opening the book at least once. The count comes from KOReader's pagemap or reading statistics, both of which are populated only after the first paginate.

License

AGPL-3.0 -- see LICENSE

Footagesus/WindUI

WindUI is a open source UI library for Roblox Script Hubs

https://footagesus.github.io/treehub-web/docs/windui

Warning

This WindUI was not inspired by, and the name has nothing to do with UI Frameworks

Warning

WindUI is currently in Beta. This project is still under active development. Bugs, issues, and unstable features may occur. We’re constantly working on improvements, so please be patient and report any problems you encounter.

Credits

Icons (https://github.com/Footagesus/Icons)

Links

Discord Server
Documentation
Installation

Example (wip)

loadstring(game:HttpGet('https://raw.githubusercontent.com/Footagesus/WindUI/refs/heads/main/main_example.lua'))()

finlater/weread.koplugin

微信读书 koreader 插件，在 koreader 里阅读微信读书里的书籍、公众号文章，支持阅读进度同步，阅读时长上报和统计，本地书籍支持获取微信读书划线和想法内容，支持Kindle、Kobo等设备。

WeRead KOReader Plugin

免责声明：本项目仅供个人学习和技术研究使用，不得用于商业用途。使用本项目所产生的一切后果（包括但不限于账号封禁、数据丢失等）由使用者自行承担，项目作者概不负责。请遵守微信读书的用户协议和相关法律法规。

在 KOReader 上阅读微信读书中的书籍、公众号文章的插件。支持同步进度同步，阅读时长同步和统计，查看书评、划线和想法。让Kindle、Kobo等封闭系统设备也能体验微信读书！

安装

⚠️ 建议使用 KOReader 2026.03 或更高版本。旧版本可能无法正常加载或使用插件，例如「工具」菜单中找不到「微信读书」。详见 #14。

前往 GitHub Releases 下载最新的 weread.koplugin-vX.Y.Z.zip 安装包。
解压安装包，得到 weread.koplugin 文件夹。
将该文件夹复制到 KOReader 的 plugins 目录：

koreader/plugins/weread.koplugin/

重启 KOReader，在菜单中找到：

工具 → 微信读书

后续更新插件可在 微信读书 → 设置 → 更新管理 菜单中在线更新。

登录与认证

插件只支持微信扫码登录，扫码前需要先为账号开通微信读书 Skill：

手机打开微信读书 App。
进入 我 → 设置 → 微信读书 Skill。
点击 获取 API Key，确认已经生成个人官方 API Key。
在 KOReader 打开 工具 → 微信读书 → 微信扫码登录。
使用微信扫码并在手机端确认；若手机显示四位验证码，请在 KOReader 中输入。

功能

主菜单	书架	公众号

阅读时间上报	阅读统计	阅读进度同步

多选章节下载	章节预下载	下载全书

书籍详情	书评	划线和想法

搜索书籍	快捷菜单	设置

SimpleUI / Zen_UI 集成

插件提供统一的“微信读书书架”入口并支持集成到 SimpleUI和 ZenUI的快捷按钮中。(需要安装最新版 SimpleUI 和 ZenUI插件)。

SimpleUI：进入 快捷操作 新建操作，类型选择 插件 → 微信读书，再把该操作加入底部栏即可。如需使用本项目图标，将 icons/weread-w-book.svg 或 icons/weread-ink.png 复制到 SimpleUI 的自定义图标目录koreader/setting/simpleui/sui_icons后，在快捷操作中选中它。
Zen_UI 底栏：进入 控件 → 按钮 → ➕ → 插件 → 微信读书，点击后直接打开微信读书书架。注册时会把 weread-w-book.svg 同步到 KOReader 用户图标目录，供 ZenUI 自动匹配或手动选择；不会自动修改、添加或启用 Tab。
Zen_UI 首页：进入 主页 → 小组件，启用“微信读书”组件。组件默认关闭，可由用户自行排序。

原生 KOReader 的 “工具 → 微信读书” 菜单保持不变。

SimpleUI	Zen_UI

菜单结构

微信读书
├── 微信扫码登录 / 已经登录 · 账号名
├── 立即同步进度       （阅读微信读书缓存书籍时显示）
├── 书籍详情           （阅读微信读书缓存书籍时显示）
├── 显示划线和想法     （阅读书籍时显示，开关）
├── 划线和想法管理     （本地书与微信下载书共用；不修改 EPUB/KOReader 笔记）
│   ├── 匹配微信读书书目 / 已关联微信书籍：书名（下载书自动关联）
│   ├── 继续匹配（显示完成章节和划线条数）
│   ├── 选择章节匹配（树状目录、父子联动多选）
│   └── 清理划线和想法（再次匹配时下载最新数据）
├── 书架               书籍 / 公众号 Tab；书架内搜索、离线缓存、手动更新
├── weread收藏夹        已下载书籍（不包含单章）的本地入口
├── 搜索               搜索微信读书
├── 阅读时间上报        后台上报阅读时长
│   ├── 启用阅读时间上报
│   ├── 仅在阅读时上报
│   ├── 选择目标书籍
│   │   ├── 自动关联微信读书书籍
│   │   └── 手动设置上报书籍
│   └── 上报状态
├── 阅读统计            阅读时长/天数/排行/偏好可视化（页内 周/月/年/总 tab 切换，可翻阅历史周期）
├── 设置
│   ├── 书架视图
│   │   ├── 列表模式（默认；适合连续滚动）
│   │   └── 封面模式（按屏幕自适应行列；仅加载当前页封面）
│   ├── 分页书架（仅列表模式；默认开启，关闭后使用连续滚动）
│   ├── 缓存管理
│   │   ├── 扫描并关联本地书籍
│   │   ├── 缓存清理
│   │   └── 缓存目录
│   ├── 进度管理
│   │   ├── 打开时拉取进度（默认关闭）
│   │   └── 关闭时上传进度（默认关闭）
│   ├── 下载设置
│   │   ├── 书籍图片（默认开启）
│   │   ├── 公众号文章图片（默认关闭）
│   │   ├── 隐藏脚注文本（默认关闭；开启需同时启用 KOReader 脚注弹框；仅影响新下载书籍）
│   │   └── 章节预下载
│   │       ├── 自动预下载下一章（默认关闭，开启时会确认网络卡顿风险）
│   │       ├── 预下载划线和想法（默认关闭，总开关关闭时不可操作）
│   │       └── 显示预下载提示（默认开启，总开关关闭时不可操作）
│   ├── 划线设置
│   │   ├── 划线边缘防误触（默认开启）
│   │   ├── 边缘区域：20%（可调 10%–40%）
│   │   └── 想法弹窗设置
│   │       ├── 位置：居中（可切换为 底部）
│   │       ├── 高度：62%（可调 20%–90%）
│   │       ├── 宽度：80%（仅居中时可用，40%–100%）
│   │       ├── 字体大小（相对文档字号，默认 -2；可切换为绝对字号）
│   │       ├── 字体对比度：默认（可调 -3–+9，最大为纯黑）
│   │       └── 点击左右区域翻页（默认关闭，底部与居中弹窗均生效）
│   │   └── 想法弹窗宽度：80%（仅居中时可用，40%–100%）
│   ├── 账号管理
│   │   ├── 账号状态
│   │   ├── 立即续期 Cookie
│   │   └── 清除账号数据
│   └── 关于
│       ├── 版本 x.y.z
│       ├── 作者：finlater
│       ├── 检查更新
│       ├── 每天自动检查一次（默认关闭）
│       └── 更新时优先使用代理（默认开启；代理失败会自动回退 GitHub）

贡献

欢迎提交 issue 和 PR。提交前请阅读 CONTRIBUTING.md。

XPointer 外部标注层仍是实验性功能，测试步骤和限制见原型说明。

许可证

本项目代码采用 GNU Affero General Public License v3.0，SPDX 标识为 AGPL-3.0-only，与 KOReader 使用的许可证保持一致。

修改、整合或再分发本项目时，必须遵守 AGPL-3.0，保留版权和许可证声明，并按许可证要求将本项目代码或其衍生作品开源。

fonts/NotoEmoji-Regular.ttf 是第三方字体，采用 SIL Open Font License 1.1，不适用本项目的 AGPL-3.0。

项目推荐

插件	简介
kindlebtcontroller.koplugin	蓝牙手柄/遥控器控制 Kindle —— 翻页、调节亮度、章节跳转等 20+ 操作，按键完全可自定义。
one.koplugin	在 KOReader 上离线阅读「ONE · 一个」每日更新：一图、一文、一问答。

nickjvandyke/opencode.nvim

Neovim 🤝 OpenCode in the flow that you already know.

opencode.nvim

Neovim plugin that integrates with OpenCode to keep you in the flow that you already know.

https://github.com/user-attachments/assets/e85e021c-fa8f-466e-830c-c667b28f611e

⭐ Motivation

AI works best at small, focused scopes — as a pair programmer with the human driving. You stay in control, craft the code that matters, and keep your skills sharp. opencode.nvim just provides the context and connection to make that pairing seamless.

Rather than introduce yet another interaction model, opencode.nvim leverages OpenCode's existing TUI and API via standard Neovim interfaces. You keep your environment, your config, your flow.

For me, the best tools are the ones that "just work." opencode.nvim is designed to be one of them.

✨ Features

Connect to any OpenCode server, or start an integrated instance
Inject editor context (cursor, selection, buffer, etc.)
Input prompts with completions and highlights
Select from built-in and custom prompts
Execute OpenCode commands
Accept/reject and reload OpenCode edits
Handle OpenCode events as autocmds
Simple, sensible, Vim-y defaults and interfaces

📦 Setup

vim.pack (recommended)

vim.pack.add({
  {
    src = "https://github.com/nickjvandyke/opencode.nvim",
    version = vim.version.range("*"), -- Latest stable release
  },
})

---@type opencode.Opts
vim.g.opencode_opts = {
  -- Your configuration, if any; goto definition on the type for details
}

-- Recommended/example keymaps
vim.keymap.set({ "n", "x" }, "<C-a>",   function() require("opencode").ask("@this: ") end,                    { desc = "Ask OpenCode…" })
vim.keymap.set({ "n", "x" }, "<C-x>",   function() require("opencode").select() end,                          { desc = "Select OpenCode…" })
vim.keymap.set({ "n", "x" }, "go",      function() return require("opencode").operator("@this ") end,         { desc = "Append range to OpenCode", expr = true })
vim.keymap.set({ "n" },      "goo",     function() return require("opencode").operator("@this ") .. "_" end,  { desc = "Append line to OpenCode", expr = true })
vim.keymap.set({ "n" },      "<S-C-u>", function() require("opencode").command("session.half.page.up") end,   { desc = "Scroll OpenCode up" })
vim.keymap.set({ "n" },      "<S-C-d>", function() require("opencode").command("session.half.page.down") end, { desc = "Scroll OpenCode down" })

lazy.nvim

{
  "nickjvandyke/opencode.nvim",
  version = "*", -- Latest stable release
  config = function()
    ---@type opencode.Opts
    vim.g.opencode_opts = {
      -- Your configuration, if any; goto definition on the type for details
    }

    -- Recommended/example keymaps
    vim.keymap.set({ "n", "x" }, "<C-a>",   function() require("opencode").ask("@this: ") end,                    { desc = "Ask OpenCode…" })
    vim.keymap.set({ "n", "x" }, "<C-x>",   function() require("opencode").select() end,                          { desc = "Select OpenCode…" })
    vim.keymap.set({ "n", "x" }, "go",      function() return require("opencode").operator("@this ") end,         { desc = "Append range to OpenCode", expr = true })
    vim.keymap.set({ "n" },      "goo",     function() return require("opencode").operator("@this ") .. "_" end,  { desc = "Append line to OpenCode", expr = true })
    vim.keymap.set({ "n" },      "<S-C-u>", function() require("opencode").command("session.half.page.up") end,   { desc = "Scroll OpenCode up" })
    vim.keymap.set({ "n" },      "<S-C-d>", function() require("opencode").command("session.half.page.down") end, { desc = "Scroll OpenCode down" })
  end,
}

nixvim

programs.nixvim = {
  extraPlugins = [
    pkgs.vimPlugins.opencode-nvim
  ];
};

Integrations

The below examples are specific, but generalize to other plugins.

snacks.nvim

require("snacks").setup({
  input = {
    enabled = true, -- Enhances Ask
  },
  picker = {
    enabled = true, -- Enhances Select
    win = {
      input = {
        keys = {
          ["<a-o>"] = { "opencode_send", mode = { "n", "i" } },
        },
      },
    },
    actions = {
      opencode_send = function(picker) ---@param picker snacks.Picker
        local items = vim.tbl_map(function(item) ---@param item snacks.picker.Item
          return item.file
            and require("opencode").format({ path = item.file, from = item.pos, to = item.end_pos })
            or item.text
        end, picker:selected({ fallback = true }))

        require("opencode").prompt(table.concat(items, ", ") .. " ")
      end,
    },
  },
})

blink.cmp

-- Configure blink.cmp to show completions in Ask from opencode.nvim's in-process LSP.
-- Only applicable when using snacks.input.
require("blink.cmp").setup({
  sources = {
    -- Either enable LSP (and optionally buffer) source globally
    default = { 'lsp', 'buffer' },
    -- Or only for Ask
    per_filetype = {
      opencode_ask = { 'lsp', 'buffer' },
    },
    -- Display buffer completions (if included above) when no LSP completions are available
    providers = { lsp = { fallbacks = {} } },
  },
})

lualine.nvim

require("lualine").setup({
  sections = {
    lualine_z = {
      {
        -- Show the currently connected server and its status
        require("opencode").statusline,
      },
    },
  },
})

Tip

Run :checkhealth opencode after setup.

⚙️ Configuration

opencode.nvim provides a rich and reliable default experience — see all available options and their defaults here.

Contexts

opencode.nvim replaces placeholders in prompts with the corresponding context:

Placeholder	Context
`@this`	Range or selection if any, else cursor position
`@buffer`	Current buffer
`@buffers`	Open buffers
`@diagnostics`	Diagnostics within the range or selection if any, else in the current buffer
`@marks`	Global marks
`@quickfix`	Quickfix list
`@visible`	Visible text

Tip

OpenCode reads referenced files from disk — save your changes!

Prompts

Select prompts to review, explain, and improve your code:

Name	Prompt
`diagnostics`	Explain `@diagnostics`
`document`	Add comments documenting `@this`
`explain`	Explain `@this` and its context
`fix`	Fix `@diagnostics`
`implement`	Implement `@this`
`optimize`	Optimize `@this` for performance and readability
`review`	Review `@this` for correctness and readability
`test`	Add tests for `@this`

Server

Run opencode locally however you like and opencode.nvim will find them! Or point vim.g.opencode_opts.server.url to a specific server, including remotes.

Important

You must run opencode with the --port flag to expose its server.

If opencode.nvim can't find a running opencode, it starts one via vim.g.opencode_opts.server.start, defaulting to term://opencode --port.

Start via snacks.terminal

local opencode_cmd = 'opencode --port'
---@type snacks.terminal.Opts
local snacks_terminal_opts = {
  win = {
    position = 'right',
    enter = false,
  },
}

---@type opencode.Opts
vim.g.opencode_opts = {
  server = {
    start = function()
      require('snacks.terminal').open(opencode_cmd, snacks_terminal_opts)
    end,
  },
}

-- Can also leverage toggle functionality.
-- If you use <leader> here, remove 't' — otherwise Neovim will add input delay to your <leader> when typing in the terminal to watch for the mapping.
vim.keymap.set({ 'n', 't' }, '<C-.>', function()
  require('snacks.terminal').toggle(opencode_cmd, snacks_terminal_opts)
end, { desc = 'Toggle OpenCode' })

-- Optionally show upon submitting prompt
vim.api.nvim_create_autocmd('User', {
  pattern = { 'OpencodeEvent:tui.command.execute' },
  callback = function(args)
    ---@type opencode.server.Event
    local event = args.data.event
    if event.properties.command == 'prompt.submit' then
      local win = require('snacks.terminal').get(opencode_cmd, { create = false })
      if win then
        win:show()
      end
    end
  end,
})

opencode.nvim prioritizes focused pairing with a single OpenCode instance. As such, it connects to an OpenCode server before interacting with it, listening for events and targeting it for future interactions. Consider disabling vim.g.opencode_opts.server.connect if you frequently jump between servers or don't care for disruptive synchronous events like permission requests.

🚀 Usage

Ask — `require("opencode").ask()`

Input a prompt for OpenCode.

Passes the text to Prompt.
Press <Up> to browse recent asks.
Highlights and completes contexts and OpenCode subagents.
- Press <Tab> to trigger built-in completion.
- Provided by in-process LSP when using snacks.input.

Select — `require("opencode").select()`

Select from all opencode.nvim functionality.

Prompts
Commands
Servers

Highlights and previews items when using snacks.picker.

Prompt — `require("opencode").prompt()`

Prompt OpenCode.

Injects configured contexts.
Trailing space appends; trailing "..." opens in Ask.
OpenCode will interpret references to files or subagents.

Operator — `require("opencode").operator()`

Wraps Prompt as an operator, supporting ranges and dot-repeat.

Command — `require("opencode").command()`

Command OpenCode:

Command	Description
`agent.cycle`	Cycle selected agent
`prompt.clear`	Clear current prompt
`prompt.submit`	Submit current prompt
`session.compact`	Compact current session
`session.first`	Jump to first message in session
`session.half.page.up`	Scroll messages up half a page
`session.half.page.down`	Scroll messages down half a page
`session.interrupt`	Interrupt current session
`session.last`	Jump to last message in current session
`session.new`	Start new session
`session.page.up`	Scroll messages up one page
`session.page.down`	Scroll messages down one page
`session.select`	Select session
`session.share`	Share current session
`session.redo`	Redo last undone action in current session
`session.undo`	Undo last action in current session

👀 Events

opencode.nvim forwards the connected OpenCode's Server-Sent-Events as an OpencodeEvent autocmd:

-- Handle OpenCode events
vim.api.nvim_create_autocmd("User", {
  pattern = "OpencodeEvent:*", -- Optionally filter event types
  callback = function(args)
    ---@type opencode.server.Event
    local event = args.data.event
    ---@type string
    local url = args.data.url

    -- See the available event types and their properties
    vim.notify(vim.inspect(event))
    -- Do something useful
    if event.type == "session.status" then
      vim.notify("OpenCode status updated: " .. event.properties.status.type)
    end
  end,
})

Note

Event payloads are passed through from the OpenCode as-is and follow its schema. They may change with OpenCode releases, so treat them as best-effort rather than a stable API contract.

Edits

When the connected OpenCode edits a file, opencode.nvim reloads the corresponding buffer in real-time. vim.o.autoread = true is set automatically to enable this unless you've explicitly configured it.

Permissions

When the connected OpenCode requests a permission, opencode.nvim asks you to approve or deny it.

Edits

When the connected Opencode requests an edit, opencode.nvim opens the target file in a new tab and uses Neovim's :diffpatch to display the proposed changes side-by-side. See :h 'diffopt' for customization.

Keymap	Function
`da`	Accept the entire edit request
`dr`	Reject the entire edit request
`]c/[c`	Next/prev change
`dp`	Natively accept only the hunk under the cursor, and reject the edit request
`do`	Natively reject only the hunk under the cursor, and reject the edit request
`q`	Close the diff

lite-xl/lite-xl

A lightweight text editor written in Lua

https://lite-xl.com

Lite XL

A lightweight text editor written in Lua, adapted from lite.

Get Lite XL — Download for Windows, Linux and Mac OS.
Get plugins — Add additional functionality, adapted for Lite XL.
Get color themes — Add additional colors themes.

Please refer to our website for the user and developer documentation, including build instructions details. A quick build guide is described below.

Lite XL has support for high DPI display on Windows and Linux and, since 1.16.7 release, it supports retina displays on macOS.

Please note that Lite XL is compatible with lite for most plugins and all color themes. We provide a separate lite-xl-plugins repository for Lite XL, because in some cases some adaptations may be needed to make them work better with Lite XL. The repository with modified plugins is https://github.com/lite-xl/lite-xl-plugins.

The changes and differences between Lite XL and rxi/lite are listed in the changelog.

Overview

Lite XL is derived from lite. It is a lightweight text editor written mostly in Lua — it aims to provide something practical, pretty, small and fast easy to modify and extend, or to use without doing either.

The aim of Lite XL compared to lite is to be more user friendly, improve the quality of font rendering, and reduce CPU usage.

Customization

Additional functionality can be added through plugins which are available in the plugins repository or in the Lite XL plugins repository.

Additional color themes can be found in the colors repository. These color themes are bundled with all releases of Lite XL by default.

Quick Build Guide

To compile Lite XL yourself, you must have the following dependencies installed via your desired package manager, or manually.

Prerequisites

Meson (>=0.63)
Ninja
SDL2
PCRE2
FreeType2
Lua 5.4
A working C compiler (GCC / Clang / MSVC)

SDL2, PCRE2, FreeType2 and Lua will be downloaded by Meson if --wrap-mode=forcefallback or --wrap-mode=default is specified.

Note

MSVC is used in the CI, but MSVC-compiled binaries are not distributed officially or tested extensively for bugs.

On Linux, you may install the following dependencies for the SDL2 X11 and/or Wayland backend to work properly:

libX11-devel
libXi-devel
libXcursor-devel
libxkbcommon-devel
libXrandr-devel
wayland-devel
wayland-protocols-devel
dbus-devel
ibus-devel

The following command can be used to install the dependencies in Ubuntu:

apt-get install python3.8 python3-pip build-essential git cmake wayland-protocols libsdl2-dev
pip3 install meson ninja

Please refer to lite-xl-build-box for a working Linux build environment used to package official Lite XL releases.

On macOS, you must install bash via Brew, as the default bash version on macOS is antiquated and may not run the build script correctly.

Building

You can use scripts/build.sh to set up Lite XL and build it.

$ bash build.sh --help
# Usage: scripts/build.sh <OPTIONS>
# 
# Available options:
# 
# -b --builddir DIRNAME         Sets the name of the build directory (not path).
#                               Default: 'build-x86_64-linux'.
#    --debug                    Debug this script.
# -f --forcefallback            Force to build dependencies statically.
# -h --help                     Show this help and exit.
# -d --debug-build              Builds a debug build.
# -p --prefix PREFIX            Install directory prefix. Default: '/'.
# -B --bundle                   Create an App bundle (macOS only)
# -A --addons                   Add in addons
# -P --portable                 Create a portable binary package.
# -r --reconfigure              Tries to reuse the meson build directory, if possible.
#                               Default: Deletes the build directory and recreates it.
# -O --pgo                      Use profile guided optimizations (pgo).
#                               macOS: disabled when used with --bundle,
#                               Windows: Implicit being the only option.
#    --cross-platform PLATFORM  Cross compile for this platform.
#                               The script will find the appropriate
#                               cross file in 'resources/cross'.
#    --cross-arch ARCH          Cross compile for this architecture.
#                               The script will find the appropriate
#                               cross file in 'resources/cross'.
#    --cross-file CROSS_FILE    Cross compile with the given cross file.

Alternatively, you can use the following commands to customize the build:

meson setup --buildtype=release --prefix <prefix> build
meson compile -C build
DESTDIR="$(pwd)/lite-xl" meson install --skip-subprojects -C build

where <prefix> might be one of /, /usr or /opt, the default is /. To build a bundle application on macOS:

meson setup --buildtype=release --Dbundle=true --prefix / build
meson compile -C build
DESTDIR="$(pwd)/Lite XL.app" meson install --skip-subprojects -C build

Please note that the package is relocatable to any prefix and the option prefix affects only the place where the application is actually installed.

Installing Prebuilt

Head over to releases and download the version for your operating system.

The prebuilt releases supports the following OSes:

Windows 7 and above
Ubuntu 18.04 and above (glibc 2.27 and above)
OS X El Capitan and above (version 10.11 and above)

Some distributions may provide custom binaries for their platforms.

Windows

Lite XL comes with installers on Windows for typical installations. Alternatively, we provide ZIP archives that you can download and extract anywhere and run directly.

To make Lite XL portable (e.g. running Lite XL from a thumb drive), simply create a user folder where lite-xl.exe is located. Lite XL will load and store all your configurations and plugins in the folder.

macOS

We provide DMG files for macOS. Simply drag the program into your Applications folder.

Important Newer versions of Lite XL are signed with a self-signed certificate, so you'll have to follow these steps when running Lite XL for the first time.

Find Lite XL in Finder (do not open it in Launchpad).

Control-click Lite XL, then choose Open from the shortcut menu.

Click Open in the popup menu.

The correct steps may vary between macOS versions, so you should refer to the macOS User Guide.

On an older version of Lite XL, you will need to run these commands instead:
# clears attributes from the directory
xattr -cr /Applications/Lite\ XL.app
Otherwise, macOS will display a very misleading error saying that the application is damaged.

Linux

Unzip the file and cd into the lite-xl directory:

tar -xzf <file>
cd lite-xl

To run lite-xl without installing:

./lite-xl

To install lite-xl copy files over into appropriate directories:

rm -rf  $HOME/.local/share/lite-xl $HOME/.local/bin/lite-xl
mkdir -p $HOME/.local/bin && cp lite-xl $HOME/.local/bin/
mkdir -p $HOME/.local/share/lite-xl && cp -r data/* $HOME/.local/share/lite-xl/

Add Lite XL to PATH

To run Lite XL from the command line, you must add it to PATH.

If $HOME/.local/bin is not in PATH:

echo -e 'export PATH=$PATH:$HOME/.local/bin' >> $HOME/.bashrc

Alternatively on recent versions of GNOME and KDE Plasma, you can add $HOME/.local/bin to PATH via ~/.config/environment.d/envvars.conf:

PATH=$HOME/.local/bin:$PATH

Note Some systems might not load .bashrc when logging in. This can cause problems with launching applications from the desktop / menu.

Add Lite XL to application launchers

To get the icon to show up in app launcher, you need to create a desktop entry and put it into /usr/share/applications or ~/.local/share/applications.

Here is an example for a desktop entry in ~/.local/share/applications/com.lite_xl.LiteXL.desktop, assuming Lite XL is in PATH:

[Desktop Entry]
Type=Application
Name=Lite XL
Comment=A lightweight text editor written in Lua
Exec=lite-xl %F
Icon=lite-xl
Terminal=false
StartupWMClass=lite-xl
Categories=Development;IDE;
MimeType=text/plain;inode/directory;

To get the icon to show up in app launcher immediately, run:

xdg-desktop-menu forceupdate

Alternatively, you may log out and log in again.

Uninstall

To uninstall Lite XL, run:

rm -f $HOME/.local/bin/lite-xl
rm -rf $HOME/.local/share/icons/hicolor/scalable/apps/lite-xl.svg \
          $HOME/.local/share/applications/com.lite_xl.LiteXL.desktop \
          $HOME/.local/share/metainfo/com.lite_xl.LiteXL.appdata.xml \
          $HOME/.local/share/lite-xl

Contributing

Any additional functionality that can be added through a plugin should be done as a plugin, after which a pull request to the Lite XL plugins repository can be made.

Pull requests to improve or modify the editor itself are welcome. See CONTRIBUTING.md for more details.

Licenses

This project is free software; you can redistribute it and/or modify it under the terms of the MIT license. See LICENSE for details.

See the licenses file for details on licenses used by the required dependencies.

bol-van/zapret-win-bundle

zapret and blockcheck binary bundle for windows

zapret winws bundle for windows

main zapret1 repository

main zapret2 repository

requirements :

Windows 7 x64, Windows server 2008 R2 (ESU updates or windivert files replacement required)
Windows 8+ x64, Windows server 2012+ (may require to disable secure boot)
Windows 11+ ARM64, Windows server 2025+ (requires testsigning mode)
Windows Server requires installing of wireless networking feature

Что это

Сборка, обьединяющая zapret1 и zapret2 под windows, включающая в себя минимальный cygwin комплект и blockcheck.

Это не однокнопочное решение, готовых стратегий и кнопки "открыть сайты" нет. Нужно понимать как работает zapret, иначе бесполезно.

Краткое описание файлов

_CMD_ADMIN.cmd : открыть командную строку под администратором
winws.exe : главный компонент zapret, средство обхода DPI, версия nfqws для windows
winws2.exe : главный компонент zapret2, средство обхода DPI, версия nfqws2 для windows
preset1_example.cmd : интерактивный запуск стратегии-примера на базе winws (не является готовым лекарством)
preset2_example.cmd : интерактивный запуск стратегии-примера на базе winws2 (не является готовым лекарством)
preset2_wireguard.cmd : интерактивный запуск обхода блокировки wireguard протокола на любых портах
service*.cmd : установка и управление службой windows (режим неинтерактивного автозапуска). НЕ ЗАПУСКАТЬ БЕЗ РЕДАКТИРОВАНИЯ !
enable_timestamps.cmd : включить таймштампы tcp. по умолчанию отключены. требуются для ts fooling.
windivert_delete.cmd : остановить и удалить драйвер windivert
killall.exe : программа из cygwin для посылки unix сигналов winws
elevator.exe : запускает программы от имени администратора
cygwin\cygwin.cmd : запуск командной строки cygwin под текущим пользователем
cygwin\cygwin-admin.cmd : запуск командной строки cygwin под администратором
blockcheck\blockcheck.cmd : анализатор способов обхода DPI. Запускать только с остановленным zapret и другими средствами обхода DPI !
blockcheck\blockcheck-kyber.cmd : то же самое, но используется CURL с многопакетным TLS Client Hello
blockcheck\blockcheck2.cmd : анализатор способов обхода DPI на базе winws2. Запускать только с остановленным zapret и другими средствами обхода DPI !
blockcheck\blockcheck2-kyber.cmd : то же самое, но используется CURL с многопакетным TLS Client Hello

ARM64 подготовка

запустите arm64/install_arm64.cmd
перезагрузите систему, если режим testsigning не был включен ранее. надпись "тестовый режим" должна быть на рабочем столе справа внизу.

WIN7 подготовка

Если windivert не работает как есть запустите win7/install_win7.cmd. Или накатите обновления ESU.

АНТИВИРУСЫ

windivert может вызвать реакцию антивируса. windivert - это инструмент для перехвата и фильтрации трафика, необходимый для работы zapret. Замена iptables и NFQUEUE в Linux, которых нет под Windows. Он может использоваться как хорошими, так и плохими программами, но сам по себе не является вирусом. Драйвер windivert64.sys подписан для возможности загрузки в 64-битное ядро windows. Любой желающий может сравнить файлы с оригиналами от автора. Но антивирусы склонны относить подобное к классам повышенного риска или хакерским инструментам. В случае проблем используйте исключения или выключайте антивирус совсем.

What is it ?

Combined zapret1 and zapret2 compilation for windows with minimal cygwin and blockcheck.

This is not one-button solution to open sites. zapret understanding is required to use.

brief files description

_CMD_ADMIN.cmd : open command prompt as administrator
winws.exe : main zapret component, DPI bypass tool, nfqws version for windows
winws2.exe : main zapret2 component, DPI bypass tool, nfqws2 version for windows
preset1_example.cmd : run interactively example strategy using winws
preset2_example.cmd : run interactively example strategy using winws2
preset2_wireguard.cmd : run interactively wireguard protocol bypass
service*.cmd : windows service setup and control (non-interactive autostart mode)
enable_timestamps.cmd : enable tcp timestamps. they are disabled by default and required for ts fooling.
windivert_delete.cmd : stop and delete windivert driver
killall.exe : cygwin tool used in reload_lists.cmd. allows to send signals to winws.
elevator.exe : simple tool to run a program as admin
cygwin\cygwin.cmd : run cygwin prompt with current user privileges
cygwin\cygwin-admin.cmd : run cygwin prompts with administrator privileges
blockcheck\blockcheck.cmd : DPI bypass analyzer tool. Run only with zapret and other DPI bypass software stopped !
blockcheck\blockcheck-kyber.cmd : use CURL with multi-segment TLS Client Hello
blockcheck\blockcheck2.cmd : DPI bypass analyzer tool, winws2 based. Run only with zapret and other DPI bypass software stopped !
blockcheck\blockcheck2-kyber.cmd : use CURL with multi-segment TLS Client Hello

ARM64 preparation

run arm64/install_arm64.cmd
reboot if testsigning mode is not already enabled. "test mode" text should be present in the right bottom corner of the screen.

WIN7 preparation

If windivert cannot start as is run win7/install_win7.cmd. Or install ESU updates.

ANTIVIRUS WARNING

windivert may cause antivirus reaction. It's not a virus, your antivirus is insane. It can treat windivert as potential risk or hacker instrument. Use exceptions or disable AV completely if you are affected.

BeamMP/BeamMP

Bringing multiplayer to BeamNG.drive

https://beammp.com

BeamMP

A Lua mod bringing online multiplayer to BeamNG.drive!

Important Links

Documentation
Discord
Website
Docs
Forum
#beammp on irc.libera.chat (webchat link)

Installation

Click here for a step-by-step guide on how to install the mod on Windows.

The BeamMP mod has been made as simple as it gets. Just head over to our website (BeamMP.com) and click download. This will download a zip file which contains the installer exe. Just run that exe and follow the instructions. Once this completes all you need to do is double click the shortcut on your desktop.

Now you can play by clicking "Play" and then "Multiplayer", logging in with either a guest account or a BeamMP Forum account. Then just select a server to play on! That's it! 😃

If you need help at any point, see the troubleshooting section. There are instructions there on how to get support from our dedicated support team.

Servers

Click here for a step-by-step guide on how to set up and run a server for you & your friends.

The server is usable free of charge for non-commercial use, and the source code is available on GitHub.

Please check out docs.beammp.com for a guide on how to setup your own server. If you run into issues, join the official Discord or join us via IRC in #beammp on irc.libera.chat (webchat link).

How does it work?

This section is a technical explanation of the inner workings of the project and is not relevant for most players.

The Launcher is a separate program which starts the game and connects to the Lua mod right away. The launcher then connects to a remote server of your choice, and these two communicate. The launcher then forwards some packets to the game, like car positions, rotations, chat messages, etc.

For more information on how the launcher and server operate, you can read the source code (C++) in their respective repositories:

Roadmap

You can see and keep track of development, planned features, etc. Here or on the GitHub Issues section of each repository.

Additionally, you can join the Discord, where regular updates are posted! Also there is our community Forum, where we post additional details.

Troubleshooting

If none of these fix your issue, we have a dedicated support team on our Discord, and our Forum

Support

The BeamMP project is supported by community donations via our Patreon This brings perks such as Patreon-only channels on our Discord, Early access to new updates, and more server keys.

Translations

BeamMP makes an effort to be maintained for multiple languages. The current progress of this sits at: We use GitLocalize for managing this. You can contribute if you wish here: https://gitlocalize.com/repo/9181.

The individual language progress is as follows:

Language	Badge
Catalan
Chinese
Czech
French
German
Japanese
Korean (South Korea)
Polish
Portuguese (Brazil)
Portuguese (Portugal)
Russian
Slovak
Spanish
Turkish

rittermod/FS25_RealisticLivestockRM

FS25_RealisticLivestock - Ritter version

https://discord.gg/KXFevNjknB

Note

My version of the awesome FS25 Realistic Livestock mod by Arrow-kb.

FS25 Realistic Livestock - Ritter version

Replaces FS25's simple animal clusters with individually tracked animals - each with unique genetics, breeding, diseases, and production traits. A maintained version of Arrow-kb's Realistic Livestock mod.

Every animal is tracked separately with its own identity, genetic makeup, health status, and production output. Genetics are inherited through breeding, diseases can spread and require treatment, and production is driven by each animal's individual traits. Everything is managed from the RL Menu - a dedicated tabbed interface for browsing, trading, moving, filtering, and automating your herds.

This is a maintained version of the original mod by Arrow-kb, who has discontinued development. The goal is to keep the mod working, fix bugs, and make improvements where needed. While less ambitious in scope than the original roadmap, this version focuses on stability and reliability.

User Documentation - Guides and per-species factsheets covering genetics, breeding, diseases, production, and settings.

Features

Individual animal tracking with unique identity (farm ID, unique ID, birthday)
Genetics system with heritable traits that affect production output
Genetics display in animal names with configurable detail level (average score or full trait breakdown)
Breeding and reproduction with pregnancy mechanics and genetic inheritance
AI insemination system with semen dewars
Disease simulation with infection, immunity, and treatment charged as a monthly fee
Animal monitoring to track individual animals over time
Weight system tied to genetics and feeding
Animal marking and castration
RL Menu: a standalone tabbed menu (default Right Shift + O, also opened from pens, dealers, and trailers) covering all animal management - animal browsing with pedigree/genetics/disease detail, moving, selling, buying, AI straw purchases, messages, and trailer loading/unloading
Saveable animal filters: build reusable filters in-game (age, gender, pregnancy, genetics, weight, health, and more) and cycle them with F across the menu tabs
Herdsman automation: named daily tasks (sell, buy, castrate, naming, AI insemination, move, horse care) driven by saved filters, with per-task caps, budgets, and a herdsman wage
Animal Country of Origin setting: choose the country new animals are registered in (ear tags, identifiers)
Dealer controls: choose which animals and age groups the dealer offers, and whether it stocks Budget, Standard or Premium quality animals
Daily summary mode for message log
In-game help pages covering monitors, pregnancy, production, weight, and genetics
Highland cattle bull support
Animal pack system: third-party mods can add new breeds or adjust animal balance
Map support: Hof Bergmann (ducks, geese, cats, rabbits, alpacas, quail) with automatic version-aware compatibility
Map support: Witcombe (UK breeds - Jersey, Gloucestershire Old Spot, Texel, Suffolk, Blue Faced Leicester, plus Hereford heritage profile) with automatic version-aware compatibility
Map support: Le Mechet (French breeds - Charolaise, Montbeliarde, Simmental, Vosgienne) with automatic version-aware compatibility
Simple support for butchers using Extended Production Point (EPP) mod
Mod compatibility checks at startup: hard-block dialog for incompatible mods, plus a dismissible warning tier for mods known to degrade gameplay
In-game warning when two map bridges or animal packs replace the same animal type's husbandry config (last-loaded wins; first one's animals can render as ghosts)
Mod compatibility bridges for foreign mods that overlap RLRM's hooks - currently coexists with Seasonal Wool Production (Argsy Gaming) without double wool output
Multiplayer support (server-authoritative)

Supported Maps & Packs

RLRM works on virtually any map out of the box. It does not need to be on a list. The maps below are special only because they add their own custom animal types or breeds, which need built-in support for those extras to get the full RLRM treatment (genetics, breeding, reproduction). On any other map, the standard animals just work.

Maps:

Hof Bergmann - ducks, geese, cats, rabbits, alpacas, quail with full breeding support
Witcombe - UK breeds (Jersey, Gloucestershire Old Spot, Texel, Suffolk, Blue Faced Leicester) with full breeding support; Hereford heritage profile
Le Mechet - French breeds (Charolaise, Montbeliarde, Simmental, Vosgienne) with full breeding support (NOT compatible with Cow Breeds Pack unless you use the latest development version - both replace the cow husbandry config)

Animal Packs:

Cow Breeds Pack for RLRM by ConGan98 - additional cattle breeds
Sheep Breeds Pack for RLRM by ConGan98 - additional sheep breeds

Notes

Based on Arrow-kb's Realistic Livestock mod (v1.2.0.5), released under GPL-3 license
Savegame data from Arrow-kb's original version is automatically migrated on first load
Font Library mod is no longer required (functionality has been inlined)
Incompatible with FS25_EnhancedLivestock, FS25_MoreVisualAnimals, and FS25_EnhancedAnimalSystem (use FS25_MoreVisualAnimalsRM instead of FS25_MoreVisualAnimals)

Installation

Place FS25_RealisticLivestockRM.zip in your mods folder.

Migrating from Arrow-kb's version: Remove FS25_RealisticLivestock.zip and FS25_FontLibrary.zip. Back up your savegame first, then load it - data migrates automatically.

Changelog

See the CHANGELOG for a detailed list of changes, fixes, and improvements in this version.

License

This mod is released under GPL-3 license. See the LICENSE file for details.

About reuse, modification and building upon the original Realistic Livestock mod by Arrow-kb

Note

TL;DR: The original Realistic Livestock mod by Arrow-kb is open source GPL-3 licensed. Anyone can freely use, modify, and redistribute it as long as they: give credit, keep the same GPL-3 license, and share their changes openly. No one can restrict reuse.

The original Realistic Livestock mod by Arrow-kb is released under GPL-3 license. This means that anyone are free to reuse and modify the mod (the work) as long as they comply with the terms of the GPL-3 license, which in short terms means, to the best of my understanding:

You are free to use, reuse, and modify the code/mod for any purpose.
You must provide attribution to the author(s) when you distribute reused/modified/built upon code.
You must release your own modified code/mod under the same GPL-3 license so others can build upon it too.
You must include a copy of the GPL-3 license with the mod.

This means that anyone can use, and build upon, any modification I make in this Ritter version of the Realistic Livestock mod without any prior consent or similar from me, as long as they too comply with the GPL-3 license terms, attibute me for the changes I have made AND release their modified code/mod under the same GPL-3 license for any changes/additions they have made.

It also means that anyone, including me, can reuse and build opon any changes made by others to the mod without any prior consent or similar from the authors of those modifications since their changes to the mod are also licensed under the same GPL-3.

Nobody can say, "No, this is my code, you can not reuse it". The GPL-3 license ensures that the code/mod and any mod built on it will always remain free and open for anyone to use, modify, and distribute under the same GPL-3 license terms. There might at some point a discussion about when is a mod no longer a "mod built on the original mod" but that is way over my paygrade.

And remember: Any vioation of this might not be intentional or malicious. People might simply not understand the implications of what they agreed to when they started building upon the mod with this license.

(I am not a OSS licensing lawyer, but most likeley neither are you. This is my understanding of the GPL-3 license as it applies to this mod. If you have QUALIFIED legal knowledge, and not armchair legal knowledge, that contradicts what I say here, please let me know.)

forest0xia/dota2bot-OpenHyperAI

A beta Dota2 Bot Script aims to provide better bot game experience

https://steamcommunity.com/sharedfiles/filedetails/?id=3246316298

Open Hyper AI (OHA) - Dota 2 Bot Scripts

The most feature-rich custom bot script for Dota 2. Play against bots that actually fight, farm, push, and use items intelligently.

To play: Create a Custom Lobby and select Local Host as the server location. Bots should have names ending with ".OHA" when installed correctly.

Steam Workshop | GitHub | Feature Requests

What Makes This Different

127 heroes supported on Patch 7.41/7.41a - including Largo, Kez, Ringmaster, Invoker, Techies, Meepo, Lone Druid, and more
Bots actually play the game - they lane, gank, push towers, defend, farm jungle, take Roshan, and use active items
Dynamic difficulty (FretBots mode) - bots get unfair bonuses that scale with difficulty for a real challenge
Bots communicate - they announce pushes, defends, Roshan, and respond to your pings with "On my way!" (in 4 languages)
10+ Game modes supported - All pick, Turbo, All random, Captain mode, 1v1 mid, All Random Deathmatch, etc.
Customizable everything - bot names, roles, hero picks, bans, item builds, skill builds, and more
AI Chatbot - bots chat like real (toxic) players (requires FretBots mode)
All roles supported - deterministic position 1-5 lane assignment

Quick Start

Subscribe on Steam Workshop
Create a Custom Lobby with Local Host server
Start the game - bots auto-pick and play

For FretBots mode (harder bots, neutral items, chatbot): Manual installation guide

In-Game Commands

Command	Description
`!pos X`	Swap your role with a bot (e.g., `!pos 2` for mid)
`!Xpos Y`	Reassign bot positions (e.g., `!3pos 5` = 3rd bot plays pos 5)
`!pick HERO`	Pick a hero (`!pick sniper`, or `/all !pick sniper` for enemy)
`!ban HERO`	Ban a hero from being picked
`!sp XX`	Set bot language (`en`, `zh`, `ru`, `ja`)

Use internal hero names if short names overlap (e.g., !pick npc_dota_hero_keeper_of_the_light). Batch commands work too: !pick io; !ban sniper.

Bot Roles & Positioning

Lobby slot order = position assignment (1-5):

Position	Lane
Pos 1 (Carry) + Pos 5 (Hard Support)	Safe Lane
Pos 2 (Mid)	Mid Lane
Pos 3 (Offlane) + Pos 4 (Soft Support)	Offlane

Customize picks, bans, and roles in Customize/general.lua.

Customization

What	Where
General settings (picks, bans, names, roles)	Customize/general.lua
Per-hero settings (items, skills)	Customize/hero/viper.lua
FretBots difficulty tuning	FretBots/SettingsDefault.lua

Permanent customization (survives Workshop updates): Copy the Customize folder to <Steam/steamapps/common/dota 2 beta/game/dota/scripts/vscripts/game/Customize>.

Game Modes

Supports most game modes (10+) . See full compatibility discussion.

Offline / LAN Play

You can start a bot game directly from the console without network or clicking UI buttons — useful for offline play, LAN parties, or quick testing. See play offline setup guide.

Developer Documentation

This project uses Claude Code for AI-assisted development. The CLAUDE.md file provides task-specific instructions for common operations like patch updates, hero fixes, and adding new heroes.

Key Docs

Document	Description
docs/ARCHITECTURE.md	Complete codebase architecture, file map, naming conventions, all systems explained
docs/PATCH_UPDATE_GUIDE.md	Step-by-step runbook for updating when a new Dota 2 patch drops
docs/BOT_API_REFERENCE.md	Comprehensive Valve bot scripting API reference with examples
CLAUDE.md	AI coding assistant guide - common tasks, rules, and workflows

Internal Name References

Dota 2 bot scripts use internal code names for heroes, items, and abilities. These are different from the display names you see in-game. When updating builds or fixing bugs, always verify against authoritative sources:

Resource	What It Contains
Liquipedia Cheats Page (Item Names)	Authoritative list of `item_*` internal names for all items including neutral items
d2vpkr npc_abilities.txt	All ability internal names and KV data
Dota 2 Patch Data API	Official patch notes in machine-readable format
Modifier Names (Valve Wiki)	`modifier_*` names for buff/debuff detection

Project Structure

root: <Steam/steamapps/common/dota 2 beta/game/dota/scripts/vscripts>
|
+-- bots/                  All bot Lua scripts
|   +-- hero_selection.lua     Hero picking/banning
|   +-- bot_generic.lua        Per-bot entry point
|   +-- ability_item_usage_generic.lua   Ability/item usage for all heroes
|   +-- item_purchase_generic.lua        Item purchase state machine
|   +-- mode_*_generic.lua     Mode scripts (farm, push, defend, roam, etc.)
|   +-- mode_assemble_generic.lua        Human ping response
|   |
|   +-- BotLib/            Per-hero builds (items, skills, ability logic)
|   |   +-- hero_axe.lua, hero_crystal_maiden.lua, ...
|   |
|   +-- FunLib/            Core libraries and utilities
|   |   +-- jmz_func.lua      Main utility library
|   |   +-- aba_item.lua      Item system
|   |   +-- aba_skill.lua     Skill/ability system
|   |   +-- aba_push.lua      Push logic
|   |   +-- aba_defend.lua    Defend logic
|   |   +-- localization.lua  Chat translations (en/zh/ru/ja)
|   |
|   +-- FretBots/          Enhanced difficulty mode
|   |   +-- SettingsDefault.lua    Difficulty tuning
|   |   +-- SettingsNeutralItemTable.lua   Neutral items + enchantments
|   |
|   +-- Customize/         User-editable settings
|       +-- general.lua    Team-level settings
|       +-- hero/          Per-hero overrides
|
+-- typescript/            TypeScript source for TS-generated Lua files
|   +-- bots/              TS versions (compiled to bots/ via tstl)
|   +-- post-process/      Post-compilation scripts
|
+-- game/                  Valve defaults + permanent customization location
|   +-- Customize/         Copy your Customize/ here to survive updates
|
+-- docs/                  Developer documentation
    +-- ARCHITECTURE.md
    +-- PATCH_UPDATE_GUIDE.md
    +-- BOT_API_REFERENCE.md

Contribute

Contributions welcome on GitHub
Custom item/skill builds don't need PRs - just tweak locally
Future development is in TypeScript for better maintainability
Open feature requests

What's Next

Current bot playstyle is limited by Valve's API. We need ML/LLM bots like OpenAI Five!
Planned improvements:
- Smarter laning, pushing, ganking
- Stronger spell casting (Invoker, Rubick, Morphling, etc.)
- Better support for bugged heroes (Dark Willow, IO, Lone Druid, Muerta, etc.)
- Full game mode support + ongoing patch fixes
Feedback to Valve Dota2 bot team

Useful Resources

Resource	Description
Dota2 AI Development Tutorial	Comprehensive guide by adamqqq
Valve Bot Scripting Intro	Official Valve documentation
Lua Bot APIs (moddota)	Community API docs
Liquipedia Cheats (Internal Names)	Item/hero/ability code names
npc_abilities.txt	Ability metadata
Enums & APIs (moddota)	Enum reference
Modifier Names	Buff/debuff modifier names

Support

Contribute on GitHub
Or buy me a coffee

Credits

Built on top of Valve's default bots + contributions from many talented authors:

New Beginner AI (dota2jmz@163.com)
Tinkering About (ryndrb)
Ranked Matchmaking AI (adamqqq)
fretbots (fretmute)
BOT Experiment (Furiospuppy)
ExtremePush (insraq)
And all other contributors who made bot games better

FrSkyRC/ETHOS-Feedback-Community

Feedback & suggestions are welcomed here for ETHOS by FrSky

Feedback about FrSky Ethos

Thank you for helping FrSky Ethos to be better! Here FrSky could collect input and suggestion from all the end users on the system operation. The goal of this program is to find issues/bugs that can be corrected in further software updates.

Please keep the GitHub section focused on reporting issues/bugs. We will add a priority label on each issue and we may not reply on every issue in the first time but we are sure to take care of them. When the problem is resolved, we ask of you to double check and close the issue. Always check if the issue has already existed on GitHub, in order to prevent double posting. Well described bug description is very important for us to try to reproduce it and fix well.

Thanks a lot for your participation in advance.

Below are some notes to help you report issues/bugs or improvement suggestions.

Issue guides

Please make sure that you have upgraded to latest software version before you post an issue.
If you find a new bug, first please look at opened and closed issues to see if the issue is already listed.
If it does exist you can comment if you have more information.
If does not exist, then create a new issue.

New issue should contain:

Firmware version where issue was found, name the topic to describe the bug as the best as possible
Description of the issue
Description of the expected behavior
Description how to reproduce the bug
If possible a screenshot or video, it is worth 1000 words 😃

Thanks again for your interest and help on this new system, we hope it becomes better and better to fulfill all your demands!

Ethos Wiki

Ethos Wiki is there: https://github.com/FrSkyRC/ETHOS-Feedback-Community/wiki

Here are some direct links to the main pages:

Ethos File Storage, ETHOS flashing and TD ISRM updating
Ethos Localization
Ethos Simulators

Ethos Manuals

If there are any mistakes, please feel free to tell us!

Thanks.

opentibiabr/canary

Canary Server 15.25 for OpenTibia community.

https://docs.opentibiabr.com/

Canary

Canary is a free and open-source MMORPG server emulator for the OpenTibia community, written in C++20 and Lua. It is a fork of the OTServBR-Global project. The repository includes the server core, datapacks, Lua scripts, database schema, build presets, automated tests and development tooling used by the project.

Getting Started

Wiki.

Docker Quickstart

Canary includes a lightweight Docker quickstart for running a local test server without compiling Canary locally. The stack starts MariaDB, the published Canary runtime image, MyAAC as the website/admin AAC, and opentibiabr/login-server as the client login webservice.

This quickstart is for local development, testing, and LAN demos. Do not expose it directly to the public Internet with the default test accounts and passwords.

Run from the docker directory:

cp .env.dist .env
docker compose up -d --build

The docker directory also provides guarded start scripts that start the stack and clean safe Docker leftovers without removing database volumes:

.\up.ps1

sh ./up.sh

Default local endpoints:

Website/admin: http://localhost:8080
Client login webservice: http://localhost:8088/login
Game port: 7172

MyAAC's login.php is intentionally removed from the quickstart image. Clients should use login-server only. See docs/docker/quickstart-for-beginners.md for a beginner guide and docker/DOCKER.md for the full setup, environment variables, test account, and troubleshooting guide.

Documentation

Recompile on Linux with executable backups. Covers seven-day retention, crash analysis, optional restart and WSL tests.
Hardware sizing and capacity planning. Measure RAM and CPU, compare training and hunting workloads, and review capacity.
Shared build cache for worktrees and forks.
Docker beginner quickstart.
Multiprotocol runtime profiles. Covers the current, 11.00, and 8.60 runtime contracts, port layout, client preparation, and validation checklist.
System documentation.
Lua API reference and VSCode IntelliSense stubs. Canary generates these files from the C++ Lua bindings during startup when generateLuaApiDocs is enabled. The repository .luarc.json already adds docs/lua-api to the Lua Language Server workspace library; for VSCode workspace settings, run tools/setup_vscode_lua_api.ps1.

Recommended Tools and Clients

Assets Editor. Use this as the single asset source of truth, then export legacy-compatible .dat/.spr packages for 8.60 clients from the same current asset set.
Remere's Map Editor.
OTClient Redemption.
Tibia Extended Client Library. Use this to prepare compatible 8.60/11.00 CipSoft clients with extended limits, config-driven login redirect, and per-client local state.
Game Client.

Nightly Packages

Development builds can be downloaded from GitHub Actions artifacts. They are useful for testing recent changes from the main branch, but may include behavior that is not present in stable releases yet.

Github Actions.

Running Tests

Tests can be run from the repository root using the tool versions and tasks pinned in .mise.toml:

mise install
mise run configure linux-debug
mise run build linux-debug
mise run test linux-debug

# Replace linux-debug with macos-debug or windows-debug as needed.

For detailed testing information including adding tests and framework usage, see tests/README.md.

Support & Community

For real-time support, join the OpenTibiaBR Discord.

The GitHub issue tracker should be used for bugs, improvements and technical project tasks. It is not a support forum.

Contributing

Contributions are welcome. You can help in several ways:

Report bugs through the Issue Tracker.
Submit improvements through Pull Requests.
Improve tests, documentation, scripts, datapacks, or C++ code.
Validate releases, nightly builds and recent changes.

Before contributing, read the Code of Conduct and the project Contributing guide.

Sponsorship

Canary is maintained by community contributors. To support development, visit the OpenTibiaBR sponsors page.

Acknowledgements

Thanks to all contributors of Canary, OTServBR-Global and the OpenTibia community.

License

This project is distributed under the GPL-2.0 license.

Stephan-S/FS25_AutoDrive

FS25 version of the AutoDrive mod

FS25_AutoDrive

FS25 version of the AutoDrive mod

Latest Release: 3.0.1.2

Direct Download: https://github.com/Stephan-S/FS25_AutoDrive/releases/latest/download/FS25_AutoDrive.zip

Discord Server:

For help & support, feel free to join us on Discord: https://discord.gg/2XfnM59DFy

For a little thank you

If you like our work, feel free to buy us a coffee (of which we drink quite a lot 😄 )
For now, there is no general link for the team, so each contributer can post his/her preferred donation link here 😃
But remember, this is absolutely not required. We value any issues and feature requests the same!
And to all who do donate: Thank you very much 😃

Stephan (Founder):

https://www.paypal.me/StephanSchlosser

Iwan1803 (Community Manager, Supporter & Tester):

https://iwan1803.de/urls/tip

Axel & Tommo (Modder)

Willi (Supporter & Tester)

Placeable Crossings and Reversing (separate mods)

Direct Download: https://github.com/Williwillswisse/AD_XandT-intersections/releases/latest/download/FS25_AutoDrive_XT_Intersection.zip
Direct Download: https://github.com/Williwillswisse/AD_xCrossing/releases/latest/download/FS25_AutoDrive_xCrossing.zip
Direct Download: https://github.com/Williwillswisse/AD_T_intersection/releases/latest/download/FS25_AutoDrive_T_intersection.zip
Direct Download: https://github.com/Williwillswisse/AD_reverseToMarker/releases/latest/download/FS25_AutoDrive_reverseToMarker.zip
Repository: https://github.com/Williwillswisse

Placeables with already prepared AD routes (separate mods)

A growing number of ingame placeables, e.g. buildings, silos, productions and so on with integrated AD routes.
Download: https://hof-hirschfeld.de/category/autodrive/

Course Editor

The course editor is now maintained by @KillBait and can be found here: https://github.com/KillBait/AutoDrive_Course_Editor

Courseplay/Courseplay_FS25

Courseplay for Farming Simulator 2025

Courseplay Beta for Farming Simulator 25

Download the latest developer version (the file FS25_Courseplay.zip).

Courseplay Website

This and the Giants ModHub is the only official source for Courseplay, if you see it anywhere else, it's a scam.

Tutorials

German Tutorial by Mario Hirschfeld: https://www.youtube.com/playlist?list=PL-UvOFIL55_jXAy6UkVJuLOD5DWKLuzIm

English Tutorial by Argsy Gaming: https://www.youtube.com/playlist?list=PLFh-GZbaG02w9uLl_qroCi6uVI0LDXrD1

Courseplay functions are also documented on our website and in the in-game Courseplay menu.

Developer version

Please be aware you're using a developer version, which may and will contain errors, bugs, mistakes and unfinished code. Chances are you computer will explode when using it. Twice. If you have no idea what "beta", "alpha", or "developer" means and entails, steer clear. The Courseplay team will not take any responsibility for crop destroyed, savegames deleted or baby pandas killed.

You have been warned.

If you're still ok with this, please remember to post possible issues that you find in the developer version. That's the only way we can find sources of error and fix them. Be as specific as possible:

tell us the version number
only use the vehicles necessary, not 10 other ones at a time
which vehicles are involved, what is the intended action?
Post! The! Log! to Gist or PasteBin
For more details on how to post a proper bug report, visit our Wiki

Help Us Out

We work long, hard, in our own free time at developing and improving Courseplay. If you like the project, show us your undying love:

id577/FS25_AdvancedDamageSystem

Advanced Damage System mod for Farming Simulator 25

Important

Support the Project

Advanced Damage System is a passion project, and I’m doing my best to make it more realistic, stable, and enjoyable for the FS25 community.

If you like the mod and want to support its development, your donation would mean a lot. Continued development depends heavily on the time I can afford to dedicate to the project, and your support helps me choose development over extra paid work.

Every donation helps me keep working on new features, fixes, and improvements.

Thank you for helping keep ADS alive and growing.

Donate via DonationAlerts · Donate via Coindrop · Donate via Ko-fi - please include 'ADS' in the donation message.

FS25_AdvancedDamageSystem

▶️ Watch ADS Feature Showcase on YouTube

Advanced Damage System is a mod that completely reworks the standard vehicle damage and maintenance system in Farming Simulator 25. A machine's reliability now depends directly on how carefully and efficiently you use it: the harder you push your equipment and the worse you maintain it, the more often it will break down.

Forget about one-click repairs. Maintenance now takes time, resources, and proper planning. You will need to manage wear, schedule repairs in advance, and organize your fleet so that breakdowns do not ruin the season.

Warning

IMPORTANT WARNING

This mod is a work in progress (WIP). Features are subject to change, and bugs are to be expected.
Use at your own risk. The author is not responsible for any potential issues with your savegame or game. It is strongly recommended to back up your saves.

Acknowledgements

A huge thank you to Frvetz (https://github.com/Frvetz), creator of the Realistic Damage System mod for FS22, for the permission to use ideas from his mod and for the support during the early stages of development.

Special thanks to Saibotsu (The Mod Workshop) for extensive balance testing, helpful feedback, and ongoing support throughout development.

A huge special thanks to Squallqt (https://github.com/Squallqt) for his direct contributions to the project. He implemented multiplayer support and provided invaluable help with testing and technical advice.

Also, a big thank you to Derwen Modding for testing the early builds.

Quick Start

If you do not want to read the full guide at the bottom of this page but still want to play with ADS without constant breakdowns and unnecessary frustration, just follow these three rules:

Always follow the service interval.
By default, the recommended interval is about 5 operating hours on average. You can check it:
- in the workshop,
- in the vehicle info panel when looking at the machine,
- in the ADS fleet management menu opened with the P key.
Once the interval is reached, perform the Maintenance procedure in the workshop.
Inspect and prepare your machines every day.
Perform a daily inspection (hold R key) and basic pre-shift maintenance. Clean the vehicle with the Air Blower and lubricate machines that require it with the Grease Gun. These simple routine actions greatly reduce the risk of avoidable failures.
Do not abuse your equipment.
Avoid overloading, overheating, using implements that are too heavy or too demanding for the machine, excessive wheel slip in mud, hard work on a cold engine, and high-speed driving over rough terrain.
As a general rule: if something would be harmful to the machine in real life, it is harmful in ADS too.

Key Features

Complete Replacement of the Vanilla Damage System: Every vehicle in the game is now divided into multiple individual systems: engine, transmission, hydraulics, cooling system, fuel system, working systems, electrical system, and chassis. Each system tracks how the machine is actually being used. For example, chassis wear increases faster if you drive quickly over rough terrain. The harsher the operating conditions, the faster wear builds up and the more often breakdowns occur.
Regular Maintenance Becomes Essential: Scheduled service is now required to prevent accelerated wear and avoid costly failures.
Dynamic Breakdowns: Dozens of different failures tied to specific systems, each with its own gameplay effects and consequences.
Fully Reworked Workshop Menu and Logic: The workshop now supports inspection, repair, maintenance, and overhaul. Each procedure has configurable options and takes time to complete, so there is no one-click repair.
Realistic Thermal Simulation: Engines need proper warm-up, and they can overheat under heavy load in hot conditions. Ignoring temperature can lead to serious consequences.
Realistic Battery and Alternator Simulation: The battery can now discharge, and the alternator can fail, leading to difficult engine starts. However, you can always jump-start a vehicle from another machine.
Vehicle-Specific Characteristics: Vehicles differ by brand and production year in Reliability (affecting wear rate, breakdown probability, and service intervals) and Maintainability (affecting service cost and service time). Premium brands are generally more reliable than budget alternatives, while older machines are often mechanically simpler and therefore more maintainable.
Pre-Operation Inspection: Before heading to the field, vehicles need to be inspected and serviced at the start of each shift: greasing components, blowing out the radiator and air intakes, and carrying out other essential routine procedures.

... More information below in the guide

Console Commands

For testing and debugging, ADS includes console commands. Most commands require you to be inside a vehicle that supports this mod.

Command	Description	Usage Example
ads_debug	Toggles ADS debug mode on/off.	`ads_debug`
ads_listBreakdowns	Lists all available breakdown IDs from the registry.	`ads_listBreakdowns`
ads_addBreakdown	Adds a breakdown to the current vehicle. Optional arguments: breakdown ID and stage.	`ads_addBreakdown ECU_MALFUNCTION 2`
ads_removeBreakdown	Removes a specific breakdown from the current vehicle. If no ID is provided, all active breakdowns are removed.	`ads_removeBreakdown ECU_MALFUNCTION`
ads_advanceBreakdown	Advances a specific active breakdown to the next stage. If no ID is provided, all active breakdowns are advanced where possible.	`ads_advanceBreakdown ECU_MALFUNCTION`
ads_setCondition	Sets the Condition value for all enabled systems on the current vehicle (`0.0`-`1.0`).	`ads_setCondition 0.5`
ads_setSystemCondition	Sets Condition for one specific system on the current vehicle (`0.0`-`1.0`).	`ads_setSystemCondition engine 0.75`
ads_setSystemStress	Sets Stress for one specific system on the current vehicle (`>= 0.0`).	`ads_setSystemStress electrical 0.25`
ads_setSystemStressMultiplier	Sets the stress accumulation multiplier for one system, or for all systems if no system is specified.	`ads_setSystemStressMultiplier 12 electrical`
ads_setService	Sets the current vehicle's Service level (`0.0`-`1.0`).	`ads_setService 0.2`
ads_resetVehicle	Fully resets the current vehicle state: condition, service, and active breakdowns.	`ads_resetVehicle`
ads_startService	Starts service on the current vehicle. Types: `inspection`, `maintenance`, `repair`, `overhaul`. With `repair`, optional `[count]` selects how many visible breakdowns to repair.	`ads_startService repair 2`
ads_finishService	Instantly finishes the currently active service on the current vehicle.	`ads_finishService`
ads_getServiceState	Prints the current workshop and service state variables for the current vehicle.	`ads_getServiceState`
ads_showServiceLog	Prints the vehicle's service log. Optional `[index]` shows one entry in detailed form.	`ads_showServiceLog 1`
ads_getDebugVehicleInfo	Prints detailed debug information about the current vehicle. Optional argument also lists attached specializations.	`ads_getDebugVehicleInfo 1`
ads_setDirtAmount	Sets the current vehicle's dirt level (`0.0`-`1.0`).	`ads_setDirtAmount 0.8`
ads_setFuelLevel	Sets the current vehicle's fuel level using either a `0.0`-`1.0` value or `0`-`100` percent.	`ads_setFuelLevel 25`
ads_resetFactorStats	Resets the accumulated factor statistics for the current vehicle.	`ads_resetFactorStats`
ads_toggleHudDebugView	Switches the ADS HUD debug view between normal and factor stats modes.	`ads_toggleHudDebugView stats`
ads_setConfigVar	Changes a value inside `ADS_Config` at runtime. Intended for testing and debugging.	`ads_setConfigVar CORE.BASE_SYSTEMS_WEAR 0.02`
ads_setSpecVar	Changes a value inside `spec_AdvancedDamageSystem` on the current vehicle. Intended for testing and debugging.	`ads_setSpecVar systems.engine.condition 0.85`

Screenshots

Mod Guide

Important

The mod is actively being developed: some mechanics are constantly being expanded, changed, and reworked, so the guide may contain some inaccuracies.

The Advanced Damage System (ADS) mod completely replaces the standard damage system, offering a deep and detailed simulation of wear, breakdowns, and technical service. This guide will help you understand all aspects of the mod.

1. Core Mechanics: Condition, Stress and Service

Each vehicle can contain all or only some of the following systems: engine, transmission, hydraulics, cooling system, fuel system, working systems, electrical system, and chassis. Every system has two key parameters: Condition and Stress.

⚙️ Condition

This is the main indicator of a system's health and remaining service life.

What does Condition affect? Condition determines how resistant a system is to breakdowns. As Stress builds up through poor or demanding operation, the Condition value defines the threshold at which breakdown risk becomes critical. In simple terms: the lower the Condition, the less abuse the system can take before it starts to fail.
How does it decrease? Condition decreases as the vehicle is used. With the default settings, this is roughly 1% per hour under normal operation. However, harsh or improper use increases wear significantly, and each system has its own factors that accelerate deterioration. Condition also decreases very slowly over time if the vehicle is stored outdoors instead of under cover.
How to restore Condition? Condition can be partially restored through the Overhaul procedure in the workshop. You can restore individual systems or rebuild several systems at once.

⚠️ Stress

This is the accumulated result of misuse, overload, and operating mistakes that a system suffers during vehicle use.

What does Stress affect? Stress directly affects the probability of failures appearing in a specific system. The higher the Stress, the higher the breakdown risk. The upper limit of Stress, where the probability becomes critical, is the current Condition value of that system.
How does it increase? Stress does not build up during normal operation. It increases only through improper use: overload, overheating, running a cold machine under load, wheel slip, harsh working conditions, and other mistakes specific to each system.
How to reduce Stress? Stress can be reduced through preventive maintenance in the workshop. In addition, Stress is automatically lowered after a breakdown occurs. Repairs also give you options: a standard repair significantly reduces Stress, while a full repair with replacement of adjacent components removes all Stress from the system.

💧 Service

This parameter reflects the state of consumables: oil, filters, technical fluids, etc.

What does Service affect? This is a critically important parameter. A low Service level significantly accelerates the decline of Condition in every system, but not all systems are affected equally. For example, the engine suffers much more from overdue service than the cooling system. Timely maintenance is the best way to save money on expensive repairs in the future.
How does it decrease? It decreases with engine operating hours, simulating the natural wear of consumables.
How to restore it? It is restored to 100% through the Maintenance procedure in the workshop (depending on the selected maintenance scope, this value can be lower or higher).

A Note on Player Knowledge: Hidden Values

You can check overall Condition, system Condition, system Stress, and Service in the workshop by running an Inspection. In most cases, the result is an approximate status (for example: Service is OPTIMAL, NOT REQUIRED, REQUIRED, or OVERDUE).

Exact percentage values are available only through a full diagnostic (defectoscopy) procedure, which is expensive and time-consuming.

In practice, this level of precision is usually unnecessary. A responsible farmer follows the manufacturer-recommended service interval for each machine, performs maintenance on schedule, and when the time comes, either carries out an overhaul or replaces the vehicle.

2. Wear Factors

Each system has its own set of wear factors that accelerate Condition loss and increase Stress. At the same time, there are several global factors that can affect multiple systems at once:

Service Factor: The effect of overdue maintenance. The longer the service interval is overdue, the stronger this factor becomes.
Breakdown Presence Factor: An active breakdown in a system accelerates the wear of its remaining components.
Idle Factor: If a system is not being actively used, its wear rate is significantly reduced. For example, the transmission experiences very little wear while the vehicle is not moving.
Downtime Factor: A small passive wear effect that applies when the vehicle is not running and is stored outdoors.

Engine

Motor Overload Factor: Triggers when engine load exceeds 90%. The effect becomes stronger as load gets closer to 100%.
Air Intake Clogging Factor: Triggers when air intake clogging exceeds 50%. The effect becomes stronger as clogging increases.
Cold Engine Factor: Triggers when engine temperature is below 50C and RPM load is above 75%. This factor does not apply to AI vehicles.
Overheated Engine Factor: Triggers when engine temperature is above 95C and engine load is above 30%. The effect becomes stronger as temperature and load increase.

Transmission

Pull Overload Factor: Triggers when engine load is above 82% and the vehicle is moving faster than 0.5 km/h. The effect builds up over time and reaches its maximum after 30 seconds of continuous overload.
Lugging Factor: Triggers when engine load is above 80%, RPM load is below 80%, and the vehicle is moving faster than 0.5 km/h. The effect becomes stronger as the gap between load and RPM increases.
Wheel Slip Factor: Triggers when wheel slip exceeds 30%. The effect becomes stronger as slip increases.
Cold Transmission Factor: Applies only to CVT transmissions. Triggers when transmission temperature is below 50C and RPM load is above 75%. This factor does not apply to AI vehicles.
Overheated Transmission Factor: Applies only to CVT transmissions. Triggers when transmission temperature is above 95C and engine load is above 30%. The effect becomes stronger as temperature increases.
Heavy Trailer Factor: Activates when the mass of the towed trailer exceeds the tractor's own mass by more than 1.2x.

Hydraulics

Operating Factor: Triggers during active hydraulic work. The effect becomes stronger as the working mass ratio increases.
Heavy Lift Factor: Triggers when lifted mass exceeds 30% of the vehicle's mass. The effect becomes stronger as lifted mass increases.
Cold Oil Factor: Triggers during active hydraulic work when engine temperature is below 30C. The effect becomes stronger as temperature gets lower.
PTO Operation Factor: Triggers when the PTO is active. In the current config, this factor is set to 0, so it currently has no effect.
Sharp PTO Angle Factor: Triggers when the connected PTO angle exceeds 20 degrees. The effect becomes stronger as the angle increases.

Cooling

High Cooling Load Factor: Triggers when thermostat state exceeds 90%. The effect becomes stronger as cooling effort increases.
Overheat Factor: Triggers when engine temperature exceeds 95C. The effect becomes stronger as temperature increases.
Cold Shock Factor: Triggers when engine temperature is below 50C and RPM load is above 75%. This factor does not apply to AI vehicles.

Electrical

Lights Usage Factor: Triggers when the main lights are on.
Weather Exposure Factor: Triggers when the vehicle is outdoors during rain, snow, or hail.
Cranking Stress Factor: Triggers while the starter is engaged.
Overheat Factor: Triggers when engine temperature exceeds 95C.

Chassis

Vibration Factor: Triggers when the vibration signal exceeds its threshold. The effect becomes stronger at higher speed and on rougher surfaces.
Steering Load Factor: Triggers at speeds up to 4 km/h when the steering input is active and changing while the wheels have ground contact. The effect becomes stronger with sharper steering input.
Brake Mass Factor: Triggers during braking above 2 km/h when total vehicle mass is greater than its own mass. The effect becomes stronger with heavier mass and stronger braking input.

Fuel

Low Fuel Starvation Factor: Triggers when fuel level drops below 20%. The effect becomes stronger as fuel level gets lower and engine load increases.
Cold Fuel Factor: Triggers when fuel temperature is below 20C and engine load is above 50%. The effect becomes stronger as temperature gets lower.
Idle Deposit Factor: Triggers after 60 seconds of idling. The effect continues to grow up to 600 seconds of idling.
High Pressure Factor: Triggers when engine load exceeds 90%. The effect becomes stronger as load gets closer to 100%.

Work Process

Wet Crop Factor: Triggers when the machine is turned on, harvesting is in progress, and the weather is wet.
Lubrication Factor: Triggers when the machine requires lubrication and lubrication level is below 100%. The effect becomes stronger as lubrication level drops.

3. Breakdowns

In ADS, your vehicles can suffer real breakdowns. Some failures are minor and only reduce performance, while others can make the machine completely inoperable.

Note

📋 Click here for a full list of breakdowns and their effects

This is a comprehensive list of all selectable (random) breakdowns in the mod. Each breakdown has several stages, with the effects becoming more severe over time. The "Critical Effect" listed is the final stage of the malfunction.

⚡ Electrical Systems

ECU Malfunction

Applicable to: Modern non-electric vehicles (Year 2000+).
Symptoms: ECU errors cause reduced engine power, increased fuel consumption, dark exhaust smoke, and at advanced stages can lead to stalls and difficult starting.
Critical Effect: Complete ECU failure. The engine can no longer be controlled and will not start.

Corroded Wiring

Applicable to: Modern vehicles (Year 2000+) equipped with lights.
Symptoms: Flickering or failed lights, unstable voltage supply, hard starting, occasional stalls, and loss of power in critical circuits.
Critical Effect: Starter control circuit failure. Lighting is inoperative and engine start is impossible.

Battery Sulfation

Applicable to: All vehicles.
Symptoms: Reduced effective battery capacity, weak electrical reserve under load, unstable cranking, and progressively harder engine starts.
Critical Effect: Battery capacity is almost gone. Cranking performance becomes too weak for reliable starting.

Alternator Regulator Failure

Applicable to: All vehicles.
Symptoms: Reduced or unstable charging output, poor battery charging, voltage losses, and a steadily weakening electrical system.
Critical Effect: No battery charging. The vehicle runs only on the remaining battery reserve.

⚙️ Engine Systems

Turbocharger Wear

Applicable to: Currently only enabled for the Fiat 160-90 DT.
Symptoms: Turbo whistle, noticeable power loss at high RPM, rising fuel consumption, and possible engine stalls under heavy load.
Critical Effect: Catastrophic turbo failure. The engine loses most of its power and is at serious risk of further damage.

Oil Pump Malfunction

Applicable to: All non-electric vehicles.
Symptoms: Low oil pressure, reduced engine torque, rising engine temperature, mechanical knocking, and possible stalling as the failure worsens.
Critical Effect: Critical oil circulation failure. Safe engine operation and reliable starting are no longer possible.

Valve Train Malfunction

Applicable to: All non-electric vehicles.
Symptoms: Reduced engine torque, increased fuel consumption, abnormal valve train noise, hesitation under load, and possible stalls.
Critical Effect: Valve train failure. The engine can no longer operate correctly and may not start at all.

⚙️ Transmission Systems

Manual Transmission Clutch Wear

Applicable to: Vehicles with manual transmissions.
Symptoms: Transmission slip under load, weak power delivery to the wheels, and increasing fuel consumption as clutch wear progresses.
Critical Effect: Clutch burnout. The vehicle is unable to move.

Transmission Synchronizer Malfunction

Applicable to: Vehicles with manual or synchro-shift transmissions, excluding Powershift.
Symptoms: Grinding noises, difficult shifts, failed gear changes, and gear rejection under load.
Critical Effect: Synchronizer failure. Shifting gears becomes impossible.

Powershift Hydraulic Pump Malfunction

Applicable to: Vehicles with Powershift transmissions.
Symptoms: Delays, harsh engagement, and violent shocks during gear changes as hydraulic pressure drops.
Critical Effect: Hydraulic pump failure. The transmission is stuck in neutral.

CVT Chain Wear

Applicable to: Vehicles with CVT transmissions.
Symptoms: Variator slip, higher fuel consumption, rising transmission temperature, and worsening torque transfer.
Critical Effect: Critical CVT chain wear. Reliable vehicle movement can no longer be guaranteed.

CVT Hydraulic Control Valve Malfunction

Applicable to: Vehicles with CVT transmissions.
Symptoms: Hydraulic pressure drops, reduced engine torque, restricted ratio range, rising transmission heat, and unstable CVT operation.
Critical Effect: Control valve failure. The transmission falls into a severely restricted emergency mode.

🛠️ Hydraulic Systems

Hydraulic Pump Malfunction

Applicable to: Most non-truck, non-passenger hydraulic vehicles from 1960+.
Symptoms: Hydraulic implements become progressively slower, weaker, and less responsive.
Critical Effect: Hydraulic pump failure. The hydraulic system becomes inoperable.

Hydraulic Cylinder Internal Leak

Applicable to: Most non-truck, non-passenger hydraulic vehicles from 1960+.
Symptoms: Slower hydraulic movement, weak actuation, and attached implements drifting or failing to hold position under load.
Critical Effect: Critical internal leakage. Hydraulic movement is almost lost and load holding is no longer possible.

PTO Clutch Slip

Applicable to: Vehicles with PTO capability.
Symptoms: Reduced PTO torque transfer and frequent automatic PTO disengagement under load.
Critical Effect: PTO clutch failure. PTO operation is no longer possible.

🚜 Chassis Systems

Brake Malfunction

Applicable to: Wheeled vehicles.
Symptoms: Reduced braking force, longer stopping distances, weak braking response, and dangerous loss of braking effectiveness.
Critical Effect: Brake system failure. Braking becomes impossible.

Bearing Wear

Applicable to: Wheeled vehicles.
Symptoms: Bearing noise, vibration, increased rolling resistance, lower maximum speed, and rising drivetrain load.
Critical Effect: Wheel bearing seizure. Wheel rotation is blocked.

Steering Linkage Wear

Applicable to: Wheeled vehicles without tracks.
Symptoms: Steering pull, reduced steering response, poor directional stability, and increasingly unreliable control.
Critical Effect: Steering linkage failure. Safe directional control can no longer be ensured.

Track Tensioner Malfunction

Applicable to: Tracked vehicles only.
Symptoms: Directional pull, vibration, drag noise, extra drivetrain load, reduced speed, and unstable track running.
Critical Effect: Track tensioner failure. The running gear can seize.

🌡️ Cooling Systems

Thermostat Malfunction

Applicable to: All non-electric vehicles.
Symptoms: Slow warm-up or unstable temperature regulation at first, followed by persistent overheating under load.
Critical Effect: Thermostat failure. Coolant circulation is disrupted and severe overheating becomes unavoidable.

Coolant Leak

Applicable to: All non-electric vehicles.
Symptoms: Reduced cooling efficiency, faster temperature rise under load, and an increasing likelihood of overheating.
Critical Effect: Critical coolant loss. Safe engine temperature can no longer be maintained.

Fan Clutch Failure

Applicable to: All non-electric vehicles.
Symptoms: Reduced fan efficiency, abnormal fan clutch noise, weak airflow through the cooling pack, and a high overheating risk.
Critical Effect: Fan clutch failure. Adequate cooling airflow is no longer possible.

⛽ Fuel Systems

Fuel Pump Malfunction

Applicable to: All non-electric vehicles.
Symptoms: Rough idle, reduced power, higher fuel consumption, hesitation, difficult starting, and frequent stalls as fuel pressure drops.
Critical Effect: Fuel pump failure. Fuel is no longer supplied to the engine.

Fuel Injector Malfunction

Applicable to: All non-electric vehicles.
Symptoms: Rough running, hesitation under load, reduced power, higher fuel consumption, and increasingly unreliable starting.
Critical Effect: Injector failure. The engine will not run correctly and may not start at all.

Fuel Filter Clogging

Applicable to: All non-electric vehicles.
Symptoms: Restricted fuel flow, hesitation under load, lower engine torque, and possible engine stalls.
Critical Effect: Critical filter blockage. Fuel flow becomes insufficient for engine operation.

Fuel Line Air Leak

Applicable to: All non-electric vehicles.
Symptoms: Unstable fuel supply, difficult starting, hesitation, and engine stalls caused by air entering the system.
Critical Effect: Critical air leak. The engine cannot maintain fuel supply and will not run reliably.

🌾 Work Process Systems

Harvest Processing System Wear

Applicable to: Combines, cotton harvesters, rice harvesters, vine harvesters, and related harvesting machines.
Symptoms: Reduced crop processing efficiency and progressively increasing yield loss during harvesting.
Critical Effect: Critical processing wear. Yield loss becomes extreme during operation.

Unloading Auger Malfunction

Applicable to: Combines with unloading auger systems.
Symptoms: Progressive unloading slowdown caused by belt, pulley, or gearbox wear in the auger drive.
Critical Effect: Unloading auger failure. Grain unloading becomes unavailable until repaired.

Chance and Severity of Breakdowns

The probability of a breakdown depends entirely on the Stress level in a specific system. The closer the current Stress is to that system's current Condition, the higher the chance of a failure occurring.

In addition, the Condition level determines the probability of a critical breakdown. A critical breakdown is a failure that appears immediately at Stage 4, skipping the earlier stages. The lower a system's Condition, the higher the chance that a breakdown will be critical from the start.

The type of breakdown is not entirely random. First, it will always belong to the damaged system. Second, ADS keeps track of which wear factors have been active most often and uses that history to determine which failure is most likely to occur.

Stages and Progression

Most breakdowns go through several stages, gradually getting worse:

Minor: A slight decrease in performance that might go unnoticed.
Moderate: Problems become more obvious. Indicators on the dashboard may light up.
Major: Significant operational problems that make using the vehicle difficult.
Critical: Complete failure of a component. The engine stalls, brakes fail, etc.

The stage at which a breakdown first appears depends on the system's Condition. The lower the Condition, the higher the starting stage is likely to be.

If not addressed, a breakdown will progress over time and can advance to a more severe stage. Progression is context-dependent: each breakdown has its own progression conditions. For example, unloading-system faults on combines progress only while the machine is unloading crop, which is intentionally modeled this way for realism.

Cost and Detection

With each new stage, the cost of repair increases. A critical breakdown can be very costly. For modern vehicles, the mod adds dashboard indicators that usually report a problem starting from the second stage.

It Pays to Be Attentive!

The cheapest repair is a preventive one. Keep an eye on—and an ear out for—your equipment. The initial stages of a breakdown are accompanied by various visual and audio cues that serve as early warning signs. This might manifest as fluctuating engine RPMs, dark exhaust smoke, or other unusual noises like knocking or squeaking during operation. If you catch these symptoms during the first, hidden stage and promptly take your vehicle for an Inspection, you can fix the problem for a minimal price.

General Wear and Tear

In addition to having a higher chance of breakdowns, older vehicles also suffer from gradual degradation of their core performance. As wear accumulates, engine power may drop, the transmission may begin to slip, battery performance may weaken, cooling efficiency may decline, and other important characteristics may deteriorate.

The closer a vehicle gets to the end of its service life, the more noticeable these degradation effects become. Even without a specific breakdown, a worn machine will already perform worse, less consistently, and less efficiently. Beyond random failures, low condition can trigger a permanent "General Wear and Tear" effect, simulating the sluggishness and aging behavior of worn machinery.

4. Workshop Repairs and Service

The workshop system has been fully reworked. You now choose between four core procedures: Inspection, Maintenance, Repair, and Overhaul.

You can also configure additional service parameters. For example, you can choose part quality (Used, Aftermarket, OEM, Premium) or set the desired maintenance scope.

These options directly affect service duration, cost, and quality. All procedures now take meaningful time, so maintenance planning is an important part of fleet management.

Inspection

What it does: Helps you detect faults and understand the current condition of the vehicle. The quality of fault detection and the level of detail in the report depend on the selected inspection type:
- Visual Inspection: A quick external check for when time is short. It can detect breakdowns, but because of the limited scope, there is a small chance that something important will be missed.
- Standard Inspection: A standard full inspection procedure. It detects faults and generates a standard condition report for the vehicle.
- Complete Defectoscopy: A complete technical defectoscopy of the vehicle. It can detect even hidden and potential breakdowns, identify defective parts, and generates a comprehensive report with exact condition values for vehicle systems.
When to use: Use it when you suspect a problem, when warning indicators appear, before expensive repairs, or when you want a clear picture of the vehicle's condition.

Maintenance

What it does: Replaces all oils, filters, and fluids, restores your vehicle's Service level, and also performs a standard inspection. The result depends on the selected maintenance scope:
- Minimal: Basic service. Significantly cheaper and faster, but does not fully restore the Service level. A great choice when time is short and you just need to finish the season.
- Standard: Routine maintenance according to manufacturer specifications. Restores Service to a normal level.
- Extended: Comprehensive service. Takes longer and costs more, but restores Service above the standard level. An ideal choice for long campaigns.
- Preventive: Preventive maintenance beyond the standard manufacturer service. Restores Service to a normal level and reduces Stress in the most problematic systems. It is expensive and time-consuming, but it significantly lowers the risk of breakdowns. An ideal choice for players who do not like unpleasant surprises in the middle of the season.
When to use: Regularly. Depending on its quality, each vehicle has its own service interval recommended by the manufacturer, and it should be followed closely. Small delays will not lead to immediate disaster, but if you ignore maintenance for too long, breakdowns will start to appear and the overall condition of the vehicle will decline rapidly. Also keep in mind that the cost of this procedure is fixed and does not depend on the actual Service level. This means servicing a vehicle at 90% costs the same as servicing it at 10%, so finding the right balance is key to managing your budget.

Repair

What it does: As the name suggests, repair removes detected breakdowns or makes them temporarily inactive. In addition, repair can also reduce the Stress level in the affected system.

Repair is available in three types:
- Quick Fix: A fast and almost free procedure that removes the negative effects of a breakdown on the vehicle, but does not eliminate the fault itself. The fault will return after some time. A service for specific situations when time is extremely limited.
- Standard: Standard repair with replacement of the failed part. Fully removes the fault and significantly reduces Stress in the system.
- Advanced: Comprehensive repair with replacement of all related parts around the failed component. Fully removes all consequences of the breakdown and reduces system Stress to zero.
When to use: Always when something has broken.

Overhaul

What it does: The most expensive and time-consuming type of work, capable of bringing old machinery back to life. Overhaul can:
- restore the Condition of one system or all systems;
- reduce Stress to zero in one or several systems;
- repair all breakdowns in one system or in the whole vehicle;
- perform maintenance as part of the procedure, unless it is a partial overhaul.
For an additional fee, you can also renew the vehicle's paintwork at a much lower cost than a normal repaint.

Overhaul comes in three variants:
- Partial: A partial overhaul that works on one selected system. Restores that system's Condition to a good level.
- Standard: A standard overhaul for the whole vehicle. Restores all systems to a good level.
- Full or Factory Restoration: A very long and expensive procedure, comparable in cost to buying another machine. Brings the vehicle back to an almost like-new state and restores system Condition to an excellent level.
When to use: For old, heavily worn-out vehicles with low Condition to bring them back to life.

Important: This procedure is expensive and does not restore Condition to a fixed 100%. The final restoration level depends on vehicle maintainability, the number of previous overhauls, and a random restoration factor.

Parts Quality Options

For Maintenance and Repair, you can choose between four part qualities:

Used (Used)
Budget analogs (Aftermarket)
Original parts (OEM)
Premium parts (Premium)

These options differ by cost and defect probability. The cheaper the parts, the higher the chance that they will be defective.

Depending on the procedure, defective parts have different negative effects. During Maintenance, defective or low-quality consumables significantly shorten the service interval and increase Condition wear across vehicle systems. During Repair, low-quality parts may fail again after some time and bring the same fault back.

Complete Defectoscopy can detect defective parts and poor-quality consumables.

⏱️ Time and Planning

Beyond money, all workshop procedures require time. The duration of a service or repair depends on the vehicle's Maintainability (simpler machines are fixed faster).

Important: The workshop has operating hours. All work is paused overnight and resumes only when the workshop opens the next day.

This adds a new layer of strategy: you now need to plan when to take your vehicles in for service. An urgent repair on a combine during the harvest season might extend into the next day, leading to downtime and financial loss.

5. Pre-Shift Inspection and Maintenance

ADS encourages you to spend a little time with your machines at the beginning of each working day. A quick pre-shift inspection and a few routine maintenance actions can help you detect problems early and avoid expensive breakdowns later in the field.

Pre-Shift Inspection

You can start a pre-shift inspection by holding the R key near the vehicle you want to inspect.

What it does: This quick routine check allows you to assess the level of technical fluids, the condition of radiator and air intake contamination, and potentially reveal active breakdowns that can realistically be identified through a visual inspection.
Why it matters: Low fluid levels may indicate an active fault. Dirt buildup in the radiator or air intake can lead to overheating and reduced engine performance. Some breakdowns can be spotted before they become serious if you make inspection part of your daily routine.
When to use: Ideally before the start of each working day, especially before heavy field work, harvesting, or transport under load. The procedure takes very little time and can be performed anywhere.

Blowing Out the Cooling System

You can buy an Air Blower in the shop and use it to clean the radiator and air intake.

What it does: Removes accumulated dust and debris from the cooling system and engine air supply.
Why it matters: A clean radiator reduces the risk of overheating, and a clean air intake helps the engine breathe properly under load. Just a few seconds of cleaning at the start of the day can prevent unnecessary wear and performance loss.
When to use: Regularly, especially during dusty field work, harvesting, and hot weather.

Lubrication

Complex machines with many moving parts, especially harvesters, require regular lubrication.

You can buy a Grease Gun in the shop and use it to lubricate the vehicle before work.

What it does: Restores lubrication for machines that require it as part of their daily preparation.
Why it matters: Poor lubrication increases wear and can eventually lead to lubrication-related failures. This is particularly important for high-complexity harvesting machines that operate under sustained load for long periods.
When to use: Before a working day or before demanding seasonal operations. Properly lubricating a combine before harvest is one of the easiest ways to avoid an inconvenient breakdown in the middle of the field.

6. Reliability and Maintainability

Each brand of vehicle in the game now has two parameters based on its real-world reputation:

✅ Reliability

What it is: Shows how well-made the vehicle is. Displayed with a checkmark icon in the shop menu.
What it affects: A vehicle with high reliability loses Condition more slowly, has a lower base probability of random breakdowns and has longer service intervals

Examples: Premium European and American brands are generally more reliable than budget or older Eastern European counterparts.

🔧 Maintainability

What it is: Shows how easily and cheaply the vehicle can be serviced and repaired.
What it affects: A vehicle with high maintainability requires less money and time for all workshop operations and restores its Condition better after an overhaul.

Examples: Simple, older vehicles are often more maintainable than modern machines packed with electronics.

7. Thermal Dynamics

The mod simulates full engine heating/cooling behavior with thermostat operation. Temperature is not just visual data: it directly affects wear and failure risk.

Engine Thermal Model

Engine operating temperature is calculated from multiple factors:

engine load (heat generation),
ambient temperature,
vehicle dirt level (radiator efficiency loss),
airflow from speed (extra cooling while moving),
thermostat opening state.

Thermostat Behavior by Vehicle Age

Thermostat control differs by production year:

Older machines (mechanical thermostat): More inert behavior, slower response to changing conditions, and higher stiction.
Modern machines (electronic control): Faster, PID-based thermostat response, allowing cooling efficiency to adapt much more quickly to load and temperature changes.

This is why older equipment is generally more temperature-sensitive under variable workload.

Overheating Protection (Limp Mode)

Modern vehicles (year >= 2000) use staged overheat protection:

power is progressively limited as temperatures rise,
at critical temperature, engine shutdown can occur.

Older vehicles do not use this staged protection logic; severe overheating can lead to a hard engine failure.

Warm-Up Is Required

Cold operation under load is heavily penalized. Before hard work, especially in cold weather, let the machine warm up first to reduce accelerated wear.

CVT Temperature Model

CVT vehicles use a dedicated transmission thermal model. Unlike the engine model (which is mainly load-driven), CVT temperature is strongly affected by:

transmission load factor,
slip factor (especially when actual speed is much lower than implement-limited target speed),
acceleration dynamics (frequent acceleration/deceleration and aggressive ratio changes),
ambient temperature, vehicle dirt, and speed-based cooling.

In practice, low-speed high-stress work and jerky driving can overheat CVT components even when engine temperature is still acceptable.

8. Alternator & Battery

ADS simulates the vehicle electrical system as a real working model rather than a simple on/off mechanic. The mod tracks battery charge, alternator output, onboard electrical loads, battery temperature, internal resistance, and voltage behavior under charging and discharge.

Battery behavior depends on several factors at once. Its available capacity drops in cold weather, internal resistance rises as the battery gets colder and more worn, and charge acceptance is reduced not only by low temperature, but also by high state of charge and poor battery health. In practice, this means a weak or cold battery does not just "have less charge" - it also charges worse, sags harder under load, and performs noticeably worse during starting.

The alternator is also modeled dynamically. Its output depends on engine RPM, current electrical load, and alternator health. If the onboard consumers demand more current than the alternator can provide, system voltage starts to sag and the battery begins to discharge. If there is charging headroom, the battery recharges gradually rather than instantly, and the charging process is limited by its real acceptance capability.

Battery temperature is simulated separately. It is influenced by ambient temperature, engine bay heat, and self-heating from current flowing through the battery's internal resistance. Because of that, the same battery can behave very differently in winter, after a cold start, or after long operation under heavy electrical load.

This system also interacts with breakdowns. A failed alternator can leave the machine running only on battery reserve, while battery failure can lead to weak cranking, hard starting, or a complete no-start situation. Depending on the condition of the electrical system, the vehicle may suffer from unstable voltage, poor charging, or total loss of starting ability.

If the battery is too weak to start the engine, you can use jumper cables and get power from another vehicle. ADS models this as an actual external power connection: both batteries are linked into a shared circuit, current flows between them, and the donor vehicle can support the receiver during cranking or temporary charging.

GitHub Lua Daily Trending Repositories

LandSandBoat/server

LandSandBoat

Getting Started

Interacting with LandSandBoat

Crashes, warnings, errors, bugs, gameplay issues, visual issues, questions, documentation issues, build problems, etc.

AI Agents and their use

LICENSE

Thanks

koreader/koreader

KOReader is a document viewer primarily aimed at e-ink readers.

Main features

Screenshots

Installation

Development

Support

Contributors

AndyHazz/bookshelf.koplugin

Bookshelf

Install

A quick tour

The shelf menu (top of the screen)

Searching

The hero card (top of the shelf area)

Micro-modules on the home screen

The shelf grid (the books)

List view

Spines

Folder styles (how groups look)

Folder shortcuts and jump-to-folder gestures

The start menu

Micro-modules

The book menu (long-press a cover)

Collections

OPDS catalogues

Kindle library

Kobo library (beta)

Hardcover enrichment

Layout

Animations

Instant book close

Cover indicators

Colours

Custom images for folders and stacks

Calibre metadata (beta)

Author names

Customising the hero card

Tokens (placeholders)

Bundled fonts

Updates

Library refresh

Page counts

Reference

Sources

Filters

Sort priority

Editor buttons

Bookends extras

Book metadata

Position and progress

Statistics (requires the statistics plugin)

Library

Time and date

Device

Conditionals

Delimited tokens

Selected keys

License

Footagesus/WindUI

Credits

Icons (https://github.com/Footagesus/Icons)

Links

finlater/weread.koplugin

WeRead KOReader Plugin

安装

登录与认证

功能

SimpleUI / Zen_UI 集成

菜单结构

贡献

Statistics (requires the `statistics` plugin)

Ask — `require("opencode").ask()`

Select — `require("opencode").select()`

Prompt — `require("opencode").prompt()`

Operator — `require("opencode").operator()`

Command — `require("opencode").command()`