Books-Without-Borders/README.md

Books Without Borders

This is a rewrite of the Books Without Borders plugin. This rewrite originally used the source code given at the original bukkit page. While the old plugin still worked the last time I checked, this plugin does not use any depreciated function calls, making sure it works for the foreseeable future.

Books without Borders!

Ever wanted to export your book to a text file? Ever want to import it back in? Accidentally sign it too soon? If so, Books without Borders has got your back!

Features

• Export written books and book and quills to .yml files
• Import books from files as written books or unsigned books
• Text files can be any length, and the import process fits the content to the correct page length
• Books can be saved privately, or to a directory visible server wide
• Encrypt books to prevent other players from reading them
• Give, encrypt, or decrypt held books with signs
• Give players books via command blocks
• Unsign or copy held books with a simple command
• Give first time players a single book or a set of books when they join
• Configurable option to require certain items or pay via Vault compatible economy to create books via command
• Add lore to any item with a simple command
• Supports adding and saving color to title, lore, and book contents
• Color and formatting codes can be manually turned into formatting using /formatbook
• Clear a book, and start anew with /clearbook
• Formatting and color codes can be turned into formatting once any book is signed. This is enabled through a config value
• Change generation of books. Create tattered books for your RPG server!
• Optionally, make it impossible to duplicate the original version of a book
• Optionally, hit a bookshelf while sneaking to display the contained books. The bookshelf can be given a title and lore with /setBookshelfData.
• Easily add a title page or chapter page (for an unsigned book, you can add a blank page as well) with /addBookTitlePage.
• Remove extra blank pages or unneeded chapter pages with /deleteBookPage
• If the necessary options are enabled, books can be truly encrypted with the AES cipher, making them impossible to decrypt without knowing the password. Even admin decryption can be made useless. Only enable if you are aware of the potential loss caused by forgotten passwords!

Group encryption

• Group encryption allows every player with the bookswithoutborders.decrypt.<group> permission to decrypt the encrypted book without using a password.

Migration from previous versions

• The /migrateBooks command allows for easy fixing of old book naming, changing the title author separator (the default changed from , to ¤, as a comma is a natural character to use in a title), or updating books saved as txt to yml.

Book formatting

• Formatting codes are automatically turned back into & codes after un-signing a book.
• /formatbook can be used on an unsigned book to preview formatting, but note that RGB colors will show up as incorrect colors. That's just how that works. You must sign the book to see the real result.
• /formatbook can be used on a signed book (if Format_Book_After_Signing is disabled) in order to make any color or formatting codes in the book display as intended.

Commands:

An in-game description of available commands is available through the /bwb command.

Command	Alias	Arguments	Permission	Description
/addBookTitlePage	bwbtitlepage	[page index] [title~description]	bookswithoutborders.addtitlepage	Adds a blank page, title page or chapter page depending on input and whether the book is signed. The title author separator (default ~) is used to separate the input into title,paragraph1,paragraph2,...
/bookswithoutborders	bwb	None		Displays information about commands (and permissions if the user has bookswithoutborders.admin)
/clearbook	bwbclear	None	bookswithoutborders.clear	Removes all text from the held un-signed book
/copybook	bwbcopy	<# of copies>	bookswithoutborders.copy	Copies the book the player is holding
/decryptbook	bwbdecrypt	<key>	bookswithoutborders.decrypt	Decrypts the book the player is holding. "key" is required and MUST be IDENTICAL to the key used to encrypt the held book
/deletebook	bwbdelete	<file name or number>	bookswithoutborders.delete	Deletes the specified file in the player's directory
/deleteBookPage	bwbdeletepage	<page>	bookswithoutborders.deletepage	Deletes one page from a book
/deletepublicbook	bwbdeletep	<file name or number>	bookswithoutborders.admin	Same as deletebook, but deletes files in the public directory
/encryptbook	bwbencrypt	<key> [encryption style]	bookswithoutborders.encrypt	Encrypts the book the player is holding. "key" is required and can be any phrase or number excluding spaces. "style" is not required. Possible values are "dna", "substitution", "aes", "onetimepad" and "magic", unless real encryption is enabled, which limits available algorithms.
/formatbook	bwbformat	None	bookswithoutborders.format	Formats the held written book (converts color and formatting codes to the corresponding formatted text)
/givebook	bwbgive	<file name or number> <playername> [# of copies (num)] [signed (true/false)]	bookswithoutborders.give	Gives the selected player a book from your personal directory
/givepublicbook	bwbgivep	<file name or number> <playername> [# of copies (num)] [signed (true/false)]	bookswithoutborders.givepublic	Same as givebook, but uses books from the public directory
/groupencryptbook	bwbgencrypt	<group name> <key> [encryption style]	bookswithoutborders.groupencrypt	Makes an encrypted book that only players with the "bookswithoutborders.decrypt." permission can decrypt. It's always auto-decrypted, so the key only matters for scrambling the contents.
/loadbook	bwbload	<file name or number> [# of copies] [signed (true/false)]	bookswithoutborders.load	Creates a book from the specified file and gives it to the player. If no file is specified, a list of available files is returned. If true is specified, the book will be signed, if false it will be unsigned
/loadpublicbook	bwbloadp	<file name or number> [# of copies] [signed (true/false)]	bookswithoutborders.loadpublic	Same as loadbook, but views files in the public directory
/migrateBooks	bwbmigrate	None	bookswithoutborders.admin	Migrates all txt books to yml, and fixes any incorrect filenames.
/reload	bwbreload	None	bookswithoutborders.reload	Reloads BwB's configuration file
/savebook	bwbsave	[overwrite (true/false)]	bookswithoutborders.save	Saves the book the player is holding to a text file in a private directory. If true is specified, a book of the same name by the same author will be overwritten by the new book
/savepublicbook	bwbsavep	[overwrite (true/false)]	bookswithoutborders.savepublic	Same as savebook, but saves files in the public directory
/setbookauthor	bwbauthor	<author>	bookswithoutborders.setauthor	Sets the author of the book the player is holding
/setbookgeneration	bwbgeneration	<generation>	bookswithoutborders.setgeneration	Sets the generation of the held book (ORIGINAL, COPY_OF_ORIGINAL, COPY_OF_COPY, TATTERED)
/setbookprice	bwbprice	<item/eco> <quantity>	bookswithoutborders.setbookprice	Sets the per-book price to create a book via commands. If "Item", the item in the player's hand in the amount of <quantity> will be the price. If "Eco", a Vault based economy will be used for price. If neither <Item/Eco> nor <quantity> are specified, the current price to create books will be removed.
/setBookshelfData	bwbshelfdata	<delete/name/lore> \text> [more text]	bookswithoutborders.editbookshelf	Sets the name/lore for a bookshelf which is shown when peeking at its contents.
/setlore	bwblore	<new lore>	bookswithoutborders.setlore	Sets the lore of the item the player is holding. Insert the lore_line_separator character to force a new line ("~" by default)
/settitle	bwbtitle	<title>	bookswithoutborders.settitle	Sets the title of the book/item the player is holding
/unsignbook	bwbunsign	None	bookswithoutborders.unsign	Un-signs the book the player is holding

Permissions:

Grouped permissions

Node	Description
bookswithoutborders.*	Grants all permissions
bookswithoutborders.admin	Grants all permissions
bookswithoutborders.use	bookswithoutborders.use - Allows player to use commands to save/load/delete in their personal directory, and peeking at bookshelves if enabled
bookswithoutborders.alterbooks	Allows player to change books' data such as lore/title/author/generation/formatting and un-signing books, and setting bookshelf data

Single permissions

Node	Description
bookswithoutborders.addtitlepage	Allows player to add a blank title page to a book
bookswithoutborders.bypassauthoronlycopy	Allows player to ignore Author_Only_Copy config setting
bookswithoutborders.bypassauthoronlyunsign	Allows player to ignore Author_Only_Unsign config setting
bookswithoutborders.bypassauthoronlysave	Allows player to ignore Author_Only_Save config setting
bookswithoutborders.bypassbookprice	Allows player to ignore Price_to_create_book config setting
bookswithoutborders.clear	Allows player to clear the contents of the held writable book
bookswithoutborders.copy	Allows player to copy books
bookswithoutborders.decrypt	Allows player to decrypt books
bookswithoutborders.decrypt.agroup	Allows player to decrypt books group-encrypted for group "agroup"
bookswithoutborders.delete	Allows player to delete books from their personal directory
bookswithoutborders.deletepage	Allows player to delete a page from a book
bookswithoutborders.editbookshelf	Allows player to set name/lore for bookshelves, used for peeking
bookswithoutborders.encrypt	Allows player to encrypt books
bookswithoutborders.format	Allows a player to format a book
bookswithoutborders.give	Allows player to give another player one of their privately saved books
bookswithoutborders.givepublic	Allows a player to give another player a book from the public directory
bookswithoutborders.groupencrypt	Allows player to use group-based encryption
bookswithoutborders.load	Allows player to load books from their personal directory
bookswithoutborders.loadpublic	Allows player to load from the public directory
bookswithoutborders.peekbookshelf	Allows player to left-click a bookshelf to see the contents of the shelf
bookswithoutborders.reload	Allows player to reload this plugin
bookswithoutborders.save	Allows a player to save books to their personal directory
bookswithoutborders.savepublic	Allows player to save to the public directory
bookswithoutborders.setauthor	Allows player to set the author of the currently held book
bookswithoutborders.setbookprice	Allows player to set the cost of creating a book
bookswithoutborders.setgeneration	Allows player to change the generation of a book (Original, Copy, Copy of Copy)
bookswithoutborders.settitle	Allows player to set the title of the currently held book
bookswithoutborders.signs	Allows player to create signs that give/encrypt/decrypt books
bookswithoutborders.unsign	Allows player to un-sign books
bookswithoutborders.setlore	Allows player to set the lore of the currently held item
bookswithoutborders.preventadmindecryption	If use real encryption and prevent admin decryption options are enabled, allows player to disable admin decryption for a book

Signs

This plugin supports several custom signs with special functionality. Each plugin sign must have [BwB] on its first line.

Give sign

The give-sign must have [Give] on its second line. The third and fourth line contains the book to be loaded. This can either be a numerical id pointing to a publicly saved book, or the full text identifier of the book (book name, author).

Encrypt sign

The encrypt-sign must have [Encrypt] on its second line. The third line must contain the encryption key The fourth line can be empty or contain "dna" for dna-based encryption.

Decrypt sign

The decrypt sign must have [Decrypt] on its second line. The third line must contain the decryption key

Configuration options:

Option	Description
Max_Number_of_Duplicates	The maximum number of duplicates of a saved book allowed
Author_Separator	The separator used to separate the book title and the book author
Lore_line_separator	The separator used to denote a new line in the book/item lore
Books_for_new_players	A list of books given to new players the first time they join the server
Message_for_new_players	An optional message displayed to new players the first time they join the server
Price_to_create_book.Item_type	The item type used as currency for copying books. Use "Economy" to use money instead of items
Price_to_create_book.Required_quantity	The quantity of currency required to pay for each book produced
Admin_Auto_Decrypt	Whether any admin can decrypt any book regardless of the group it was encrypted for
Author_Only_Copy	Whether to only allow the author of a book to create copies
Author_Only_Unsign	Whether to only allow the author of a book to unsign it
Author_Only_Save	Whether to only allow saving a player's own books with /savebook
Format_Book_After_Signing	Whether to automatically format every book when it's signed
Change_Generation_On_Copy	Whether to display "COPY" or "COPY_OF_COPY" instead of "ORIGINAL" when a book is copied. This also uses the vanilla behavior where a copy of a copy or tattered book cannot be copied further.
Enable_Book_Peeking	Whether to enable hitting a chiseled bookshelf while sneaking to see the shelf's contents.
Use_Real_Encryption	Enables true AES encryption instead of the very fake legacy encryption. The encryption key is stored in the book file to allow admin decryption, but looking at the encrypted book in the file system, only reveals the encrypted pages. Note that real encryption might alter, corrupt or lose a book's contents, so don't use real encryption with books that have no backup in in-game book form or saved book form.
Allow_Prevent_Admin_Decryption	Allows players to disable storing the encryption key for an encrypted book. This is only usable for real encryption. This effectively disable admin decryption for the book. Providing the correct password is the only way to decrypt a book without a stored key. THIS IS A DANGEROUS OPTION!