sr: add proper wiki

Author: rlnt

wikis/summoningrituals/.vitepress/config.mts

@@ -7,10 +7,37 @@ export default defineConfig({
     themeConfig: {
         sidebar: [
             {
-                text: "Intro",
+                text: "Introduction",
                 items: [
-                    { text: "Introduction", link: "/" },
-                    { text: "Example", link: "/example" },
+                    { text: "Getting Started", link: "/" },
+                    { text: "What's New", link: "/whats_new" },
+                    { text: "Usage for Players", link: "/usage_for_players" },
+                    { text: "Usage for Developers", link: "/usage_for_developers" },
+                    { text: "Full Example", link: "/full_example" },
+                ],
+            },
+            {
+                text: "Recipe",
+                items: [
+                    { text: "Basics", link: "/recipe/basics" },
+                    { text: "Inputs", link: "/recipe/inputs" },
+                    { text: "Outputs", link: "/recipe/outputs" },
+                    { text: "Conditions", link: "/recipe/conditions" },
+                ],
+            },
+            {
+                text: "Events",
+                items: [
+                    { text: "Event Overview", link: "/event/overview" },
+                    { text: "Summoning Start", link: "/event/start" },
+                    { text: "Summoning Complete", link: "/event/complete" },
+                ],
+            },
+            {
+                text: "Bindings",
+                items: [
+                    { text: "Summoning Item", link: "/binding/item" },
+                    { text: "Summoning Entity", link: "/binding/entity" },
                 ],
             },
         ],

wikis/summoningrituals/docs/binding/entity.md

@@ -0,0 +1,3 @@
+# Summoning Entity
+
+Work in progress!

wikis/summoningrituals/docs/binding/item.md

@@ -0,0 +1,3 @@
+# Summoning Item
+
+Work in progress!

wikis/summoningrituals/docs/binding/time.md

@@ -0,0 +1,3 @@
+# Summoning Time
+
+Work in progress!

wikis/summoningrituals/docs/event/complete.md

@@ -0,0 +1,62 @@
+# Summoning Complete Event
+
+This event allows you to invoke logic when a ritual is completed.
+
+**It is a server event and reloadable.** Keep in mind that server events have to be located inside the `kubejs/server_scripts` folder.
+
+## Overview
+
+The event is fired after a ritual has successfully been performed. This means the altar no longer contains the initiator item, the item inputs, and all entity inputs are sacrificed.
+
+At this point, the altar has already invoked the output commands and spawned the item and entity outputs. You can access the spawned outputs within the event.
+
+-   access in a server script via: `SummoningRituals.complete`
+-   properties
+    -   `level`
+        -   type: `ServerLevel`
+        -   description: the level where the ritual completed
+    -   `pos`
+        -   type: `BlockPos`
+        -   description: the position of the altar block
+    -   `recipeInfo`
+        -   type: `RecipeInfoContainer`
+        -   description: a container object holding information about the recipe that was processed
+        -   container properties:
+            -   `recipeId` - the ID of the recipe that was processed as `ResourceLocation`
+            -   `recipe` - the `AltarRecipe` that was processed
+            -   `inputEntities` - an `Entity` collection holding all entities that were sacrificed (already dead)
+            -   `outputItems` - an `ItemEntity` collection holding all item outputs that were spawned
+            -   `outputEntities` - an `Entity` collection holding all entity outputs that were spawned
+    -   `player`
+        -   type: `ServerPlayer` (nullable)
+        -   description: the player who inserted the initiator item; may be null if the ritual was started by automation
+
+## Event Listener
+
+To access the event, the first thing you need to do is to open an event listener for the `complete` event in a server script.
+
+```js
+SummoningRituals.complete(event => {
+    // ...
+})
+```
+
+## Example
+
+```js
+SummoningRituals.complete(event => {
+    const { level, pos, recipeInfo, player } = event
+
+    // check for a specific recipe
+    if (recipeInfo.recipeId.toString() !== "kubejs:forbidden_ritual") {
+        return
+    }
+
+    // if an item output is a sword, enchant it with sharpness 3
+    for (let itemEntity of recipeInfo.outputItems) {
+        if (itemEntity.item.id.contains("sword")) {
+            itemEntity.item.enchant("minecraft:sharpness", 3)
+        }
+    }
+})
+```

wikis/summoningrituals/docs/event/overview.md

@@ -0,0 +1,6 @@
+# Event Overview
+
+| Name                              | Server | Cancelable |
+| --------------------------------- | :----: | :--------: |
+| [Summoning Start](start.md)       |   ✓    |     ✓      |
+| [Summoning Complete](complete.md) |   ✓    |            |

wikis/summoningrituals/docs/event/start.md

@@ -0,0 +1,64 @@
+# Summoning Start Event
+
+This event allows you to invoke logic when a ritual is started and to optionally cancel the ritual start.
+
+**It is a server event and reloadable.** Keep in mind that server events have to be located inside the `kubejs/server_scripts` folder.
+
+## Overview
+
+The event is fired after a valid recipe is found but before the ritual is started. This means the altar contains all required item inputs, all required entity inputs are within the sacrifice zone around the altar, and all conditions match.
+
+At this point, the altar block also contains the initiator item and is about to start the ritual.
+
+-   access in a server script via: `SummoningRituals.start`
+-   properties
+    -   `level`
+        -   type: `ServerLevel`
+        -   description: the level where the ritual is about to happen
+    -   `pos`
+        -   type: `BlockPos`
+        -   description: the position of the altar block
+    -   `recipeInfo`
+        -   type: `RecipeInfoContainer`
+        -   description: a container object holding information about the recipe that is about to be processed
+        -   container properties:
+            -   `recipeId` - the ID of the recipe that is about to be processed as `ResourceLocation`
+            -   `recipe` - the `AltarRecipe` that is about to be processed
+            -   `inputEntities` - an `Entity` collection holding all entities that are about to be sacrificed
+    -   `player`
+        -   type: `ServerPlayer` (nullable)
+        -   description: the player who inserted the initiator item; may be null if the ritual was started by automation
+-   functions
+    -   `cancel()`
+        -   description: cancels the ritual start; this will reset the altar and drop the initiator item
+
+## Event Listener
+
+To access the event, the first thing you need to do is to open an event listener for the `start` event in a server script.
+
+```js
+SummoningRituals.start(event => {
+    // ...
+})
+```
+
+## Example
+
+```js
+SummoningRituals.start(event => {
+    const { level, pos, recipeInfo, player } = event
+
+    // check for a specific recipe
+    if (recipeInfo.recipeId.toString() !== "kubejs:forbidden_ritual") {
+        return
+    }
+
+    // cancel the ritual if one of the entity inputs has less than their max health
+    for (let entity of recipeInfo.inputEntities) {
+        if (player) {
+            player.tell("Ritual cancelled: Entity health too low")
+        }
+        event.cancel()
+    }
+})
+```

wikis/summoningrituals/docs/example.md …is/summoningrituals/docs/full_example.mdwikis/summoningrituals/docs/example.md renamed to wikis/summoningrituals/docs/full_example.md wikis/summoningrituals/docs/example.md renamed to wikis/summoningrituals/docs/full_example.md

@@ -1,3 +1,7 @@
+# Full Example
+
+This page shows a full example of a very complex altar recipe with all available functions. This example only shows how it looks when you combine the logic described on all other pages. It won't explain any concepts. For that, please read the [usage for developers page](usage_for_developers.md) and navigate from there.
+
 ```js
 ServerEvents.recipes(event => {
     event.recipes.summoningrituals
@@ -25,7 +29,7 @@ ServerEvents.recipes(event => {
             SummoningEntity.output("blaze", 2)
                 .data({
                     Health: 50,
-                    Attributes: [{ Name: "generic.max_health", Base: 50 }],
+                    attributes: [{ id: "generic.max_health", base: 50 }],
                 })
                 .offset([1, 2, 2])
                 .tooltip([Text.of("50 health").aqua()]),
@@ -45,10 +49,10 @@ ServerEvents.recipes(event => {
                 .spread([4, 2, 4])
                 .data({
                     Health: 50,
-                    Attributes: [{ Name: "generic.max_health", Base: 50 }],
+                    attributes: [{ id: "generic.max_health", base: 50 }],
                 }),
         ])
-        .commands(["say Hi", "/say Hello"]) // doesn't matter if with slash or not
+        .commands(["say Foo", "/say Bar"])
         .sacrificeZone([3, 3, 3])
         .conditions(conditions =>
             conditions

wikis/summoningrituals/docs/index.md

@@ -1,7 +1,16 @@
 # Getting Started
 
-> [!WARNING]
-> This wiki is still work in progress! It just lists all examples for now without further explanation.
+> [!WARNING] NOTE
+> This wiki is for Summoning Rituals for Minecraft 1.21.1 and above. For previous versions, please refer to the [old wiki](https://github.com/AlmostReliable/summoningrituals/wiki).
+
+Summoning Rituals is intended to be used as a progression mod in modpacks. It adds an Altar block you can use to perform summoning rituals. By default, this mod has no content apart from the block itself.
+
+If you have used the mod in previous versions, you can read the [What's New page](whats_new.md) to see what changed.
+
+For players: Please refer to [this page](/usage_for_players.md).<br>
+For developers: Please refer to [this page](/usage_for_developers.md).
+
+If you want to see a full example that uses all available functions, see the [full example page](full_example.md).
 
 Useful links:
 

wikis/summoningrituals/docs/recipe/basics.md

@@ -0,0 +1,147 @@
+# Recipe Basics
+
+Summoning Rituals provides a single crafting recipe type that is reused across all systems: the altar recipe.
+
+It is possible to create custom recipes via datapacks as well, but it's not recommended since you'd miss a lot of customization options. Instead, you should make use of [KubeJS](https://github.com/KubeJS-Mods/KubeJS) because the mod has native integration for it.
+
+> [!WARNING] NOTE
+> Due to the limitations, creating the recipe via datapacks is not documented on this wiki.
+
+## Creating a Recipe
+
+To create a new altar recipe, you need to set up a listener for the recipe event in a KubeJS server script. Keep in mind that server events have to be located inside the `kubejs/server_scripts` folder.
+
+```js
+ServerEvents.recipes(event => {
+    event.recipes.summoningrituals.altar("minecraft:stick")
+})
+```
+
+The `altar()` function creates a new instance of the altar recipe builder. It takes a single argument, which acts as the **initiator** of the recipe. An initiator must be inserted last into the altar to start the recipe after all other inputs have been placed. For this, you can use any kind of `Ingredient`. That means it allows a simple item or a tag.
+
+> [!TIP] NOTE
+> Specifying a count will not have any effect because an initiator can only be a single item.
+
+After calling the function, you can chain many different functions to assign inputs, outputs, and conditions. You can read more about that in the following sections.
+
+## Recipe Components
+
+Each recipe uses the same set of components which define inputs, outputs, conditions, and special information like custom tooltips.
+
+### Structure
+
+-   `initiator`
+    -   type: `Ingredient`
+    -   required: yes (passed to `.altar(...)`)
+    -   description: the item used to start the ritual
+-   `item_inputs`
+    -   type: `List<SizedIngredient>`
+    -   required: no
+    -   default: empty list
+    -   primary access: `itemInputs(...)`
+    -   aliases: `itemInput`, `inputs`, `input`
+    -   description: items consumed when the ritual starts
+-   `entity_inputs`
+    -   type: `List<EntityInput>`
+    -   required: no
+    -   default: empty list
+    -   primary access: `entityInputs(...)`
+    -   aliases: `entityInput`, `mobInputs`, `mobInput`
+    -   description: entities inside the sacrifice zone that are killed when the ritual starts
+-   `item_outputs`
+    -   type: `List<ItemOutput>`
+    -   required: no
+    -   default: empty list
+    -   primary access: `itemOutputs(...)`
+    -   aliases: `itemOutput`, `outputs`, `output`
+    -   description: items spawned around the altar when the ritual finishes
+-   `entity_outputs`
+    -   type: `List<EntityOutput>`
+    -   required: no
+    -   default: empty list
+    -   primary access: `entityOutputs(...)`
+    -   aliases: `entityOutput`, `mobOutputs`, `mobOutput`
+    -   description: entities spawned around the altar when the ritual finishes
+-   `commands`
+    -   type: `CommandOutput`
+    -   required: no
+    -   default: empty
+    -   primary access: `commands(...)`
+    -   aliases: `command`
+    -   description: commands executed when the ritual completes
+-   `zone`
+    -   type: `BlockPos`
+    -   required: no
+    -   default: `[3, 2, 3]`
+    -   primary access: `entityInputZone(...)`
+    -   aliases: `entityInputZone`, `mobInputZone`, `inputZone`, `sacrificeZone`, `entityZone`, `mobZone`, `zone`
+    -   description: half-size region around altar used to search required entities
+-   `conditions`
+    -   type: `List<LootItemCondition>`
+    -   required: no
+    -   default: empty list
+    -   primary access: `conditions(...)`
+    -   description: conditions evaluated before the ritual can start
+-   `ticks`
+    -   type: `int`
+    -   required: no
+    -   default: `40`
+    -   primary access: `ticks(...)`
+    -   aliases: `time`, `duration`
+    -   description: ritual duration in game ticks
+
+### Inputs
+
+Inputs can be items, entities, or both. If you want to learn more about how players interact with the altar to provide the required inputs, check out the [player usage page](../usage_for_players.md).
+
+Item inputs support components. That means an input item could specify a required enchantment. Item input components are strictly enforced in the recipe. That means if the item does not have the specified component, the input will not be valid for the recipe.
+
+Entity inputs support data (known as NBT). Contrary to item inputs, this data is not enforced. It is only being used for rendering purposes in the recipe viewer pages. If specific NBT should be enforced, you have to attach a custom validator to the entity input. Entity inputs are considered a sacrifice when they are within the sacrifice zone.
+
+For more information about inputs with all available functions and examples, please read the [inputs page](inputs.md).
+
+### Outputs
+
+Outputs can be items, entities, commands, or all three.
+
+Similar to inputs, outputs support components as well. Items with components and entities with NBT will be spawned with their assigned data. Additionally, item and entity outputs can have custom spawn positions altered by offset and spread values.
+
+Furthermore, commands can be used as outputs. When the ritual finishes, the altar will invoke these commands on the server. You can specify whether a command requires player interaction. Commands with required player context won't be invoked if the ritual was performed by automation.
+
+For more information about outputs with all available functions and examples, please read the [outputs page](outputs.md).
+
+### Conditions
+
+This component defines which conditions need to be fulfilled before the ritual can start. Conditions are additive meaning if multiple conditions are specified, they all have to pass.
+
+The condition system hijacks the vanilla Minecraft loot condition system. Plenty of conditions that can be used for loot can also be used for rituals.
+
+To learn more about available conditions and how to specify them, please read the [conditions page](conditions.md).
+
+### Ticks
+
+The `ticks` component defines the duration the ritual needs to be finished. When the ritual starts, all item inputs are consumed and all entity inputs are killed (they don't drop any loot). An animation will play while the ritual is active. When it's done, the altar will spawn the item and entity outputs and invoke the output commands.
+
+Values passed to this function are specified in ticks (_1 second = 20 ticks_). Higher values mean longer duration for the ritual.
+
+## Recipe Validation
+
+After a recipe has been created, the mod will check its validity internally. There are multiple checks in place to ensure a recipe is valid.
+
+1. the initiator **cannot** be empty
+    - this happens if an invalid item id was specified or if the tag provided does not exist
+2. the recipe **must** have at least one item or entity input
+3. the amount of inputs exceeds the specified altar inventory size in the config
+    - you can set the size higher in the config
+    - this restriction exists to prevent the altar from being used as an infinite storage solution
+4. the recipe **must** have at least one item, entity, or command output
+
+In addition to the general validation, a recipe performs the following steps before it can start:
+
+1. initiator item matches
+2. all item inputs are present in altar inventory
+3. all entity inputs are found inside the configured zone
+4. all start conditions pass
+5. start event is not blocked
+
+After the duration ticks have elapsed, the ritual executes commands, and spawns outputs.