Apply suggestions from code review

Co-authored-by: chris <github@onechris.mozmail.com>

sidebars.ts

@@ -89,16 +89,18 @@ const sidebars: SidebarsConfig = {
         },
         {
             type: 'category',
-            label: 'Custom Resource Packs',
+            label: 'Custom Content',
             link: {
                 type: 'doc',
-                id: 'geyser/custom-resource-packs'
+                id: 'geyser/custom-content'
             },
             items: [
                 'geyser/packs',
                 'geyser/custom-items',
                 'geyser/custom-blocks',
                 'geyser/custom-skulls',
+                'geyser/custom-waypoints',
+                'geyser/custom-entities'
             ]
         },
         {

src/data/versions.json

@@ -1,12 +1,12 @@
 {
     "bedrock": {
-        "supported": "26.0-26.30",
+        "supported": "26.0-26.32",
         "latest": {
             "id": 1001,
-            "name": "26.30"
+            "name": "26.32"
         }
     },
     "java": {
-        "supported": "26.1-26.1.2"
+        "supported": "26.2"
     }
 }

wiki/geyser/custom-blocks.md

@@ -7,6 +7,11 @@ To setup custom blocks in geyser, you have to choose how you are going to regist
 
 It should be noted that blocks and their associated components are not very stable. Mojang tends to make changes to these much more often than they do for items. This means that any components Geyser allows you to register are liable to break in future versions of Bedrock.
 
+:::warning
+Geyser does not convert resource packs from Java Edition, and also does not generate custom block mappings automatically.
+However, you can use automatic tools such as [Rainbow](/wiki/other/rainbow/) to make converting content simpler.
+:::
+
 ## Enabling custom blocks {#enabling-custom-blocks}
 
 Before beginning, ensure that `gameplay.enable-custom-content` is set to `true` in your `config.yml` file.

wiki/geyser/custom-content.md

@@ -0,0 +1,17 @@
+---
+title: Custom Content
+description: How to use custom content (requiring resource packs) with Geyser.
+---
+
+Geyser supports mapping various custom additions to the game via resource packs and mappings, such as custom items, blocks, and skulls. See:
+
+- [Custom items](/wiki/geyser/custom-items)
+- [Custom blocks](/wiki/geyser/custom-blocks)
+- [Custom skulls](/wiki/geyser/custom-skulls)
+- [Custom waypoint icons](/wiki/geyser/custom-waypoints)
+- [Custom entities](/wiki/geyser/custom-entities)
+
+:::info
+Geyser does not convert resource packs from Java Edition automatically.
+However, you can use automatic tools such as [Rainbow](/wiki/other/rainbow/) or [Thunder](/wiki/other/thunder) to make converting custom content simpler.
+:::

wiki/geyser/custom-entities.md

@@ -0,0 +1,234 @@
+---
+title: Geyser Entity API
+description: Geyser extensions can register custom Bedrock entity definitions, modify existing entities, and replace built-in types in entity spawning events.
+---
+
+:::warning Experimental API
+The (Custom) Entity API was introduced with Geyser API **2.11.0** (26.2 update) and is currently marked `@ApiStatus.Experimental`. This means that the API may change or be rewritten in parts in a future version without prior deprecation.
+If you have feedback on this API, encounter issues, or wish to request further features, please reach out to us!
+
+The `GeyserDefineEntityPropertiesEvent` has been available since **2.9.0**, but its identifier parameter changed in 2.11.0: it now takes a **Bedrock** entity identifier instead of a Java one. See [Entity Properties](#entity-properties) for details.
+:::
+
+:::info
+This API currently cannot be used via JSON mappings. In the future, we are planning to support entity variants, which would likely also be usable through JSON mappings. 
+:::
+
+Custom entities currently (as of 26.2) do not exist in Minecraft: Java Edition. Instead, they can be simulated with armor stands holding item models, or item/block display entity combinations.
+Unlike Java Edition, Bedrock does support custom entity types, but does not have item or block display entities. With this API, Geyser extensions can register custom Bedrock entity definitions to use instead of Java
+entity types in entity spawning events to properly support custom entities for Bedrock players. Further, it allows modifying entity properties and data for any entity sent to a Bedrock player at runtime.
+
+Additionally to registering custom entity definitions, you will also need to provide a resource pack to players [defining custom entity textures and animations](https://wiki.bedrock.dev/guide/custom-entity).
+
+## Prerequisites: Vocabulary {#vocabulary}
+
+- **Bedrock Entity Definition** (`GeyserEntityDefinition` / `CustomEntityDefinition`): Identifies the Bedrock entity type to spawn, either a built-in type, or a custom type
+- **Entity Properties**: Bedrock Molang-queryable values (`query.property(...)`) registered per Bedrock entity type. See [here](https://learn.microsoft.com/en-us/minecraft/creator/documents/introductiontoentityproperties?view=minecraft-bedrock-stable) for official documentation.
+- **Entity Data Types**: Properties on entities that can be changed dynamically, such as scale, size, hitboxes, and color.
+
+## Registering a Custom Entity Definition {#registering-entity-definition}
+
+Custom entity definitions are registered using `GeyserDefineEntitiesEvent`, which fires once during Geyser's startup:
+
+```java
+@Subscribe
+public void onDefineEntities(GeyserDefineEntitiesEvent event) {
+    CustomEntityDefinition myEntity = CustomEntityDefinition.of(Identifier.of("mynamespace:my_entity"));
+    event.register(myEntity);
+}
+```
+
+Do note:
+- Custom entity definition type identifier must not use the `minecraft` namespace
+- Entity types must have a unique identifier
+
+## Summoning custom entities {#custom-entity-spawning}
+
+Whenever the Java server creates a new non-player entity for any connection, a `ServerSpawnEntityEvent` is fired. It can be used to change which Bedrock entity definition is sent to the Bedrock player or cancel the spawn entirely. 
+Each connection has its own entity cache, so different players will never share the same entity instance.
+
+Example:
+
+```java
+private static final Identifier ZOMBIE = Identifier.of("minecraft:zombie");
+private static final CustomEntityDefinition MY_ENTITY = CustomEntityDefinition.of(Identifier.of("mynamespace:my_entity"));
+
+@Subscribe
+public void onDefineEntities(GeyserDefineEntitiesEvent event) {
+    event.register(MY_ENTITY);
+}
+
+@Subscribe
+public void onSpawn(ServerSpawnEntityEvent event) {
+    if (event.entityType().is(ZOMBIE)) {
+        event.definition(MY_ENTITY); // definition must be registered beforehand
+    }
+}
+```
+
+This example replaces all spawned zombies with our custom entity, which we registered in `onDefineEntities`.
+
+:::info
+The `ServerSpawnEntityEvent` fires before the entity is spawned (since it could be canceled). You can provide a consumer for the resulting `GeyserEntity` to set initial entity data values before the entity is spawned on the client:
+
+```java
+private static final Identifier ZOMBIE = Identifier.of("minecraft:zombie");
+private static final CustomEntityDefinition MY_ENTITY = CustomEntityDefinition.of(Identifier.of("mynamespace:my_entity"));
+
+@Subscribe
+public void onSpawn(ServerSpawnEntityEvent event) {
+    if (!event.entityType().is(ZOMBIE)) {
+        return;
+    }
+    event.definition(MY_ENTITY);
+    event.preSpawnConsumer(entity -> {
+        entity.override(GeyserEntityDataTypes.SCALE, 2.0f);
+        entity.override(GeyserEntityDataTypes.COLOR, (byte) 5);
+    });
+}
+```
+:::
+
+### Modifying shoulder parrots {#shoulder-parrots}
+
+`ServerAttachParrotsEvent` fires when a parrot is attached to a player's shoulder. It extends `ServerSpawnEntityEvent`, so definition replacement, cancellation, and setting a pre spawn consumer for the 
+resulting `GeyserEntity` instance are all available.
+
+```java
+@Subscribe
+public void onParrotAttach(ServerAttachParrotsEvent event) {
+    event.definition(myParrotReplacement); // this entity definition would also be registered previously
+}
+```
+
+## Modifying entity data {#entity-data}
+
+Entity data consists of runtime-modifiable values such as scale, size, and hitboxes. All constants live in `GeyserEntityDataTypes`. Values for these types can be updated on a `GeyserEntity` 
+at any time using `entity.override(type, value)`, or set inside a pre-spawn consumer in the entity spawn events to modify it before the spawn packet is sent.
+
+Updating any of these values will override the value sent by the server until the override is removed. To remove an override, a `null` value can be used.
+
+| Constant                           | Value Type     | Description                                                                  |
+|------------------------------------|----------------|------------------------------------------------------------------------------|
+| `COLOR`                            | `Byte`         | Bedrock color component (0–15)                                               |
+| `VARIANT`                          | `Integer`      | Numeric variant index, queryable via `query.variant` in resource packs       |
+| `WIDTH`                            | `Float`        | Collision box width                                                          |
+| `HEIGHT`                           | `Float`        | Collision box height                                                         |
+| `VERTICAL_OFFSET`                  | `Float`        | Y-axis offset applied on top of the Java entity position                     |
+| `SCALE`                            | `Float`        | Visual scale multiplier                                                      |
+| `HITBOXES`                         | `List<Hitbox>` | Custom hitboxes. Set an empty list to remove all hitboxes                    |
+| `SEAT_OFFSET`                      | `Vector3f`     | Riding position offset                                                       |
+| `ROTATION_LOCKED_TO_VEHICLE`       | `Boolean`      | Whether the rider's rotation is locked to the vehicle's rotation             |
+| `SEAT_LOCK_RIDER_ROTATION_DEGREES` | `Float`        | The degrees of rotation a rider may rotate within when mounted on an entity. |
+| `SEAT_HAS_ROTATION`                | `Boolean`      | Whether a seat has rotation                                                  | 
+| `ROTATE_RIDER_DEGREES`             | `Float`        | Rotation offset for the seat in degrees                                      |
+
+:::info
+Hitbox `min`, `max` and `pivot` are absolute world coordinates, not relative to the entity's position.
+:::
+
+## Entity Properties {#entity-properties}
+
+Entity properties expose Java-side state to Bedrock resource packs via `query.property('namespace:name')` in Molang. Entity properties can be registered for both custom, and vanilla entity types using the `GeyserDefineEntityPropertiesEvent`, which fires during Geyser startup.
+
+:::warning Breaking Change in 2.11.0
+`GeyserDefineEntityPropertiesEvent` has been available since **2.9.0**, but its first parameter changed in 2.11.0: it now takes a **Bedrock** entity type identifier.
+:::
+
+A maximum of 32 properties per entity type can be registered.
+
+```java
+private GeyserFloatEntityProperty aggression = null;
+private GeyserIntEntityProperty state = null;
+private GeyserBooleanEntityProperty enraged = null;
+private GeyserEnumEntityProperty<Phase> phase = null;
+private GeyserStringEnumProperty mode = null;
+
+@Subscribe
+public void onDefineProperties(GeyserDefineEntityPropertiesEvent event) {
+    Identifier zombieType = Identifier.of("minecraft:zombie");
+
+    // Float property: min, max, default (null default uses min)
+    aggression = event.registerFloatProperty(zombieType, Identifier.of("mynamespace:aggression"), 0f, 1f, 0f);
+
+    // Integer property
+    state = event.registerIntegerProperty(zombieType, Identifier.of("mynamespace:state"), 0, 10, null);
+
+    // Boolean property
+    enraged = event.registerBooleanProperty(zombieType, Identifier.of("mynamespace:enraged"), false);
+
+    // Enum from a Java enum class (max 16 values, names max 32 chars, must start with a letter)
+    phase = event.registerEnumProperty(zombieType, Identifier.of("mynamespace:phase"), Phase.class, Phase.IDLE);
+
+    // Enum from a string list
+    mode = event.registerEnumProperty(zombieType, Identifier.of("mynamespace:mode"), List.of("idle", "active", "fleeing"), "idle");
+}
+```
+
+Properties can be updated on a `GeyserEntity` instance at any time:
+
+```java
+// Single property
+entity.updateProperty(aggression, 0.5f);
+```
+
+## Looking up entities {#looking-up-entities}
+
+After an entity has spawned it can be looked up through `GeyserConnection#entities()`. All lookup methods are thread-safe.
+
+```java
+EntityData entityData = connection.entities();
+
+// By Java entity ID (int)
+GeyserEntity entity = entityData.byJavaId(javaId);
+
+// By UUID
+GeyserEntity entity = entityData.byUuid(uuid);
+
+// By Geyser/Bedrock runtime ID (long)
+GeyserEntity entity = entityData.byGeyserId(geyserId);
+```
+
+All three return `null` if no entity is found. A `GeyserEntity` exposes various properties, such as the entity uuid, current passengers / vehicle if applicable, and it can further be used to update
+entity properties or entity data type values.
+
+## Full Example {#full-example}
+
+<details>
+<summary>Expand for a full extension example</summary>
+
+```java
+public class MyExtension implements Extension {
+    // Create a custom entity definition
+    private final CustomEntityDefinition enhancedZombie = CustomEntityDefinition.of(Identifier.of("myext:enhanced_zombie"));
+    private GeyserFloatEntityProperty healthFraction = null;
+
+    // Register the custom entity type
+    @Subscribe
+    public void onDefineEntities(GeyserDefineEntitiesEvent event) {
+        event.register(enhancedZombie);
+    }
+
+    // Optionally: Register entity properties (Bedrock identifier)
+    @Subscribe
+    public void onDefineProperties(GeyserDefineEntityPropertiesEvent event) {
+        healthFraction = event.registerFloatProperty(
+            enhancedZombie.identifier(),
+            Identifier.of("myext:health_fraction"), 
+            0f, 1f, 1f
+        );
+    }
+
+    // Replace a default Bedrock entity definition with our custom one
+    @Subscribe
+    public void onSpawn(ServerSpawnEntityEvent event) {
+        // Unless you want to replace everything, you should probably add checks for e.g., entity type, or entity UUID
+        event.definition(enhancedZombie);
+        event.preSpawnConsumer(entity -> {
+            entity.override(GeyserEntityDataTypes.SCALE, 1.5f);
+            entity.override(GeyserEntityDataTypes.COLOR, (byte) 4);
+        });
+    }
+}
+```
+</details>

wiki/geyser/custom-resource-packs.md

@@ -1,9 +0,0 @@
----
-title: Custom Resource Packs
-description: How to use custom resource packs for Geyser.
----
-
-Geyser supports custom resource packs for use with custom items, blocks, and skulls. See:
-- [Custom items](/wiki/geyser/custom-items)
-- [Custom blocks](/wiki/geyser/custom-blocks)
-- [Custom skulls](/wiki/geyser/custom-skulls)

wiki/geyser/custom-waypoints.mdx

@@ -0,0 +1,226 @@
+---
+title: Custom Waypoint Icons
+description: Geyser supports custom locator bar icons (also known as waypoint icons), though they have to be mapped manually.
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+Minecraft: Java Edition supports showing custom icons on the locator bar. These are known as custom waypoints and, on
+Java Edition, are implemented through custom "waypoint styles" in a resource pack. These waypoint styles specify a near
+and far distance in blocks, and a list of sprites to display on the locator bar.
+
+Bedrock Edition also supports custom waypoint icons through behaviour + resource packs. In Geyser, these are implemented through custom JSON mappings, similar to custom block or item mappings, alongside a Bedrock resource pack.
+
+Geyser extensions can also make use out of Bedrock's support for custom waypoint icons. Unlike JSON mappings however,
+extensions have more freedom in how icons are displayed to the client.
+
+When an unknown custom waypoint style is sent to Geyser by the Java server,
+Geyser will display the waypoint using vanilla's default icons.
+
+:::info
+This guide only describes the steps required to write custom waypoint style mappings. You still need to create a resource pack
+for Bedrock Edition, add the waypoint icons to it, and use it in Geyser. Geyser cannot automatically pull icons from
+Java Edition resource packs.
+:::
+
+:::warning
+As with custom blocks and items, Geyser does not convert resource packs from Java Edition, and also does not generate
+custom waypoint mappings automatically. However, [Rainbow](/wiki/other/rainbow/) is planning
+support for these conversions.
+:::
+
+## Simple icons
+
+Custom waypoint icons following Java's system of having a near- and far-distance should be mapped using JSON mappings, or,
+when using Geyser extensions, Geyser's `CustomWaypointStyle.VanillaBuilder` helper builder. Both of these methods follow
+the same format as Java's custom waypoint styles and should feel very familiar.
+
+<Tabs groupId="custom-waypoint-implementation">
+    <TabItem value="json" label="JSON-mappings">
+        JSON mappings have to specify the `format_version` set to `1`, and list all custom waypoint styles under the
+        `waypoint_styles` key. This key holds an object in which keys are identifiers of waypoint styles, and each
+        value is the definition of that waypoint style.
+
+        For example, take the following `waypoint_mappings.json` file:
+        ```json
+        {
+          "format_version": 1,
+          "waypoint_styles": {
+            "geyser:my_first_waypoint": {
+              "near_distance": 10,
+              "far_distance": 100,
+              "sprites": [
+                "geyser:custom_waypoint_0",
+                "geyser:custom_waypoint_1"
+              ]
+            },
+            "geyser:my_second_waypoint": {
+              "sprites": [
+                "geyser:second_waypoint/texture_1",
+                "geyser:second_waypoint/texture_2",
+                "geyser:second_waypoint/texture_3",
+                "geyser:second_waypoint/texture_4"
+              ]
+            },
+            "geyser:the_best_waypoint": {
+              "near_distance": 50,
+              "sprites": [
+                "geyser:ultimate_waypoint/near",
+                "geyser:ultimate_waypoint/far"
+              ]
+            }
+          }
+        }
+        ```
+
+        These mappings specify 3 custom waypoint styles, `geyser:my_first_waypoint`, `geyser:my_second_waypoint`, and
+        `geyser:the_best_waypoint`.
+
+        Just like on Java Edition, the default value for `near_distance` when not specified is 128, and for `far_distance`
+        it is 332. And, just like on Java Edition, at least one texture sprite must be specified.
+
+        Since namespaces do not exist in Bedrock Edition's resource packs, Geyser must flatten the texture sprite identifier
+        to be used in the resource pack on Bedrock Edition. Geyser does this using the following format:
+
+        > `textures/ui/<namespace>/locator_bar_dot/<path>`
+
+        As such, in the example above, the `geyser:my_first_waypoint` waypoint style refers to the following textures in the Bedrock resource pack:
+
+        - `textures/ui/geyser/locator_bar_dot/custom_waypoint_0`
+        - `textures/ui/geyser/locator_bar_dot/custom_waypoint_1`
+    </TabItem>
+    <TabItem value="api" label="Geyser API">
+        The Geyser API provides a helper builder, called `VanillaBuilder` in `CustomWaypointStyle`, to implement custom
+        waypoint icons that are similar to Java Edition's custom icons. The builder is similar to JSON-mappings in use
+        and requires the same fields to be specified.
+
+        Custom waypoint styles are registered per-connection in the `SessionDefineCustomWaypointsEvent`,
+        and as such you can check the `GeyserConnection` before registering a custom waypoint style. If a custom waypoint
+        style is used across multiple connections, it can be useful to only create it once to save memory.
+
+        `VanillaBuilder` instances are created by using `CustomWaypointStyle#vanillaLike(int nearDistance, int farDistance)`.
+        When not specifying a near- and far-distance, the Java defaults of 128 and 332 are used.
+
+        ```java
+        @Subscribe
+        public void onSessionDefineCustomWaypoints(SessionDefineCustomWaypointsEvent event) {
+            event.register(Identifier.of("geyser:my_first_waypoint"), CustomWaypointStyle.vanillaLike(10, 100)
+                .withTexture(Identifier.of("geyser:custom_waypoint_0"))
+                .withTexture(Identifier.of("geyser:custom_waypoint_1"))
+                .build());
+
+            event.register(Identifier.of("geyser:my_second_waypoint"), CustomWaypointStyle.vanillaLike()
+                .withTexture(Identifier.of("geyser:second_waypoint/texture_1"))
+                .withTexture(Identifier.of("geyser:second_waypoint/texture_2"))
+                .withTexture(Identifier.of("geyser:second_waypoint/texture_3"))
+                .withTexture(Identifier.of("geyser:second_waypoint/texture_4"))
+                .build());
+
+            event.register(Identifier.of("geyser:the_best_waypoint"), CustomWaypointStyle.vanillaLike(50, 332)
+                .withTexture(Identifier.of("geyser:ultimate_waypoint/near"))
+                .withTexture(Identifier.of("geyser:ultimate_waypoint/far"))
+                .build());
+        }
+        ```
+
+        As with JSON mappings, Geyser flattens the texture identifier into a string using the following format:
+
+        > `textures/ui/<namespace>/locator_bar_dot/<path>`
+
+        However, you can also pass a literal texture string to `withTexture`. This string must not be prefixed with
+        `textures/` and must also not be suffixed with the texture extension (e.g. `.png`).
+
+        You can register the same custom waypoint style for multiple waypoint style identifiers. However, each
+        waypoint style identifier may only have one custom waypoint style attached to it. If a duplicate is registered,
+        a `CustomWaypointStyleRegisterException` will be thrown.
+    </TabItem>
+</Tabs>
+
+---
+
+<details>
+    <summary>Changing vanilla waypoint styles</summary>
+    Creating custom waypoint styles for vanilla waypoint styles, like `minecraft:default`, is allowed, and can be done
+    as follows:
+
+    <Tabs groupId="custom-waypoint-implementation">
+        <TabItem value="json" label="JSON-mappings">
+            ```json
+            {
+              "format_version": 1,
+              "waypoint_styles": {
+                "minecraft:default": {
+                  "sprites": [
+                    "geyser:custom_vanilla_0",
+                    "geyser:custom_vanilla_1",
+                    "geyser:custom_vanilla_2",
+                    "geyser:custom_vanilla_3",
+                    "geyser:custom_vanilla_4"
+                  ]
+                }
+              }
+            }
+            ```
+        </TabItem>
+        <TabItem value="api" label="Geyser API">
+            ```java
+            @Subscribe
+            public void onSessionDefineCustomWaypoints(SessionDefineCustomWaypointsEvent event) {
+                event.register(Identifier.of("minecraft:default"), CustomWaypointStyle.vanillaLike(128, 332)
+                    .withTexture(Identifier.of("geyser:custom_vanilla_0"))
+                    .withTexture(Identifier.of("geyser:custom_vanilla_1"))
+                    .withTexture(Identifier.of("geyser:custom_vanilla_2"))
+                    .withTexture(Identifier.of("geyser:custom_vanilla_3"))
+                    .withTexture(Identifier.of("geyser:custom_vanilla_4"))
+                    .build());
+            }
+            ```
+        </TabItem>
+    </Tabs>
+</details>
+
+## Advanced icons
+
+Geyser API users may write custom implementations of `CustomWaypointStyle`, to run custom checks for waypoint textures
+and waypoint icon sizes. Just like waypoint styles created using the `VanillaBuilder`, these can be registered for one
+or more custom waypoint style identifiers in the `SessionDefineCustomWaypointsEvent`. For example, the following
+implementation will always use the same texture and icon size, no matter the distance:
+
+```java
+public final class MyCustomWaypointStyle implements CustomWaypointStyle {
+    public static final CustomWaypointStyle INSTANCE = new MyCustomWaypointStyle();
+    private static final Vector2f SIZE = Vector2f.from(0.5, 0.5);
+
+    private MyCustomWaypointStyle() {}
+
+    @Override
+    public String texturePath(Identifier style, float distance) {
+        return "ui/geyser/locator_bar_dot/my_icon";
+    }
+
+    @Override
+    public Vector2f textureSize(Identifier style, float distance) {
+        return SIZE;
+    }
+}
+```
+
+Implementations must always implement `texturePath(Identifier, float)` and `textureSize(Identifier, float)`. The first
+returns the texture path to use for that waypoint style and distance (not prefixed with `textures/`), and the second
+returns the size of the texture to use (where a size of `[1, 1]` is the size icons normally appear as when the waypoint
+is close to the player).
+
+Implementations can then be registered through the `SessionDefineCustomWaypointsEvent` as follows:
+
+```java
+@Subscribe
+public void onSessionDefineCustomWaypoints(SessionDefineCustomWaypointsEvent event) {
+    event.register(Identifier.of("geyser:my_style", MyCustomWaypointStyle.INSTANCE));
+}
+```
+
+Like with `VanillaBuilder`, should you use a custom waypoint style across multiple connections,
+it can be useful to only keep one instance of it, to save memory. Also, avoid running time-taking operations in your
+`texturePath` or `textureSize` implementations, since these methods are called frequently. For full implementation details,
+refer to the Javadocs of `CustomWaypointStyle`.

wiki/geyser/packs.md

@@ -81,7 +81,8 @@ However, many things that are possible with add-ons or behavior packs can be don
 or [custom blocks](/wiki/geyser/custom-blocks).
 
 - **Does Geyser convert Java edition resource packs?** <br />
-Not currently. For now, you need to manually create a Bedrock edition resource pack equivalent.
+Not currently. For now, you need to manually create a Bedrock edition resource pack equivalent. You can however
+use automatic tools such as [Rainbow](/wiki/other/rainbow/) or [Thunder](/wiki/other/thunder) to make converting content simpler.
 
 - **Can I allow players to choose resource packs themselves?** <br />
 On most Bedrock platforms (except consoles), players are able to download and install resource packs on the client. 

wiki/geyser/using-geyser-with-consoles.md

@@ -60,11 +60,11 @@ If you'd rather try emulating a LAN game on your network on another device, here
 
 ### MultiPlatform {#multiplatform}
 
-#### Netherlink — free and ad-free.
+#### MCCompanion — free and ad-free.
 
 - iOS (iOS 12.0 or later): [Download on the App Store](https://apps.apple.com/be/app/netherlink/id6747323142?l=en)  
 - Android: [Download on the Play Store](https://play.google.com/store/apps/details?id=net.netherdev.netherLink)  
-- macOS: [Download DMG](https://github.com/NetherLinkMC/NetherLinkWebsite/raw/refs/heads/main/downloads/apple/NetherLink.dmg)  
+- macOS: [Download on the App Store](https://apps.apple.com/us/app/mccompanion/id6747323142?platform=mac)  
 - Windows: [Download on the Microsoft Store](https://apps.microsoft.com/detail/9NSFPT6D8PTR)
 
 

wiki/other/index.mdx

@@ -16,6 +16,7 @@ This includes community projects, but also other projects by the GeyserMC team,
     'community-geyser-projects',
     'hurricane',
     'thunder',
+    'rainbow',
     'thirdpartycosmetics',
     'hydraulic',
     'geyserconnect',

wiki/other/rainbow.md

@@ -1,35 +1,163 @@
 ---
 title: Rainbow
-description: A Minecraft mod to generate Geyser item mappings and bedrock resourcepacks for use with Geyser's Custom Item API V2.
+description: A tool to convert custom content to Bedrock.
 ---
 
-Rainbow is a Fabric client-sided Minecraft mod to generate Geyser item mappings and bedrock resourcepacks for use with Geyser's custom item API (v2) for use on servers. 
+Rainbow is a client-sided Minecraft mod to convert resource packs with custom content created for Java Edition to
+an equivalent resource pack for Bedrock Edition, together with custom mappings to be used in Geyser. Rainbow is available
+for the Fabric modloader.
 
-## What is Rainbow? {#what-is-rainbow}
+Rainbow can be downloaded at [our website](https://geysermc.org/download?project=other-projects&rainbow=expanded),
+or over at [Modrinth](https://modrinth.com/mod/rainbow-mod).
 
-Rainbow is a generator to create Geyser item mappings and Bedrock Edition resource packs, it uses the Geyser Custom Item API V2 format to allow the use of 1.21.4+ Java Edition packs.
+:::info
+Rainbow is a mod installed on the Java client! As such, you need to be able to use a Java client to use Rainbow.
+Rainbow can be used with every resource pack, regardless of your server's software (it may be used with Spigot or
+Paper servers, for example).
+:::
+
+:::warning
+Rainbow is used to convert resource packs adding new, custom content. For resource packs modifying vanilla content,
+you should look into using [Thunder](/wiki/other/thunder).
+:::
 
 :::caution
-
-This project is early in development! Any bugs and issues should be reported in our [Discord](https://discord.gg/geysermc).
-
+This project is in early development! Any bugs and issues should be reported at its [issue tracker](https://github.com/GeyserMC/Rainbow/issues).
 :::
 
+You can use Rainbow to convert custom content of datapacks (that require a resource pack), custom content plugins like Nexo or ItemsAdder, or even
+server-side only Fabric/NeoForge mods, such as Polymer mods. However, these custom content providers may use
+[item displays](https://minecraft.wiki/w/Display), which Geyser does not yet support. This may result in your custom blocks or items
+not rendering on Bedrock when placed in the world.
+
+You can use extensions created by the community, such as [GeyserDisplayEntity](https://github.com/GeyserExtensionists/GeyserDisplayEntity),
+to add support for item displays to Geyser. However, keep in mind that these are not created by or affiliated with Geyser,
+and as such any issues that may occur should not be reported to us.
+
 ## Usage {#usage}
 
-To use Rainbow:
-1. You need to set up a 26.1 Fabric client for Java Edition and ensure the mod is present on the client.
-2. Join your server of choice to start converting packs and run `/rainbow create <pack name>` with `<pack name>` being the name of your output pack.
-3. You can map things in a couple of ways:
-    - Hold each item in your hand one by one and run `/rainbow map` while holding the item.
-    - Fill your inventory with the custom items and run `/rainbow mapinventory` to map your entire inventory.
-    - Run `/rainbow auto inventory` and open a UI with the custom content (For example, a chest or command from a plugin to show custom content.). Rainbow will continue mapping all custom items until you stop the process with `/rainbow auto stop`.
-4. Run `/rainbow finish` to finish your conversion, Rainbow will then output your pack and mappings file to `<instance folder>/rainbow/<pack name>`, optionally, you can click the `Wrote pack to disk` message in chat to open the folder.
-5. In this folder, you will find 3 files, `pack.zip` which you put in your `packs` folder of your server, `geyser_mappings.json` which you put in your `custom_mappings` folder of your server and finally `report.txt` which you can send in our [Discord](https://discord.gg/geysermc) if you face issues, otherwise, you can ignore this file.
+Rainbow works by analysing the loaded resource packs on the client and extracting the custom content found. As such,
+you need to ensure all the necessary resource packs for your custom content are loaded on your client. If custom content
+appears correctly on your Java client, then Rainbow is able to analyse it.
 
-## Download {#download} 
+Generally, you use Rainbow as follows:
 
-You can download Rainbow [here](/download/?project=other-projects&rainbow=expanded).
+1. Set up a Java Edition 26.1 client, with Fabric installed, and ensure that Rainbow is present on your client.
+2. Join a world or server of choice and make sure all the necessary resource packs are loaded. Then, run `/rainbow create <pack name>`, with `<pack name>` replaced with the name of your resource pack on Bedrock Edition.
+3. You can then start converting (or "mapping") custom content to be exported in your Bedrock resource pack. You can find a full list of ways to map custom content below.
+4. Run `/rainbow finish` to finish your conversion. Rainbow will then output the generated resource pack and additional files to `.minecraft/rainbow/<pack name>`. You can click the `Wrote pack to disk` message in chat to open that folder.
+5. In this folder, you'll find 5 important files/folders:
+    - `custom-skulls.yml`: put this in Geyser's config folder. These are the exported player skulls. The file may already exist in Geyser's config folder, be careful with overwriting it!
+    - `custom_mappings`: you need to put the files in here in the `custom_mappings` folder in Geyser's config folder. These are the generated Geyser mappings.
+    - `pack.zip`: this is the generated resource pack for Bedrock Edition. You need to put this file in the `packs` folder in Geyser's config folder.
+    - `lang`: you need to put all files in this folder in the `locales/overrides` folder in Geyser's config folder.
+      - The folder can be empty or non-existent if no language files were found. This is usually not an issue!
+    - `report.txt`: you don't need to do anything with this file, but it contains information about generated assets and possible problems that occurred. It can be useful to diagnose potential issues with Rainbow, and you should upload it when filing a bug report.
+6. Once you've taken all the necessary steps and uploaded the generated content to your Geyser server, restart your server. If everything went well, Bedrock users should now see your custom content!
+
+### Mapping custom blocks
+
+Rainbow is able to map custom blocks that are created by overriding unused vanilla block states. Most blocks can automatically
+be mapped by running `/rainbow auto blocks`, which will scan through all loaded resource packs for custom blocks created using block state overrides,
+and mapping all that are found.
+
+:::warning
+Running `/rainbow auto blocks` may shortly freeze your client.
+:::
+
+With some resource packs, Rainbow may not be able to automatically detect all custom blocks. In this case, you may have to
+map blocks manually, which you can do by using `/rainbow map block <target>`, where `<target>` is a position in the world,
+at which a custom block is placed.
+
+### Mapping custom items and skulls
+
+Rainbow supports mapping custom items, by detecting items with custom `minecraft:item_model` or `minecraft:custom_model_data` components.
+Rainbow is also able to map custom skulls. Each method of mapping custom items is described below.
+
+#### Mapping manually
+
+You can map custom items manually by running `/rainbow map item`. This will map the custom item or skull you're currently
+holding in your hand in-game, if any. You can also run `/rainbow mapinventory`, which will scan your entire inventory
+for any custom items or skulls, and maps all that are found.
+
+:::info
+Rainbow is automatically able to find most kinds of custom items when using `mapinventory`, however,
+items created by overriding a vanilla item model definition may not be automatically detected,
+so you'll have to map these explicitly.
+:::
+
+#### Mapping inventory menus automatically
+
+Custom item plugins, like Nexo or ItemsAdder, commonly include an inventory menu listing all custom items. Rainbow
+can make use of this and automatically map all items listed in such an inventory menu, by running `/rainbow auto inventory`.
+This will scan all inventory menus and containers you open for custom items or skulls, and maps all that are found.
+You can also use this with chests that are filled with custom items, for example.
+
+Run `/rainbow auto stop` to stop the mapping of custom items.
+
+:::info
+Like with `mapinventory`, items created by overriding a vanilla item model definition may not be automatically detected,
+so you'll have to map these explicitly.
+:::
+
+#### Mapping custom items from recipe outputs automatically
+
+Rainbow is able to search through all known recipes for outputs that are custom items or skulls, and map any that are found,
+by running `/rainbow auto recipes`. This can be useful when mapping datapacks that add large amounts of custom items with
+custom recipes, for example.
+
+:::info
+You can use the vanilla `/recipe give @s *` command to give yourself all recipes, which helps Rainbow recognise custom items when using this
+way of mapping items.
+:::
+
+:::info
+As with `mapinventory` and `auto inventory`, items created by overriding a vanilla item model definition may not be automatically detected,
+so you'll have to map these explicitly.
+:::
+
+### Mapping custom sounds
+
+Custom sounds may be mapped by using `/rainbow auto sounds`, which scans through all loaded resource packs for custom sounds,
+and maps all that are found. You may also use `/rainbow map sound <namespace>`, which maps all the custom sounds
+of the given namespace. This can be useful when you only want to export custom sounds of a single resource pack.
+
+## Capabilities and limitations
+
+Rainbow is currently capable of the following:
+
+- Generating Geyser block mappings for custom blocks made using block state overrides, both automatically and manually from loaded resource packs.
+- Generating Geyser item mappings complete with data components and proper bedrock options, by detecting items with custom `minecraft:item_model` or `minecraft:custom_model_data` components, and analysing their components.
+   - Also includes generating mappings with predicates for more complicated Java item model definitions, such as checks for if an item is broken. The following definition types are currently supported by Rainbow:
+      - Plain item model definitions.
+      - Conditional item models, supported properties are:
+         - `broken`,
+         - `damaged`,
+         - `custom_model_data`,
+         - `has_component`, and,
+         - `fishing_rod/cast`.
+      - Range dispatch item models, supported properties are:
+         - `bundle/fullness`,
+         - `count`,
+         - `custom_model_data`, and,
+         - `damage`.
+      - Select item models, supported properties are:
+         - `charge_type`,
+         - `trim_material`,
+         - `context_dimension`, and,
+         - `custom_model_data`.
+         - For the `display_context` property, the `gui` case is mapped, if present.
+   - Also includes detecting if an item should be displayed handheld by looking at the item's model.
+   - Also is able to detect and map items using the "legacy" `custom_model_data` range-dispatch style, and map them to Geyser's `legacy` item mappings.
+- Generating a simple Bedrock resource pack for blocks and simple 2D items, as well as:
+   - Simple custom armour items, by analysing an item's `minecraft:equippable` component and loaded equipment assets.
+      - Custom elytra items also work, but only visually, due to bedrock limitations.
+   - 3D items, by converting the Java model to a bedrock one, and generating an attachable and animations for it, as well as rendering a custom GUI icon.
+      - Is able to translate display transformations for the head, first-person and third-person item slots.
+   - Custom sounds.
+- Generating working animated (flipbook) textures for 2D items and 3D items that make use of a single texture only.
+- Exporting merged language files from loaded resource packs to a folder, for easy copying to Geyser's `locales/overrides` folder.
+   - Files from different resource packs for the same language are merged together.
 
 ## Contributing {#contributing}