From f62945a247c82965328679d99e928ad9245b2889 Mon Sep 17 00:00:00 2001 From: illegitimate-egg Date: Tue, 18 Mar 2025 23:14:53 +0000 Subject: [PATCH] Add a book --- .github/workflows/build.yml | 15 ++++----- .github/workflows/release.yml | 34 +++++++++++++++++++ book/.gitignore | 1 + book/book.toml | 6 ++++ book/src/README.md | 5 +++ book/src/SUMMARY.md | 22 +++++++++++++ book/src/extensions/README.md | 25 ++++++++++++++ book/src/extensions/functions/README.md | 3 ++ book/src/extensions/functions/logging.md | 27 ++++++++++++++++ book/src/extensions/types/Context.md | 29 +++++++++++++++++ book/src/extensions/types/Event.md | 25 ++++++++++++++ book/src/extensions/types/Metadata.md | 21 ++++++++++++ book/src/extensions/types/Player.md | 9 ++++++ book/src/extensions/types/PlayersWrapper.md | 36 +++++++++++++++++++++ book/src/extensions/types/README.md | 3 ++ book/src/extensions/types/Vec3.md | 16 +++++++++ book/src/extensions/types/Version.md | 16 +++++++++ book/src/extensions/types/WorldWrapper.md | 23 +++++++++++++ book/src/guide/configuration.md | 27 ++++++++++++++++ book/src/guide/extensions.md | 17 ++++++++++ justfile | 8 +++++ 21 files changed, 360 insertions(+), 8 deletions(-) create mode 100644 book/.gitignore create mode 100644 book/book.toml create mode 100644 book/src/README.md create mode 100644 book/src/SUMMARY.md create mode 100644 book/src/extensions/README.md create mode 100644 book/src/extensions/functions/README.md create mode 100644 book/src/extensions/functions/logging.md create mode 100644 book/src/extensions/types/Context.md create mode 100644 book/src/extensions/types/Event.md create mode 100644 book/src/extensions/types/Metadata.md create mode 100644 book/src/extensions/types/Player.md create mode 100644 book/src/extensions/types/PlayersWrapper.md create mode 100644 book/src/extensions/types/README.md create mode 100644 book/src/extensions/types/Vec3.md create mode 100644 book/src/extensions/types/Version.md create mode 100644 book/src/extensions/types/WorldWrapper.md create mode 100644 book/src/guide/configuration.md create mode 100644 book/src/guide/extensions.md diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index f4e0558..250f558 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -80,11 +80,10 @@ jobs: command: clippy args: -- -D warnings - # This package does not provide docs - # - name: Run rustdoc lints - # uses: actions-rs/cargo@v1 - # env: - # RUSTDOCFLAGS: "-D missing_docs -D rustdoc::missing_doc_code_examples" - # with: - # command: doc - # args: --workspace --all-features --no-deps --document-private-items + - name: Run rustdoc lints + uses: actions-rs/cargo@v1 + env: + RUSTDOCFLAGS: "-D missing_docs -D rustdoc::missing_doc_code_examples" + with: + command: doc + args: --workspace --all-features --no-deps --document-private-items diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 582f045..a418fd8 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -217,4 +217,38 @@ jobs: # - run: cargo publish --token ${CRATES_TOKEN} # env: # CRATES_TOKEN: ${{ secrets.CRATES_TOKEN }} + book: + name: Book + runs-on: ubuntu-latest + steps: + - name: Checkout sources + uses: actions/checkout@v2 + - name: Install nightly toolchain + uses: dtolnay/rust-toolchain@stable + with: + toolchain: nightly + + - uses: Swatinem/rust-cache@v2 + + - name: Install mdbook + uses: actions-rs/cargo@v1 + with: + command: install mdbook --no-default-features --features search --vers "^0.4" --locked + + - name: Build book + run: | + cd book + mdbook build + + - name: Setup Pages + uses: actions/configure-pages@v4 + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: 'mcrizzledizzle/book' + + - name: Deploy to GitHub pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/book/.gitignore b/book/.gitignore new file mode 100644 index 0000000..7585238 --- /dev/null +++ b/book/.gitignore @@ -0,0 +1 @@ +book diff --git a/book/book.toml b/book/book.toml new file mode 100644 index 0000000..57945cb --- /dev/null +++ b/book/book.toml @@ -0,0 +1,6 @@ +[book] +authors = ["illegitimate-egg"] +language = "en" +multilingual = false +src = "src" +title = "The Emporium of mcrizzledizzle Configuration and Plugin Development" diff --git a/book/src/README.md b/book/src/README.md new file mode 100644 index 0000000..c22e3ce --- /dev/null +++ b/book/src/README.md @@ -0,0 +1,5 @@ +# Introduction + +Mcrizzledizzle is an incredibly shitty yet somehow performant take on the classic Minecraft server. + +Here you can find information about writing plugins and configuring the server. diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md new file mode 100644 index 0000000..c10094f --- /dev/null +++ b/book/src/SUMMARY.md @@ -0,0 +1,22 @@ +# Summary + +- [Introduction](README.md) + +# User Guide +- [Configuration](guide/configuration.md) +- [Installing Extensions](guide/extensions.md) + +# Extension Development + +- [Extensions](./extensions/README.md) + - [Types](extensions/types/README.md) + - [Metadata](extensions/types/Metadata.md) + - [Version](extensions/types/Version.md) + - [Player](extensions/types/Player.md) + - [PlayersWrapper](extensions/types/PlayersWrapper.md) + - [WorldWrapper](extensions/types/WorldWrapper.md) + - [Context](extensions/types/Context.md) + - [Vec3](extensions/types/Vec3.md) + - [Event](extensions/types/Event.md) + - [Functions](extensions/functions/README.md) + - [Logging](extensions/functions/logging.md) diff --git a/book/src/extensions/README.md b/book/src/extensions/README.md new file mode 100644 index 0000000..12d72f7 --- /dev/null +++ b/book/src/extensions/README.md @@ -0,0 +1,25 @@ +# Extensions + +
+This guide is intended for experienced programmers, it is not a step by step guide. If in doubt check the official plugins. +
+ +The extensions interface uses the [rhai](https://rhai.rs/) programming language with some custom functionality to provide a full set of instructions for making extensions. + +## Extension Structure + +All extensions must provide a `metadata()` and `init(players, world)` function. mcrizzledizzle uses these internally to populate information about the extension as well as register any commands or event listeners that the extension might want to use. + +Example: +```rust + +fn metadata() { + Metadata("My Awesome Plugin's name!", "My Plugin's (less awesome) author", Version("1.0.0")) +} + +fn init(players, world) { + ... +} +``` + +The `Metadata` struct expects a name string, description string and valid `Version()`. The Version should be a valid [semantic version](https://semver.org/) otherwise the plugin will not load correctly. diff --git a/book/src/extensions/functions/README.md b/book/src/extensions/functions/README.md new file mode 100644 index 0000000..f54e147 --- /dev/null +++ b/book/src/extensions/functions/README.md @@ -0,0 +1,3 @@ +# Functions + +These functions can be called directly from an extension. They aren't tied to any structure. diff --git a/book/src/extensions/functions/logging.md b/book/src/extensions/functions/logging.md new file mode 100644 index 0000000..9edfabd --- /dev/null +++ b/book/src/extensions/functions/logging.md @@ -0,0 +1,27 @@ +# Logging + +These functions all go directly to the server logs, as you'd expect. They all take a message and handle the rest for you. + +## info +Signature: +```rust +fn info(msg: String) +``` + +## warn +Signature: +```rust +fn warn(msg: String) +``` + +## error +Signature: +```rust +fn error(msg: String) +``` + +## debug +Signature: +```rust +fn debug(msg: String) +``` diff --git a/book/src/extensions/types/Context.md b/book/src/extensions/types/Context.md new file mode 100644 index 0000000..c051ba8 --- /dev/null +++ b/book/src/extensions/types/Context.md @@ -0,0 +1,29 @@ +# Context + +The context is a struct that you can create to tell the server about what your plugin wants to do. You must create one if you want to register commands or add event listeners. + +```rust +struct Context { + commands: HashMap, + event_listener: HashMap, +}; +``` + +## Implementations + +### register_command +```rust +fn register_command(&mut self, name: String, callback: FnPtr) +``` + +This is how you can register commands on the server. Your `callback`` likely should be a closure as you almost certainly want to capture information from the environment. + +### add_event_listener +```rust +fn add_event_listener(&mut self, event: &str, callback: FnPtr) +``` + +This is how event listeners are created. `callback`` should probably be a closure because you almost certainly want information from the environment. The currently available event types are: + +- `"block_break"` This is fired when a black is broken. This is interruptible. +- `"player_leave"` This is fired when a player leaves the server. This is not interruptible. diff --git a/book/src/extensions/types/Event.md b/book/src/extensions/types/Event.md new file mode 100644 index 0000000..7e3ac4a --- /dev/null +++ b/book/src/extensions/types/Event.md @@ -0,0 +1,25 @@ +# Event + +Events are structs that tell the extension about changes in server or player state. + +```rust +struct Event { + player: u8, + position: Vec3, + selected_block: u8, + is_cancelled: bool, +} +``` + +Only certain parts of the struct are used for certain events. Since events are only returned to their corresponding handler, the event type is not provided in the struct. Available event types are: + +- `"block_break"` This is fired when a black is broken. This is interruptible. +- `"player_leave"` This is fired when a player leaves the server. This is not interruptible. + +## Implementations +### cancel +```rust +fn cancel(&mut self) +``` + +This sets is_cancelled to true, cancelling interruptible events, like block breaking. diff --git a/book/src/extensions/types/Metadata.md b/book/src/extensions/types/Metadata.md new file mode 100644 index 0000000..114c300 --- /dev/null +++ b/book/src/extensions/types/Metadata.md @@ -0,0 +1,21 @@ +# Metadata + +This type tells mcrizzledizzle important imformation about the plugin. + +The struct signature looks like this: + +```rust +struct Metadata { + name: String, + author: String, + version: Version, +}; +``` + +It should be used inside the metadata function like so: + +```rust +fn metadata() { + Metadata("Example Name", "Example Description", Version("1.0.0")) +} +``` diff --git a/book/src/extensions/types/Player.md b/book/src/extensions/types/Player.md new file mode 100644 index 0000000..7e5643a --- /dev/null +++ b/book/src/extensions/types/Player.md @@ -0,0 +1,9 @@ +# Player + +The player struct probably shouldn't be modified by plugins, in any case, here's the struct definition: + +```rust +struct Player { + id: u8, +}; +``` diff --git a/book/src/extensions/types/PlayersWrapper.md b/book/src/extensions/types/PlayersWrapper.md new file mode 100644 index 0000000..58fdbf0 --- /dev/null +++ b/book/src/extensions/types/PlayersWrapper.md @@ -0,0 +1,36 @@ +# PlayersWrapper + +The PlayersWrapper struct wraps around the server's Player Data mutex. It provides a friendly interface for extensions. + +```rust +struct PlayersWrapper(Arc>); +``` + +You cannot instantiate a PlayersWrapper yourself, it is passed as the first argument of init() and can then be called upon from there. + +## Implementations + +### send_message +```rust +fn send_message( + self, + player: u8, + message: String, +) +``` + +This function expects a player id and a message to be passed as arguments. Keep in mind that the length limit for messages is 64 characters. + +### send_all +```rust +fn send_all(self, message: String) +``` + +This function is like `send_message` except it sends the message to all connected players. + +### username +```rust +fn username(self, player: u8) +``` + +This function gets the username of a player from their id. diff --git a/book/src/extensions/types/README.md b/book/src/extensions/types/README.md new file mode 100644 index 0000000..1a73a58 --- /dev/null +++ b/book/src/extensions/types/README.md @@ -0,0 +1,3 @@ +# Types + +This contains a big list of structs and their available functions to call from rhai. diff --git a/book/src/extensions/types/Vec3.md b/book/src/extensions/types/Vec3.md new file mode 100644 index 0000000..3c79388 --- /dev/null +++ b/book/src/extensions/types/Vec3.md @@ -0,0 +1,16 @@ +# Vec3 + +Vec3s are used to store positions of blocks and players. + +```rust +struct Vec3 { + pub x: i16, + pub y: i16, + pub z: i16, +} +``` + +You can create one using the constructor: +```rust +Vec3(x: i64, y: i64, z: i64) +``` diff --git a/book/src/extensions/types/Version.md b/book/src/extensions/types/Version.md new file mode 100644 index 0000000..3e6f09a --- /dev/null +++ b/book/src/extensions/types/Version.md @@ -0,0 +1,16 @@ +# Version + +This type is stored internally as a complete semantic version, an easy constructor is provided that converts a valid semver to a set of parts, providing a display function. + +Struct signature: +```rust +struct Version { + major: u16, + minor: u16, + patch: u16, + prerelease: String, + build: String, +}; +``` + +Usually it would be used along with [Metadata](./Metadata.md) to setup an extension. diff --git a/book/src/extensions/types/WorldWrapper.md b/book/src/extensions/types/WorldWrapper.md new file mode 100644 index 0000000..961d824 --- /dev/null +++ b/book/src/extensions/types/WorldWrapper.md @@ -0,0 +1,23 @@ +# WorldWrapper + +The WorldWrapper struct wraps around the server's World Data mutex. It provides a friendly interface for extensions. + +```rust +struct WorldWrapper(Arc>); +``` + +You cannot instantiate a WorldWrapper yourself, it is passed as the second argument of init() and can be called upon from there. + +## Implementations + +### set_block +```rust +fn set_block( + self, + players_wrapper: PlayersWrapper, + position: Vec3, + block_type: u8, +) +``` + +This functions sets a block at the desired position. Since it uses the player data internally it requires the PlayersWrapper. diff --git a/book/src/guide/configuration.md b/book/src/guide/configuration.md new file mode 100644 index 0000000..b4077c6 --- /dev/null +++ b/book/src/guide/configuration.md @@ -0,0 +1,27 @@ +# Configuration + +The config file is a regular toml file that is placed in the same directory that the program is run from. There's an example [in the repo](https://github.com/illegitimate-egg/mcrizzledizzle/blob/master/rte/config.toml) where all the available parameters have been set. + +The config is split into two parts, one relating to server operations and another relating to world operations. + +## [server] +Under server you can set the port, motd and name of the server. + +```toml +name = "server of ire" +motd = "Message of the day" # There's a 64 character limit on these so be careful (including colour escapes) +port = 25565 # default mc port +max_players = 255 # 255 is the maximum number +``` + +## [world] +For the world you can set the path and size (for generation) of the world. + +```toml +world = "world.wrld" # This is a custom world format that will not work with other servers + +# Generator settings +size_x = 64 +size_y = 32 +size_z = 64 +``` diff --git a/book/src/guide/extensions.md b/book/src/guide/extensions.md new file mode 100644 index 0000000..920f3b3 --- /dev/null +++ b/book/src/guide/extensions.md @@ -0,0 +1,17 @@ +# Installing Extensions + +Extensions are distributed as `rhai` files. As with all software that you install on your computer, it's important to make sure that you trust the program that you're running as they are quite powerful. + +Extensions go into the auto-generated extension folder. Some official examples can be found in the [extensions](https://github.com/illegitimate-egg/mcrizzledizzle/tree/master/rte/extensions) folder on the repository: + +- `fill.rhai` - A worldedit like fill command +- `ping-pong.rhai` - A very basic command, responds when you using /ping +- `utils.rhai` - A set of utilities used for development of the extension interface + +To see what commands are available you can use the `/help` command. To see what extensions are installed and their versions you can use the `/extensions` command. + +## Other extensions + +There are some third-party extensions that are officially endorsed by mcrizzledizzle. + +- [williamist/rizzle-extensions](https://github.com/williamistGitHub/rizzle-extensions) - A great (set of) extension(s) written by a contributor diff --git a/justfile b/justfile index 91407c7..8c06780 100644 --- a/justfile +++ b/justfile @@ -1,8 +1,16 @@ alias r := run alias t := test +alias b := build run: cd rte; cargo run test: cargo test + +build: + mdbook build + +install_book_toolchain: + cargo install mdbook --locked --version 0.4.47 + # cargo install --locked --path packages/mdbook-trpl # mdbook repo needed for this one lmao