diff --git a/.vitepress/config.mts b/.vitepress/config.mts index 822bbc7..c32d9d1 100644 --- a/.vitepress/config.mts +++ b/.vitepress/config.mts @@ -137,6 +137,7 @@ export default defineConfig({ }, ], }, + { text: "Locator Bar", link: "/docs/feature/locator-bar" }, { text: "Query System", link: "/docs/feature/query" }, { text: "Open to LAN", link: "/docs/feature/open-to-lan" }, ], diff --git a/docs/feature/locator-bar.md b/docs/feature/locator-bar.md new file mode 100644 index 0000000..05c391d --- /dev/null +++ b/docs/feature/locator-bar.md @@ -0,0 +1,41 @@ +# Locator Bar +The [locator bar](https://minecraft.wiki/w/Locator_bar) is a new UI element added in Minecraft version 1.21.6. In Minestom, it can be accessed by sending the related waypoint packet. + +```java +// A waypoint can be identified by a UUID or a string +UUID uuid = UUID.randomUUID(); + +// Let's make it point to the center of the map +BlockVec center = new BlockVec(0, 0, 0); +TrackedWaypointPacket.Target target = new TrackedWaypointPacket.Target.Vec3i(center); + +// Set the icon to be a green circle/square +TrackedWaypointPacket.Icon icon = new TrackedWaypointPacket.Icon(TrackedWaypointPacket.Icon.DEFAULT_STYLE, NamedTextColor.GREEN); + +// Put it all together to start tracking the waypoint +TrackedWaypointPacket.Waypoint waypoint = new TrackedWaypointPacket.Waypoint(Either.left(uuid), icon, target); +player.sendPacket(new TrackedWaypointPacket(TrackedWaypointPacket.Operation.TRACK, waypoint)); + +// If you wanted a string ID instead +// TrackedWaypointPacket.Waypoint waypoint = new TrackedWaypointPacket.Waypoint(Either.right("emerald_generator"), icon, target); + +// Create a new waypoint with the same ID to update its properties +TrackedWaypointPacket.Waypoint updatedWaypoint = new TrackedWaypointPacket.Waypoint(...); +player.sendPacket(new TrackedWaypointPacket(TrackedWaypointPacket.Operation.UPDATE, updatedWaypoint)); + +// Stop tracking the waypoint +player.sendPacket(new TrackedWaypointPacket(TrackedWaypointPacket.Operation.UNTRACK, waypoint)); +``` + +## Targets +- `Empty`: The waypoint will be positioned in the center of the locator bar and use the small circle texture (which appears when the target is too far away). +- `Vec3i`: Points to an X, Y, Z [world position](/docs/world/coordinates.md). +- `Chunk`: Points to the coordinates of a chunk. +- `Azimuth`: Points to an angle (in radians) without revealing the precise coordinates. + +## Icon +An icon can have a key to a style (defined in the resource pack), as well as an optional RGB color. The below image shows the default texture (`minecraft:default`). + +![The default style of a waypoint.](/docs/feature/locator-bar/example.png) + +See the [Minecraft Wiki](https://minecraft.wiki/w/Waypoint_style) for more info on how to add a custom waypoint texture. diff --git a/public/docs/feature/locator-bar/example.png b/public/docs/feature/locator-bar/example.png new file mode 100644 index 0000000..2c2b165 Binary files /dev/null and b/public/docs/feature/locator-bar/example.png differ