feat: firmament api

4 files changed, 118 insertions, 0 deletions

diff --git a/src/api/java/moe/nea/firmament/api/v1/FirmamentAPI.java b/src/api/java/moe/nea/firmament/api/v1/FirmamentAPI.java
new file mode 100644
index 0000000..d01e88b
--- /dev/null
+++ b/src/api/java/moe/nea/firmament/api/v1/FirmamentAPI.java
@@ -0,0 +1,45 @@
+package moe.nea.firmament.api.v1;
+
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.Nullable;
+
+import java.util.List;
+import java.util.Optional;
+
+/**
+ * Methods you can call to get information about firmaments current state.
+ */
+@ApiStatus.NonExtendable
+public abstract class FirmamentAPI {
+	private static @Nullable FirmamentAPI INSTANCE;
+
+	/**
+	 * @return the canonical instance of the {@link FirmamentAPI}.
+	 */
+	public static FirmamentAPI getInstance() {
+		if (INSTANCE != null)
+			return INSTANCE;
+		try {
+			return INSTANCE = (FirmamentAPI) Class.forName("moe.nea.firmament.impl.v1.FirmamentAPIImpl")
+				.getField("INSTANCE")
+				.get(null);
+		} catch (IllegalAccessException | NoSuchFieldException | ClassCastException e) {
+			throw new RuntimeException("Firmament API implementation class found, but could not load api instance.", e);
+		} catch (ClassNotFoundException e) {
+			throw new RuntimeException("Could not find Firmament API, check FabricLoader.getInstance().isModLoaded(\"firmament\") first.");
+		}
+	}
+
+	/**
+	 * @return list-view of registered extensions
+	 */
+	public abstract List<? extends FirmamentExtension> getExtensions();
+
+	/**
+	 * Obtain a reference to the currently hovered item widget, which may be either in the item list or placed in a UI.
+	 * This widget may or may not also be present in the Widgets on the current screen.
+	 *
+	 * @return the currently hovered firmament item widget.
+	 */
+	public abstract Optional<FirmamentItemWidget> getHoveredItemWidget();
+}
diff --git a/src/api/java/moe/nea/firmament/api/v1/FirmamentExtension.java b/src/api/java/moe/nea/firmament/api/v1/FirmamentExtension.java
new file mode 100644
index 0000000..1fa3c11
--- /dev/null
+++ b/src/api/java/moe/nea/firmament/api/v1/FirmamentExtension.java
@@ -0,0 +1,32 @@
+package moe.nea.firmament.api.v1;
+
+import net.minecraft.client.gui.navigation.ScreenRectangle;
+import net.minecraft.client.gui.screens.Screen;
+
+import java.util.Collection;
+import java.util.List;
+
+public interface FirmamentExtension {
+
+	/**
+	 * This method gets called during client initialization, if firmament is installed. Can be used as an alternative to
+	 * checking {@code FabricLoader.getInstance().isModLoaded("firmament")}.
+	 */
+	default void onLoad() {}
+
+	/**
+	 * @param screen the current active screen
+	 * @return whether inventory buttons should be hidden on the current screen.
+	 */
+	default boolean shouldHideInventoryButtons(Screen screen) {
+		return false;
+	}
+
+	/**
+	 * @param screen the current active screen
+	 * @return a list of zones which contain content rendered by other mods, which should therefore hide the items in those areas
+	 */
+	default Collection<? extends ScreenRectangle> getExclusionZones(Screen screen) {
+		return List.of();
+	}
+}
diff --git a/src/api/java/moe/nea/firmament/api/v1/FirmamentItemWidget.java b/src/api/java/moe/nea/firmament/api/v1/FirmamentItemWidget.java
new file mode 100644
index 0000000..89bb17c
--- /dev/null
+++ b/src/api/java/moe/nea/firmament/api/v1/FirmamentItemWidget.java
@@ -0,0 +1,37 @@
+package moe.nea.firmament.api.v1;
+
+import net.minecraft.world.item.ItemStack;
+import org.jetbrains.annotations.ApiStatus;
+
+@ApiStatus.NonExtendable
+public interface FirmamentItemWidget {
+	/**
+	 * non-exhaustive enum for the placement position of an item widget
+	 */
+	@ApiStatus.NonExtendable
+	interface Placement {
+		String name();
+
+		Placement ITEM_LIST = () -> "ITEM_LIST";
+		Placement RECIPE_SCREEN = () -> "RECIPE_SCREEN";
+	}
+
+	/**
+	 * @return where in the UI the item widget is placed
+	 */
+	Placement getPlacement();
+
+	/**
+	 * get the currently displayed {@link ItemStack}. this empty stack might be empty. care should be taken not to
+	 * mutate the item stack instance, without {@link ItemStack#copy copying} it first.
+	 *
+	 * @return the currently displayed {@link ItemStack}, may be empty.
+	 */
+	ItemStack getItemStack();
+
+	/**
+	 * @return a SkyBlock id, potentially processed to reflect more details about the item stack, such as which specific
+	 * {@code PET} it is. this is sometimes referred to as the "neu id".
+	 */
+	String getSkyBlockId();
+}
diff --git a/src/api/java/moe/nea/firmament/api/v1/package-info.java b/src/api/java/moe/nea/firmament/api/v1/package-info.java
new file mode 100644
index 0000000..62719b2
--- /dev/null
+++ b/src/api/java/moe/nea/firmament/api/v1/package-info.java
@@ -0,0 +1,4 @@
+@NullMarked
+package moe.nea.firmament.api.v1;
+
+import org.jspecify.annotations.NullMarked;