Books-Without-Borders/README.md

# Books Without Borders

This is an attempt at a rewrite of the Books Without Borders plugin. This rewrite uses the source code given
at [the original bukkit page](https://dev.bukkit.org/projects/books-without-borders). I'm not planning any new features
at this time. The only goal is to make it 1.17.1 compliant, but I'll make the code more maintainable along the way.
While the original version still works, it's using a lot of depreciated function calls which will most likely break in
the 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 .txt or .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
- 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!

#### Group encryption

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

### Commands:

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

- /bookswithoutborders - Displays information about commands (and permissions if the user has bookswithoutborders.admin)
- /copybook <# of copies> - Copies the book the player is holding
- /decryptbook <key> - Decrypts the book the player is holding. "key" is required and MUST be IDENTICAL to the key used
  to encrypt the held book
- /deletebook <file name or number> - Deletes the specified file in the player's directory
- /deletepublicbook <file name or number> - Same as deletebook, but deletes files in the public directory
- encryptbook <key> \[encryption style] - 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" or ""
- /formatbook - Formats the held written book (converts color and formatting codes to the corresponding formatted text)
- /givebook <file name or number> <playername> \[# of copies (num)] \[signed (true/false)] - Gives the selected player a
  book from your personal directory
- /givepublicbook <file name or number> <playername> \[# of copies (num)] \[signed (true/false)] - Same as givebook, but
  uses books from the public directory
- /loadbook <file name or number> \[# of copies] \[signed (true/false)] - 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 <file name or number> \[# of copies] \[signed (true/false)] - Same as loadbook, but views files in the
  public directory
- /reload - Reloads BwB's configuration file
- /savebook \[overwrite (true/false)] - 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 \[overwrite (true/false)] - Same as savebook, but saves files in the public directory
- /setbookauthor <author> - Sets the author of the book the player is holding
- /setbookgeneration <generation> - Sets the generation (ORIGINAL, COPY_OF_ORIGINAL, COPY_OF_COPY, TATTERED)
- /setbookprice <item/eco> <quantity> - 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.
- /setlore <new lore> - Sets the lore of the item the player is holding. Insert the lore_line_separator character to
  force a new line ("~" by default)
- /settitle <title> - Sets the title of the book/item the player is holding
- /unsignbook - Un-signs the book the player is holding

### Permissions:

- bookswithoutborders.* - Grants all permissions
- bookswithoutborders.admin - Grants all permissions
- bookswithoutborders.use - Allows player to use commands to save/load/delete in their personal directory
- bookswithoutborders.alterbooks - Allows player to change books' data such as lore/title/author/formatting and
  unsigning books
- bookswithoutborders.reload - Allows player to reload this plugin
- bookswithoutborders.format - Allows a player to format a book
- bookswithoutborders.save - Allows a player to save books to their personal directory
- bookswithoutborders.load - Allows player to load books from their personal directory
- bookswithoutborders.delete - Allows player to delete books from their personal directory
- bookswithoutborders.unsign - Allows player to un-sign books
- bookswithoutborders.copy - Allows player to copy books
- bookswithoutborders.loadpublic - Allows player to load from the public directory
- bookswithoutborders.savepublic - Allows player to save to the public directory
- bookswithoutborders.encrypt - Allows player to encrypt books
- bookswithoutborders.groupencrypt - Allows player to use group-based encryption
- bookswithoutborders.decrypt - Allows player to decrypt books
- bookswithoutborders.decrypt.agroup - Allows player to decrypt books group-encrypted for group "agroup"
- bookswithoutborders.signs - Allows player to create signs that give/encrypt/decrypt books
- 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.settitle - Allows player to set the title of the currently held book
- bookswithoutborders.setauthor - Allows player to set the author of the currently held book
- bookswithoutborders.setlore - Allows player to set the lore of the currently held item
- bookswithoutborders.bypassauthoronlycopy - Allows player to ignore Author_Only_Copy config setting
- bookswithoutborders.bypassauthoronlyunsign - Allows player to ignore Author_Only_Unsign config setting
- bookswithoutborders.bypassbookprice - Allows player to ignore Price_to_create_book config setting
- 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)

### 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:

- Save_Books_in_Yaml_Format - Whether to use YAML for saved books instead of just storing them as text
- 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
- 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 cannot be copied further.