2. Core Features

Here's a breakdown of what the plugin can actually do once you've fetched the data for a book.

Characters

This is a list of everyone mentioned in the story.

• Details: Tap any character's name to read their bio, role, and occupation.
• Search: Use the search icon to find a specific person quickly.

• Fetch More: If you notice a minor character is missing, hit "Fetch More Characters". The AI will do another pass just looking for names it missed.

For information on how X-Ray data gets fetched and updated — including the background auto-fetch feature — see the Fetching page.

Merging Duplicates

If you have multiple entries for the same person (e.g., "Dracula" and "Count Dracula"), you can merge them into a single profile. The plugin will use AI to combine their existing descriptions into one cohesive summary while preserving all their mentions and timeline data.

Custom Description Lengths

You can control the verbosity of the AI-generated content in Settings → AI Settings → Description Length. The plugin provides four distinct tiers of detail that can be configured independently for different types of data:

• Characters: Control how deep the character bios go.
• Locations: Adjust the detail for setting and place descriptions.
• Timeline: Change the length of individual plot summaries in the timeline.
• Historical Figures: Fine-tune the depth of real-world historical context.

For each of these, you can choose between:

• Short: Quick, one-sentence summaries.
• Default: Balanced descriptions (the standard experience).
• Detailed: Longer bios and more context for complex entries.
• Very Detailed: Deep dives for those who want as much information as possible.

Linked Entries

Linked Entries automatically connects characters, locations, and historical figures when they are mentioned in each other's descriptions.

• Smart Navigation: When viewing an entry (e.g., Abraham Van Helsing), you will see a "Linked Entries" button if other entities are mentioned in his bio (e.g., Dracula or Whitby).

Tip

You can enable or disable this feature under Settings → Linked Entries Settings. Disabling it will hide the button from detail dialogs for a cleaner interface.

Timeline

The Timeline gives you a chronological summary of the plot, broken down by chapter. It follows your Spoiler Protection settings, so it won't show you events you haven't read yet if you're using Spoiler-free mode.

Series Context (Prior Books Recap)

When reading a series, keeping track of what happened in previous volumes can be difficult. The X-Ray plugin solves this by fetching a recap of all previous books in the series:

• Auto-Prompting: When you open a book that is Book 2 or later in a series (either detected via metadata or AI), the plugin will ask if you want to load a recap of the previous books.
• Smart Integration:
  • Merged Bios: Character, location, and term descriptions from prior books are merged into the current book's list and prefixed with [From Book X]. Uniquely, they are tagged with a [Prior] label.
  • Timeline Recap: A collapsible ── Prior Books ── header is added to the top of your timeline. Expanding it lets you view consolidated recaps of the events of each previous book.
• Caching: Recap data is saved globally under the series' unique name, meaning it only needs to be fetched once for the entire series.
• Settings: You can toggle auto-prompting on/off under Settings → Series Context, or manually fetch/refresh the series recap at any time.

Historical Figures & Locations

• Historical Figures: If you're reading historical fiction or non-fiction, this pulls up real-world info about actual historical people mentioned in the text. We've refined these prompts for better accuracy and fewer false positives when identifying real-world figures.
• Locations: Gives you a quick description and context for the places the story happens.

Mentions

Mentions scanning allows you to find every occurrence of a character, location, or historical figure throughout the book.

• How to Use: Tap on any entity in the X-Ray menu and select "Find Mentions".
• Wait for Scan: The initial scan for an entity's mentions happens in the "foreground" while you have the menu open. You should wait for the progress indicator to finish before closing the menu or attempting to navigate to a mention.
• Navigation: Once the scan is complete, you will see a list of page numbers and context snippets. Tapping a mention will jump you directly to that page.

• In-Text Banner: When you jump to a mention, a small navigation banner will appear at the top of the screen. This allows you to quickly cycle through occurrences (Next / Prev) or return to exactly where you were reading before (Back).

Tip

You can enable or disable this feature entirely under Settings → Mentions Settings.

Author Info

If you want to know a bit more about the author, go to Menu → X-Ray → Author Info. If it's empty, you can run a quick search to pull their bio and birth/death dates.

Quick In-Text Lookups

You don't have to navigate through the main menu every time you want to check a character's name.

• Selection Popup: If you long-press a word or name while reading, you'll see a dedicated X-Ray button directly in the dictionary/selection popup.
  • Instant Lookup: Tapping the X-Ray button will immediately search your local data for that character or location.
  • Inline Fetching: If the word isn't in your X-Ray database yet, the plugin will ask if you want to look it up using AI. This is a "Targeted Fetch" that only retrieves info for that specific name, making it much faster than a full book scan.
• Highlights: If you long-press an existing highlight, the standard KOReader menu will pop up. There's an X-Ray option added in there too.
• Keyboard Shortcut: If you happen to be using a device with a keyboard, pressing Alt + X will open the quick menu.

Tip

You can disable this feature entirely under Settings → X-Ray Mode Settings.

Language & Localization

The plugin interface and AI-generated content are fully localized into 11 languages: English, German, French, Spanish, Brazilian Portuguese, Russian, Ukrainian, Turkish, Simplified Chinese, Dutch, and Hungarian.

You can configure the language settings under Menu → X-Ray → Settings → Language:

• Automatic (Follow System): Matches KOReader's global UI language.
• Automatic (Follow Book): Matches the language of the book you are currently reading (ideal for bilingual readers).
• Manual Selection: Force a specific language for all menus and X-Ray data.

Smart Detection: If you open a book in a supported language that differs from your current X-Ray setting, the plugin will automatically ask if you want to switch languages to match the book.

Checking for Updates

The plugin can check for new versions automatically. You can find this under Menu → X-Ray → Maintenance → Check for Updates. It's a quick way to grab the latest improvements without having to manually download files from GitHub.

There's also a weekly silent check that runs automatically when you open a book, so you'll get a notification if something new is available without having to think about it.

Beta Channel

If you want to help test the latest features before they are officially released, you can opt into the Beta Channel:

1. Go to Menu → X-Ray → Maintenance → Beta Channel.
2. Toggle the setting to Enabled.
3. Run a manual update check to grab the latest pre-release build.

Warning

Beta builds include the latest improvements but may be less stable than the regular releases. You can switch back to the stable channel at any time.