Add a book

.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

.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

book/.gitignore

@@ -0,0 +1 @@
+book

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"

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.

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)

book/src/extensions/README.md

@@ -0,0 +1,25 @@
+# Extensions
+
+<div class="warning">
+This guide is intended for experienced programmers, it is not a step by step guide. If in doubt check the <a href="https://github.com/illegitimate-egg/mcrizzledizzle/tree/master/rte/extensions">official plugins</a>.
+</div>
+
+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.

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.

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)
+```

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<String, FnPtr>,
+  event_listener: HashMap<EventType, FnPtr>,
+};
+```
+
+## 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.

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.

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"))
+}
+```

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,
+};
+```

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<Mutex<[Player; 255]>>);
+```
+
+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.

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.

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)
+```

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.

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<Mutex<World>>);
+```
+
+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.

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
+```

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

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