BiblePlugin

BiblePlugin 2.0.0
Read, search and explore the Bible in-game. Menus, sounds, bookmarks and temporary books. Minecraft 1.21 to 26.x.

Read the Word. Hide it in your heart.

God's Message to You

For God so loved the world, that he gave his only begotten Son, that whosoever believeth in him should not perish, but have everlasting life.

John 3:16 (KJV)

The Bible tells one clear story, from beginning to end:

• Everyone has sinned. "For all have sinned, and come short of the glory of God;" (Romans 3:23)
• Sin leads to death, but God gives life. "For the wages of sin is death; but the gift of God is eternal life through Jesus Christ our Lord." (Romans 6:23)
• Jesus died for you. "But God commendeth his love toward us, in that, while we were yet sinners, Christ died for us." (Romans 5:8)
• Jesus is the only way to God. "Jesus saith unto him, I am the way, the truth, and the life: no man cometh unto the Father, but by me." (John 14:6)
• Salvation is a gift, received by faith, not earned. "For by grace are ye saved through faith; and that not of yourselves: it is the gift of God: Not of works, lest any man should boast." (Ephesians 2:8-9)
• Confess and believe. "That if thou shalt confess with thy mouth the Lord Jesus, and shalt believe in thine heart that God hath raised him from the dead, thou shalt be saved." (Romans 10:9)
• He invites you. "Come unto me, all ye that labour and are heavy laden, and I will give you rest." (Matthew 11:28)
• He forgives and cleanses. "If we confess our sins, he is faithful and just to forgive us our sins, and to cleanse us from all unrighteousness." (1 John 1:9)

If you have never received this gift, you can receive it today. Speak to God honestly, in your own words, or use this prayer: "Lord Jesus, I know that I am a sinner. I believe that You died for me and rose again. Forgive my sins, and come into my life as my Saviour and Lord. Amen." Then read the Gospel of John and find a church or a believer near you to walk with.

This plugin is a tool. The Word itself is the message, and it is the most important thing you will ever read.

What It Does

BiblePlugin brings Scripture into the game. Players can download Bibles in many languages, read any passage in a menu, search for words and phrases, count how often a word appears, and receive a temporary book with the passage they need. Searches use an index, Bibles load from a compact cache, and downloads and searches run off the main server thread.

Features

Editions and languages

• 117 editions in 69 languages, downloaded from the free getBible API. The list is bundled, so browsing works offline.
• Download, load, unload and delete editions, with live progress messages.
• A default edition for commands that do not name one.
• Import your own Bible from a JSON file, so you can use any edition you have the rights to.
• Edition info: language, licence, year, number of books and verses, and reading difficulty.

Reading

• Verses, ranges and whole chapters in chat, for example John 3:16, John 3:16-18 or Psalm 23.
• Reader menu: browse chapter by chapter and page by page, with previous and next buttons.
• Click a verse to share it in chat. Right-click a verse to bookmark it.
• Continue exactly where you stopped.
• Random verse, and verse of the day (the same verse for everyone each day).
• Book, chapter and verse counts for any Bible.
• Bookmarks: save, list and remove (up to 50 per player).
• Join verse: a verse greets players when they join. Players can switch it off.

Search

• Search results menu with every matching verse, paged, with counts of verses and occurrences.
• Word and phrase search, accent and case insensitive: senor finds señor.
• Occurrence counter: how often a word appears in a whole Bible, one book or one chapter.
• Scoped search with "in": /bible occurrences love in John 3.
• Typed search on a sign by default. Chat is used if a sign cannot be placed.
• Chinese, Japanese, Thai and other scripts without spaces are searched by substring automatically.

Temporary books

• /bible book gives you a written book with any passage, from one verse to a whole book.
• Each book is marked as temporary. It disappears after 20 minutes by default, when you log out, and it never drops when you die.
• Long passages are split across pages, capped by a configurable page limit.

Menus, sounds and style

• Library menu (/bible gui): every edition, with its language, licence and difficulty. Click to download and read.
• Bookshelf, chapter and reader menus, to move through any Bible without typing.
• Sounds for clicks, page turns, opening, success, downloads and errors. Volume and on/off are configurable.
• Coloured chat: gold references, white text, wrapped lines and a clear help screen.

Reading difficulty
Every English edition is rated with the Flesch-Kincaid grade level, measured from its own text:

• Easy (below grade 6.6): Basic English Bible, World English Bible
• Moderate (6.6 to 7.5): King James Version, American King James, American Standard, Webster's, Tyndale
• Advanced (7.5 to 8.5): Weymouth New Testament, Douay-Rheims
• Scholarly (8.5 and above): Young's Literal Translation

The ratings rank editions against each other. They are not an absolute measure.

Commands

The main command is /bible. The aliases /bib and /scripture also work. Type /bible help in game for the list you are allowed to use. In every command, the Bible name is optional when a default is set.

Click to show all commands

Editions

• /bible available [language | page] (alias list): list languages, or the editions of one language.
• /bible downloaded (alias installed): show which editions are loaded or installed.
• /bible download <id>: download an edition from the catalogue. Permission: bible.download
• /bible load <id>: load an installed edition into memory. Permission: bible.admin
• /bible unload <id>: remove an edition from memory. Its file is kept. Permission: bible.admin
• /bible delete <id>: delete an edition from disk. Permission: bible.admin
• /bible default <id>: set the default edition. Permission: bible.admin
• /bible info [bible] (alias about): details and reading difficulty.
• /bible import <file> <id> <language-code> [name]: import a JSON Bible from the imports folder. Permission: bible.admin
• /bible gui (aliases library, menu): open the library menu.
• /bible reload: reload config.yml and messages.yml. Permission: bible.admin

Reading

• /bible verse [bible] <reference> (alias v): show a verse, a range or a chapter.
• /bible read [bible] [reference] (alias open): open the reader menu.
• /bible continue (alias resume): reopen where you stopped.
• /bible book [bible] <reference> (aliases temp, pages): get a temporary written book. Permission: bible.book
• /bible chapters [bible] <book>: how many chapters a book has.
• /bible verses [bible] <book:chapter>: how many verses a chapter has.
• /bible books [bible] [page]: list the books of a Bible.
• /bible random [bible] (alias rand): a random verse.
• /bible daily [bible] (alias votd): the verse of the day.
• /bible bookmark add [bible] <reference>, /bible bookmark list, /bible bookmark remove <n> (alias bm): manage bookmarks.
• /bible loginverse on|off: show or hide the verse shown when you join.

Search

• /bible occurrences [bible] <word> [in <reference>] (alias count): count how often a word appears.
• /bible find [bible] <phrase> [in <reference>]: list verses that contain a phrase.
• /bible search [bible] (alias s): type a search on a sign and browse the results in a menu.

Reference syntax

• John 3:16 is a single verse.
• John 3:16-18 is a range of verses.
• John 3 is a whole chapter.
• Psalm 23 or Psalms 23 is a whole chapter.
• John is a whole book.
• 1 John 3:16, 1john 3:16 or I John 3:16 are numbered books.
• gen 1:1: any unique start of a book name works, for example rev 22.
• John:3:16: the colon form works too.

If a start matches more than one book, the plugin lists the candidates so you can be more specific.

Permissions

• bible.use (default: everyone): read, search, bookmarks, menus and the join verse
• bible.book (default: everyone): temporary written books
• bible.download (default: op): download editions
• bible.admin (default: op): load, unload, delete, default, import and reload
• bible.* (default: op): all of the above

Configuration

The file is plugins/BiblePlugin/config.yml. Every option is commented in the file. The main settings are below.

Click to show the main config settings

bibles:
default: kjv # edition used when no name is given
keep-loaded: [kjv] # loaded at startup; missing ones are downloaded
download:
timeout-seconds: 30
attempts: 3
search:
results-per-page: 8
max-results: 200
reader:
input: SIGN # SIGN (recommended) or ANVIL
temporary-book:
lifetime-minutes: 20
chars-per-page: 240
max-pages: 100
author: BiblePlugin
sounds:
enabled: true
volume: 0.7
login-verse: true

Every message the plugin sends is in messages.yml, with colour codes and placeholders, so you can translate or restyle it.

Importing Your Own Bible

Some editions, such as the NIV, NKJV, ESV, NLT and CSB, are copyrighted and cannot be downloaded from a free source. If you own a licensed copy, you can convert it to one of these JSON layouts and import it. You are responsible for the licence terms.

• getBible layout: {"books":[{"name":"Genesis","chapters":[{"chapter":1,"verses":[{"verse":1,"text":"..."}]}]}]}
• Array layout: [{"name":"Genesis","abbrev":"gn","chapters":[["In the beginning...","..."]]}]

Put the file in plugins/BiblePlugin/imports/, then run /bible import niv.json niv en New International Version.

What Changed From 1.x

• Downloads come from the getBible API: 117 editions in 69 languages, instead of seven.
• Searches are indexed, Bibles load from a binary cache, and everything runs off the main thread.
• /bible verse accepts ranges, such as John 3:16-18. The old four-part form Exodus:6:15:4 is no longer accepted.
• The occurrence scope is now written as "in <reference>", for example /bible occurrences love in John 3, instead of bible:book.
• The permission bible.commands is replaced by bible.use.
• The old bible.implementation setting is gone. Search always uses the index now.
• New: menus, sounds, search results, bookmarks, continue, random and daily verses, temporary books, the join verse, import, and the developer API.

Developers

Other plugins can read loaded Bibles through the public API. Get the service from Bukkit's services manager after BiblePlugin enables.

Click to show the API example

RegisteredServiceProvider<BiblePluginApi> provider =
getServer().getServicesManager().getRegistration(BiblePluginApi.class);
BiblePluginApi bible = provider.getProvider();
bible.passage("kjv", "John 3:16").forEach(v -> getLogger().info(v.text()));

The API covers loaded editions, references, passages, search, readability and listeners for load and unload events.

Compatibility and Requirements

• Minecraft 1.21 to 26.x on Spigot, Paper and their forks. The jar is compiled against the Spigot APIs 1.21 and 26.3, so one file covers the whole range.
• Java 21 or newer on the server.
• An internet connection the first time an edition is downloaded. Each edition is usually 5 to 10 MB. After that the plugin works offline.
• No other plugin is required.

Troubleshooting

• The search asks for a sign, but nothing happens: check that reader.input is SIGN in config.yml and run /bible reload. Existing servers keep the config they were first started with.
• The search asks for text in chat: the sign could not be placed, for example in a tight space, or the anvil returned nothing. Type your search in chat, or type cancel.
• A download fails: the server needs internet access. Raise bibles.download.timeout-seconds if your connection is slow.
• An edition is missing: check /bible available for its ID, then run /bible download <id>.

Credits
Bible text from the getBible API, which lists every edition with its licence. Please respect each edition's licence when you use it.

"Thy word is a lamp unto my feet, and a light unto my path." (Psalm 119:105)