StandardBooks #

A PaperMC plugin that publishes and reads in-game books on the AT Protocol via Standard.site.

---

Requirements #

• PaperMC 26.1.2+ (api-version 1.21)
• Java 26+
• Optional: PlaceholderAPI for placeholder expansion

---

Installation #

1. Download the latest release JAR from the releases page
2. Place the JAR in your server's plugins/ folder
3. Restart the server
4. Edit plugins/StandardBooks/config.yml to configure the OAuth callback server
5. Run /standardbooks reload to apply changes

---

Configuration #

plugins/StandardBooks/config.yml:

enabled: true

oauth:
  port: 8765
  callback-path: /callback
  external-url: "" # e.g. https://mc.example.com:8765

publication:
  auto-create: true
  default-name: "{player}'s Minecraft Books"
  default-url: ""

books:
  max-pages: 100
  max-chars-per-page: 1024
  auto-publish-on-sign: false

bstats-enabled: true

OAuth Setup #

The plugin runs an embedded HTTP server to receive OAuth callbacks. The external-url must be publicly accessible from the player's browser. If left blank, http://localhost:{port} is used (works only for single-player or local servers).

For production servers, set external-url to your server's public address and ensure the port is forwarded or tunnelled.

---

Commands #

Command	Permission	Description
/sb login <handle>	standardbooks.use	Connect your AT Protocol account via OAuth
/sb logout	standardbooks.use	Disconnect your account
/sb publish	standardbooks.use	Publish the book you're holding to AT Protocol
/sb browse [page]	standardbooks.use	Browse published books in a chest GUI
/sb read <uri>	standardbooks.use	Read a book by its AT URI
/sb list	standardbooks.use	List your published books
/sb delete <uri>	standardbooks.use	Delete a book you've published
/sb update <uri>	standardbooks.use	Update a published book with the one you're holding
/sb status	standardbooks.use	Show your connection status
/sb help	standardbooks.use	Show help
/sb reload	standardbooks.admin	Reload config

---

How It Works #

Publishing #

1. Player writes a book in-game (book & quill, signed)
2. Player runs /sb publish while holding the book
3. The plugin converts the book to a site.standard.document record:
   • Book title → document title
   • Book pages → content (structured site.standard.content.standardbooks format)
   • Book text → textContent (plain text with --- page delimiters)
   • Player identity → contributors with role author
   • Tags: minecraft, standardbooks
4. The record is published to the player's PDS via com.atproto.repo.createRecord

Reading #

1. Player runs /sb browse to open a chest GUI
2. Book items show title and author
3. Clicking a book opens it for reading in-game
4. Alternatively, /sb read <at-uri> reads a specific book

Interoperability #

StandardBooks reuses the site.standard.document lexicon directly. Books published from Minecraft appear in Inkwell on iOS, and books written in Inkwell appear in Minecraft. The textContent field ensures plain-text fallback for any Standard.site client.

Extended Book Limits #

Vanilla Minecraft limits books to 50 pages, 256 characters per page. StandardBooks extends these limits (configurable, defaults to 100 pages, 1024 chars/page) since the plugin operates server-side and is not bound by vanilla constraints.

---

Placeholders #

Placeholder	Description
%standardbooks_logged_in%	true if the player is logged in, false otherwise
%standardbooks_handle%	Player's AT Protocol handle, or none
%standardbooks_did%	Player's DID, or none

---

Build #

./gradlew build

Output: build/libs/StandardBooks-0.1.0.jar

---

Tech Stack #

• Kotlin 2.3.21
• PaperMC API 26.1.2
• atproto-kotlin SDK (runtime, models, oauth)
• Ktor 3.1.2 (embedded OAuth callback server)
• kotlinx.serialization 1.7.3
• Shadow plugin for shaded JAR
• MiniMessage for text formatting
• bStats for anonymous metrics

---

Support #

If you find this project useful, consider supporting its development:

License #

AGPL-3.0-only