diff --git a/docs/curios/api/_category_.json b/docs/curios/api/_category_.json index 53db1d6..2a5de4e 100644 --- a/docs/curios/api/_category_.json +++ b/docs/curios/api/_category_.json @@ -3,6 +3,6 @@ "position": 4, "link": { "type": "generated-index", - "description": "All about curio slots and how to manage them." + "description": "All about the Curio API interfaces." } } diff --git a/docs/curios/configuration.md b/docs/curios/configuration.md new file mode 100644 index 0000000..fb2cc95 --- /dev/null +++ b/docs/curios/configuration.md @@ -0,0 +1,73 @@ +--- +sidebar_position: 13 +--- + +# Configuration + +Curios has various configuration files that can be used to change settings related to the user interface, curios +behavior, and more. + +## Slot Configuration + +Although the datapack method described in the [slot types](./slots/slot-register.md) page is the recommended method for +all consumers, users who are not familiar with datapacks or do not need the features of the format are able to create +and modify slots through the Curios configuration file. + +This configuration is located in the `curios-common.toml` configuration file found in the `config` folder of the user's +root Minecraft instance. + +```toml +#List of slots to create or modify. +slots = [] +``` + +The slots list will be empty at first. Users can define a slot entry by inputting a string entry into the array. All +slots that are defined in this setting will automatically be assigned to players if they are not already assigned. + +:::note +This setting is loaded server-side only and synced to clients. Servers can change this setting without updating clients +and clients will receive the proper slots upon joining. +::: + +### Syntax + +Each entry must include an `id` field that represents the identifier of the slot type, and fields in the entry must be +separated by semicolons. The following fields are available for use through the configuration file: + +#### **id** (string, *required*) +The identifier for the slot type to create or modify. + +#### **size** (integer) +The number of slots of this slot type to give by default. + +#### **operation** (`"SET"`\|`"ADD"`\|`"REMOVE"`) +Whether to use `size` to set, add, or remove from the total number of slots. + +#### **order** (integer) +The order the slots will appear in the native Curios GUI, lower numbers appear first. + +#### **icon** (string) +The location of the icon to use for the slot type. + +#### **add_cosmetic** (boolean) +The location of the icon to use for the slot type. + +#### **use_native_gui** (boolean) +When `false`, does not add the slot type to the native Curios GUI. + +#### **render_toggle** (boolean) +When `false`, does not allow the slot type to toggle its rendering. + +#### **drop_rule** (`"DEFAULT"`\|`"ALWAYS_DROP"`\|`"ALWAYS_KEEP"`\|`"DESTROY"`) +Whether to drop, keep, destroy, or follow the `keepCurios` configuration setting. + +### Example + +```toml +slots = ["id=ring;size=10", "id=charm;size=3;add_cosmetic=true"] +``` + +This setting will create or modify two slot types, `"ring"` and `"charm"`, and assign both of them to all players. The +ring slot type will be created at size 10, and the charm slot type will be created at size 3 while also adding cosmetic +slots for them. These settings will override any settings from the datapack configurations as described in the main +[slot types page](./slots/slot-register.md). diff --git a/docs/curios/inventory/_category_.json b/docs/curios/inventory/_category_.json new file mode 100644 index 0000000..f263191 --- /dev/null +++ b/docs/curios/inventory/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Inventory", + "position": 3, + "link": { + "type": "generated-index", + "description": "All about the curio inventory and how to manage it." + } +} diff --git a/docs/curios/inventory/basic-inventory.mdx b/docs/curios/inventory/basic-inventory.mdx new file mode 100644 index 0000000..bb4855c --- /dev/null +++ b/docs/curios/inventory/basic-inventory.mdx @@ -0,0 +1,129 @@ +--- +sidebar_position: 1 +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Basic Inventory Management + +Learn how to access and manage the Curios inventory attached to an entity. + +## Overview +--- +Each entity that has been assigned any number of slot types based on [entity registration](../slots/entity-register.md) +will automatically gain a Curios inventory, initialized with a sub-inventory for each slot type that has been assigned. +This inventory can be used for a variety of purposes, such as finding out which items are held in the inventory or +modifying the number of slots that are in each sub-inventory. + +The interface for the Curios inventory can be found as `top.theillusivec4.curios.api.type.capability.ICuriosItemHandler`, +which holds all of the methods that developers can use to access and manage the inventory. + +## Using the inventory +--- +To begin using the inventory, developers will need to grab the instance associated with each entity. The +`top.theillusivec4.curios.api.CuriosApi` class has a `getCuriosInventory` method that can be used: + + + +```java +LazyOptional maybeCuriosInventory = CuriosApi.getCuriosInventory(livingEntity); +``` +The query returns a `LazyOptional` as the specified entity may not have a curios inventory. If the result is certain to +exist, then the optionality can be disregarded and simplified to: +```java +ICuriosItemHandler curiosInventory = CuriosApi.getCuriosInventory(livingEntity).resolve().get(); +``` + + +```java +Optional maybeCuriosInventory = CuriosApi.getCuriosInventory(livingEntity); +``` +The query returns a `Optional` as the specified entity may not have a curios inventory. If the result is certain to +exist, then the optionality can be disregarded and simplified to: +```java +ICuriosItemHandler curiosInventory = CuriosApi.getCuriosInventory(livingEntity).get(); +``` + + + +Since the method returns an `Optional` by default, developers will need to make sure to use `Optional#ifPresent` first +in order to check that the inventory actually exists: + +```java +CuriosApi.getCuriosInventory(livingEntity).ifPresent(curiosInventory -> { + // code here - with access to the inventory instance that now definitely exists +}); +``` + +Once a developer has the `ICuriosItemHandler` instance, they can use the methods from that instance to interact with the +Curios inventory. + +## Accessing the inventory +--- + +As mentioned previously, each slot type assigned to an entity is given a sub-inventory in the Curios inventory to +provide easy and categorical access. There are two main ways to interact with these slot inventories, depending on +whether the developer wants to access all of the slot inventories or just a particular one. + +### Accessing the entire inventory + +The entire Curios inventory exists as a `Map`, with the slot type identifiers acting as each +key and the `ICurioStackHandler` acting as the inventory attached to the slot type. To access this, the `getCurios` +method can be used: + +```java +Map curios = curiosInventory.getCurios(); +``` +:::caution +This returns an **unmodifiable** map so attempts to change the structure of the map directly through this method, such +as adding or removing slot inventories, will not work. Any changes to the structure needs to be done through other +methods, this method is primarily for accessing the list of slot inventories on the entity. +::: + +From here, developers can either iterate through the entire map: + +```java +curios.forEach((identifier, slotInventory) -> { + // code here - with the identifier and slot inventory access +}) +``` + +Or developers can access a particular sub-inventory, such as a slot type with the `"ring"` identifier: + +```java +ICurioStackHandler slotInventory = curios.get("ring"); + +// null check to ensure that the slot inventory exists +if (slotInventory != null) { + // code here +} +``` + +However, if all a developer wants is to access a particular sub-inventory, there's a more straightforward method +outlined in the next section that can be used instead. + +### Accessing an inventory for a slot type + +In order to access a particular inventory for slot type, developers can either access the whole inventory as outlined +in the preceding section or skip straight to a sub-inventory for that slot type: + +```java +Optional slotInventory = curiosInventory.getStacksHandler("ring"); +``` + +The above code will retrive an `Optional` for the slot inventory with the `"ring"` identifier passed into the +parameter. This is an `Optional` because the slot inventory being queried may not exist on the entity, which is a +possibility that developers must consider because higher-priority datapacks are capable of removing slot types from +entities. For that reason, be sure to use `ifPresent` before accessing the inventory: + +```java +curiosInventory.getStacksHandler("ring").ifPresent(slotInventory -> { + // code here - with access to the slot inventory with the "ring" identifier +}); +``` + + + + + + diff --git a/docs/curios/items/_category_.json b/docs/curios/items/_category_.json index d42200b..e68a196 100644 --- a/docs/curios/items/_category_.json +++ b/docs/curios/items/_category_.json @@ -3,6 +3,6 @@ "position": 2, "link": { "type": "generated-index", - "description": "All about curio slots and how to manage them." + "description": "All about curio items and how to create or manage them." } } diff --git a/docs/curios/slots/entity-register.md b/docs/curios/slots/entity-register.md index 35bb1b1..09317d6 100644 --- a/docs/curios/slots/entity-register.md +++ b/docs/curios/slots/entity-register.md @@ -8,13 +8,17 @@ A tutorial on how to add registered slot types to entities. ## Overview --- -Beginning in 1.20, the recommended way to add a registered slot type to an entity is through a datapack. If you are -unfamiliar with datapacks, it is recommended to read through the [wiki page](https://minecraft.fandom.com/wiki/Data_pack) -in order to understand the concept and structure before proceeding to the rest of this page. +The recommended way to add a registered slot type to an entity is through a datapack. If you are unfamiliar with +datapacks, it is recommended to read through the [wiki page](https://minecraft.fandom.com/wiki/Data_pack) in order to +understand the concept and structure before proceeding to the rest of this page. [Registered slot types](slot-register.md) will all be available for use but will not appear in-game until they are added to one or more entities. +Alternatively, users can instead choose to use the [Curios configuration](../configuration#slot-configuration) to create +and assign slot types to **players only**. There are fewer features than those offered in the datapack method, but some +users may find the process to be more straightforward. + ## Directory --- The file should be a `.json` file located in the `~/data/(namespace)/curios/entities/` folder of the datapack. @@ -32,14 +36,23 @@ anything that is lowercased with no special characters. The structure of the `.json` file for the entity configuration consists of a top-level JSON object that holds several potential fields. -* `entities` - * An array of registry names of entity types or entity type tags. -* `slots` - * An array of `identifier` names for registered slot types. -* `replace` - * A boolean, `true` if the values listed in this file should replace values in lower-priority datapacks -* `conditions` - * An array of `ICondition` implementations that must all pass before these slots are loaded into these entities +All fields are optional unless otherwise noted. + +### **replace** (boolean) +When `true`, replaces data from lower-priority datapacks. +* **default:** `false` + +### **entities** (string[]) +An array of registry names of entity types or entity type tags. +* **default:** `[]` + +### **slots** (string[]) +An array of `identifier` names for registered slot types. +* **default:** `[]` + +### **conditions** (string[]) +An array of `ICondition` implementations that must all pass before these slots are loaded into these entities. +* **default:** `[]` All the listed slots will be associated to all the listed entities. diff --git a/docs/curios/slots/slot-modifiers.mdx b/docs/curios/slots/slot-modifiers.mdx index 7ed755e..ea3ac9a 100644 --- a/docs/curios/slots/slot-modifiers.mdx +++ b/docs/curios/slots/slot-modifiers.mdx @@ -16,29 +16,8 @@ remove health or attack damage. In fact, it uses the exact same `AttributeModifi ## Getting Started The main way to interact with and add slot modifiers is through the `top.theillusivec4.curios.api.type.capability.ICuriosItemHandler` -interface. A developer can grab the specific instance of this on the entity by querying the capability from Curios: - - -```java -LazyOptional maybeCuriosInventory = CuriosApi.getCuriosInventory(livingEntity); -``` -The query returns a `LazyOptional` as the specified entity may not have a curios inventory. If the result is certain to -exist, then the optionality can be disregarded and simplified to: -```java -ICuriosItemHandler curiosInventory = CuriosApi.getCuriosInventory(livingEntity).resolve().get(); -``` - - -```java -Optional maybeCuriosInventory = CuriosApi.getCuriosInventory(livingEntity); -``` -The query returns a `Optional` as the specified entity may not have a curios inventory. If the result is certain to -exist, then the optionality can be disregarded and simplified to: -```java -ICuriosItemHandler curiosInventory = CuriosApi.getCuriosInventory(livingEntity).get(); -``` - - +interface. A developer can grab the specific instance of this on the entity by following the steps from the [inventory](../inventory/basic-inventory.mdx) +guide to query the capability from Curios. ## Adding or Removing Slots diff --git a/docs/curios/slots/slot-register.md b/docs/curios/slots/slot-register.md index a3c181e..d5fc5f2 100644 --- a/docs/curios/slots/slot-register.md +++ b/docs/curios/slots/slot-register.md @@ -8,9 +8,13 @@ A tutorial on how to register and modify slot types that are recognized by Curio ## Overview --- -Beginning in 1.20, the recommended way to register a slot type is through a datapack. If you are unfamiliar with -datapacks, it is recommended to read through the [wiki page](https://minecraft.fandom.com/wiki/Data_pack) in order to -understand the concept and structure before proceeding to the rest of this page. +The recommended way to register a slot type is through a datapack. If a user or developer is unfamiliar with datapacks, +it is recommended to read through the [wiki page](https://minecraft.fandom.com/wiki/Data_pack) in order to understand +the concept and structure before proceeding to the rest of this page. + +Alternatively, users can instead choose to use the [Curios configuration](../configuration#slot-configuration) to create +and modify slot types. There are fewer features than those offered in the datapack method, but some users may find the +process to be more straightforward. If using one of the [Preset Slot Types](./preset-slots), this step can be skipped since Curios natively provides the needed datapack registration. @@ -42,17 +46,58 @@ anything that is lowercased with no special characters. The structure of the `.json` file for the slot type consists of a top-level JSON object that holds various fields related to that slot type. -| Field | Type | Default | Required | Description | Merge Behavior | -|------------------|------------------------------------------------------------|---------------------------------|----------|----------------------------------------------------------------------------------------------------------------------|---------------------------------------------| -| `replace` | boolean | `false` | `false` | When `true`, replaces data from lower-priority datapacks | N/A | -| `size` | integer | `1` | `false` | The number of slots of this slot type to give by default | The highest size will be used | -| `operation` | `"SET"`\|`"ADD"`\|`"REMOVE"` | `"SET"` | `false` | Whether to use `size` to set, add, or remove from the total number of slots | N/A | -| `order` | integer | `1000` | `false` | The order the slots will appear in the native Curios GUI, lower numbers appear higher | The lowest order will be used | -| `icon` | string | `curios:slot/empty_curios_slot` | `false` | The location of the icon to use for the slot type | The last icon will be used | -| `add_cosmetic` | boolean | `false` | `false` | When `true`, adds a cosmetic slot next to the original that does not provide function but still renders its contents | `true` if any add a cosmetic slot | -| `use_native_gui` | boolean | `true` | `false` | When `false`, does not add the slot type to the native Curios GUI | `false` if any do not use the native GUI | -| `render_toggle` | boolean | `true` | `false` | When `false`, does not allow the slot type to toggle its rendering | `false` if any do not allow render toggling | -| `drop_rule` | `"DEFAULT"`\|`"ALWAYS_DROP"`\|`"ALWAYS_KEEP"`\|`"DESTROY"` | `"DEFAULT"` | `false` | Whether to drop, keep, destroy, or follow the `keepCurios` configuration | N/A | +All fields are optional unless otherwise noted. Each field denotes certain merging behavior which defines how the +field is merged between all data files that include it. + +### **replace** (boolean) +When `true`, replaces data from lower-priority datapacks. +* **default:** `false` +* **merging:** N/A + +### **size** (integer) +The number of slots of this slot type to give by default. +* **default:** `1` +* **merging:** The highest size will be used. + +### **operation** (`"SET"`\|`"ADD"`\|`"REMOVE"`) +Whether to use `size` to set, add, or remove from the total number of slots. +* **default:** `"SET"` +* **merging:** N/A + +### **order** (integer) +The order the slots will appear in the native Curios GUI, lower numbers appear first. +* **default:** `1000` +* **merging:** The lowest order will be used. + +### **icon** (string) +The location of the icon to use for the slot type. +* **default:** `"curios:slot/empty_curios_slot"` +* **merging:** The last icon will be used. + +### **add_cosmetic** (boolean) +The location of the icon to use for the slot type. +* **default:** `false` +* **merging:** `true` if any data file sets this field to `true`. + +### **use_native_gui** (boolean) +When `false`, does not add the slot type to the native Curios GUI. +* **default:** `true` +* **merging:** `false` if any data file sets this field to `false`. + +### **render_toggle** (boolean) +When `false`, does not allow the slot type to toggle its rendering. +* **default:** `true` +* **merging:** `false` if any data file sets this field to `false`. + +### **drop_rule** (`"DEFAULT"`\|`"ALWAYS_DROP"`\|`"ALWAYS_KEEP"`\|`"DESTROY"`) +Whether to drop, keep, destroy, or follow the `keepCurios` configuration setting. +* **default:** `"DEFAULT"` +* **merging:** N/A + +### **validators** (string[]) +The list of registered predicates from the Curios API used by this slot type to validate item insertions. +* **default:** `["curios:tag"]` +* **merging:** Each entry is added into the final array. :::info **Which `operation` value should I use?**