From 5c6f105f407c5493b4cfc6afa29e0a31094e6118 Mon Sep 17 00:00:00 2001 From: Mysterious_Dev Date: Sat, 12 Aug 2023 17:27:45 +0200 Subject: [PATCH 01/21] Begin Work --- docs/advanced/accesstransformers.md | 6 ++++-- docs/blockentities/ber.md | 6 ++++-- docs/blockentities/index.md | 5 +++-- docs/blocks/index.md | 5 +++-- docs/blocks/states.md | 6 ++++-- 5 files changed, 18 insertions(+), 10 deletions(-) diff --git a/docs/advanced/accesstransformers.md b/docs/advanced/accesstransformers.md index 707e3ce9c..1b63a82b4 100644 --- a/docs/advanced/accesstransformers.md +++ b/docs/advanced/accesstransformers.md @@ -1,5 +1,7 @@ -Access Transformers -=================== +--- +sidebar_position: 1 +title: Access Transformers +--- Access Transformers (ATs for short) allow for widening the visibility and modifying the `final` flags of classes, methods, and fields. They allow modders to access and modify otherwise inaccessible members in classes outside their control. diff --git a/docs/blockentities/ber.md b/docs/blockentities/ber.md index 0196f965d..608907228 100644 --- a/docs/blockentities/ber.md +++ b/docs/blockentities/ber.md @@ -1,5 +1,7 @@ -BlockEntityRenderer -================== +--- +sidebar_position: 1 +title: BlockEntityRenderer +--- A `BlockEntityRenderer` or `BER` is used to render blocks in a way that cannot be represented with a static baked model (JSON, OBJ, B3D, others). A block entity renderer requires the block to have a `BlockEntity`. diff --git a/docs/blockentities/index.md b/docs/blockentities/index.md index 89ef2b872..7b6d02e18 100644 --- a/docs/blockentities/index.md +++ b/docs/blockentities/index.md @@ -1,5 +1,6 @@ -Block Entities -====== +--- +title: Block Entities +--- `BlockEntities` are like simplified `Entities` that are bound to a Block. They are used to store dynamic data, execute tick based tasks, and dynamic rendering. diff --git a/docs/blocks/index.md b/docs/blocks/index.md index f083f104d..1e29540d5 100644 --- a/docs/blocks/index.md +++ b/docs/blocks/index.md @@ -1,5 +1,6 @@ -Blocks -====== +--- +title: Blocks +--- Blocks are, obviously, essential to the Minecraft world. They make up all of the terrain, structures, and machines. Chances are if you are interested in making a mod, then you will want to add some blocks. This page will guide you through the creation of blocks, and some of the things you can do with them. diff --git a/docs/blocks/states.md b/docs/blocks/states.md index f18bc385e..441a3bd27 100644 --- a/docs/blocks/states.md +++ b/docs/blocks/states.md @@ -1,5 +1,7 @@ -Block States -============ +--- +sidebar_position: 1 +title: Block States +--- Legacy Behavior --------------------------------------- From ada68feb553b3f846d783a715bb42da99af69cb2 Mon Sep 17 00:00:00 2001 From: Mysterious_Dev Date: Sat, 12 Aug 2023 17:31:49 +0200 Subject: [PATCH 02/21] Migrate H2 for Block States page --- docs/blocks/states.md | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/docs/blocks/states.md b/docs/blocks/states.md index 441a3bd27..fcde8770e 100644 --- a/docs/blocks/states.md +++ b/docs/blocks/states.md @@ -3,8 +3,7 @@ sidebar_position: 1 title: Block States --- -Legacy Behavior ---------------------------------------- +## Legacy Behavior In Minecraft 1.7 and previous versions, blocks which need to store placement or state data that did not have BlockEntities used **metadata**. Metadata was an extra number stored with the block, allowing different rotations, facings, or even completely separate behaviors within a block. @@ -22,8 +21,7 @@ switch (meta) { Because the numbers carry no meaning by themselves, no one could know what they represent unless they had access to the source code and comments. -Introduction of States ---------------------------------------- +## Introduction of States In Minecraft 1.8 and above, the metadata system, along with the block ID system, was deprecated and eventually replaced with the **block state system**. The block state system abstracts out the details of the block's properties from the other behaviors of the block. @@ -33,8 +31,7 @@ A unique pair can be constructed from the `Block` and a map of the `Property` The previous system of meaningless metadata values were replaced by a system of block properties, which are easier to interpret and deal with. Previously, a stone button which is facing east and is powered or held down is represented by "`minecraft:stone_button` with metadata `9`. Now, this is represented by "`minecraft:stone_button[facing=east,powered=true]`". -Proper Usage of Block States ---------------------------------------- +## Proper Usage of Block States The `BlockState` system is a flexible and powerful system, but it also has limitations. `BlockState`s are immutable, and all combinations of their properties are generated on startup of the game. This means that having a `BlockState` with many properties and possible values will slow down the loading of the game, and befuddle anyone trying to make sense of your block logic. @@ -47,8 +44,7 @@ A good rule of thumb is: **if it has a different name, it should be a separate b An example is making chair blocks: the *direction* of the chair should be a *property*, while the different *types of wood* should be separated into different blocks. An "Oak Chair" facing east (`oak_chair[facing=east]`) is different from a "Spruce Chair" facing west (`spruce_chair[facing=west]`). -Implementing Block States ---------------------------------------- +## Implementing Block States In your Block class, create or reference `static final` `Property` objects for every property that your Block has. You are free to make your own `Property` implementations, but the means to do that are not covered in this article. The vanilla code provides several convenience implementations: @@ -89,8 +85,7 @@ Because `BlockState`s are immutable, and all combinations of their properties ar Because all possible `BlockState`s are generated at startup, you are free and encouraged to use the reference equality operator (`==`) to check if two `BlockState`s are equal. -Using `BlockState`'s ---------------------- +## Using `BlockState`'s You can get the value of a property by calling `BlockState#getValue(Property)`, passing it the property you want to get the value of. If you want to get a `BlockState` with a different set of values, simply call `BlockState#setValue(Property, T)` with the property and its value. From 4ea2ab8ca71787b0bbaba3408d1a7b38be322c82 Mon Sep 17 00:00:00 2001 From: Mysterious_Dev Date: Sat, 12 Aug 2023 17:35:18 +0200 Subject: [PATCH 03/21] Migrate H2 for many pages --- docs/advanced/accesstransformers.md | 12 ++++-------- docs/blockentities/ber.md | 6 ++---- docs/blocks/index.md | 9 +++------ 3 files changed, 9 insertions(+), 18 deletions(-) diff --git a/docs/advanced/accesstransformers.md b/docs/advanced/accesstransformers.md index 1b63a82b4..9ebd55656 100644 --- a/docs/advanced/accesstransformers.md +++ b/docs/advanced/accesstransformers.md @@ -7,8 +7,7 @@ Access Transformers (ATs for short) allow for widening the visibility and modify The [specification document][specs] can be viewed on the NeoForged GitHub. -Adding ATs ----------- +## Adding ATs Adding an Access Transformer to your mod project is as simple as adding a single line into your `build.gradle`: @@ -23,13 +22,11 @@ After adding or modifying the Access Transformer, the gradle project must be ref During development, the AT file can be anywhere specified by the line above. However, when loading in a non-development environment, Forge will only search for the exact path of `META-INF/accesstransformer.cfg` in your JAR file. -Comments --------- +## Comments All text after a `#` until the end of the line will be treated as a comment and will not be parsed. -Access Modifiers ----------------- +## Access Modifiers Access modifiers specify to what new member visibility the given target will be transformed to. In decreasing order of visibility: @@ -46,8 +43,7 @@ Directives only modify the method they directly reference; any overriding method Examples of methods that can be safely transformed are `private` methods, `final` methods (or methods in `final` classes), and `static` methods. ::: -Targets and Directives ----------------------- +## Targets and Directives :::caution When using Access Transformers on Minecraft classes, the SRG name must be used for fields and methods. diff --git a/docs/blockentities/ber.md b/docs/blockentities/ber.md index 608907228..4dbc0b015 100644 --- a/docs/blockentities/ber.md +++ b/docs/blockentities/ber.md @@ -5,8 +5,7 @@ title: BlockEntityRenderer A `BlockEntityRenderer` or `BER` is used to render blocks in a way that cannot be represented with a static baked model (JSON, OBJ, B3D, others). A block entity renderer requires the block to have a `BlockEntity`. -Creating a BER --------------- +## Creating a BER To create a BER, create a class that inherits from `BlockEntityRenderer`. It takes a generic argument specifying the block's `BlockEntity` class. The generic argument is used in the BER's `render` method. @@ -24,7 +23,6 @@ This method is called every frame in order to render the block entity. * `combinedLight`: An integer of the current light value on the block entity. * `combinedOverlay`: An integer set to the current overlay of the block entity, usually `OverlayTexture#NO_OVERLAY` or 655,360. -Registering a BER ------------------ +## Registering a BER In order to register a BER, you must subscribe to the `EntityRenderersEvent$RegisterRenderers` event on the mod event bus and call `#registerBlockEntityRenderer`. diff --git a/docs/blocks/index.md b/docs/blocks/index.md index 1e29540d5..763c90b02 100644 --- a/docs/blocks/index.md +++ b/docs/blocks/index.md @@ -4,8 +4,7 @@ title: Blocks Blocks are, obviously, essential to the Minecraft world. They make up all of the terrain, structures, and machines. Chances are if you are interested in making a mod, then you will want to add some blocks. This page will guide you through the creation of blocks, and some of the things you can do with them. -Creating a Block ----------------- +## Creating a Block ### Basic Blocks @@ -26,8 +25,7 @@ Blocks have no setter for their `CreativeModeTab`. This is handled by the [`Buil Of course, the above only allows for extremely basic blocks. If you want to add functionality, like player interaction, a custom class is required. However, the `Block` class has many methods and unfortunately not every single one can be documented here. See the rest of the pages in this section for things you can do with blocks. -Registering a Block -------------------- +## Registering a Block Blocks must be [registered][registering] to function. @@ -41,8 +39,7 @@ When a block is registered, *only* a block is registered. The block does not aut In the past there have been several mods that have allowed users to disable blocks/items in a configuration file. However, you shouldn't do this. There is no limit on the amount of blocks that can be register, so register all blocks in your mod! If you want a block to be disabled through a configuration file, you should disable the crafting recipe. If you would like to disable the block in the creative tab, use a `FeatureFlag` when building the contents within [`BuildCreativeModeTabContentsEvent`][creativetabs]. -Further Reading ---------------- +## Further Reading For information about block properties, such as those used for vanilla blocks like fences, walls, and many more, see the section on [blockstates]. From 95fa2f5ff2f2bcdd57ed544a5dcba3029120dccd Mon Sep 17 00:00:00 2001 From: Mysterious_Dev Date: Mon, 14 Aug 2023 12:10:16 +0200 Subject: [PATCH 04/21] Client model resources --- docs/resources/client/models/index.md | 9 +++++---- docs/resources/client/models/itemproperties.md | 12 ++++++------ docs/resources/client/models/tinting.md | 6 ++++-- 3 files changed, 15 insertions(+), 12 deletions(-) diff --git a/docs/resources/client/models/index.md b/docs/resources/client/models/index.md index 510bec1fd..88bae73cc 100644 --- a/docs/resources/client/models/index.md +++ b/docs/resources/client/models/index.md @@ -1,10 +1,11 @@ -Models -====== +--- +sidebar_position: 1 +title: Models +--- The [model system][models] is Minecraft's way of giving blocks and items their shapes. Through the model system, blocks and items are mapped to their models, which define how they look. One of the main goals of the model system is to allow not only textures but the entire shape of a block/item to be changed by resource packs. Indeed, any mod that adds items or blocks also contains a mini-resource pack for their blocks and items. -Model Files ------------ +## Model Files Models and textures are linked through [`ResourceLocation`][resloc]s but are stored in the `ModelManager` using `ModelResourceLocation`s. Models are referenced in different locations through the block or item's registry name depending on whether they are referencing [block states][statemodel] or [item models][itemmodels]. Blocks will have their `ModelResourceLocation` represent their registry name along with a stringified version of its current [`BlockState`][state] while items will use their registry name followed by `inventory`. diff --git a/docs/resources/client/models/itemproperties.md b/docs/resources/client/models/itemproperties.md index 998f162dd..69578a603 100644 --- a/docs/resources/client/models/itemproperties.md +++ b/docs/resources/client/models/itemproperties.md @@ -1,12 +1,13 @@ -Item Properties -=============== +--- +sidebar_position: 2 +title: Item Properties +--- Item properties are a way for the "properties" of items to be exposed to the model system. An example is the bow, where the most important property is how far the bow has been pulled. This information is then used to choose a model for the bow, creating an animation for pulling it. An item property assigns a certain `float` value to every `ItemStack` it is registered for, and vanilla item model definitions can use these values to define "overrides", where an item defaults to a certain model, but if an override matches, it overrides the model and uses another. They are useful mainly because they are continuous. For example, bows use item properties to define their pull animation. The item models are decided by the 'float' number predicates, it is not limited but generally between `0.0F` and `1.0F`. This allows resource packs to add as many models as they want for the bow pulling animation along that spectrum, instead of being stuck with four "slots" for their models in the animation. The same is true of the compass and clock. -Adding Properties to Items --------------------------- +## Adding Properties to Items `ItemProperties#register` is used to add a property to a certain item. The `Item` parameter is the item the property is being attached to (e.g. `ExampleItems#APPLE`). The `ResourceLocation` parameter is the name given to the property (e.g. `new ResourceLocation("pull")`). The `ItemPropertyFunction` is a functional interface that takes the `ItemStack`, the `ClientLevel` it is in (may be null), the `LivingEntity` that holds it (may be null), and the `int` containing the id of the holding entity (may be `0`), returning the `float` value for the property. For modded item properties, it is recommended that the mod id of the mod is used as the namespace (e.g. `examplemod:property` and not just `property`, as that really means `minecraft:property`). These should be done in `FMLClientSetupEvent`. There's also another method `ItemProperties#registerGeneric` that is used to add properties to all items, and it does not take `Item` as its parameter since all items will apply this property. @@ -19,8 +20,7 @@ Use `FMLClientSetupEvent#enqueueWork` to proceed with the tasks, since the data `ItemPropertyFunction` is deprecated by Mojang in favor of using the subinterface `ClampedItemPropertyFunction` which clamps the result between `0` and `1`. ::: -Using Overrides ---------------- +## Using Overrides The format of an override can be seen on the [wiki][format], and a good example can be found in `model/item/bow.json`. For reference, here is a hypothetical example of an item with an `examplemod:power` property. If the values have no match, the default is the current model, but if there are multiple matches, the last match in the list will be selected. diff --git a/docs/resources/client/models/tinting.md b/docs/resources/client/models/tinting.md index d0604a930..920f4ef03 100644 --- a/docs/resources/client/models/tinting.md +++ b/docs/resources/client/models/tinting.md @@ -1,5 +1,7 @@ -Coloring Textures -================= +--- +sidebar_position: 1 +title: Texture Tinting +--- Many blocks and items in vanilla change their texture color depending on where they are or what properties they have, such as grass. Models support specifying "tint indices" on faces, which are integers that can then be handled by `BlockColor`s and `ItemColor`s. See the [wiki][] for information on how tint indices are defined in vanilla models. From 0e6418ef5f31cb99ff52b1a805aae31d175b02b5 Mon Sep 17 00:00:00 2001 From: Mysterious_Dev Date: Wed, 16 Aug 2023 13:17:24 +0200 Subject: [PATCH 05/21] More index pages --- docs/datagen/index.md | 15 +++++++-------- docs/items/index.md | 11 +++++------ docs/networking/index.md | 5 +++-- docs/rendering/modelloaders/index.md | 8 ++++---- docs/resources/client/index.md | 5 +++-- docs/resources/client/models/index.md | 1 - docs/resources/server/index.md | 6 ++++-- docs/resources/server/recipes/index.md | 14 ++++++-------- 8 files changed, 32 insertions(+), 33 deletions(-) diff --git a/docs/datagen/index.md b/docs/datagen/index.md index 5bf0547f2..de451922c 100644 --- a/docs/datagen/index.md +++ b/docs/datagen/index.md @@ -1,5 +1,6 @@ -Data Generators -=============== +--- +title: Data Generators +--- Data generators are a way to programmatically generate the assets and data of mods. It allows the definition of the contents of these files in the code and their automatic generation, without worrying about the specifics. @@ -7,16 +8,15 @@ The data generator system is loaded by the main class `net.minecraft.data.Main`. The default configurations in the MDK `build.gradle` adds the `runData` task for running the data generators. -Existing Files --------------- +## Existing Files + All references to textures or other data files not generated for data generation must reference existing files on the system. This is to ensure that all referenced textures are in the correct places, so typos can be found and corrected. `ExistingFileHelper` is the class responsible for validating the existence of those data files. An instance can be retrieved from `GatherDataEvent#getExistingFileHelper`. The `--existing ` argument allows the specified folder and its subfolders to be used when validating the existence of files. Additionally, the `--existing-mod ` argument allows the resources of a loaded mod to be used for validation. By default, only the vanilla datapack and resources are available to the `ExistingFileHelper`. -Generator Modes ---------------- +## Generator Modes The data generator can be configured to run 4 different data generations, which are configured from the command-line parameters, and can be checked from `GatherDataEvent#include***` methods. @@ -35,8 +35,7 @@ The data generator can be configured to run 4 different data generations, which All of the generators can be included using `--all`. -Data Providers --------------- +## Data Providers Data providers are the classes that actually define what data will be generated and provided. All data providers implement `DataProvider`. Minecraft has abstract implementations for most assets and data, so modders need only to extend and override the specified method. diff --git a/docs/items/index.md b/docs/items/index.md index 2b592394d..4b39b3fce 100644 --- a/docs/items/index.md +++ b/docs/items/index.md @@ -1,10 +1,10 @@ -Items -===== +--- +title: Items +--- Along with blocks, items are a key component of most mods. While blocks make up the level around you, items exist within inventories. -Creating an Item ----------------- +## Creating an Item ### Basic Items @@ -63,8 +63,7 @@ public static final RegistryObject EXAMPLE_TAB = REGISTRAR.regi ); ``` -Registering an Item -------------------- +## Registering an Item Items must be [registered][registering] to function. diff --git a/docs/networking/index.md b/docs/networking/index.md index 9d88ae644..93a5d7262 100644 --- a/docs/networking/index.md +++ b/docs/networking/index.md @@ -1,5 +1,6 @@ -Networking -========== +--- +title: Networking +--- Communication between servers and clients is the backbone of a successful mod implementation. diff --git a/docs/rendering/modelloaders/index.md b/docs/rendering/modelloaders/index.md index 9856d688a..dbf53c2f7 100644 --- a/docs/rendering/modelloaders/index.md +++ b/docs/rendering/modelloaders/index.md @@ -1,5 +1,6 @@ -Custom Model Loaders -==================== +--- +title: Custom Model Loaders +--- A "model" is simply a shape. It can be a simple cube, it can be several cubes, it can be a truncated icosidodecahedron, or anything in between. Most models you'll see will be in the vanilla JSON format. Models in other formats are loaded into `IUnbakedGeometry`s by an `IGeometryLoader` at runtime. Forge provides default implementations for WaveFront OBJ files, buckets, composite models, models in different render layers, and a reimplementation of Vanilla's `builtin/generated` item model. Most things do not care about what loaded the model or what format it's in as they are all eventually represented by an `BakedModel` in code. @@ -7,8 +8,7 @@ A "model" is simply a shape. It can be a simple cube, it can be several cubes, i Specifying a custom model loader through the top-level `loader` entry in a model JSON will cause the `elements` entry to be ignored unless it is consumed by the custom loader. All other vanilla entries will still be loaded and available in the unbaked `BlockModel` representation and may be consumed outside of the custom loader. ::: -WaveFront OBJ Models --------------------- +## WaveFront OBJ Models Forge adds a loader for the `.obj` file format. To use these models, the JSON must reference the `forge:obj` loader. This loader accepts any model location that is in a registered namespace and whose path ends in `.obj`. The `.mtl` file should be placed in the same location with the same name as the `.obj` to be used automatically. The `.mtl` file will probably have to be manually edited to change the paths pointing to textures defined within the JSON. Additionally, the V axis for textures may be flipped depending on the external program that created the model (i.e. V = 0 may be the bottom edge, not the top). This may be rectified in the modelling program itself or done in the model JSON like so: diff --git a/docs/resources/client/index.md b/docs/resources/client/index.md index a0afbe318..6715fc4f5 100644 --- a/docs/resources/client/index.md +++ b/docs/resources/client/index.md @@ -1,5 +1,6 @@ -Resource Packs -============== +--- +title: Resource Packs +--- [Resource Packs][respack] allow for the customization of client resources through the `assets` directory. This includes textures, models, sounds, localizations, and others. Your mod (as well as Forge itself) can also have resource packs. Any user can therefore modify all the textures, models, and other assets defined within this directory. diff --git a/docs/resources/client/models/index.md b/docs/resources/client/models/index.md index 88bae73cc..042e93613 100644 --- a/docs/resources/client/models/index.md +++ b/docs/resources/client/models/index.md @@ -1,5 +1,4 @@ --- -sidebar_position: 1 title: Models --- diff --git a/docs/resources/server/index.md b/docs/resources/server/index.md index 042076c70..5415b587d 100644 --- a/docs/resources/server/index.md +++ b/docs/resources/server/index.md @@ -1,5 +1,7 @@ -Datapacks -========= +--- +title: Datapacks +--- + In 1.13, Mojang added [datapacks][datapack] to the base game. They allow for the modification of the files for logical servers through the `data` directory. This includes advancements, loot_tables, structures, recipes, tags, etc. Forge, and your mod, can also have datapacks. Any user can therefore modify all the recipes, loot tables, and other data defined within this directory. ### Creating a Datapack diff --git a/docs/resources/server/recipes/index.md b/docs/resources/server/recipes/index.md index 7bb8cf838..ff0fc97ea 100644 --- a/docs/resources/server/recipes/index.md +++ b/docs/resources/server/recipes/index.md @@ -1,10 +1,10 @@ -Recipes -======= +--- +title: Recipes +--- Recipes are a way to transform some number of objects into other objects within a Minecraft world. Although the vanilla system deals purely with item transformations, the system as a whole can be expanded to use any object the programmer creates. -Data-Driven Recipes -------------------- +## Data-Driven Recipes Most recipe implementations within vanilla are data driven via JSON. This means that a mod is not necessary to create a new recipe, only a [Data pack][datapack]. A full list on how to create and put these recipes within the mod's `resources` folder can be found on the [Minecraft Wiki][wiki]. @@ -30,8 +30,7 @@ A recipe can be obtained within the Recipe Book as a reward for completing an [a Data-driven recipes and their unlocking advancement can be [generated][datagen] via `RecipeProvider`. -Recipe Manager --------------- +## Recipe Manager Recipes are loaded and stored via the `RecipeManager`. Any operations relating to getting available recipe(s) are handled by this manager. There are two important methods to know of: @@ -51,8 +50,7 @@ recipeManger.getRecipeFor(RecipeType.CRAFTING, new RecipeWrapper(handler), level ``` ::: -Additional Features -------------------- +## Additional Features Forge provides some additional behavior to the recipe schema and its implementations for greater control of the system. From 60812bb11b6c8549a0e6237a1398139232b817c9 Mon Sep 17 00:00:00 2001 From: Mysterious_Dev Date: Wed, 23 Aug 2023 13:24:54 +0200 Subject: [PATCH 06/21] Getting Started section --- docs/gettingstarted/index.md | 4 +++- docs/gettingstarted/modfiles.md | 12 ++++++------ docs/gettingstarted/structuring.md | 15 +++++++-------- docs/gettingstarted/versioning.md | 9 +++++---- 4 files changed, 21 insertions(+), 19 deletions(-) diff --git a/docs/gettingstarted/index.md b/docs/gettingstarted/index.md index e3f8a5dac..ed5013cf1 100644 --- a/docs/gettingstarted/index.md +++ b/docs/gettingstarted/index.md @@ -1,4 +1,6 @@ -# Getting Started with Forge +--- +title: Getting Started with Forge +--- :::caution Please note that this documentation may not be up to date considering the recent creation of NeoForged. diff --git a/docs/gettingstarted/modfiles.md b/docs/gettingstarted/modfiles.md index aabf06118..60f778ef6 100644 --- a/docs/gettingstarted/modfiles.md +++ b/docs/gettingstarted/modfiles.md @@ -1,10 +1,11 @@ -Mod Files -========= +--- +sidebar_position: 1 +title: Mod Files +--- The mod files are responsible for determining what mods are packaged into your JAR, what information to display within the 'Mods' menu, and how your mod should be loaded in the game. -mods.toml ---------- +## mods.toml The `mods.toml` file defines the metadata of your mod(s). It also contains additional information that is displayed within the 'Mods' menu and how your mod(s) should be loaded into the game. @@ -124,8 +125,7 @@ Property | Type | Default | Description | Example The `ordering` of two mods may cause a crash due to a cyclic dependency: for example, mod A must load `"BEFORE"` mod B and mod B `"BEFORE"` mod A. ::: -Mod Entrypoints ---------------- +## Mod Entrypoints Now that the `mods.toml` is filled out, we need to provide an entrypoint to being programming the mod. Entrypoints are essentially the starting point for executing the mod. The entrypoint itself is determined by the language loader used in the `mods.toml`. diff --git a/docs/gettingstarted/structuring.md b/docs/gettingstarted/structuring.md index 641015478..bb709fc2f 100644 --- a/docs/gettingstarted/structuring.md +++ b/docs/gettingstarted/structuring.md @@ -1,5 +1,7 @@ -Structuring Your Mod -==================== +--- +sidebar_position: 2 +title: Structuring Your Mod +--- Structured mods are beneficial for maintenance, making contributions, and providing a clearer understanding of the underlying codebase. Some of the recommendations from Java, Minecraft, and Forge are listed below. @@ -7,8 +9,7 @@ Structured mods are beneficial for maintenance, making contributions, and provid You do not have to follow the advice below; you can structure your mod any way you see fit. However, it is still highly recommended to do so. ::: -Packaging ---------- +## Packaging When structuring your mod, pick a unique, top-level package structure. Many programmers will use the same name for different classes, interfaces, etc. Java allows classes to have the same name as long as they are in different packages. As such, if two classes have the same package with the same name, only one would be loaded, most likely causing the game to crash. @@ -58,8 +59,7 @@ In general, code only for a given side or runtime should be isolated from the ot However, it is highly recommended that [client-only code][sides] should be isolated in a `client` subpackage. This is because dedicated servers have no access to any of the client-only packages in Minecraft. As such, having a dedicated package would provide a decent sanity check to verify you are not reaching across sides within your mod. -Class Naming Schemes --------------------- +## Class Naming Schemes A common class naming scheme makes it easier to decipher the purpose of the class or to easily locate specific classes. @@ -73,8 +73,7 @@ Classes are commonly suffixed with its type, for example: Mojang typically follows a similar structure for all classes except entities. Those are represented by just their names (e.g. `Pig`, `Zombie`, etc.). ::: -Choose One Method from Many ---------------------------- +## Choose One Method from Many There are many methods for performing a certain task: registering an object, listening for events, etc. It's generally recommended to be consistent by using a single method to accomplish a given task. While this does improve code formatting, it also avoid any weird interactions or redundancies that may occur (e.g. your event listener executing twice). diff --git a/docs/gettingstarted/versioning.md b/docs/gettingstarted/versioning.md index 2db561eb4..596b56d35 100644 --- a/docs/gettingstarted/versioning.md +++ b/docs/gettingstarted/versioning.md @@ -1,5 +1,7 @@ -Versioning -========== +--- +sidebar_position: 3 +title: Versioning +--- In general projects, [semantic versioning][semver] is often used (which has the format `MAJOR.MINOR.PATCH`). However, in the case of modding it may be more beneficial to use the format `MCVERSION-MAJORMOD.MAJORAPI.MINOR.PATCH` to be able to differentiate between world-breaking and API-breaking changes of a mod. @@ -7,8 +9,7 @@ In general projects, [semantic versioning][semver] is often used (which has the Forge uses [Maven version ranges][cmpver] to compare version strings, which is not fully compatible with the Semantic Versioning 2.0.0 spec, such as the 'prerelease' tag. ::: -Examples --------- +## Examples Here is a list of examples that can increment the various variables. From 3b7547ded005352e3a819076694b2c8bc87ea50f Mon Sep 17 00:00:00 2001 From: Mysterious_Dev Date: Wed, 23 Aug 2023 13:29:02 +0200 Subject: [PATCH 07/21] Legacy section --- docs/legacy/porting.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/legacy/porting.md b/docs/legacy/porting.md index cc7c0480b..de41d704f 100644 --- a/docs/legacy/porting.md +++ b/docs/legacy/porting.md @@ -1,5 +1,7 @@ -Porting to Minecraft 1.20 -========================= +--- +sidebar_position: 1 +title: Porting to Minecraft 1.20 +--- Here you can find a list of primers on how to port from old versions to the current version. Some versions are lumped together since that particular version never saw much usage. From b3e14ba954ba7d1f659a17b36e26854bb794d60a Mon Sep 17 00:00:00 2001 From: Mysterious_Dev Date: Fri, 1 Sep 2023 13:49:21 +0200 Subject: [PATCH 08/21] Concepts section --- docs/concepts/events.md | 24 ++++++++++-------------- docs/concepts/internationalization.md | 17 +++++++++-------- docs/concepts/lifecycle.md | 21 +++++++++------------ docs/concepts/registries.md | 18 ++++++++---------- docs/concepts/resources.md | 9 +++++---- docs/concepts/sides.md | 20 ++++++++++---------- 6 files changed, 51 insertions(+), 58 deletions(-) diff --git a/docs/concepts/events.md b/docs/concepts/events.md index d3982b36e..499aa018b 100644 --- a/docs/concepts/events.md +++ b/docs/concepts/events.md @@ -1,5 +1,7 @@ -Events -====== +--- +sidebar_position: 3 +title: Events +--- Forge uses an event bus that allows mods to intercept events from various Vanilla and mod behaviors. @@ -11,8 +13,7 @@ Every event is fired on one of these busses: most events are fired on the main f An event handler is some method that has been registered to an event bus. -Creating an Event Handler -------------------------- +## Creating an Event Handler Event handlers methods have a single parameter and do not return a result. The method could be static or instance depending on implementation. @@ -88,8 +89,7 @@ public class MyStaticClientOnlyEventHandler { This does not register an instance of the class; it registers the class itself (i.e. the event handling methods must be static). ::: -Canceling ---------- +## Canceling If an event can be canceled, it will be marked with the `@Cancelable` annotation, and the method `Event#isCancelable()` will return `true`. The cancel state of a cancelable event may be modified by calling `Event#setCanceled(boolean canceled)`, wherein passing the boolean value `true` is interpreted as canceling the event, and passing the boolean value `false` is interpreted as "un-canceling" the event. However, if the event cannot be canceled (as defined by `Event#isCancelable()`), an `UnsupportedOperationException` will be thrown regardless of the passed boolean value, since the cancel state of a non-cancelable event event is considered immutable. @@ -97,8 +97,7 @@ If an event can be canceled, it will be marked with the `@Cancelable` annotation Not all events can be canceled! Attempting to cancel an event that is not cancelable will result in an unchecked `UnsupportedOperationException` being thrown, which is expected to result in the game crashing! Always check that an event can be canceled using `Event#isCancelable()` before attempting to cancel it! ::: -Results -------- +## Results Some events have an `Event$Result`. A result can be one of three things: `DENY` which stops the event, `DEFAULT` which uses the Vanilla behavior, and `ALLOW` which forces the action to take place, regardless if it would have originally. The result of an event can be set by calling `#setResult` with an `Event$Result` on the event. Not all events have results; an event with a result will be annotated with `@HasResult`. @@ -106,18 +105,15 @@ Some events have an `Event$Result`. A result can be one of three things: `DENY` Different events may use results in different ways, refer to the event's JavaDoc before using the result. ::: -Priority --------- +## Priority Event handler methods (marked with `@SubscribeEvent`) have a priority. You can set the priority of an event handler method by setting the `priority` value of the annotation. The priority can be any value of the `EventPriority` enum (`HIGHEST`, `HIGH`, `NORMAL`, `LOW`, and `LOWEST`). Event handlers with priority `HIGHEST` are executed first and from there in descending order until `LOWEST` events which are executed last. -Sub Events ----------- +## Sub Events Many events have different variations of themselves. These can be different but all based around one common factor (e.g. `PlayerEvent`) or can be an event that has multiple phases (e.g. `PotionBrewEvent`). Take note that if you listen to the parent event class, you will receive calls to your method for *all* subclasses. -Mod Event Bus -------------- +## Mod Event Bus The mod event bus is primarily used for listening to lifecycle events in which mods should initialize. Each event on the mod bus is required to implement `IModBusEvent`. Many of these events are also ran in parallel so mods can be initialized at the same time. This does mean you can't directly execute code from other mods in these events. Use the `InterModComms` system for that. diff --git a/docs/concepts/internationalization.md b/docs/concepts/internationalization.md index 288840717..ec019e31b 100644 --- a/docs/concepts/internationalization.md +++ b/docs/concepts/internationalization.md @@ -1,5 +1,9 @@ -Internationalization and Localization -===================================== +--- +sidebar_position: 6 +title: Internationalization +--- + +# Internationalization and Localization Internationalization, i18n for short, is a way of designing code so that it requires no changes to be adapted for various languages. Localization is the process of adapting displayed text to the user's language. @@ -7,8 +11,7 @@ I18n is implemented using _translation keys_. A translation key is a string that Localization will happen in the game's locale. In a Minecraft client the locale is specified by the language settings. On a dedicated server, the only supported locale is `en_us`. A list of available locales can be found on the [Minecraft Wiki][langs]. -Language files --------------- +## Language files Language files are located by `assets/[namespace]/lang/[locale].json` (e.g. all US English translations provided by `examplemod` would be within `assets/examplemod/lang/en_us.json`). The file format is simply a json map from translation keys to values. The file must be encoded in UTF-8. Old .lang files can be converted to json using a [converter][converter]. @@ -20,8 +23,7 @@ Language files are located by `assets/[namespace]/lang/[locale].json` (e.g. all } ``` -Usage with Blocks and Items ---------------------------- +## Usage with Blocks and Items Block, Item and a few other Minecraft classes have built-in translation keys used to display their names. These translation keys are specified by overriding `#getDescriptionId`. Item also has `#getDescriptionId(ItemStack)` which can be overridden to provide different translation keys depending on ItemStack NBT. @@ -37,8 +39,7 @@ By default, `#getDescriptionId` will return `block.` or `item.` prepended to the The only purpose of a translation key is internationalization. Do not use them for logic. Use registry names instead. ::: -Localization methods --------------------- +## Localization methods :::caution A common issue is having the server localize for clients. The server can only localize in its own locale, which does not necessarily match the locale of connected clients. diff --git a/docs/concepts/lifecycle.md b/docs/concepts/lifecycle.md index 99e66f2fd..090da963f 100644 --- a/docs/concepts/lifecycle.md +++ b/docs/concepts/lifecycle.md @@ -1,5 +1,7 @@ -Mod Lifecycle -============== +--- +sidebar_position: 4 +title: Mod Lifecycle +--- During the mod loading process, the various lifecycle events are fired on the mod-specific event bus. Many actions are performed during these events, such as [registering objects][registering], preparing for [data generation][datagen], or [communicating with other mods][imc]. @@ -28,8 +30,7 @@ Most of the lifecycle events are fired in parallel: all mods will concurrently r Mods *must* take care to be thread-safe, like when calling other mods' APIs or accessing vanilla systems. Defer code for later execution via `ParallelDispatchEvent#enqueueWork`. ::: -Registry Events ---------------- +## Registry Events The registry events are fired after the mod instance construction. There are three: `NewRegistryEvent`, `DataPackRegistryEvent$NewRegistry` and `RegisterEvent`. These events are fired synchronously during mod loading. @@ -39,23 +40,19 @@ The registry events are fired after the mod instance construction. There are thr `RegisterEvent` is for [registering objects][registering] into the registries. The event is fired for each registry. -Data Generation ---------------- +## Data Generation If the game is setup to run [data generators][datagen], then the `GatherDataEvent` will be the last event to fire. This event is for registering mods' data providers to their associated data generator. This event is also fired synchronously. -Common Setup ------------- +## Common Setup `FMLCommonSetupEvent` is for actions that are common to both physical client and server, such as registering [capabilities][capabilities]. -Sided Setup ------------ +## Sided Setup The sided-setup events are fired on their respective [physical sides][sides]: `FMLClientSetupEvent` on the physical client, and `FMLDedicatedServerSetupEvent` for the dedicated server. This is where physical side-specific initialization should occur, such as registering client-side key bindings. -InterModComms -------------- +## InterModComms This is where messages can be sent to mods for cross-mod compatibility. There are two events: `InterModEnqueueEvent` and `InterModProcessEvent`. diff --git a/docs/concepts/registries.md b/docs/concepts/registries.md index 22325c439..4a7412e89 100644 --- a/docs/concepts/registries.md +++ b/docs/concepts/registries.md @@ -1,5 +1,7 @@ -Registries -========== +--- +sidebar_position: 1 +title: Registries +--- Registration is the process of taking the objects of a mod (such as items, blocks, sounds, etc.) and making them known to the game. Registering things is important, as without registration the game will simply not know about these objects, which will cause unexplainable behaviors and crashes. @@ -7,8 +9,7 @@ Most things that require registration in the game are handled by the Forge regis Every type of registrable object has its own registry. To see all registries wrapped by Forge, see the `ForgeRegistries` class. All registry names within a registry must be unique. However, names in different registries will not collide. For example, there's a `Block` registry, and an `Item` registry. A `Block` and an `Item` may be registered with the same name `example:thing` without colliding; however, if two different `Block`s or `Item`s were registered with the same exact name, the second object will override the first. -Methods for Registering ------------------- +## Methods for Registering There are two proper ways to register objects: the `DeferredRegister` class, and the `RegisterEvent` lifecycle event. @@ -73,8 +74,7 @@ public static final RegistryObject> EXAMPLE_ ``` ::: -Referencing Registered Objects ------------------------------- +## Referencing Registered Objects Registered objects should not be stored in fields when they are created and registered. They are to be always newly created and registered whenever `RegisterEvent` is fired for that registry. This is to allow dynamic loading and unloading of mods in a future version of Forge. @@ -145,8 +145,7 @@ class Holder { } ``` -Creating Custom Forge Registries --------------------------------- +## Creating Custom Forge Registries Custom registries can usually just be a simple map of key to value. This is a common style; however, it forces a hard dependency on the registry being present. It also requires that any data that needs to be synced between sides must be done manually. Custom Forge Registries provide a simple alternative for creating soft dependents along with better management and automatic syncing between sides (unless told otherwise). Since the objects also use a Forge registry, registration becomes standardized in the same way. @@ -174,8 +173,7 @@ The `DeferredRegister` method is once again another wrapper around the above eve `DeferredRegister#makeRegistry` must be called before the `DeferredRegister` is added to the mod event bus via `#register`. `#makeRegistry` also uses the `#register` method to create the registry during `NewRegistryEvent`. ::: -Handling Missing Entries ------------------------- +## Handling Missing Entries There are cases where certain registry objects will cease to exist whenever a mod is updated or, more likely, removed. It is possible to specify actions to handle the missing mapping through the third of the registry events: `MissingMappingsEvent`. Within this event, a list of missing mappings can be obtained either by `#getMappings` given a registry key and mod id or all mappings via `#getAllMappings` given a registry key. diff --git a/docs/concepts/resources.md b/docs/concepts/resources.md index d0d0b2074..c561cfedb 100644 --- a/docs/concepts/resources.md +++ b/docs/concepts/resources.md @@ -1,5 +1,7 @@ -Resources -========= +--- +sidebar_position: 5 +title: Resources +--- A resource is extra data used by the game, and is stored in a data file, instead of being in the code. Minecraft has two primary resource systems active: one on the logical client used for visuals such as models, textures, and localization called `assets`, and one on the logical server used for gameplay such as recipes and loot tables called `data`. @@ -11,8 +13,7 @@ When multiple resource packs or data packs are enabled, they are merged. General All resources should have snake case paths and filenames (lowercase, using "_" for word boundaries), which is enforced in 1.11 and above. -`ResourceLocation` ------------------- +## `ResourceLocation` Minecraft identifies resources using `ResourceLocation`s. A `ResourceLocation` contains two parts: a namespace and a path. It generally points to the resource at `assets///`, where `ctx` is a context-specific path fragment that depends on how the `ResourceLocation` is being used. When a `ResourceLocation` is written/read as from a string, it is seen as `:`. If the namespace and the colon are left out, then when the string is read into an `ResourceLocation` the namespace will always default to `"minecraft"`. A mod should put its resources into a namespace with the same name as its mod id (e.g. a mod with the id `examplemod` should place its resources in `assets/examplemod` and `data/examplemod` respectively, and `ResourceLocation`s pointing to those files would look like `examplemod:`.). This is not a requirement, and in some cases it can be desirable to use a different (or even more than one) namespace. `ResourceLocation`s are used outside the resource system, too, as they happen to be a great way to uniquely identify objects (e.g. [registries][]). diff --git a/docs/concepts/sides.md b/docs/concepts/sides.md index f3e66ae15..fd23d5489 100644 --- a/docs/concepts/sides.md +++ b/docs/concepts/sides.md @@ -1,10 +1,13 @@ -Sides in Minecraft -=================== +--- +sidebar_position: 2 +title: Sides +--- + +# Sides in Minecraft A very important concept to understand when modding Minecraft are the two sides: *client* and *server*. There are many, many common misconceptions and mistakes regarding siding, which can lead to bugs that might not crash the game, but can rather have unintended and often unpredictable effects. -Different Kinds of Sides ------------------------- +## Different Kinds of Sides When we say "client" or "server", it usually follows with a fairly intuitive understanding of what part of the game we are talking about. After all, a client is what the user interacts with, and a server is where the user connects for a multiplayer game. Easy, right? @@ -17,8 +20,7 @@ As it turns out, there can be some ambiguity even with two such terms. Here we d In the MinecraftForge codebase, the physical side is represented by an enum called `Dist`, while the logical side is represented by an enum called `LogicalSide`. -Performing Side-Specific Operations ------------------------------------ +## Performing Side-Specific Operations ### `Level#isClientSide` @@ -75,8 +77,7 @@ If `Thread.currentThread().getThreadGroup() == SidedThreadGroups.SERVER` is true Annotating a method or field with the `@OnlyIn(Dist)` annotation indicates to the loader that the respective member should be completely stripped out of the definition not on the specified **physical** side. Usually, these are only seen when browsing through the decompiled Minecraft code, indicating methods that the Mojang obfuscator stripped out. There is **NO** reason for using this annotation directly. Use `DistExecutor` or a check on `FMLEnvironment#dist` instead. -Common Mistakes ---------------- +## Common Mistakes ### Reaching Across Logical Sides @@ -87,8 +88,7 @@ This is actually very commonly inadvertently done through static fields. Since t This mistake can also be made explicitly by accessing physical client-only classes such as `Minecraft` from common code that runs or can run on the logical server. This mistake is easy to miss for beginners who debug in a physical client. The code will work there, but it will immediately crash on a physical server. -Writing One-Sided Mods ----------------------- +## Writing One-Sided Mods In recent versions, Minecraft Forge has removed a "sidedness" attribute from the mods.toml. This means that your mods are expected to work whether they are loaded on the physical client or the physical server. So for one-sided mods, you would typically register your event handlers inside a `DistExecutor#safeRunWhenOn` or `DistExecutor#unsafeRunWhenOn` instead of directly calling the relevant registration methods in your mod constructor. Basically, if your mod is loaded on the wrong side, it should simply do nothing, listen to no events, and so on. A one-sided mod by nature should not register blocks, items, ... since they would need to be available on the other side, too. From fc702d4a012b7b885b25ead2c46c645c108c1836 Mon Sep 17 00:00:00 2001 From: Mysterious_Dev Date: Fri, 22 Sep 2023 16:12:13 +0200 Subject: [PATCH 09/21] Data Generators Section --- docs/datagen/client/localization.md | 9 ++++--- docs/datagen/client/modelproviders.md | 30 +++++++++-------------- docs/datagen/client/sounds.md | 9 ++++--- docs/datagen/server/advancements.md | 12 ++++----- docs/datagen/server/datapackregistries.md | 12 ++++----- docs/datagen/server/glm.md | 6 +++-- docs/datagen/server/loottables.md | 12 ++++----- docs/datagen/server/recipes.md | 18 ++++++-------- docs/datagen/server/tags.md | 12 ++++----- 9 files changed, 58 insertions(+), 62 deletions(-) diff --git a/docs/datagen/client/localization.md b/docs/datagen/client/localization.md index c13486992..8d7e30b4c 100644 --- a/docs/datagen/client/localization.md +++ b/docs/datagen/client/localization.md @@ -1,5 +1,7 @@ -Language Generation -=================== +--- +sidebar_position: 2 +title: Language Generation +--- [Language files][lang] can be generated for a mod by subclassing `LanguageProvider` and implementing `#addTranslations`. Each `LanguageProvider` subclass created represents a separate [locale] (`en_us` represents American English, `es_es` represents Spanish, etc.). After implementation, the provider must be [added][datagen] to the `DataGenerator`. @@ -16,8 +18,7 @@ public void gatherData(GatherDataEvent event) { } ``` -`LanguageProvider` ------------------- +## `LanguageProvider` Each language provider is simple a map of strings where each translation key is mapped to a localized name. A translation key mapping can be added using `#add`. Additionally, there are methods which use the translation key of a `Block`, `Item`, `ItemStack`, `Enchantment`, `MobEffect`, and `EntityType`. diff --git a/docs/datagen/client/modelproviders.md b/docs/datagen/client/modelproviders.md index 614fb1ef4..f0a46a775 100644 --- a/docs/datagen/client/modelproviders.md +++ b/docs/datagen/client/modelproviders.md @@ -1,5 +1,7 @@ -Model Generation -================ +--- +sidebar_position: 1 +title: Model Generation +--- [Models] can be generated for models or block states by default. Each provides a method of generating the necessary JSONs (`ModelBuilder#toJson` for models and `IGeneratedBlockState#toJson` for block states). After implementation, the [associated providers][provider] must be [added][datagen] to the `DataGenerator`. @@ -22,8 +24,7 @@ public void gatherData(GatherDataEvent event) { } ``` -Model Files ------------ +## Model Files A `ModelFile` acts as the base for all models referenced or generated by a provider. Each model file stores the location relative to the `models` subdirectory and can assert whether the file exists. @@ -39,8 +40,7 @@ A `ModelFile` acts as the base for all models referenced or generated by a provi There should be no cases where an `UncheckedModelFile` is used to reference a model. If there is, then the associated resources are not properly being tracked by `ExistingFileHelper`. ::: -Model Builders --------------- +## Model Builders A `ModelBuilder` represents a to-be-generated `ModelFile`. It contains all the data about a model: its parent, faces, textures, transformations, lighting, and [loader]. @@ -76,8 +76,7 @@ A `BlockModelBuilder` represents a block model to-be-generated. In addition to t An `ItemModelBuilder` represents an item model to-be-generated. In addition to the `ModelBuilder`, [overrides] (`OverrideBuilder#override`) can be generated. Each override applied to a model can apply conditions which represent for a given property that must be above the specified value (`OverrideBuilder#predicate`). If the conditions are met, then the specified model (`OverrideBuilder#model`) will be rendered instead of this model. -Model Providers ---------------- +## Model Providers The `ModelProvider` subclasses are responsible for generating the constructed `ModelBuilder`s. The provider takes in the generator, mod id, subdirectory in the `models` folder to generate within, a `ModelBuilder` factory, and the existing file helper. Each provider subclass must implement `#registerModels`. @@ -126,8 +125,7 @@ this.basicItem(EXAMPLE_ITEM.get()); Item models for blocks should typically parent an existing block model instead of generating a separate model for an item. ::: -Block State Provider --------------------- +## Block State Provider A `BlockStateProvider` is responsible for generating [block state JSONs][blockstate] in `blockstates`, block models in `models/block`, and item models in `models/item` for said blocks. The provider takes in the data generator, mod id, and existing file helper. Each `BlockStateProvider` subclass must implement `#registerStatesAndModels`. @@ -288,8 +286,7 @@ this.getMultipartBuilder(REDSTONE) // Get multipart builder .end(); // Finish part ``` -Model Loader Builders ---------------------- +## Model Loader Builders Custom model loaders can also be generated for a given `ModelBuilder`. Custom model loaders subclass `CustomLoaderBuilder` and can be applied to a `ModelBuilder` via `#customLoader`. The factory method passed in creates a new loader builder to which configurations can be made. After all the changes have been finished, the custom loader can return back to the `ModelBuilder` via `CustomLoaderBuilder#end`. @@ -311,8 +308,7 @@ builder.customLoader(ObjModelBuilder::begin) // Custom loader 'forge:obj' .texture("texture0", mcLoc("block/dirt")); // Set 'texture0' texture to dirt ``` -Custom Model Loader Builders ----------------------------- +## Custom Model Loader Builders Custom loader builders can be created by extending `CustomLoaderBuilder`. The constructor can still have a `protected` visibility with the `ResourceLocation` hardcoded to the loader id registered via `ModelEvent$RegisterGeometryLoaders#register`. The builder can then be initialized via a static factory method or the constructor if made `public`. @@ -355,8 +351,7 @@ public JsonObject toJson(JsonObject json) { } ``` -Custom Model Providers ----------------------- +## Custom Model Providers Custom model providers require a `ModelBuilder` subclass, which defines the base of the model to generate, and a `ModelProvider` subclass, which generates the models. @@ -380,8 +375,7 @@ public class ExampleModelProvider extends ModelProvider { } ``` -Custom Model Consumers ----------------------- +## Custom Model Consumers Custom model consumers like [`BlockStateProvider`][blockstateprovider] can be created by manually generating the models themselves. The `ModelProvider` subclass used to generate the models should be specified and made available. diff --git a/docs/datagen/client/sounds.md b/docs/datagen/client/sounds.md index 6f0ec9136..a3b115510 100644 --- a/docs/datagen/client/sounds.md +++ b/docs/datagen/client/sounds.md @@ -1,5 +1,7 @@ -Sound Definition Generation -=========================== +--- +sidebar_position: 3 +title: Sound Definition Generation +--- The `sounds.json` file can be generated for a mod by subclassing `SoundDefinitionsProvider` and implementing `#registerSounds`. After implementation, the provider must be [added][datagen] to the `DataGenerator`. @@ -15,8 +17,7 @@ public void gatherData(GatherDataEvent event) { } ``` -Adding a Sound --------------- +## Adding a Sound A sound definition can be generated by specifying the sound name and definition via `#add`. The sound name can either be provided from a [`SoundEvent`][soundevent], `ResourceLocation`, or string. diff --git a/docs/datagen/server/advancements.md b/docs/datagen/server/advancements.md index 4b27b85d1..22b249ee2 100644 --- a/docs/datagen/server/advancements.md +++ b/docs/datagen/server/advancements.md @@ -1,5 +1,7 @@ -Advancement Generation -====================== +--- +sidebar_position: 4 +title: Advancement Generation +--- [Advancements] can be generated for a mod by constructing a new `AdvancementProvider` and providing `AdvancementSubProvider`s. Advancements can either be created and supplied manually or, for convenience, created using `Advancement$Builder`. The provider must be [added][datagen] to the `DataGenerator`. @@ -24,8 +26,7 @@ public void gatherData(GatherDataEvent event) { } ``` -`ForgeAdvancementProvider$AdvancementGenerator` ------------------------------------------------ +## `ForgeAdvancementProvider$AdvancementGenerator` A `ForgeAdvancementProvider$AdvancementGenerator` is responsible for generating advancements, containing a method which takes in a registry lookup, the writer (`Consumer`), and the existing file helper.. @@ -38,8 +39,7 @@ public void generate(HolderLookup.Provider registries, Consumer wri } ``` -`Advancement$Builder` ---------------------- +## `Advancement$Builder` `Advancement$Builder` is a convenience implementation for creating `Advancement`s to generate. It allows the definition of the parent advancement, the display information, the rewards when the advancement has been completed, and the requirements to unlock the advancement. Only the requirements need to be specified to create an `Advancement`. diff --git a/docs/datagen/server/datapackregistries.md b/docs/datagen/server/datapackregistries.md index 3f105921e..3fbac8994 100644 --- a/docs/datagen/server/datapackregistries.md +++ b/docs/datagen/server/datapackregistries.md @@ -1,5 +1,7 @@ -Datapack Registry Object Generation -================================== +--- +sidebar_position: 6 +title: Datapack Registry Object Generation +--- Datapack registry objects can be generated for a mod by constructing a new `DatapackBuiltinEntriesProvider` and providing a `RegistrySetBuilder` with the new objects to register. The provider must be [added][datagen] to the `DataGenerator`. @@ -25,8 +27,7 @@ public void gatherData(GatherDataEvent event) { } ``` -`RegistrySetBuilder` --------------------- +## `RegistrySetBuilder` A `RegistrySetBuilder` is responsible for building all datapack registry objects to be used within the game. The builder can add a new entry for a registry, which can then register objects to that registry. @@ -47,8 +48,7 @@ new RegistrySetBuilder() !!! note Datapack registries created through Forge can also generate their objects using this builder by also passing in the associated `ResourceKey`. -Registering with `BootstapContext` ----------------------------------- +## Registering with `BootstapContext` The `#register` method in the `BootstapContext` provided by the builder can be used to register objects. It takes in the `ResourceKey` representing the registry name of the object, the object to register, and an optional `Lifecycle` argument to indicate the registry object's current lifecycle status. diff --git a/docs/datagen/server/glm.md b/docs/datagen/server/glm.md index 1192b2377..4caf07fcd 100644 --- a/docs/datagen/server/glm.md +++ b/docs/datagen/server/glm.md @@ -1,5 +1,7 @@ -Global Loot Modifier Generation -=============================== +--- +sidebar_position: 5 +title: Global Loot Modifier Generation +--- [Global Loot Modifiers (GLMs)][glm] can be generated for a mod by subclassing `GlobalLootModifierProvider` and implementing `#start`. Each GLM can be added generated by calling `#add` and specifying the name of the modifier and the [modifier instance][instance] to be serialized. After implementation, the provider must be [added][datagen] to the `DataGenerator`. diff --git a/docs/datagen/server/loottables.md b/docs/datagen/server/loottables.md index 2436a2d2b..e70f96f3c 100644 --- a/docs/datagen/server/loottables.md +++ b/docs/datagen/server/loottables.md @@ -1,5 +1,7 @@ -Loot Table Generation -===================== +--- +sidebar_position: 2 +title: Loot Table Generation +--- [Loot tables][loottable] can be generated for a mod by constructing a new `LootTableProvider` and providing `LootTableProvider$SubProviderEntry`s. The provider must be [added][datagen] to the `DataGenerator`. @@ -21,8 +23,7 @@ public void gatherData(GatherDataEvent event) { } ``` -`LootTableSubProvider` ----------------------- +## `LootTableSubProvider` Each `LootTableProvider$SubProviderEntry` takes in a supplied `LootTableSubProvider`, which generates the loot table, for a given `LootContextParamSet`. The `LootTableSubProvider` contains a method which takes in the writer (`BiConsumer`) to generate a table. @@ -99,8 +100,7 @@ public void generate() { } ``` -Loot Table Builders -------------------- +## Loot Table Builders To generate loot tables, they are accepted by the `LootTableSubProvider` as a `LootTable$Builder`. Afterwards, the specified `LootContextParamSet` is set in the `LootTableProvider$SubProviderEntry` and then built via `#build`. Before being built, the builder can specify entries, conditions, and modifiers which affect how the loot table functions. diff --git a/docs/datagen/server/recipes.md b/docs/datagen/server/recipes.md index b74e98b96..8c616a3d8 100644 --- a/docs/datagen/server/recipes.md +++ b/docs/datagen/server/recipes.md @@ -1,5 +1,7 @@ -Recipe Generation -================= +--- +sidebar_position: 1 +title: Recipe Generation +--- Recipes can be generated for a mod by subclassing `RecipeProvider` and implementing `#buildRecipes`. A recipe is supplied for data generation once a `FinishedRecipe` view is accepted by the consumer. `FinishedRecipe`s can either be created and supplied manually or, for convenience, created using a `RecipeBuilder`. @@ -17,8 +19,7 @@ public void gatherData(GatherDataEvent event) { } ``` -`RecipeBuilder` ---------------- +## `RecipeBuilder` `RecipeBuilder` is a convenience implementation for creating `FinishedRecipe`s to generate. It provides basic definitions for unlocking, grouping, saving, and getting the result of a recipe. This is done through `#unlockedBy`, `#group`, `#save`, and `#getResult` respectively. @@ -90,8 +91,7 @@ SingleItemRecipeBuilder builder = SingleItemRecipeBuilder.stonecutting(input, Re .save(writer); // Add data to builder ``` -Non-`RecipeBuilder` Builders ----------------------------- +## Non-`RecipeBuilder` Builders Some recipe builders do not implement `RecipeBuilder` due to lacking features used by all previously mentioned recipes. @@ -127,8 +127,7 @@ SpecialRecipeBuilder.special(dynamicRecipeSerializer) .save(writer, name); // Add data to builder ``` -Conditional Recipes -------------------- +## Conditional Recipes [Conditional recipes][conditional] can also be data generated via `ConditionalRecipe$Builder`. The builder can be obtained using `#builder`. @@ -180,8 +179,7 @@ To simplify adding conditions to conditional recipes without having to construct ) ``` -Custom Recipe Serializers -------------------------- +## Custom Recipe Serializers Custom recipe serializers can be data generated by creating a builder that can construct a `FinishedRecipe`. The finished recipe encodes the recipe data and its unlocking advancement, when present, to JSON. Additionally, the name and serializer of the recipe is also specified to know where to write to and what can decode the object when loading. Once a `FinishedRecipe` is constructed, it simply needs to be passed to the `Consumer` supplied by `RecipeProvider#buildRecipes`. diff --git a/docs/datagen/server/tags.md b/docs/datagen/server/tags.md index ce3db346b..e72bca301 100644 --- a/docs/datagen/server/tags.md +++ b/docs/datagen/server/tags.md @@ -1,5 +1,7 @@ -Tag Generation -============== +--- +sidebar_position: 3 +title: Tag Generation +--- [Tags] can be generated for a mod by subclassing `TagsProvider` and implementing `#addTags`. After implementation, the provider must be [added][datagen] to the `DataGenerator`. @@ -21,8 +23,7 @@ public void gatherData(GatherDataEvent event) { } ``` -`TagsProvider` --------------- +## `TagsProvider` The tags provider has two methods used for generating tags: creating a tag with objects and other tags via `#tag`, or using tags from other object types to generate the tag data via `#getOrCreateRawBuilder`. @@ -87,8 +88,7 @@ Blocks have item representations to obtain them in the inventory. As such, many this.copy(EXAMPLE_BLOCK_TAG, EXAMPLE_ITEM_TAG); ``` -Custom Tag Providers --------------------- +## Custom Tag Providers A custom tag provider can be created via a `TagsProvider` subclass which takes in the registry key to generate tags for. From bc73dbde7598d789a30f872a1d8c128a5217ebdb Mon Sep 17 00:00:00 2001 From: Mysterious_Dev Date: Fri, 22 Sep 2023 17:38:35 +0200 Subject: [PATCH 10/21] Misc section --- docs/misc/components.md | 15 +++++++-------- docs/misc/config.md | 15 +++++++-------- docs/misc/debugprofiler.md | 5 ++++- docs/misc/gametest.mdx | 21 +++++++++------------ docs/misc/keymappings.md | 5 ++++- docs/misc/updatechecker.md | 15 +++++++-------- 6 files changed, 38 insertions(+), 38 deletions(-) diff --git a/docs/misc/components.md b/docs/misc/components.md index 921f2d75e..21c2823ac 100644 --- a/docs/misc/components.md +++ b/docs/misc/components.md @@ -1,5 +1,7 @@ -Text Components -================== +--- +sidebar_position: 6 +title: Text Components +--- A `Component` is a holder for text which can be formatted and chained with other components via its subtype `MutableComponent`. A component can be created using one of the available static helpers: @@ -16,8 +18,7 @@ A `Component` is a holder for text which can be formatted and chained with other A component's text contents are represented by `ComponentContents`. Notably, the subtype `TranslatableContents` not only supports [localization][internalization] but also [text formatting][formatting]. -Applying Style --------------- +## Applying Style Components can be formatted (e.g., bold, click actions, color) via `Style`s. `Style`s are immutable, creating a new `Style` each time when modified. The empty style `Style#EMPTY` can be used as a base for configuration. @@ -55,8 +56,7 @@ text.withStyle(red).withStyle(bold).withStyle(doubleLines); This creates a red, bold text with two lines: ![red_hello] -Chaining Components -------------------- +## Chaining Components `MutableComponent#append` can chain multiple components together. Chained components can be retrieved with `MutableComponent#getSiblings`. @@ -86,8 +86,7 @@ bold.append(fourth).append(fifth).append(sixth); ``` ![style_annotated] -Text Formatting ---------------- +## Text Formatting Text formatting is the process of inserting data as text into predefined larger text. It can be used for displaying coordinates, showing unit measurements, etc. **Format specifiers** are used for indicating where a text can be inserted. diff --git a/docs/misc/config.md b/docs/misc/config.md index e940fdb93..3c92240c1 100644 --- a/docs/misc/config.md +++ b/docs/misc/config.md @@ -1,10 +1,11 @@ -Configuration -============= +--- +sidebar_position: 1 +title: Configuration +--- Configurations define settings and consumer preferences that can be applied to a mod instance. Forge uses a configuration system using [TOML][toml] files and read with [NightConfig][nightconfig]. -Creating a Configuration ------------------------- +## Creating a Configuration A configuration can be created using a subtype of `IConfigSpec`. Forge implements the type via `ForgeConfigSpec` and enables its construction through `ForgeConfigSpec$Builder`. The builder can separate the config values into sections via `Builder#push` to create a section and `Builder#pop` to leave a section. Afterwards, the configuration can be built using one of two methods: @@ -102,8 +103,7 @@ The values themselves can be obtained using `ConfigValue#get`. The values are ad * Class Type: `Boolean` * Method Name: `#define` -Registering a Configuration ---------------------------- +## Registering a Configuration Once a `ForgeConfigSpec` has been built, it must be registered to allow Forge to load, track, and sync the configuration settings as required. Configurations should be registered in the mod constructor via `ModLoadingContext#registerConfig`. A configuration can be registered with a given type representing the side the config belongs to, the `ForgeConfigSpec`, and optionally a specific file name for the configuration. @@ -124,8 +124,7 @@ SERVER | Server Side Only | Yes | `.minecraft/saves//se Forge documents the [config types][type] within their codebase. ::: -Configuration Events --------------------- +## Configuration Events Operations that occur whenever a config is loaded or reloaded can be done using the `ModConfigEvent$Loading` and `ModConfigEvent$Reloading` events. The events must be [registered][events] to the mod event bus. diff --git a/docs/misc/debugprofiler.md b/docs/misc/debugprofiler.md index f59e33b56..98572df55 100644 --- a/docs/misc/debugprofiler.md +++ b/docs/misc/debugprofiler.md @@ -1,4 +1,7 @@ -# Debug Profiler +--- +sidebar_position: 5 +title: Debug Profiler +--- Minecraft provides a Debug Profiler that provides system data, current game settings, JVM data, level data, and sided tick information to find time consuming code. Considering things like `TickEvent`s and ticking `BlockEntities`, this can be very useful for modders and server owners that want to find a lag source. diff --git a/docs/misc/gametest.mdx b/docs/misc/gametest.mdx index 90b1f0470..a7d9bc791 100644 --- a/docs/misc/gametest.mdx +++ b/docs/misc/gametest.mdx @@ -1,10 +1,11 @@ -Game Tests -========== +--- +sidebar_position: 3 +title: Game Tests +--- Game Tests are a way to run in-game unit tests. The system was designed to be scalable and in parallel to run large numbers of different tests efficiently. Testing object interactions and behaviors are simply a few of the many applications of this framework. -Creating a Game Test --------------------- +## Creating a Game Test A standard Game Test follows three basic steps: @@ -128,8 +129,7 @@ public class ExampleGameTests { } ``` -Registering a Game Test ------------------------ +## Registering a Game Test A Game Test must be registered to be ran in-game. There are two methods of doing so: via the `@GameTestHolder` annotation or `RegisterGameTestsEvent`. Both registration methods still require the test methods to be annotated with either `@GameTest`, `@GameTestGenerator`, `@BeforeBatch`, or `@AfterBatch`. @@ -165,8 +165,7 @@ public static void exampleTest3(GameTestHelper helper) { The value supplied to `GameTestHolder#value` and `GameTest#templateNamespace` can be different from the current mod id. The configuration within the [buildscript][namespaces] would need to be changed. ::: -Structure Templates -------------------- +## Structure Templates Game Tests are performed within scenes loaded by structures, or templates. All templates define the dimensions of the scene and the initial data (blocks and entities) that will be loaded. The template must be stored as an `.nbt` file within `data//structures`. @@ -215,8 +214,7 @@ public class ExampleGameTests { } ``` -Running Game Tests ------------------- +## Running Game Tests Game Tests can be run using the `/test` command. The `test` command is highly configurable; however, only a few are of importance to running tests: @@ -232,8 +230,7 @@ Subcommand | Description Subcommands follow the test command: `/test `. ::: -Buildscript Configurations --------------------------- +## Buildscript Configurations Game Tests provide additional configuration settings within a buildscript (the `build.gradle` file) to run and integrate into different settings. diff --git a/docs/misc/keymappings.md b/docs/misc/keymappings.md index b95863e7b..06ef4eee0 100644 --- a/docs/misc/keymappings.md +++ b/docs/misc/keymappings.md @@ -1,4 +1,7 @@ -# Key Mappings +--- +sidebar_position: 2 +title: Key Mappings +--- A key mapping, or key binding, defines a particular action that should be tied to an input: mouse click, key press, etc. Each action defined by a key mapping can be checked whenever the client can take an input. Furthermore, each key mapping can be assigned to any input through the [Controls option menu][controls]. diff --git a/docs/misc/updatechecker.md b/docs/misc/updatechecker.md index 85d7960ce..ef2c32f8c 100644 --- a/docs/misc/updatechecker.md +++ b/docs/misc/updatechecker.md @@ -1,15 +1,15 @@ -Forge Update Checker -==================== +--- +sidebar_position: 4 +title: Forge Update Checker +--- Forge provides a very lightweight, opt-in, update-checking framework. If any mods have an available update, it will show a flashing icon on the 'Mods' button of the main menu and mod list along with the respective changelogs. It *does not* download updates automatically. -Getting Started ---------------- +## Getting Started The first thing you want to do is specify the `updateJSONURL` parameter in your `mods.toml` file. The value of this parameter should be a valid URL pointing to an update JSON file. This file can be hosted on your own web server, GitHub, or wherever you want as long as it can be reliably reached by all users of your mod. -Update JSON format ------------------- +## Update JSON format The JSON itself has a relatively simple format as follows: @@ -40,8 +40,7 @@ This is fairly self-explanatory, but some notes: - Some examples can be found here for [nocubes][], [Corail Tombstone][corail] and [Chisels & Bits 2][chisel]. -Retrieving Update Check Results -------------------------------- +## Retrieving Update Check Results You can retrieve the results of the Forge Update Checker using `VersionChecker#getResult(IModInfo)`. You can obtain your `IModInfo` via `ModContainer#getModInfo`. You can get your `ModContainer` using `ModLoadingContext.get().getActiveContainer()` inside your constructor, `ModList.get().getModContainerById()`, or `ModList.get().getModContainerByObject()`. You can obtain any other mod's `ModContainer` using `ModList.get().getModContainerById()`. The returned object has a method `#status` which indicates the status of the version check. From 44d1d0e788a3e7d1f52993baf352ab108bb11fb4 Mon Sep 17 00:00:00 2001 From: Mysterious_Dev Date: Sat, 23 Sep 2023 12:39:39 +0200 Subject: [PATCH 11/21] Networking section --- docs/networking/entities.md | 6 ++++-- docs/networking/simpleimpl.md | 6 ++++-- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/networking/entities.md b/docs/networking/entities.md index 466b6cfcb..02fd7e627 100644 --- a/docs/networking/entities.md +++ b/docs/networking/entities.md @@ -1,5 +1,7 @@ -Entities -======== +--- +sidebar_position: 2 +title: Synchronizing Entities +--- In addition to regular network messages, there are various other systems provided to handle synchronizing entity data. diff --git a/docs/networking/simpleimpl.md b/docs/networking/simpleimpl.md index 88380f089..3d76aea67 100644 --- a/docs/networking/simpleimpl.md +++ b/docs/networking/simpleimpl.md @@ -1,5 +1,7 @@ -SimpleImpl -========== +--- +sidebar_position: 1 +title: SimpleImpl +--- SimpleImpl is the name given to the packet system that revolves around the `SimpleChannel` class. Using this system is by far the easiest way to send custom data between clients and the server. From 571d2ff1ce3444f88a0a5d95261c715dd865c18f Mon Sep 17 00:00:00 2001 From: Mysterious_Dev Date: Sun, 15 Oct 2023 11:24:12 +0200 Subject: [PATCH 12/21] Finish items section --- docs/items/bewlr.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/items/bewlr.md b/docs/items/bewlr.md index fcabedad8..d0d0f3e4b 100644 --- a/docs/items/bewlr.md +++ b/docs/items/bewlr.md @@ -1,9 +1,10 @@ -BlockEntityWithoutLevelRenderer -======================= +--- +title: BlockEntityWithoutLevelRenderer +--- + `BlockEntityWithoutLevelRenderer` is a method to handle dynamic rendering on items. This system is much simpler than the old `ItemStack` system, which required a `BlockEntity`, and did not allow access to the `ItemStack`. -Using BlockEntityWithoutLevelRenderer --------------------------- +## Using BlockEntityWithoutLevelRenderer BlockEntityWithoutLevelRenderer allows you to render your item using `public void renderByItem(ItemStack itemStack, ItemDisplayContext ctx, PoseStack poseStack, MultiBufferSource bufferSource, int combinedLight, int combinedOverlay)`. From 36a8d542d493ce77ead8155c393e307bbc0dc688 Mon Sep 17 00:00:00 2001 From: Mysterious_Dev Date: Sun, 15 Oct 2023 11:26:25 +0200 Subject: [PATCH 13/21] Add position --- docs/items/bewlr.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/items/bewlr.md b/docs/items/bewlr.md index d0d0f3e4b..0e90c037b 100644 --- a/docs/items/bewlr.md +++ b/docs/items/bewlr.md @@ -1,4 +1,5 @@ --- +sidebar_position: 1 title: BlockEntityWithoutLevelRenderer --- From e9f77ace60542fbd30489951db06e2162dfc1c9e Mon Sep 17 00:00:00 2001 From: Mysterious_Dev Date: Sun, 15 Oct 2023 11:30:34 +0200 Subject: [PATCH 14/21] Data Storage section --- docs/datastorage/capabilities.md | 30 ++++++++++++------------------ docs/datastorage/codecs.md | 12 ++++-------- docs/datastorage/saveddata.md | 12 ++++++------ 3 files changed, 22 insertions(+), 32 deletions(-) diff --git a/docs/datastorage/capabilities.md b/docs/datastorage/capabilities.md index 9204511d5..98e865bcf 100644 --- a/docs/datastorage/capabilities.md +++ b/docs/datastorage/capabilities.md @@ -1,5 +1,7 @@ -The Capability System -===================== +--- +sidebar_position: 1 +title: Capabilities +--- Capabilities allow exposing features in a dynamic and flexible way without having to resort to directly implementing many interfaces. @@ -7,8 +9,7 @@ In general terms, each capability provides a feature in the form of an interface Forge adds capability support to BlockEntities, Entities, ItemStacks, Levels, and LevelChunks, which can be exposed either by attaching them through an event or by overriding the capability methods in your own implementations of the objects. This will be explained in more detail in the following sections. -Forge-provided Capabilities ---------------------------- +## Forge-provided Capabilities Forge provides three capabilities: `IItemHandler`, `IFluidHandler` and `IEnergyStorage` @@ -18,8 +19,7 @@ Forge provides three capabilities: `IItemHandler`, `IFluidHandler` and `IEnergyS `IEnergyStorage` exposes an interface for handling energy containers. It can be applied to BlockEntities, Entities, or ItemStacks. It is based on the RedstoneFlux API by TeamCoFH. -Using an Existing Capability ----------------------------- +## Using an Existing Capability As mentioned earlier, BlockEntities, Entities, and ItemStacks implement the capability provider feature through the `ICapabilityProvider` interface. This interface adds the method `#getCapability`, which can be used to query the capabilities present in the associated provider objects. @@ -37,8 +37,7 @@ Even if you have a non-null capability available to you at all times, it does no The `#getCapability` method has a second parameter, of type `Direction`, which can be used to request the specific instance for that one face. If passed `null`, it can be assumed that the request comes either from within the block or from some place where the side has no meaning, such as a different dimension. In this case a general capability instance that does not care about sides will be requested instead. The return type of `#getCapability` will correspond to a `LazyOptional` of the type declared in the capability passed to the method. For the Item Handler capability, this is `LazyOptional`. If the capability is not available for a particular provider, it will return an empty `LazyOptional` instead. -Exposing a Capability ---------------------- +## Exposing a Capability In order to expose a capability, you will first need an instance of the underlying capability type. Note that you should assign a separate instance to each object that keeps the capability, since the capability will most probably be tied to the containing object. @@ -86,8 +85,7 @@ public LazyOptional getCapability(Capability cap, Direction side) { It is strongly suggested that direct checks in code are used to test for capabilities instead of attempting to rely on maps or other data structures, since capability tests can be done by many objects every tick, and they need to be as fast as possible in order to avoid slowing down the game. -Attaching Capabilities ----------------------- +## Attaching Capabilities As mentioned, attaching capabilities to existing providers, `Level`s, and `LevelChunk`s can be done using `AttachCapabilitiesEvent`. The same event is used for all objects that can provide capabilities. `AttachCapabilitiesEvent` has 5 valid generic types providing the following events: @@ -103,8 +101,7 @@ In all cases, the event has a method `#addCapability` which can be used to attac For information on how to implement `ICapabilityProvider`, refer to the [Exposing a Capability][expose] section. -Creating Your Own Capability ----------------------------- +## Creating Your Own Capability A capability can be registered using one of two ways: `RegisterCapabilitiesEvent` or `@AutoRegisterCapability`. @@ -130,8 +127,7 @@ public interface IExampleCapability { } ``` -Persisting LevelChunk and BlockEntity capabilities --------------------------------------------- +## Persisting LevelChunk and BlockEntity capabilities Unlike Levels, Entities, and ItemStacks, LevelChunks and BlockEntities are only written to disk when they have been marked as dirty. A capability implementation with persistent state for a LevelChunk or a BlockEntity should therefore ensure that whenever its state changes, its owner is marked as dirty. @@ -152,8 +148,7 @@ public class MyBlockEntity extends BlockEntity { } ``` -Synchronizing Data with Clients -------------------------------- +## Synchronizing Data with Clients By default, capability data is not sent to clients. In order to change this, the mods have to manage their own synchronization code using packets. @@ -165,8 +160,7 @@ There are three different situations in which you may want to send synchronizati Refer to the [Networking][network] page for more information on implementing network packets. -Persisting across Player Deaths -------------------------------- +## Persisting across Player Deaths By default, the capability data does not persist on death. In order to change this, the data has to be manually copied when the player entity is cloned during the respawn process. diff --git a/docs/datastorage/codecs.md b/docs/datastorage/codecs.md index 0d08b3dd6..35b4bcf3b 100644 --- a/docs/datastorage/codecs.md +++ b/docs/datastorage/codecs.md @@ -1,4 +1,7 @@ -# Codecs +--- +sidebar_position: 3 +title: Codecs +--- Codecs are a serialization tool from Mojang's [DataFixerUpper] used to describe how objects can be transformed between different formats, such as `JsonElement`s for JSON and `Tag`s for NBT. @@ -432,10 +435,3 @@ public static final Codec = DISPATCH.getCodec() // Gets Codec Date: Sun, 15 Oct 2023 11:32:31 +0200 Subject: [PATCH 15/21] Game effects section --- docs/gameeffects/particles.md | 15 ++++++--------- docs/gameeffects/sounds.md | 24 ++++++++---------------- 2 files changed, 14 insertions(+), 25 deletions(-) diff --git a/docs/gameeffects/particles.md b/docs/gameeffects/particles.md index 91a216bdc..8f6bad2f0 100644 --- a/docs/gameeffects/particles.md +++ b/docs/gameeffects/particles.md @@ -1,10 +1,11 @@ -Particles -========= +--- +sidebar_position: 1 +title: Particles +--- Particles are an effect within the game used as polish to better improve immersion. Their usefulness also requires great caution because of their methods of creation and reference. -Creating a Particle -------------------- +## Creating a Particle Particles are broken up between its [**client only**][sides] implementation to display the particle and its common implementation to reference the particle or sync data from the server. @@ -120,10 +121,6 @@ To register these particle textures, a `SpriteParticleRegistration` needs to be If you are registering a `TextureSheetParticle` subtype which only contains one texture, then you can supply a `ParticleProvider$Sprite` instead to the `#registerSprite` method, which has essentially the same functional interface method as `ParticleProvider`. ::: -Spawning a Particle -------------------- +## Spawning a Particle Particles can be spawned from either level instance. However, each side has a specific way to spawn a particle. If on the `ClientLevel`, `#addParticle` can be called to spawn a particle or `#addAlwaysVisibleParticle` can be called to spawn a particle that is visible from any distance. If on the `ServerLevel`, `#sendParticles` can be called to send a packet to the client to spawn the particle. Calling the two `ClientLevel` methods on the server will result in nothing. - -[sides]: ../concepts/sides.md -[registration]: ../concepts/registries.md#methods-for-registering diff --git a/docs/gameeffects/sounds.md b/docs/gameeffects/sounds.md index 1f28503b9..bcc7b6f40 100644 --- a/docs/gameeffects/sounds.md +++ b/docs/gameeffects/sounds.md @@ -1,8 +1,9 @@ -Sounds -====== +--- +sidebar_position: 2 +title: Sounds +--- -Terminology ------------ +## Terminology | Term | Description | |----------------|----------------| @@ -10,8 +11,7 @@ Terminology | Sound Category | The category of the sound, for example `player`, `block` or simply `master`. The sliders in the sound settings GUI represent these categories. | | Sound File | The literal file on disk that is played: an .ogg file. | -`sounds.json` -------------- +## `sounds.json` This JSON defines sound events, and defines which sound files they play, the subtitle, etc. Sound events are identified with [`ResourceLocation`][loc]s. `sounds.json` should be located at the root of a resource namespace (`assets//sounds.json`), and it defines sound events in that namespace (`assets//sounds.json` defines sound events in the namespace `namespace`.). @@ -42,8 +42,7 @@ In all cases, the path to a sound file for namespace `namespace` and path `path` A `sounds.json` can be [data generated][datagen]. -Creating Sound Events ---------------------- +## Creating Sound Events In order to reference sounds on the server, a `SoundEvent` holding a corresponding entry in `sounds.json` must be created. This `SoundEvent` must then be [registered][registration]. Normally, the location used to create a sound event should be set as it's registry name. @@ -53,8 +52,7 @@ The `SoundEvent` acts as a reference to the sound and is passed around to play t As long as a sound is registered within the `sounds.json`, it can still be referenced on the logical client regardless of whether there is a referencing `SoundEvent`. ::: -Playing Sounds --------------- +## Playing Sounds Vanilla has lots of methods for playing sounds, and it is unclear which to use at times. @@ -103,9 +101,3 @@ Note that each takes a `SoundEvent`, the ones registered above. Additionally, th - **Client Behavior**: Just plays the Sound Event. - **Server Behavior**: Method is client-only. - **Usage**: Just like the ones in `Level`, these two overrides in the player classes seem to be for code that runs together on both sides. The client handles playing the sound to the user, while the server handles everyone else hearing it without re-playing to the original user. - -[loc]: ../concepts/resources.md#resourcelocation -[wiki]: https://minecraft.fandom.com/wiki/Sounds.json -[datagen]: ../datagen/client/sounds.md -[registration]: ../concepts/registries.md#methods-for-registering -[sides]: ../concepts/sides.md From 451c1854c3440fdc918846d9aa86bc4a6eed9955 Mon Sep 17 00:00:00 2001 From: Mysterious_Dev Date: Sun, 15 Oct 2023 11:33:57 +0200 Subject: [PATCH 16/21] Gui section --- docs/gui/menus.md | 13 ++++--------- docs/gui/screens.md | 13 ++++--------- 2 files changed, 8 insertions(+), 18 deletions(-) diff --git a/docs/gui/menus.md b/docs/gui/menus.md index 3a5f63c25..f0d41c18a 100644 --- a/docs/gui/menus.md +++ b/docs/gui/menus.md @@ -1,4 +1,7 @@ -# Menus +--- +sidebar_position: 1 +title: Menus +--- Menus are one type of backend for Graphical User Interfaces, or GUIs; they handle the logic involved in interacting with some represented data holder. Menus themselves are not data holders. They are views which allow to user to indirectly modify the internal data holder state. As such, a data holder should not be directly coupled to any menu, instead passing in the data references to invoke and modify. @@ -337,11 +340,3 @@ public class MyMob extends Mob implements MenuProvider { :::note Once again, this is the simplest way to implement the logic, not the only way. ::: - -[registered]: ../concepts/registries.md#methods-for-registering -[acm]: #abstractcontainermenu -[mt]: #menutype -[qms]: #quickmovestack -[cap]: ../datastorage/capabilities.md#forge-provided-capabilities -[screen]: ./screens.md -[icf]: #icontainerfactory diff --git a/docs/gui/screens.md b/docs/gui/screens.md index b1591033f..91e2efeab 100644 --- a/docs/gui/screens.md +++ b/docs/gui/screens.md @@ -1,4 +1,7 @@ -# Screens +--- +sidebar_position: 2 +title: Screens +--- Screens are typically the base of all Graphical User Interfaces (GUIs) in Minecraft: taking in user input, verifying it on the server, and syncing the resulting action back to the client. They can be combined with [menus] to create an communication network for inventory-like views, or they can be standalone which modders can handle through their own [network] implementations. @@ -344,11 +347,3 @@ private void clientSetup(FMLClientSetupEvent event) { :::danger `MenuScreens#register` is not thread-safe, so it needs to be called inside `#enqueueWork` provided by the parallel dispatch event. ::: - -[menus]: ./menus.md -[network]: ../networking/index.md -[screen]: #the-screen-subtype -[argb]: https://en.wikipedia.org/wiki/RGBA_color_model#ARGB32 -[component]: ../concepts/internationalization.md#translatablecontents -[keymapping]: ../misc/keymappings.md#inside-a-gui -[modbus]: ../concepts/events.md#mod-event-bus From 041ef68eec9c8f6029953f246c1ecab5c6e38dc2 Mon Sep 17 00:00:00 2001 From: Mysterious_Dev Date: Thu, 2 Nov 2023 10:22:34 +0100 Subject: [PATCH 17/21] Resources section --- docs/resources/server/advancements.md | 12 +++++----- docs/resources/server/conditional.md | 15 ++++++------ docs/resources/server/glm.md | 21 ++++++++--------- docs/resources/server/loottables.md | 15 ++++++------ docs/resources/server/recipes/custom.md | 24 ++++++++------------ docs/resources/server/recipes/incode.md | 15 ++++++------ docs/resources/server/recipes/ingredients.md | 12 +++++----- docs/resources/server/tags.md | 23 +++++++++---------- 8 files changed, 63 insertions(+), 74 deletions(-) diff --git a/docs/resources/server/advancements.md b/docs/resources/server/advancements.md index 2e50757c8..cb2131181 100644 --- a/docs/resources/server/advancements.md +++ b/docs/resources/server/advancements.md @@ -1,12 +1,13 @@ -Advancements -============ +--- +sidebar_position: 4 +title: Advancements +--- Advancements are tasks that can be achieved by the player which may advance the progress of the game. Advancements can trigger based on any action the player may be directly involved in. All advancement implementations within vanilla are data driven via JSON. This means that a mod is not necessary to create a new advancement, only a [data pack][datapack]. A full list on how to create and put these advancements within the mod's `resources` can be found on the [Minecraft Wiki][wiki]. Additionally, advancements can be [loaded conditionally and defaulted][conditional] depending on what information is present (mod loaded, item exists, etc.). -Advancement Criteria --------------------- +## Advancement Criteria To unlock an advancement, the specified criteria must be met. Criteria are tracked through triggers which execute when a certain action is performed: killing an entity, changing an inventory, breading animals, etc. Any time an advancement is loaded into the game, the criteria defined are read and added as listeners to the trigger. Afterwards a trigger function is called (usually named `#trigger`) which checks all listeners as to whether the current state meets the conditions of the advancement criteria. The criteria listeners for the advancement are only removed once the advancement has been obtained by completing all requirements. @@ -137,8 +138,7 @@ public void performExampleAction(ServerPlayer player, ItemStack stack) { } ``` -Advancement Rewards -------------------- +## Advancement Rewards When an advancement is completed, rewards may be given out. These can be a combination of experience points, loot tables, recipes for the recipe book, or a [function] executed as a creative player. diff --git a/docs/resources/server/conditional.md b/docs/resources/server/conditional.md index 89b8562f0..f90496354 100644 --- a/docs/resources/server/conditional.md +++ b/docs/resources/server/conditional.md @@ -1,10 +1,11 @@ -Conditionally-Loaded Data -========================= +--- +sidebar_position: 5 +title: Conditionally-Loaded Data +--- There are times when modders may want to include data-driven objects using information from another mod without having to explicitly make that mod a dependency. Other cases may be to swap out certain objects with other modded entries when they are present. This can be done through the conditional subsystem. -Implementations ---------------- +## Implementations Currently, conditional loading is implemented for recipes and advancements. For any conditional recipe or advancement, a list of conditions to datum pair is loaded. If the conditions specified for a datum in the list is true, then that datum is returned. Otherwise, the datum is discarded. @@ -39,8 +40,7 @@ Currently, conditional loading is implemented for recipes and advancements. For Conditionally-loaded data additionally have wrappers for [data generation][datagen] through `ConditionalRecipe$Builder` and `ConditionalAdvancement$Builder`. -Conditions ----------- +## Conditions Conditions are specified by setting `type` to the name of the condition as specified by [`IConditionSerializer#getID`][serializer]. @@ -127,8 +127,7 @@ Boolean operator conditions consist of the condition(s) being operated upon and } ``` -Creating Custom Conditions --------------------------- +## Creating Custom Conditions Custom conditions can be created by implementing `ICondition` and its associated `IConditionSerializer`. diff --git a/docs/resources/server/glm.md b/docs/resources/server/glm.md index 71fae565a..d7b469ace 100644 --- a/docs/resources/server/glm.md +++ b/docs/resources/server/glm.md @@ -1,10 +1,11 @@ -Global Loot Modifiers -=========== +--- +sidebar_position: 2 +title: Global Loot Modifiers +--- Global Loot Modifiers are a data-driven method of handling modification of harvested drops without the need to overwrite dozens to hundreds of vanilla loot tables or to handle effects that would require interactions with another mod's loot tables without knowing what mods may be loaded. Global Loot Modifiers are also stacking, rather than last-load-wins, similar to tags. -Registering a Global Loot Modifier -------------------------------- +## Registering a Global Loot Modifier You will need 4 things: @@ -17,8 +18,7 @@ You will need 4 things: 4. Finally, a codec to encode and decode your operational class. * This is [registered] as any other `IForgeRegistryEntry`. -The `global_loot_modifiers.json` -------------------------------- +## The `global_loot_modifiers.json` The `global_loot_modifiers.json` represents all loot modifiers to be loaded into the game. This file **MUST** be placed within `data/forge/loot_modifiers/global_loot_modifiers.json`. @@ -42,8 +42,7 @@ The `global_loot_modifiers.json` represents all loot modifiers to be loaded into } ``` -The Serialized JSON -------------------------------- +## The Serialized JSON This file contains all of the potential variables related to your modifier, including the conditions that must be met prior to modifying any loot. Avoid hard-coded values wherever possible so that data pack makers can adjust balance if they wish to. @@ -71,8 +70,7 @@ Any additional properties read by the serializer and defined by the modifier can } ``` -`IGlobalLootModifier` ---------------------- +## `IGlobalLootModifier` To supply the functionality a global loot modifier specifies, a `IGlobalLootModifier` implementation must be specified. These are instances generated each time a serializer decodes the information from JSON and supplies it into this object. @@ -115,8 +113,7 @@ public class ExampleModifier extends LootModifier { } ``` -The Loot Modifier Codec ------------------------ +## The Loot Modifier Codec The connector between the JSON and the `IGlobalLootModifier` instance is a [`Codec`][codecdef], where `T` represents the type of the `IGlobalLootModifier` to use. diff --git a/docs/resources/server/loottables.md b/docs/resources/server/loottables.md index 83878378c..46623a806 100644 --- a/docs/resources/server/loottables.md +++ b/docs/resources/server/loottables.md @@ -1,15 +1,15 @@ -Loot Tables -=========== +--- +sidebar_position: 1 +title: Loot Tables +--- Loot tables are logic files which dictate what should happen when various actions or scenarios occur. Although the vanilla system deals purely with item generation, the system can be expanded to perform any number of defined actions. -Data-Driven Tables ------------------- +## Data-Driven Tables Most loot tables within vanilla are data driven via JSON. This means that a mod is not necessary to create a new loot table, only a [Data pack][datapack]. A full list on how to create and put these loot tables within the mod's `resources` folder can be found on the [Minecraft Wiki][wiki]. -Using a Loot Table ------------------- +## Using a Loot Table A loot table is referenced by its `ResourceLocation` which points to `data//loot_tables/.json`. The `LootTable` associated with the reference can be obtained using `LootDataResolver#getLootTable`, where `LootDataResolver` can be obtained via `MinecraftServer#getLootData`. @@ -29,8 +29,7 @@ Method | Description Loot tables were built for generating items, so the methods expect some handling for the `ItemStack`s. ::: -Additional Features -------------------- +## Additional Features Forge provides some additional behavior to loot tables for greater control of the system. diff --git a/docs/resources/server/recipes/custom.md b/docs/resources/server/recipes/custom.md index c6b409fad..aa1f5a4e1 100644 --- a/docs/resources/server/recipes/custom.md +++ b/docs/resources/server/recipes/custom.md @@ -1,10 +1,11 @@ -Custom Recipes -============== +--- +sidebar_position: 1 +title: Custom Recipes +--- Every recipe definition is made up of three components: the `Recipe` implementation which holds the data and handles the execution logic with the provided inputs, the `RecipeType` which represents the category or context the recipe will be used in, and the `RecipeSerializer` which handles decoding and network communication of the recipe data. How one chooses to use the recipe is up to the implementor. -Recipe ------- +## Recipe The `Recipe` interface describes the recipe data and the execution logic. This includes matching the inputs and providing the associated result. As the recipe subsystem performs item transformations by default, the inputs are supplied through a `Container` subtype. @@ -32,8 +33,7 @@ public record ExampleRecipe(Ingredient input, int data, ItemStack output) implem While a record is used in the above example, it is not required to do so in your own implementation. ::: -RecipeType ----------- +## RecipeType `RecipeType` is responsible for defining the category or context the recipe will be used within. For example, if a recipe was going to be smelted in a furnace, it would have a type of `RecipeType#SMELTING`. Being blasted in a blast furnace would have a type of `RecipeType#BLASTING`. @@ -50,8 +50,7 @@ public RecipeType getType() { } ``` -RecipeSerializer ----------------- +## RecipeSerializer A `RecipeSerializer` is responsible for decoding JSONs and communicating across the network for an associated `Recipe` subtype. Each recipe decoded by the serializer is saved as a unique instance within the `RecipeManager`. A `RecipeSerializer` must be [registered][forge]. @@ -78,8 +77,7 @@ public RecipeSerializer getSerializer() { There are some useful methods to make reading and writing data for recipes easier. `Ingredient`s can use `#fromJson`, `#toNetwork`, and `#fromNetwork` while `ItemStack`s can use `CraftingHelper#getItemStack`, `FriendlyByteBuf#writeItem`, and `FriendlyByteBuf#readItem`. ::: -Building the JSON ------------------ +## Building the JSON Custom Recipe JSONs are stored in the same place as other [recipes][json]. The specified `type` should represent the registry name of the **recipe serializer**. Any additional data is specified by the serializer during decoding. @@ -97,8 +95,7 @@ Custom Recipe JSONs are stored in the same place as other [recipes][json]. The s } ``` -Non-Item Logic --------------- +## Non-Item Logic If items are not used as part of the input or result of a recipe, then the normal methods provided in [`RecipeManager`][manager] will not be useful. Instead, an additional method for testing a recipe's validity and/or supplying the result should be added to the custom `Recipe` instance. From there, all the recipes for that specific `RecipeType` can be obtained via `RecipeManager#getAllRecipesFor` and then checked and/or supplied the result using the newly implemented methods. @@ -121,8 +118,7 @@ public Optional getRecipeFor(Level level, BlockPos pos) { } ``` -Data Generation ---------------- +## Data Generation All custom recipes, regardless of input or output data, can be created into a `FinishedRecipe` for [data generation][datagen] using the `RecipeProvider`. diff --git a/docs/resources/server/recipes/incode.md b/docs/resources/server/recipes/incode.md index 26d1f7ce4..81dda1a90 100644 --- a/docs/resources/server/recipes/incode.md +++ b/docs/resources/server/recipes/incode.md @@ -1,10 +1,11 @@ -Non-Datapack Recipes -==================== +--- +sidebar_position: 3 +title: Non-Datapack Recipes +--- Not all recipes are simplistic enough or migrated to using data-driven recipes. Some subsystems still need to be patched within the codebase to provide support for adding new recipes. -Brewing Recipes ---------------- +## Brewing Recipes Brewing is one of the few recipes that still exist in code. Brewing recipes are added as part of a bootstrap within `PotionBrewing` for their containers, container recipes, and potion mixes. To expand upon the existing system, Forge allows brewing recipes to be added by calling `BrewingRecipeRegistry#addRecipe` in `FMLCommonSetupEvent`. @@ -24,8 +25,7 @@ When copying data between `ItemStack`s or `CompoundTag`s, make sure to use their There is no wrapper for adding additional potion containers or potion mixes similar to vanilla. A new `IBrewingRecipe` implementation will need to be added to replicate this behavior. -Anvil Recipes -------------- +## Anvil Recipes Anvils are responsible for taking a damaged input and given some material or a similar input, remove some of the damage on the input result. As such, its system is not easily data-driven. However, as anvil recipes are an input with some number of materials equals some output when the user has the required experience levels, it can be modified to create a pseudo-recipe system via `AnvilUpdateEvent`. This takes in the input and materials and allows the modder to specify the output, experience level cost, and number of materials to use for the output. The event can also prevent any output by [canceling][cancel] it. @@ -43,8 +43,7 @@ public void updateAnvil(AnvilUpdateEvent event) { The update event must be [attached] to the Forge event bus. -Loom Recipes ------------- +## Loom Recipes Looms are responsible for applying a dye and pattern (either from the loom or from an item) to a banner. While the banner and the dye must be a `BannerItem` or `DyeItem` respectively, custom patterns can be created and applied in the loom. Banner Patterns can be created by [registering] a `BannerPattern`. diff --git a/docs/resources/server/recipes/ingredients.md b/docs/resources/server/recipes/ingredients.md index 94722bc43..b357b461c 100644 --- a/docs/resources/server/recipes/ingredients.md +++ b/docs/resources/server/recipes/ingredients.md @@ -1,10 +1,11 @@ -Ingredients -=========== +--- +sidebar_position: 2 +title: Ingredients +--- `Ingredient`s are predicate handlers for item-based inputs which check whether a certain `ItemStack` meets the condition to be a valid input in a recipe. All [vanilla recipes][recipes] that take inputs use an `Ingredient` or a list of `Ingredient`s, which is then merged into a single `Ingredient`. -Custom Ingredients ------------------- +## Custom Ingredients Custom ingredients can be specified by setting `type` to the name of the [ingredient's serializer][serializer], with the exception of [compound ingredients][compound]. When no type is specified, `type` defaults to the vanilla ingredient `minecraft:item`. Custom ingredients can also easily be used in [data generation][datagen]. @@ -113,8 +114,7 @@ Though they are functionally identical, Compound ingredients replaces the way on } ``` -Creating Custom Ingredients ---------------------------- +## Creating Custom Ingredients Custom ingredients can be created by implementing `IIngredientSerializer` for the created `Ingredient` subclass. diff --git a/docs/resources/server/tags.md b/docs/resources/server/tags.md index f161460b1..d672638f8 100644 --- a/docs/resources/server/tags.md +++ b/docs/resources/server/tags.md @@ -1,10 +1,12 @@ -Tags -==== +--- +sidebar_position: 3 +title: Tags +--- Tags are generalized sets of objects in the game used for grouping related things together and providing fast membership checks. -Declaring Your Own Groupings ----------------------------- +## Declaring Your Own Groupings + Tags are declared in your mod's [datapack][datapack]. For example, a `TagKey` with a given identifier of `modid:foo/tagname` will reference a tag at `/data//tags/blocks/foo/tagname.json`. Tags for `Block`s, `Item`s, `EntityType`s, `Fluid`s, and `GameEvent`s use the plural forms for their folder location while all other registries use the singular version (`EntityType` uses the folder `entity_types` while `Potion` would use the folder `potion`). Similarly, you may append to or override tags declared in other domains, such as Vanilla, by declaring your own JSONs. For example, to add your own mod's saplings to the Vanilla sapling tag, you would specify it in `/data/minecraft/tags/blocks/saplings.json`, and Vanilla will merge everything into one tag at reload, if the `replace` option is false. @@ -31,8 +33,8 @@ There is also a Forge extension on the Vanilla syntax. You may declare a `remove` array of the same format as the `values` array. Any values listed here will be removed from the tag. This acts as a finer grained version of the Vanilla `replace` option. -Using Tags In Code ------------------- +## Using Tags In Code + Tags for all registries are automatically sent from the server to any remote clients on login and reload. `Block`s, `Item`s, `EntityType`s, `Fluid`s, and `GameEvent`s are special cased as they have `Holder`s allowing for available tags to be accessible through the object itself. :::note @@ -86,8 +88,7 @@ ResourceKey villagerTypeKey = /*...*/; boolean isInVillagerTypeGroup = BuiltInRegistries.VILLAGER_TYPE.getHolder(villagerTypeKey).map(holder -> holder.is(myVillagerTypeTag)).orElse(false); ``` -Conventions ------------ +## Conventions There are several conventions that will help facilitate compatibility in the ecosystem: @@ -98,8 +99,7 @@ There are several conventions that will help facilitate compatibility in the eco * Item tags should be sorted into subdirectories according to their type (e.g. `forge:ingots/iron`, `forge:nuggets/brass`, etc.). -Migration from OreDictionary ----------------------------- +## Migration from OreDictionary * For recipes, tags can be used directly in the vanilla recipe format (see below). * For matching items in code, see the section above. @@ -108,8 +108,7 @@ Migration from OreDictionary * For example, brass ingots should be registered under the `forge:ingots/brass` tag and cobalt nuggets under the `forge:nuggets/cobalt` tag. -Using Tags in Recipes and Advancements --------------------------------------- +## Using Tags in Recipes and Advancements Tags are directly supported by Vanilla. See the respective Vanilla wiki pages for [recipes] and [advancements] for usage details. From d0fa04da53c369a76979ce3a1c4667b9827c01ea Mon Sep 17 00:00:00 2001 From: Mysterious-Dev Date: Thu, 23 Nov 2023 16:55:32 +0100 Subject: [PATCH 18/21] Apply review --- docs/advanced/accesstransformers.md | 3 ++- docs/blockentities/ber.md | 3 ++- docs/blocks/states.md | 3 ++- docs/concepts/events.md | 3 ++- docs/concepts/internationalization.md | 3 ++- docs/concepts/lifecycle.md | 3 ++- docs/concepts/registries.md | 3 ++- docs/concepts/resources.md | 3 ++- docs/concepts/sides.md | 3 ++- docs/datagen/client/localization.md | 3 ++- docs/datagen/client/modelproviders.md | 3 ++- docs/datagen/client/sounds.md | 3 ++- docs/datagen/server/advancements.md | 3 ++- docs/datagen/server/datapackregistries.md | 5 +++-- docs/datagen/server/glm.md | 3 ++- docs/datagen/server/loottables.md | 3 ++- docs/datagen/server/recipes.md | 3 ++- docs/datagen/server/tags.md | 3 ++- docs/datastorage/capabilities.md | 3 ++- docs/datastorage/codecs.md | 3 ++- docs/datastorage/saveddata.md | 3 ++- docs/gameeffects/particles.md | 3 ++- docs/gameeffects/sounds.md | 3 ++- docs/gettingstarted/modfiles.md | 3 ++- docs/gettingstarted/structuring.md | 3 ++- docs/gettingstarted/versioning.md | 3 ++- docs/gui/menus.md | 3 ++- docs/gui/screens.md | 3 ++- docs/items/bewlr.md | 3 ++- docs/misc/components.md | 3 ++- docs/misc/config.md | 3 ++- docs/misc/debugprofiler.md | 3 ++- docs/misc/gametest.mdx | 3 ++- docs/misc/keymappings.md | 3 ++- docs/misc/updatechecker.md | 3 ++- docs/networking/entities.md | 3 ++- docs/networking/simpleimpl.md | 3 ++- docs/resources/client/models/itemproperties.md | 3 ++- docs/resources/client/models/tinting.md | 3 ++- docs/resources/server/advancements.md | 3 ++- docs/resources/server/glm.md | 3 ++- docs/resources/server/loottables.md | 3 ++- docs/resources/server/recipes/custom.md | 3 ++- docs/resources/server/recipes/ingredients.md | 3 ++- docs/resources/server/tags.md | 3 ++- 45 files changed, 91 insertions(+), 46 deletions(-) diff --git a/docs/advanced/accesstransformers.md b/docs/advanced/accesstransformers.md index 9ebd55656..4081b04d5 100644 --- a/docs/advanced/accesstransformers.md +++ b/docs/advanced/accesstransformers.md @@ -1,8 +1,9 @@ --- sidebar_position: 1 -title: Access Transformers --- +# Access Transformers + Access Transformers (ATs for short) allow for widening the visibility and modifying the `final` flags of classes, methods, and fields. They allow modders to access and modify otherwise inaccessible members in classes outside their control. The [specification document][specs] can be viewed on the NeoForged GitHub. diff --git a/docs/blockentities/ber.md b/docs/blockentities/ber.md index 4dbc0b015..74ea6d9ce 100644 --- a/docs/blockentities/ber.md +++ b/docs/blockentities/ber.md @@ -1,8 +1,9 @@ --- sidebar_position: 1 -title: BlockEntityRenderer --- +# BlockEntityRenderer + A `BlockEntityRenderer` or `BER` is used to render blocks in a way that cannot be represented with a static baked model (JSON, OBJ, B3D, others). A block entity renderer requires the block to have a `BlockEntity`. ## Creating a BER diff --git a/docs/blocks/states.md b/docs/blocks/states.md index fcde8770e..18b3dc54b 100644 --- a/docs/blocks/states.md +++ b/docs/blocks/states.md @@ -1,8 +1,9 @@ --- sidebar_position: 1 -title: Block States --- +# Block States + ## Legacy Behavior In Minecraft 1.7 and previous versions, blocks which need to store placement or state data that did not have BlockEntities used **metadata**. Metadata was an extra number stored with the block, allowing different rotations, facings, or even completely separate behaviors within a block. diff --git a/docs/concepts/events.md b/docs/concepts/events.md index 499aa018b..fbefbda1e 100644 --- a/docs/concepts/events.md +++ b/docs/concepts/events.md @@ -1,8 +1,9 @@ --- sidebar_position: 3 -title: Events --- +# Events + Forge uses an event bus that allows mods to intercept events from various Vanilla and mod behaviors. Example: An event can be used to perform an action when a Vanilla stick is right clicked. diff --git a/docs/concepts/internationalization.md b/docs/concepts/internationalization.md index 4636fa3b9..c1903cf07 100644 --- a/docs/concepts/internationalization.md +++ b/docs/concepts/internationalization.md @@ -1,8 +1,9 @@ --- sidebar_position: 6 -title: Internationalization --- +# Internationalization + # Internationalization and Localization Internationalization, i18n for short, is a way of designing code so that it requires no changes to be adapted for various languages. Localization is the process of adapting displayed text to the user's language. diff --git a/docs/concepts/lifecycle.md b/docs/concepts/lifecycle.md index 090da963f..f6201ce8c 100644 --- a/docs/concepts/lifecycle.md +++ b/docs/concepts/lifecycle.md @@ -1,8 +1,9 @@ --- sidebar_position: 4 -title: Mod Lifecycle --- +# Mod Lifecycle + During the mod loading process, the various lifecycle events are fired on the mod-specific event bus. Many actions are performed during these events, such as [registering objects][registering], preparing for [data generation][datagen], or [communicating with other mods][imc]. Event listeners should be registered either using `@EventBusSubscriber(bus = Bus.MOD)` or in the mod constructor: diff --git a/docs/concepts/registries.md b/docs/concepts/registries.md index 4a7412e89..a5213452f 100644 --- a/docs/concepts/registries.md +++ b/docs/concepts/registries.md @@ -1,8 +1,9 @@ --- sidebar_position: 1 -title: Registries --- +# Registries + Registration is the process of taking the objects of a mod (such as items, blocks, sounds, etc.) and making them known to the game. Registering things is important, as without registration the game will simply not know about these objects, which will cause unexplainable behaviors and crashes. Most things that require registration in the game are handled by the Forge registries. A registry is an object similar to a map that assigns values to keys. Forge uses registries with [`ResourceLocation`][ResourceLocation] keys to register objects. This allows the `ResourceLocation` to act as the "registry name" for objects. diff --git a/docs/concepts/resources.md b/docs/concepts/resources.md index c561cfedb..bef55f53c 100644 --- a/docs/concepts/resources.md +++ b/docs/concepts/resources.md @@ -1,8 +1,9 @@ --- sidebar_position: 5 -title: Resources --- +# Resources + A resource is extra data used by the game, and is stored in a data file, instead of being in the code. Minecraft has two primary resource systems active: one on the logical client used for visuals such as models, textures, and localization called `assets`, and one on the logical server used for gameplay such as recipes and loot tables called `data`. [Resource packs][respack] control the former, while [Datapacks][datapack] control the latter. diff --git a/docs/concepts/sides.md b/docs/concepts/sides.md index fd23d5489..c8c924371 100644 --- a/docs/concepts/sides.md +++ b/docs/concepts/sides.md @@ -1,8 +1,9 @@ --- sidebar_position: 2 -title: Sides --- +# Sides + # Sides in Minecraft A very important concept to understand when modding Minecraft are the two sides: *client* and *server*. There are many, many common misconceptions and mistakes regarding siding, which can lead to bugs that might not crash the game, but can rather have unintended and often unpredictable effects. diff --git a/docs/datagen/client/localization.md b/docs/datagen/client/localization.md index 5daf1c113..baf0a73d8 100644 --- a/docs/datagen/client/localization.md +++ b/docs/datagen/client/localization.md @@ -1,8 +1,9 @@ --- sidebar_position: 2 -title: Language Generation --- +# Language Generation + [Language files][lang] can be generated for a mod by subclassing `LanguageProvider` and implementing `#addTranslations`. Each `LanguageProvider` subclass created represents a separate [locale] (`en_us` represents American English, `es_es` represents Spanish, etc.). After implementation, the provider must be [added][datagen] to the `DataGenerator`. ```java diff --git a/docs/datagen/client/modelproviders.md b/docs/datagen/client/modelproviders.md index 3dc619e3c..5962642d8 100644 --- a/docs/datagen/client/modelproviders.md +++ b/docs/datagen/client/modelproviders.md @@ -1,8 +1,9 @@ --- sidebar_position: 1 -title: Model Generation --- +# Model Generation + [Models] can be generated for models or block states by default. Each provides a method of generating the necessary JSONs (`ModelBuilder#toJson` for models and `IGeneratedBlockState#toJson` for block states). After implementation, the [associated providers][provider] must be [added][datagen] to the `DataGenerator`. ```java diff --git a/docs/datagen/client/sounds.md b/docs/datagen/client/sounds.md index a3b115510..4842bb6e7 100644 --- a/docs/datagen/client/sounds.md +++ b/docs/datagen/client/sounds.md @@ -1,8 +1,9 @@ --- sidebar_position: 3 -title: Sound Definition Generation --- +# Sound Definition Generation + The `sounds.json` file can be generated for a mod by subclassing `SoundDefinitionsProvider` and implementing `#registerSounds`. After implementation, the provider must be [added][datagen] to the `DataGenerator`. ```java diff --git a/docs/datagen/server/advancements.md b/docs/datagen/server/advancements.md index 22b249ee2..df3909b2a 100644 --- a/docs/datagen/server/advancements.md +++ b/docs/datagen/server/advancements.md @@ -1,8 +1,9 @@ --- sidebar_position: 4 -title: Advancement Generation --- +# Advancement Generation + [Advancements] can be generated for a mod by constructing a new `AdvancementProvider` and providing `AdvancementSubProvider`s. Advancements can either be created and supplied manually or, for convenience, created using `Advancement$Builder`. The provider must be [added][datagen] to the `DataGenerator`. !!! note diff --git a/docs/datagen/server/datapackregistries.md b/docs/datagen/server/datapackregistries.md index 3fbac8994..70e3bffdf 100644 --- a/docs/datagen/server/datapackregistries.md +++ b/docs/datagen/server/datapackregistries.md @@ -1,8 +1,9 @@ --- sidebar_position: 6 -title: Datapack Registry Object Generation --- +# Datapack Registry Object Generation + Datapack registry objects can be generated for a mod by constructing a new `DatapackBuiltinEntriesProvider` and providing a `RegistrySetBuilder` with the new objects to register. The provider must be [added][datagen] to the `DataGenerator`. !!! note @@ -125,4 +126,4 @@ new RegistrySetBuilder() }); ``` -[datagen]: ../index.md#data-providers \ No newline at end of file +[datagen]: ../index.md#data-providers diff --git a/docs/datagen/server/glm.md b/docs/datagen/server/glm.md index 4caf07fcd..67e6534f8 100644 --- a/docs/datagen/server/glm.md +++ b/docs/datagen/server/glm.md @@ -1,8 +1,9 @@ --- sidebar_position: 5 -title: Global Loot Modifier Generation --- +# Global Loot Modifier Generation + [Global Loot Modifiers (GLMs)][glm] can be generated for a mod by subclassing `GlobalLootModifierProvider` and implementing `#start`. Each GLM can be added generated by calling `#add` and specifying the name of the modifier and the [modifier instance][instance] to be serialized. After implementation, the provider must be [added][datagen] to the `DataGenerator`. ```java diff --git a/docs/datagen/server/loottables.md b/docs/datagen/server/loottables.md index e70f96f3c..d30c5a6d0 100644 --- a/docs/datagen/server/loottables.md +++ b/docs/datagen/server/loottables.md @@ -1,8 +1,9 @@ --- sidebar_position: 2 -title: Loot Table Generation --- +# Loot Table Generation + [Loot tables][loottable] can be generated for a mod by constructing a new `LootTableProvider` and providing `LootTableProvider$SubProviderEntry`s. The provider must be [added][datagen] to the `DataGenerator`. ```java diff --git a/docs/datagen/server/recipes.md b/docs/datagen/server/recipes.md index 8c616a3d8..dcc1527fd 100644 --- a/docs/datagen/server/recipes.md +++ b/docs/datagen/server/recipes.md @@ -1,8 +1,9 @@ --- sidebar_position: 1 -title: Recipe Generation --- +# Recipe Generation + Recipes can be generated for a mod by subclassing `RecipeProvider` and implementing `#buildRecipes`. A recipe is supplied for data generation once a `FinishedRecipe` view is accepted by the consumer. `FinishedRecipe`s can either be created and supplied manually or, for convenience, created using a `RecipeBuilder`. After implementation, the provider must be [added][datagen] to the `DataGenerator`. diff --git a/docs/datagen/server/tags.md b/docs/datagen/server/tags.md index e72bca301..6b2176a3e 100644 --- a/docs/datagen/server/tags.md +++ b/docs/datagen/server/tags.md @@ -1,8 +1,9 @@ --- sidebar_position: 3 -title: Tag Generation --- +# Tag Generation + [Tags] can be generated for a mod by subclassing `TagsProvider` and implementing `#addTags`. After implementation, the provider must be [added][datagen] to the `DataGenerator`. ```java diff --git a/docs/datastorage/capabilities.md b/docs/datastorage/capabilities.md index 98e865bcf..2b38809c2 100644 --- a/docs/datastorage/capabilities.md +++ b/docs/datastorage/capabilities.md @@ -1,8 +1,9 @@ --- sidebar_position: 1 -title: Capabilities --- +# Capabilities + Capabilities allow exposing features in a dynamic and flexible way without having to resort to directly implementing many interfaces. In general terms, each capability provides a feature in the form of an interface. diff --git a/docs/datastorage/codecs.md b/docs/datastorage/codecs.md index 35b4bcf3b..a351bc91a 100644 --- a/docs/datastorage/codecs.md +++ b/docs/datastorage/codecs.md @@ -1,8 +1,9 @@ --- sidebar_position: 3 -title: Codecs --- +# Codecs + Codecs are a serialization tool from Mojang's [DataFixerUpper] used to describe how objects can be transformed between different formats, such as `JsonElement`s for JSON and `Tag`s for NBT. ## Using Codecs diff --git a/docs/datastorage/saveddata.md b/docs/datastorage/saveddata.md index 9dfb545d8..94d82ca90 100644 --- a/docs/datastorage/saveddata.md +++ b/docs/datastorage/saveddata.md @@ -1,8 +1,9 @@ --- sidebar_position: 2 -title: Saved Data --- +# Saved Data + The Saved Data (SD) system is an alternative to level capabilities that can attach data per level. ## Declaration diff --git a/docs/gameeffects/particles.md b/docs/gameeffects/particles.md index 8f6bad2f0..5a8c8b3a3 100644 --- a/docs/gameeffects/particles.md +++ b/docs/gameeffects/particles.md @@ -1,8 +1,9 @@ --- sidebar_position: 1 -title: Particles --- +# Particles + Particles are an effect within the game used as polish to better improve immersion. Their usefulness also requires great caution because of their methods of creation and reference. ## Creating a Particle diff --git a/docs/gameeffects/sounds.md b/docs/gameeffects/sounds.md index bcc7b6f40..c3304f5ae 100644 --- a/docs/gameeffects/sounds.md +++ b/docs/gameeffects/sounds.md @@ -1,8 +1,9 @@ --- sidebar_position: 2 -title: Sounds --- +# Sounds + ## Terminology | Term | Description | diff --git a/docs/gettingstarted/modfiles.md b/docs/gettingstarted/modfiles.md index 60f778ef6..025e1bcfa 100644 --- a/docs/gettingstarted/modfiles.md +++ b/docs/gettingstarted/modfiles.md @@ -1,8 +1,9 @@ --- sidebar_position: 1 -title: Mod Files --- +# Mod Files + The mod files are responsible for determining what mods are packaged into your JAR, what information to display within the 'Mods' menu, and how your mod should be loaded in the game. ## mods.toml diff --git a/docs/gettingstarted/structuring.md b/docs/gettingstarted/structuring.md index bb709fc2f..83d27f95c 100644 --- a/docs/gettingstarted/structuring.md +++ b/docs/gettingstarted/structuring.md @@ -1,8 +1,9 @@ --- sidebar_position: 2 -title: Structuring Your Mod --- +# Structuring Your Mod + Structured mods are beneficial for maintenance, making contributions, and providing a clearer understanding of the underlying codebase. Some of the recommendations from Java, Minecraft, and Forge are listed below. :::note diff --git a/docs/gettingstarted/versioning.md b/docs/gettingstarted/versioning.md index 596b56d35..e82f5228a 100644 --- a/docs/gettingstarted/versioning.md +++ b/docs/gettingstarted/versioning.md @@ -1,8 +1,9 @@ --- sidebar_position: 3 -title: Versioning --- +# Versioning + In general projects, [semantic versioning][semver] is often used (which has the format `MAJOR.MINOR.PATCH`). However, in the case of modding it may be more beneficial to use the format `MCVERSION-MAJORMOD.MAJORAPI.MINOR.PATCH` to be able to differentiate between world-breaking and API-breaking changes of a mod. :::caution diff --git a/docs/gui/menus.md b/docs/gui/menus.md index f0d41c18a..4578aa33a 100644 --- a/docs/gui/menus.md +++ b/docs/gui/menus.md @@ -1,8 +1,9 @@ --- sidebar_position: 1 -title: Menus --- +# Menus + Menus are one type of backend for Graphical User Interfaces, or GUIs; they handle the logic involved in interacting with some represented data holder. Menus themselves are not data holders. They are views which allow to user to indirectly modify the internal data holder state. As such, a data holder should not be directly coupled to any menu, instead passing in the data references to invoke and modify. ## `MenuType` diff --git a/docs/gui/screens.md b/docs/gui/screens.md index 91e2efeab..169e6c95e 100644 --- a/docs/gui/screens.md +++ b/docs/gui/screens.md @@ -1,8 +1,9 @@ --- sidebar_position: 2 -title: Screens --- +# Screens + Screens are typically the base of all Graphical User Interfaces (GUIs) in Minecraft: taking in user input, verifying it on the server, and syncing the resulting action back to the client. They can be combined with [menus] to create an communication network for inventory-like views, or they can be standalone which modders can handle through their own [network] implementations. Screens are made up of numerous parts, making it difficult to fully understand what a 'screen' actually is in Minecraft. As such, this document will go over each of the screen's components and how it is applied before discussing the screen itself. diff --git a/docs/items/bewlr.md b/docs/items/bewlr.md index 0e90c037b..4804a3832 100644 --- a/docs/items/bewlr.md +++ b/docs/items/bewlr.md @@ -1,8 +1,9 @@ --- sidebar_position: 1 -title: BlockEntityWithoutLevelRenderer --- +# BlockEntityWithoutLevelRenderer + `BlockEntityWithoutLevelRenderer` is a method to handle dynamic rendering on items. This system is much simpler than the old `ItemStack` system, which required a `BlockEntity`, and did not allow access to the `ItemStack`. ## Using BlockEntityWithoutLevelRenderer diff --git a/docs/misc/components.md b/docs/misc/components.md index b999ccfbb..201c3743d 100644 --- a/docs/misc/components.md +++ b/docs/misc/components.md @@ -1,8 +1,9 @@ --- sidebar_position: 6 -title: Text Components --- +# Text Components + A `Component` is a holder for text which can be formatted and chained with other components via its subtype `MutableComponent`. A component can be created using one of the available static helpers: | Method Name | Description | diff --git a/docs/misc/config.md b/docs/misc/config.md index 3c92240c1..adb8c2626 100644 --- a/docs/misc/config.md +++ b/docs/misc/config.md @@ -1,8 +1,9 @@ --- sidebar_position: 1 -title: Configuration --- +# Configuration + Configurations define settings and consumer preferences that can be applied to a mod instance. Forge uses a configuration system using [TOML][toml] files and read with [NightConfig][nightconfig]. ## Creating a Configuration diff --git a/docs/misc/debugprofiler.md b/docs/misc/debugprofiler.md index 98572df55..91ff6aa4a 100644 --- a/docs/misc/debugprofiler.md +++ b/docs/misc/debugprofiler.md @@ -1,8 +1,9 @@ --- sidebar_position: 5 -title: Debug Profiler --- +# Debug Profiler + Minecraft provides a Debug Profiler that provides system data, current game settings, JVM data, level data, and sided tick information to find time consuming code. Considering things like `TickEvent`s and ticking `BlockEntities`, this can be very useful for modders and server owners that want to find a lag source. ## Using the Debug Profiler diff --git a/docs/misc/gametest.mdx b/docs/misc/gametest.mdx index a7d9bc791..05cdbf95f 100644 --- a/docs/misc/gametest.mdx +++ b/docs/misc/gametest.mdx @@ -1,8 +1,9 @@ --- sidebar_position: 3 -title: Game Tests --- +# Game Tests + Game Tests are a way to run in-game unit tests. The system was designed to be scalable and in parallel to run large numbers of different tests efficiently. Testing object interactions and behaviors are simply a few of the many applications of this framework. ## Creating a Game Test diff --git a/docs/misc/keymappings.md b/docs/misc/keymappings.md index dad816d5e..8413727ad 100644 --- a/docs/misc/keymappings.md +++ b/docs/misc/keymappings.md @@ -1,8 +1,9 @@ --- sidebar_position: 2 -title: Key Mappings --- +# Key Mappings + A key mapping, or key binding, defines a particular action that should be tied to an input: mouse click, key press, etc. Each action defined by a key mapping can be checked whenever the client can take an input. Furthermore, each key mapping can be assigned to any input through the [Controls option menu][controls]. ## Registering a `KeyMapping` diff --git a/docs/misc/updatechecker.md b/docs/misc/updatechecker.md index ef2c32f8c..0575e6b1a 100644 --- a/docs/misc/updatechecker.md +++ b/docs/misc/updatechecker.md @@ -1,8 +1,9 @@ --- sidebar_position: 4 -title: Forge Update Checker --- +# Forge Update Checker + Forge provides a very lightweight, opt-in, update-checking framework. If any mods have an available update, it will show a flashing icon on the 'Mods' button of the main menu and mod list along with the respective changelogs. It *does not* download updates automatically. ## Getting Started diff --git a/docs/networking/entities.md b/docs/networking/entities.md index 02fd7e627..f34eedc37 100644 --- a/docs/networking/entities.md +++ b/docs/networking/entities.md @@ -1,8 +1,9 @@ --- sidebar_position: 2 -title: Synchronizing Entities --- +# Synchronizing Entities + In addition to regular network messages, there are various other systems provided to handle synchronizing entity data. Spawn Data diff --git a/docs/networking/simpleimpl.md b/docs/networking/simpleimpl.md index 3d76aea67..e6b147149 100644 --- a/docs/networking/simpleimpl.md +++ b/docs/networking/simpleimpl.md @@ -1,8 +1,9 @@ --- sidebar_position: 1 -title: SimpleImpl --- +# SimpleImpl + SimpleImpl is the name given to the packet system that revolves around the `SimpleChannel` class. Using this system is by far the easiest way to send custom data between clients and the server. Getting Started diff --git a/docs/resources/client/models/itemproperties.md b/docs/resources/client/models/itemproperties.md index 619242f7a..e46e934c0 100644 --- a/docs/resources/client/models/itemproperties.md +++ b/docs/resources/client/models/itemproperties.md @@ -1,8 +1,9 @@ --- sidebar_position: 2 -title: Item Properties --- +# Item Properties + Item properties are a way for the "properties" of items to be exposed to the model system. An example is the bow, where the most important property is how far the bow has been pulled. This information is then used to choose a model for the bow, creating an animation for pulling it. An item property assigns a certain `float` value to every `ItemStack` it is registered for, and vanilla item model definitions can use these values to define "overrides", where an item defaults to a certain model, but if an override matches, it overrides the model and uses another. They are useful mainly because they are continuous. For example, bows use item properties to define their pull animation. The item models are decided by the 'float' number predicates, it is not limited but generally between `0.0F` and `1.0F`. This allows resource packs to add as many models as they want for the bow pulling animation along that spectrum, instead of being stuck with four "slots" for their models in the animation. The same is true of the compass and clock. diff --git a/docs/resources/client/models/tinting.md b/docs/resources/client/models/tinting.md index 04e824bbc..5c68d35ea 100644 --- a/docs/resources/client/models/tinting.md +++ b/docs/resources/client/models/tinting.md @@ -1,8 +1,9 @@ --- sidebar_position: 1 -title: Texture Tinting --- +# Texture Tinting + Many blocks and items in vanilla change their texture color depending on where they are or what properties they have, such as grass. Models support specifying "tint indices" on faces, which are integers that can then be handled by `BlockColor`s and `ItemColor`s. See the [wiki][] for information on how tint indices are defined in vanilla models. ### `BlockColor`/`ItemColor` diff --git a/docs/resources/server/advancements.md b/docs/resources/server/advancements.md index 671740852..92ab9e8a5 100644 --- a/docs/resources/server/advancements.md +++ b/docs/resources/server/advancements.md @@ -1,8 +1,9 @@ --- sidebar_position: 4 -title: Advancements --- +# Advancements + Advancements are tasks that can be achieved by the player which may advance the progress of the game. Advancements can trigger based on any action the player may be directly involved in. All advancement implementations within vanilla are data driven via JSON. This means that a mod is not necessary to create a new advancement, only a [data pack][datapack]. A full list on how to create and put these advancements within the mod's `resources` can be found on the [Minecraft Wiki][wiki]. Additionally, advancements can be [loaded conditionally and defaulted][conditional] depending on what information is present (mod loaded, item exists, etc.). diff --git a/docs/resources/server/glm.md b/docs/resources/server/glm.md index d7b469ace..3af5284fa 100644 --- a/docs/resources/server/glm.md +++ b/docs/resources/server/glm.md @@ -1,8 +1,9 @@ --- sidebar_position: 2 -title: Global Loot Modifiers --- +# Global Loot Modifiers + Global Loot Modifiers are a data-driven method of handling modification of harvested drops without the need to overwrite dozens to hundreds of vanilla loot tables or to handle effects that would require interactions with another mod's loot tables without knowing what mods may be loaded. Global Loot Modifiers are also stacking, rather than last-load-wins, similar to tags. ## Registering a Global Loot Modifier diff --git a/docs/resources/server/loottables.md b/docs/resources/server/loottables.md index 739e55e7b..ffb53a1b3 100644 --- a/docs/resources/server/loottables.md +++ b/docs/resources/server/loottables.md @@ -1,8 +1,9 @@ --- sidebar_position: 1 -title: Loot Tables --- +# Loot Tables + Loot tables are logic files which dictate what should happen when various actions or scenarios occur. Although the vanilla system deals purely with item generation, the system can be expanded to perform any number of defined actions. ## Data-Driven Tables diff --git a/docs/resources/server/recipes/custom.md b/docs/resources/server/recipes/custom.md index e6566ac12..a425998f5 100644 --- a/docs/resources/server/recipes/custom.md +++ b/docs/resources/server/recipes/custom.md @@ -1,8 +1,9 @@ --- sidebar_position: 1 -title: Custom Recipes --- +# Custom Recipes + Every recipe definition is made up of three components: the `Recipe` implementation which holds the data and handles the execution logic with the provided inputs, the `RecipeType` which represents the category or context the recipe will be used in, and the `RecipeSerializer` which handles decoding and network communication of the recipe data. How one chooses to use the recipe is up to the implementor. ## Recipe diff --git a/docs/resources/server/recipes/ingredients.md b/docs/resources/server/recipes/ingredients.md index 7cd9e2e27..0bea10926 100644 --- a/docs/resources/server/recipes/ingredients.md +++ b/docs/resources/server/recipes/ingredients.md @@ -1,8 +1,9 @@ --- sidebar_position: 2 -title: Ingredients --- +# Ingredients + `Ingredient`s are predicate handlers for item-based inputs which check whether a certain `ItemStack` meets the condition to be a valid input in a recipe. All [vanilla recipes][recipes] that take inputs use an `Ingredient` or a list of `Ingredient`s, which is then merged into a single `Ingredient`. ## Custom Ingredients diff --git a/docs/resources/server/tags.md b/docs/resources/server/tags.md index fbe9aee63..2ecbb38e8 100644 --- a/docs/resources/server/tags.md +++ b/docs/resources/server/tags.md @@ -1,8 +1,9 @@ --- sidebar_position: 3 -title: Tags --- +# Tags + Tags are generalized sets of objects in the game used for grouping related things together and providing fast membership checks. ## Declaring Your Own Groupings From 32a53208d2351a9cf1540b5acad771c26705febe Mon Sep 17 00:00:00 2001 From: Mysterious-Dev Date: Thu, 23 Nov 2023 16:58:28 +0100 Subject: [PATCH 19/21] 2nd pass --- docs/blockentities/index.md | 4 +--- docs/blocks/index.md | 4 +--- docs/datagen/index.md | 4 +--- docs/gettingstarted/index.md | 4 +--- docs/items/index.md | 4 +--- docs/networking/index.md | 4 +--- docs/rendering/modelloaders/index.md | 4 +--- docs/resources/client/index.md | 4 +--- docs/resources/client/models/index.md | 4 +--- docs/resources/server/index.md | 4 +--- docs/resources/server/recipes/index.md | 4 +--- 11 files changed, 11 insertions(+), 33 deletions(-) diff --git a/docs/blockentities/index.md b/docs/blockentities/index.md index 7b6d02e18..37955d3e2 100644 --- a/docs/blockentities/index.md +++ b/docs/blockentities/index.md @@ -1,6 +1,4 @@ ---- -title: Block Entities ---- +# Block Entities `BlockEntities` are like simplified `Entities` that are bound to a Block. They are used to store dynamic data, execute tick based tasks, and dynamic rendering. diff --git a/docs/blocks/index.md b/docs/blocks/index.md index 763c90b02..d3748835d 100644 --- a/docs/blocks/index.md +++ b/docs/blocks/index.md @@ -1,6 +1,4 @@ ---- -title: Blocks ---- +# Blocks Blocks are, obviously, essential to the Minecraft world. They make up all of the terrain, structures, and machines. Chances are if you are interested in making a mod, then you will want to add some blocks. This page will guide you through the creation of blocks, and some of the things you can do with them. diff --git a/docs/datagen/index.md b/docs/datagen/index.md index 937c45430..fa5070c4b 100644 --- a/docs/datagen/index.md +++ b/docs/datagen/index.md @@ -1,6 +1,4 @@ ---- -title: Data Generators ---- +# Data Generators Data generators are a way to programmatically generate the assets and data of mods. It allows the definition of the contents of these files in the code and their automatic generation, without worrying about the specifics. diff --git a/docs/gettingstarted/index.md b/docs/gettingstarted/index.md index ed5013cf1..e3f8a5dac 100644 --- a/docs/gettingstarted/index.md +++ b/docs/gettingstarted/index.md @@ -1,6 +1,4 @@ ---- -title: Getting Started with Forge ---- +# Getting Started with Forge :::caution Please note that this documentation may not be up to date considering the recent creation of NeoForged. diff --git a/docs/items/index.md b/docs/items/index.md index 4b39b3fce..06a71d5ee 100644 --- a/docs/items/index.md +++ b/docs/items/index.md @@ -1,6 +1,4 @@ ---- -title: Items ---- +# Items Along with blocks, items are a key component of most mods. While blocks make up the level around you, items exist within inventories. diff --git a/docs/networking/index.md b/docs/networking/index.md index 93a5d7262..6a7f76077 100644 --- a/docs/networking/index.md +++ b/docs/networking/index.md @@ -1,6 +1,4 @@ ---- -title: Networking ---- +# Networking Communication between servers and clients is the backbone of a successful mod implementation. diff --git a/docs/rendering/modelloaders/index.md b/docs/rendering/modelloaders/index.md index dbf53c2f7..57a17f807 100644 --- a/docs/rendering/modelloaders/index.md +++ b/docs/rendering/modelloaders/index.md @@ -1,6 +1,4 @@ ---- -title: Custom Model Loaders ---- +# Custom Model Loaders A "model" is simply a shape. It can be a simple cube, it can be several cubes, it can be a truncated icosidodecahedron, or anything in between. Most models you'll see will be in the vanilla JSON format. Models in other formats are loaded into `IUnbakedGeometry`s by an `IGeometryLoader` at runtime. Forge provides default implementations for WaveFront OBJ files, buckets, composite models, models in different render layers, and a reimplementation of Vanilla's `builtin/generated` item model. Most things do not care about what loaded the model or what format it's in as they are all eventually represented by an `BakedModel` in code. diff --git a/docs/resources/client/index.md b/docs/resources/client/index.md index e2db6e9b6..c72c9cd08 100644 --- a/docs/resources/client/index.md +++ b/docs/resources/client/index.md @@ -1,6 +1,4 @@ ---- -title: Resource Packs ---- +# Resource Packs [Resource Packs][respack] allow for the customization of client resources through the `assets` directory. This includes textures, models, sounds, localizations, and others. Your mod (as well as Forge itself) can also have resource packs. Any user can therefore modify all the textures, models, and other assets defined within this directory. diff --git a/docs/resources/client/models/index.md b/docs/resources/client/models/index.md index 6219dd7b0..907657682 100644 --- a/docs/resources/client/models/index.md +++ b/docs/resources/client/models/index.md @@ -1,6 +1,4 @@ ---- -title: Models ---- +# Models The [model system][models] is Minecraft's way of giving blocks and items their shapes. Through the model system, blocks and items are mapped to their models, which define how they look. One of the main goals of the model system is to allow not only textures but the entire shape of a block/item to be changed by resource packs. Indeed, any mod that adds items or blocks also contains a mini-resource pack for their blocks and items. diff --git a/docs/resources/server/index.md b/docs/resources/server/index.md index dbcf07e49..98908aa04 100644 --- a/docs/resources/server/index.md +++ b/docs/resources/server/index.md @@ -1,6 +1,4 @@ ---- -title: Datapacks ---- +# Datapacks In 1.13, Mojang added [datapacks][datapack] to the base game. They allow for the modification of the files for logical servers through the `data` directory. This includes advancements, loot_tables, structures, recipes, tags, etc. Forge, and your mod, can also have datapacks. Any user can therefore modify all the recipes, loot tables, and other data defined within this directory. diff --git a/docs/resources/server/recipes/index.md b/docs/resources/server/recipes/index.md index 30941bffc..6d19eb9ac 100644 --- a/docs/resources/server/recipes/index.md +++ b/docs/resources/server/recipes/index.md @@ -1,6 +1,4 @@ ---- -title: Recipes ---- +# Recipes Recipes are a way to transform some number of objects into other objects within a Minecraft world. Although the vanilla system deals purely with item transformations, the system as a whole can be expanded to use any object the programmer creates. From 1564b42f27dfc02fee5322d30585e3a931953b9c Mon Sep 17 00:00:00 2001 From: Mysterious-Dev Date: Thu, 23 Nov 2023 16:59:49 +0100 Subject: [PATCH 20/21] Finish --- docs/legacy/porting.md | 5 +---- docs/resources/server/conditional.md | 5 +---- docs/resources/server/recipes/incode.md | 5 +---- 3 files changed, 3 insertions(+), 12 deletions(-) diff --git a/docs/legacy/porting.md b/docs/legacy/porting.md index de41d704f..f67f052e5 100644 --- a/docs/legacy/porting.md +++ b/docs/legacy/porting.md @@ -1,7 +1,4 @@ ---- -sidebar_position: 1 -title: Porting to Minecraft 1.20 ---- +# Porting to Minecraft 1.20 Here you can find a list of primers on how to port from old versions to the current version. Some versions are lumped together since that particular version never saw much usage. diff --git a/docs/resources/server/conditional.md b/docs/resources/server/conditional.md index f90496354..e84331dd0 100644 --- a/docs/resources/server/conditional.md +++ b/docs/resources/server/conditional.md @@ -1,7 +1,4 @@ ---- -sidebar_position: 5 -title: Conditionally-Loaded Data ---- +# Conditionally-Loaded Data There are times when modders may want to include data-driven objects using information from another mod without having to explicitly make that mod a dependency. Other cases may be to swap out certain objects with other modded entries when they are present. This can be done through the conditional subsystem. diff --git a/docs/resources/server/recipes/incode.md b/docs/resources/server/recipes/incode.md index 81dda1a90..895f001d5 100644 --- a/docs/resources/server/recipes/incode.md +++ b/docs/resources/server/recipes/incode.md @@ -1,7 +1,4 @@ ---- -sidebar_position: 3 -title: Non-Datapack Recipes ---- +# Non-Datapack Recipes Not all recipes are simplistic enough or migrated to using data-driven recipes. Some subsystems still need to be patched within the codebase to provide support for adding new recipes. From 27a1b1baa9f7c488cd0f41edd142c776d9ad5194 Mon Sep 17 00:00:00 2001 From: Mysterious-Dev Date: Fri, 24 Nov 2023 14:28:51 +0100 Subject: [PATCH 21/21] Use manual sidebar --- sidebars.js | 120 ++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 97 insertions(+), 23 deletions(-) diff --git a/sidebars.js b/sidebars.js index 917aff8a7..9e7be49dd 100644 --- a/sidebars.js +++ b/sidebars.js @@ -1,33 +1,107 @@ -/** - * Creating a sidebar enables you to: - - create an ordered group of docs - - render a sidebar for each doc of that group - - provide next/previous navigation - - The sidebars can be generated from the filesystem, or explicitly defined here. - - Create as many sidebars as you want. - */ - // @ts-check - /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ const sidebars = { - // By default, Docusaurus generates a sidebar from the docs folder structure - mainSidebar: [{type: 'autogenerated', dirName: '.'}], - - // But you can create a sidebar manually - /* - tutorialSidebar: [ - 'intro', - 'hello', + mainSidebar: [ + { + type: 'category', + label: 'Getting Started', + link: { + type: 'doc', + id: 'gettingstarted/index', + }, + items: [{type: 'autogenerated', dirName: 'gettingstarted'}], + }, + { + type: 'category', + label: 'Core Concepts', + items: [{type: 'autogenerated', dirName: 'concepts'}], + }, + { + type: 'category', + label: 'Blocks', + link: { + type: 'doc', + id: 'blocks/index', + }, + items: [{type: 'autogenerated', dirName: 'blocks'}], + }, + { + type: 'category', + label: 'Items', + link: { + type: 'doc', + id: 'items/index', + }, + items: [{type: 'autogenerated', dirName: 'items'}], + }, + { + type: 'category', + label: 'Networking', + link: { + type: 'doc', + id: 'networking/index', + }, + items: [{type: 'autogenerated', dirName: 'networking'}], + }, + { + type: 'category', + label: 'Block Entities', + link: { + type: 'doc', + id: 'blockentities/index', + }, + items: [{type: 'autogenerated', dirName: 'blockentities'}], + }, + { + type: 'category', + label: 'Game Effects', + items: [{type: 'autogenerated', dirName: 'gameeffects'}], + }, + { + type: 'category', + label: 'Data Storage', + items: [{type: 'autogenerated', dirName: 'datastorage'}], + }, + { + type: 'category', + label: 'Graphical User Interfaces', + items: [{type: 'autogenerated', dirName: 'gui'}], + }, + { + type: 'category', + label: 'Rendering', + items: [{type: 'autogenerated', dirName: 'rendering'}], + }, + { + type: 'category', + label: 'Resources', + items: [{type: 'autogenerated', dirName: 'resources'}], + }, + { + type: 'category', + label: 'Data Generation', + link: { + type: 'doc', + id: 'datagen/index', + }, + items: [{type: 'autogenerated', dirName: 'datagen'}], + }, + { + type: 'category', + label: 'Miscellaneous Features', + items: [{type: 'autogenerated', dirName: 'misc'}], + }, + { + type: 'category', + label: 'Advanced Topics', + items: [{type: 'autogenerated', dirName: 'advanced'}], + }, { type: 'category', - label: 'Tutorial', - items: ['tutorial-basics/create-a-document'], + label: 'Legacy Versions', + items: [{type: 'autogenerated', dirName: 'legacy'}], }, ], - */ }; module.exports = sidebars;