From 0cff73e2fcc988839ebfbd9e056e70d3812b3ac9 Mon Sep 17 00:00:00 2001
From: Jonathan Coates <git@squiddev.cc>
Date: Mon, 3 Mar 2025 21:30:19 +0000
Subject: [PATCH] Add turtle.getEquipped{Left,Right}

These just return details about the currently equipped *item*. This
allows us to expose information about the currently equipped upgrade,
without having to invent a whole new format.

Docs are a bit consise, but didn't really know how to flesh them out any
further.

Fixes #964, fixes #1613, closes #1692.
---
 gradle/libs.versions.toml                     |  2 +-
 .../shared/turtle/apis/TurtleAPI.java         | 34 +++++++++++++++++++
 2 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
index 6c3e81ff7..e7e634de1 100644
--- a/gradle/libs.versions.toml
+++ b/gradle/libs.versions.toml
@@ -57,7 +57,7 @@ junitPlatform = "1.11.4"
 jmh = "1.37"
 
 # Build tools
-cctJavadoc = "1.8.3"
+cctJavadoc = "1.8.4"
 checkstyle = "10.21.2"
 errorProne-core = "2.36.0"
 errorProne-plugin = "4.1.0"
diff --git a/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java b/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java
index 029f681bb..0e052045a 100644
--- a/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java
+++ b/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java
@@ -13,7 +13,9 @@ import dan200.computercraft.core.metrics.Metrics;
 import dan200.computercraft.core.metrics.MetricsObserver;
 import dan200.computercraft.shared.peripheral.generic.methods.AbstractInventoryMethods;
 import dan200.computercraft.shared.turtle.core.*;
+import org.jspecify.annotations.Nullable;
 
+import java.util.Map;
 import java.util.Optional;
 
 /**
@@ -659,6 +661,7 @@ public class TurtleAPI implements ILuaAPI {
      * @cc.treturn [2] string The reason equipping this item failed.
      * @cc.since 1.6
      * @see #equipRight()
+     * @see #getEquippedLeft()
      */
     @LuaFunction
     public final MethodResult equipLeft() {
@@ -678,12 +681,43 @@ public class TurtleAPI implements ILuaAPI {
      * @cc.treturn [2] string The reason equipping this item failed.
      * @cc.since 1.6
      * @see #equipLeft()
+     * @see #getEquippedRight()
      */
     @LuaFunction
     public final MethodResult equipRight() {
         return trackCommand(new TurtleEquipCommand(TurtleSide.RIGHT));
     }
 
+    /**
+     * Get the upgrade currently equipped on the left of the turtle.
+     * <p>
+     * This returns information about the currently equipped item, in the same form as
+     * {@link #getItemDetail(ILuaContext, Optional, Optional)}.
+     *
+     * @return Details about the currently equipped item, or {@code nil} if no upgrade is equipped.
+     * @see #equipLeft()
+     */
+    @LuaFunction(mainThread = true)
+    public final @Nullable Map<?, ?> getEquippedLeft() {
+        var upgrade = turtle.getUpgradeWithData(TurtleSide.LEFT);
+        return upgrade == null ? null : VanillaDetailRegistries.ITEM_STACK.getDetails(upgrade.getUpgradeItem());
+    }
+
+    /**
+     * Get the upgrade currently equipped on the right of the turtle.
+     * <p>
+     * This returns information about the currently equipped item, in the same form as
+     * {@link #getItemDetail(ILuaContext, Optional, Optional)}.
+     *
+     * @return Details about the currently equipped item, or {@code nil} if no upgrade is equipped.
+     * @see #equipRight()
+     */
+    @LuaFunction(mainThread = true)
+    public final @Nullable Map<?, ?> getEquippedRight() {
+        var upgrade = turtle.getUpgradeWithData(TurtleSide.RIGHT);
+        return upgrade == null ? null : VanillaDetailRegistries.ITEM_STACK.getDetails(upgrade.getUpgradeItem());
+    }
+
     /**
      * Get information about the block in front of the turtle.
      *