EpicKnarvik97/Books-Without-Borders
1
0
Fork 0
Code Issues Pull Requests Projects Releases 12 Wiki Activity
Files
e9e4836a167e46ac68c8d7daf929a1e13db2f379
Books-Without-Borders/README.md
EpicKnarvik97 1437739fe3
All checks were successful
EpicKnarvik97/Books-Without-Borders/pipeline/head This commit looks good
Details
Cleans the config file, and properly migrates existing configurations #16
2025-09-05 22:39:32 +02:00

197 lines
34 KiB
Markdown
Raw Blame History

# 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](https://dev.bukkit.org/projects/books-without-borders). 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 |
| /createbwbsign | bwbSign | \<give/encrypt/decrypt> \[book identifier/password] \[encryption style] | bookswithoutborders.signs | Creates a books without borders sign, as specified. This command is not restricted by the normal sign line text limit, and can load books with any name length for give signs. Encrypt and decrypts signs can be created manually just fine, but using this avoids manual formatting. |
| /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.<group>" 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> \[title] ... \[setDisplayName (true/false)] | bookswithoutborders.settitle | Sets the title of the book or the display name of the item the player is holding. Add a true at the end (`/settitle some title true`) to set a book's display name instead of its title. |
| /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.
It is recommended to use the `createbwbsign` command over manual creation for give signs, as it bypasses the text
limit, and specifying books by index is really unstable. If you have some other plugin for editing sign lines, you can
first specify the visual text on the sign's third and fourth line, then add a `:` and put the full book name after that.
#### 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). Use the `createbwbsign` command in order to specify book names of any length.
#### 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 |
|------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| language | The language to use. Only "en" is built-in, but custom languages can be added. | |
| limit.maxDuplicates | The maximum number of duplicates of an unsigned saved book allowed. |
| separator.titleAuthor | The separator used to separate the book title and the book author. It is recommended to change this to some rarely used character such as `¤`, and migrating existing books with `/migrateBooks`. |
| separator.loreLine | The separator used to denote a new line in the book/item lore. It is also used for `/addbooktitlepage` for differentiating between the header and description. |
| firstJoin.booksToGive | A list of books given to new players the first time they join the server. Use the full file name with extension. The book must be in the public directory. |
| firstJoin.welcomeMessage | An optional message displayed to new players the first time they join the server. |
| bookPrice.itemType | The item type used as currency for copying books. Use "Economy" to use money instead of items. |
| bookPrice.quantity | The quantity of currency required to pay for each book produced. You can use decimals if you use economy, but decimals will be ignored for item cost. |
| authorRestricted.copy | Whether to only allow the author of a book to create copies |
| authorRestricted.unsign | Whether to only allow the author of a book to unsign it |
| authorRestricted.save | Whether to only allow saving a player's own books with `/savebook` |
| functionality.formatBookOnSigning | Whether to automatically format every book when it's signed, if the player has the necessary permission. |
| functionality.changeBookGenerationOnCopy | Whether to set the generation to "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. |
| functionality.enableBookPeeking | Whether to enable hitting a chiseled bookshelf while sneaking to see the shelf's contents. |
| encryption.allowAdminBypass | Whether any admin can decrypt any book regardless of the group it was encrypted for, and decrypt normally encrypted books without having to supply a password. |
| encryption.useRealEncryption | 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. |
| encryption.allowAdminBypassBlocking | 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! |
## Language customization
User-facing messages and most formatting is customizable. If you place a strings.yml file in the plugin folder, it will
take priority over built-in languages. If you want to change strings, look at
BooksWithoutBorders/src/main/resources/strings.yml for the proper keys. All strings have the format:
ENUM: "Displayed string". The enum must be identical as it defines which string you have changed. All strings belonging
to a language are beneath the language code and indented with two spaces.
The easiest way to add a new language is to copy an existing language and paste it into your custom strings.yml and
change strings as necessary. If you don't include all strings, the remaining will use the built-in English translation.
Remember to change the language code to whichever you use for your custom language.
Reference in New Issue View Git Blame Copy Permalink