Allow equipping pocket computers on the bottom

This allows equipping pocket computers on both the back (as before) and
bottom of a pocket computer. The asymmetry is a little unfortunate here,
but makes some sense with the crafting recipe (above goes behind, below
goes on the bottom).

 - Move some functionality from IPocketAccess into a PocketComputer
   interface (and PocketComputerInternal) interface, used by the pocket
   API.

   IPocketAccess preserves the same interface as before. Unlike
   ITurtleAccess, we /don't/ expose the PocketSide in the public API.

 - Several pocket-computer methods (e.g. setUpgradeData, setColour) are
   now required to be called on the main thread, and when the computer
   is being held. This allows us to write back changes to the item
   immediately, rather than the next time the item is ticked.

   Sadly this doesn't actually remove the need for onCraftedPostProcess
   as I'd originally hoped, but I think does make the code a little
   simpler.

 - Rename "computercraft:pocket_computer" component to
   "computercraft:back_pocket_computer".

 - And finally, support multiple upgrades on the pocket computer. This
   is actually quite an easy change, just tedious — there's lots of
   places to update!

Fixes #1406, and I think fixes #1148 — you can use a speaker to notify
you now.

projects/common-api/src/main/java/dan200/computercraft/api/component/ComputerComponents.java

@@ -6,6 +6,7 @@ package dan200.computercraft.api.component;
 
 import dan200.computercraft.api.ComputerCraftAPI;
 import dan200.computercraft.api.pocket.IPocketAccess;
+import dan200.computercraft.api.pocket.PocketComputer;
 import dan200.computercraft.api.turtle.ITurtleAccess;
 
 /**
@@ -20,7 +21,7 @@ public class ComputerComponents {
     /**
      * The {@link IPocketAccess} associated with a pocket computer.
      */
-    public static final ComputerComponent<IPocketAccess> POCKET = ComputerComponent.create(ComputerCraftAPI.MOD_ID, "pocket");
+    public static final ComputerComponent<PocketComputer> POCKET = ComputerComponent.create(ComputerCraftAPI.MOD_ID, "pocket");
 
     /**
      * This component is only present on "command computers", and other computers with admin capabilities.

projects/common-api/src/main/java/dan200/computercraft/api/pocket/IPocketAccess.java

@@ -7,60 +7,15 @@ package dan200.computercraft.api.pocket;
 import dan200.computercraft.api.upgrades.UpgradeBase;
 import dan200.computercraft.api.upgrades.UpgradeData;
 import net.minecraft.core.component.DataComponentPatch;
-import net.minecraft.server.level.ServerLevel;
-import net.minecraft.world.entity.Entity;
 import net.minecraft.world.item.ItemStack;
-import net.minecraft.world.phys.Vec3;
 import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.Nullable;
 
 /**
- * Wrapper class for pocket computers.
+ * Access to a pocket computer for {@linkplain IPocketUpgrade pocket upgrades}.
  */
 @ApiStatus.NonExtendable
-public interface IPocketAccess {
-    /**
-     * Get the level in which the pocket computer exists.
-     *
-     * @return The pocket computer's level.
-     */
-    ServerLevel getLevel();
-
-    /**
-     * Get the position of the pocket computer.
-     *
-     * @return The pocket computer's position.
-     */
-    Vec3 getPosition();
-
-    /**
-     * Gets the entity holding this item.
-     * <p>
-     * This must be called on the server thread.
-     *
-     * @return The holding entity, or {@code null} if none exists.
-     */
-    @Nullable
-    Entity getEntity();
-
-    /**
-     * Get the colour of this pocket computer as a RGB number.
-     *
-     * @return The colour this pocket computer is. This will be a RGB colour between {@code 0x000000} and
-     * {@code 0xFFFFFF} or -1 if it has no colour.
-     * @see #setColour(int)
-     */
-    int getColour();
-
-    /**
-     * Set the colour of the pocket computer to a RGB number.
-     *
-     * @param colour The colour this pocket computer should be changed to. This should be a RGB colour between
-     *               {@code 0x000000} and {@code 0xFFFFFF} or -1 to reset to the default colour.
-     * @see #getColour()
-     */
-    void setColour(int colour);
-
+public interface IPocketAccess extends PocketComputer {
     /**
      * Get the colour of this pocket computer's light as a RGB number.
      *
@@ -92,7 +47,8 @@ public interface IPocketAccess {
     /**
      * Set the upgrade for this pocket computer, also updating the item stack.
      * <p>
-     * Note this method is not thread safe - it must be called from the server thread.
+     * This method can only be called from the main server thread, when this computer is {@linkplain #isActive() is
+     * active}.
      *
      * @param upgrade The new upgrade to set it to, may be {@code null}.
      * @see #getUpgrade()
@@ -114,6 +70,9 @@ public interface IPocketAccess {
 
     /**
      * Update the upgrade-specific data.
+     * <p>
+     * This method can only be called from the main server thread, when this computer is {@linkplain #isActive() is
+     * active}.
      *
      * @param data The new upgrade data.
      * @see #getUpgradeData()

projects/common-api/src/main/java/dan200/computercraft/api/pocket/IPocketUpgrade.java

@@ -12,7 +12,7 @@ import dan200.computercraft.impl.ComputerCraftAPIService;
 import net.minecraft.core.Registry;
 import net.minecraft.resources.ResourceKey;
 import net.minecraft.resources.ResourceLocation;
-import net.minecraft.world.level.Level;
+import net.minecraft.server.level.ServerLevel;
 import org.jspecify.annotations.Nullable;
 
 /**
@@ -71,7 +71,7 @@ public interface IPocketUpgrade extends UpgradeBase {
     /**
      * Called when the pocket computer is right clicked.
      *
-     * @param world      The world the computer is in.
+     * @param level      The world the computer is in.
      * @param access     The access object for the pocket item stack.
      * @param peripheral The peripheral for this upgrade.
      * @return {@code true} to stop the GUI from opening, otherwise false. You should always provide some code path
@@ -79,7 +79,7 @@ public interface IPocketUpgrade extends UpgradeBase {
      * access the GUI.
      * @see #createPeripheral(IPocketAccess)
      */
-    default boolean onRightClick(Level world, IPocketAccess access, @Nullable IPeripheral peripheral) {
+    default boolean onRightClick(ServerLevel level, IPocketAccess access, @Nullable IPeripheral peripheral) {
         return false;
     }
 }

projects/common-api/src/main/java/dan200/computercraft/api/pocket/PocketComputer.java

@@ -0,0 +1,81 @@
+// SPDX-FileCopyrightText: 2025 The CC: Tweaked Developers
+//
+// SPDX-License-Identifier: MPL-2.0
+
+package dan200.computercraft.api.pocket;
+
+import net.minecraft.server.level.ServerLevel;
+import net.minecraft.world.entity.Entity;
+import net.minecraft.world.phys.Vec3;
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * A pocket computer.
+ *
+ * @see IPocketAccess
+ * @see dan200.computercraft.api.component.ComputerComponents#POCKET
+ */
+@ApiStatus.NonExtendable
+public interface PocketComputer {
+    /**
+     * Get the level in which the pocket computer exists.
+     *
+     * @return The pocket computer's level.
+     */
+    ServerLevel getLevel();
+
+    /**
+     * Get the position of the pocket computer.
+     *
+     * @return The pocket computer's position.
+     */
+    Vec3 getPosition();
+
+    /**
+     * Gets the entity holding this item.
+     * <p>
+     * This must be called on the server thread.
+     *
+     * @return The holding entity, or {@code null} if none exists.
+     */
+    @Nullable
+    Entity getEntity();
+
+    /**
+     * Check whether this pocket computer is currently being held by a player, lectern, or other valid entity.
+     * <p>
+     * As pocket computers are backed by item stacks, you must check for validity before updating the computer.
+     * <p>
+     * This must be called on the server thread.
+     *
+     * @return Whether this computer is active.
+     */
+    boolean isActive();
+
+    /**
+     * Get the colour of this pocket computer as an RGB number.
+     *
+     * <p>
+     * This method can only be called from the main server thread, when this computer is {@linkplain #isActive() is
+     * active}.
+     *
+     * @return The colour this pocket computer is. This will be a RGB colour between {@code 0x000000} and
+     * {@code 0xFFFFFF} or -1 if it has no colour.
+     * @see #setColour(int)
+     */
+    int getColour();
+
+    /**
+     * Set the colour of the pocket computer to an RGB number.
+     * <p>
+     * This method can only be called from the main server thread, when this computer is {@linkplain #isActive() is
+     * active}.
+     *
+     * @param colour The colour this pocket computer should be changed to. This should be a RGB colour between
+     *               {@code 0x000000} and {@code 0xFFFFFF} or -1 to reset to the default colour.
+     * @see #getColour()
+     */
+    void setColour(int colour);
+
+}