From b63b894fde861ed0850e7c38cdb84f2c9c68d659 Mon Sep 17 00:00:00 2001 From: gegy1000 Date: Sun, 29 Nov 2020 22:37:09 +0200 Subject: [PATCH] Add README and documentation --- README.md | 126 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..1c7a3b8 --- /dev/null +++ b/README.md @@ -0,0 +1,126 @@ +# Leukocyte +Leukocyte is a simple world protection mod for Fabric providing optional integration with [player-roles](https://github.com/Gegy/player-roles/). + +The basis of world protection with leukocyte is an "authority". An authority is responsible for applying specific rules +to players within it. An authority has a unique name, as well as a priority ("level"), and set of player exclusions. + +### creating authorities +To create an empty authority, run: `/protect add `. +Alternatively, an authority can be created to apply within a specific area like: + - `/protect add with universe` (applies universally) + - `/protect add with ` (applies within a specific dimension) + - `/protect add with ` (applies within a cuboid between two block coordinates) + +An authority can be later removed with `/protect remove `. + +### setting rules +Leukocyte provides various rules that can be applied within authorities. These rules are: + - `break` controls whether players can break blocks + - `place` controls whether players can place blocks + - `block_drops` controls whether blocks drop items when broken + - `interact_blocks` controls whether players can interact with blocks + - `interact_entities` controls whether players can interact with entities + - `interact` controls global interaction over blocks and entities + - `attack` controls whether players can attack other entities + - `pvp` controls whether players can attack other players + - `portals` controls whether players can construct portals + - `crafting` controls whether players can craft items + - `fall_damage` controls whether players should receive fall damage + - `hunger` controls whether players will become hungry + - `throw_items` controls whether players can throw items from their inventory + +To set a rule as `allow` or `deny` on an authority, use `/protect set rule `. + +For example: `/protect set example place deny` will disallow block placement within the authority named `example`. + +### making shapes +Often, you may want to protect an area with a weird shape that is not just a simple box. +To achieve this, it is possible to combine multiple simple shapes into a more complex one which will be used to apply rules. + +To start, run: `/protect shape start`. This will begin the construction of a shape. +Next, to add primitives to this shape, run: + - `/protect shape add universe` to add the universe into this shape + - `/protect shape add ` to add a dimension into this shape + - `/protect shape add ` to add a cuboid between two block coordinates into this shape + +These commands can be run multiple times to compose your shape. + +Once you have finished composing a shape, you can run: `/protect shape finish to `. +This will add a shape with the given name to the given authority. + +This shape can be removed in the future with `/protect shape remove from `. + +### setting levels +When dealing with multiple authorities, you may want one to take priority over another. +For example, you may want a global authority to disallow griefing everywhere *except* specific areas for building. + +This is where levels come in: a level is just any number, where a higher level indicates higher priority, and a lower level indicates lower priority. +Given an authority with a level of -1, an overlapping authority with a level of 10 will override the rules of the first. + +Levels can be set on an authority with: `/protect set level `. + +### adding exclusions +It may not be desirable for the rules of an authority to apply to everyone. +In this case, it is possible to exclude specific players, or entire [roles](https://github.com/Gegy/player-roles/) from being affected by a given authority. + +This is achieved through running: `/protect exclusion add player ` or `/protect exclusion add role `. + +These exclusions can additionally be later removed with `/protect exclusion remove`. + +### putting it together: an example +That was a lot of things! Let's put this knowledge together on a simple example. + +Our example server will want to have global grief protection, except in our survival dimension and free-build areas. +We additionally want to be able to exclude certain players from building in the free-build areas by use of a role. + +Let's consider the two dimensions: `minecraft:overworld` and `example:survival`, as well as the role `builders`. + +First, let's create an authority named `global`. Since we will mostly want protection everywhere, it makes sense to +globally apply protection and then specifically override this in specific areas. + - `/protect add global with universe` + +Next, we can set the rules on this authority: + - `/protect set rule global place deny` + - `/protect set rule global break deny` + +Done! Now, let's override this behavior in our survival dimension. + - `/protect add survival with example:survival` + - `/protect set rule survival place allow` + - `/protect set rule survival break allow` + +But wait..! How will the mod know to apply the rules of `global` or `survival`, since `global` also applies in the survival dimension? +Here, we can make use of levels: the default level for an authority is `0`, and a larger value means higher priority. +So: let's set the level of our `global` authority to `-1` such that anything we add in the future overrides it by default. + - `/protect set level global -1` + +Now we can similarly add our free build areas as exclusions too! Let's say we have two free build areas, creatively named `free_build_1` and `free_build_2`. +First, we should create an empty authority that applies to both of them, since they both have the same rules. + - `/protect add free_build` + - `/protect set rule free_build place allow` + - `/protect set rule free_build break allow` + +Next, let's compose the shape for `free_build_1`: + - `/protect shape start` + - `/protect shape add -10 0 -10 10 255 10` + ... and add it to our authority + - `/protect shape finish free_build_1 to free_build` + +And repeat the same for `free_build_2`: + - `/protect shape start` + - `/protect shape add -100 0 -10 90 255 10` + ... and add it to our authority + - `/protect shape finish free_build_2 to free_build` + +Done! Now the free-build areas should be editable by any player- except, we want to create exclusions such that we can 'ban' players from the areas. +Let's do that with a `free_build_banned` role: + - `/protect exclusion add free_build role free_build_banned` + +With that, all our protection should be set up nicely! :) + +### testing! querying and checking rules +Okay, we've set up authorities, but how can we easily check which rules are set and by what? + +A few commands may come in handy: + - `/protect test`: tests all the rules that apply at a given location, and shows from which authority they originate + - `/protect list`: lists all authorities in the world + - `/protect display `: displays the rules and shape of the given authority