Skip to content

User Patches

Jump to bottom
Jimmy Pautz edited this page Sep 1, 2026 · 2 revisions

User Patches

KOReader User Patches allow you to customize, extend, or monkey-patch KOReader and plugin behavior at startup without modifying core source code.

This page catalogs community-maintained user patches designed to work alongside the KOReader X-Ray plugin (xray.koplugin).

Community Patches

1. Entity Footnotes (by Dukko)

Overview

The Entity Footnotes patch brings in-text visual indicators and interactive tap popups for AI-extracted entities. While the core X-Ray plugin provides in-text underlines and tooltips for unit conversions, this patch extends the same mechanism to:

  • Characters & Key Figures
  • Historical Figures
  • Locations & Settings
  • Glossary & World Terminology

When reading, recognized names and terms are subtly underlined. Tapping an underlined entity brings up a footnote-style popup showing the AI-generated description directly over the page without needing to open the full X-Ray menu or search dictionaries.

Key Features

  • In-Text Underlines: Automatically underlines known entities in your current chapter or page using the same rendering engine as X-Ray's unit converter.
  • Tap-to-Reveal Popups: Displays character bios, location descriptions, and glossary definitions on tap.
  • Chunked Scanning: Scans page text in chunked batches across the book text to process entity mentions.
  • Category Filters: Configure which entity types should be underlined (e.g., characters only, locations only, or all entities).
  • Non-Destructive: Does not modify xray.koplugin source files. Updating the base X-Ray plugin will not overwrite or disable this patch.

Installation

Option A: Install via Storefront (Recommended)

If you use the Storefront plugin manager for KOReader, you can download and install community user patches directly on your device:

  1. Open KOReader and navigate to Tools Menu (wrench icon) → Storefront.
  2. Go to the User Patches section or search for Entity Footnotes / X-Ray Patch.
  3. Tap Install (Storefront automatically places 2-xray-entity-footnotes.lua into your patches/ directory).
  4. Restart KOReader when prompted.
Option B: Manual Installation
  1. Download the latest 2-xray-entity-footnotes.lua from the Dukko/xray-patch Releases page (or grab it from the patches/ folder in the repository).
  2. Copy the file into your device's KOReader patches directory:
    • Linux / Android / Kobo / Kindle: koreader/patches/2-xray-entity-footnotes.lua (or koreader/settings/patches/ depending on your KOReader folder layout).
  3. Restart KOReader.
  4. Open a book with fetched X-Ray data. In the X-Ray menu, navigate to Entity Footnotes to enable the feature, select active categories, or trigger a manual rescan.

Known Notes & Limitations

  • Blocking Scan Operation: While the scan is split into chunks, the scan routine is blocking / synchronous. When opening a new chapter or re-scanning books with extensive entity databases, you may experience perceptible UI pauses or momentary delays.
  • Language Fallback: As an external patch, menu items and notifications default to English regardless of KOReader's active UI locale.
  • Case-Sensitive Matching: Matches entities with exact casing to avoid false-positive collisions with common lowercase words (e.g., matching the surname "Black" rather than the color "black").

How KOReader User Patches Work

KOReader executes Lua scripts located in the patches/ folder in alphanumeric order during the startup boot sequence (e.g., 1-patch.lua, 2-patch.lua).

Managing Patches

Action Via Storefront Manual Method
Install Browse to the patch in Storefront and tap Install. Place the .lua patch script into koreader/patches/ and restart KOReader.
Update Check the updates section in Storefront and tap Update. Overwrite the existing patch file in koreader/patches/ with the new version and restart.
Disable / Remove Toggle or remove the patch in Storefront. Delete the .lua file from koreader/patches/ (or rename to .lua.disabled) and restart KOReader.

Contributing Community Patches

Have you created or found another user patch for X-Ray? Feel free to share it in the GitHub Issues / Discussions so it can be added to this community list.

Related Pages

Clone this wiki locally