AnvilGUI

https://github.com/wesjd/anvilgui
Admin
AnvilGUI is a library that provides a straightforward, versatile, and easy-to-use solution for...
Tokens:30,190
Snippets:429
Trust Score:9.3
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Complete AnvilGUI Implementation Example

Source: https://github.com/wesjd/anvilgui/blob/master/USAGE.md

A comprehensive example demonstrating event handling, input validation, and GUI configuration.

```java
new AnvilGUI.Builder()
    .onClose(stateSnapshot -> {
        stateSnapshot.getPlayer().sendMessage("You closed the inventory.");
    })
    .onClick((slot, stateSnapshot) -> { // Either use sync or async variant, not both
        if(slot != AnvilGUI.Slot.OUTPUT) {
            return Collections.emptyList();
        }

        if(stateSnapshot.getText().equalsIgnoreCase("you")) {
            stateSnapshot.getPlayer().sendMessage("You have magical powers!");
            return Arrays.asList(AnvilGUI.ResponseAction.close());
        } else {
            return Arrays.asList(AnvilGUI.ResponseAction.replaceInputText("Try again"));
        }
    })
    .preventClose()                                                    //prevents the inventory from being closed
    .text("What is the meaning of life?")                              //sets the text the GUI should start with
    .title("Enter your answer.")                                       //set the title of the GUI (only works in 1.14+)
    .plugin(myPluginInstance)                                          //set the plugin instance
    .open(myPlayer);                                                   //opens the GUI for the player provided
```

--------------------------------

### Quick Start AnvilGUI Implementation

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/README.md

Demonstrates the basic builder pattern to initialize an AnvilGUI, set the title and initial text, and define a click handler that processes player input.

```java
new AnvilGUI.Builder()
    .plugin(plugin)                    // Required: your plugin instance
    .text("Enter your name")            // Initial text in rename field
    .title("Profile Setup")             // Window title (1.14+)
    .onClick((slot, snapshot) -> {      // Click handler
        if (slot != AnvilGUI.Slot.OUTPUT) {
            return Collections.emptyList();
        }
        
        String name = snapshot.getText();
        snapshot.getPlayer().sendMessage("Hello, " + name);
        
        return Arrays.asList(ResponseAction.close());
    })
    .open(player);                     // Display the GUI
```

--------------------------------

### Implement VersionWrapper Methods

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/02-version-wrapper.md

Example implementation of player casting and packet sending for Wrapper1_20_R1.

```java
private EntityPlayer toNMS(Player player) {
    return ((CraftPlayer) player).getHandle();
}

@Override
public void sendPacketOpenWindow(Player player, int containerId, Object inventoryTitle) {
    toNMS(player).c.a(new PacketPlayOutOpenWindow(containerId, Containers.h, (IChatBaseComponent) inventoryTitle));
}
```

--------------------------------

### Maven Installation Configuration

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/00-API-reference-index.md

Add the repository and dependency to your project's pom.xml file.

```xml
<repository>
    <id>mvn-wesjd-net</id>
    <url>https://mvn.wesjd.net/</url>
</repository>

<dependency>
    <groupId>net.wesjd</groupId>
    <artifactId>anvilgui</artifactId>
    <version>1.10.13-SNAPSHOT</version>
    <scope>compile</scope>
</dependency>
```

--------------------------------

### Migrating Response Actions

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/04-types-and-enums.md

Examples showing the transition from the deprecated Response class to modern ResponseAction usage.

```java
return Response.close();  // Returns List<ResponseAction>
```

```java
return Arrays.asList(ResponseAction.close());  // Explicit list
```

```java
return List.of(ResponseAction.close());  // Java 9+
```

--------------------------------

### Get Player

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/01-anvilgui-class.md

Retrieves the player associated with the snapshot.

```java
public Player getPlayer()
```

--------------------------------

### Get Output Item

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/01-anvilgui-class.md

Retrieves the item in the output slot (slot 2).

```java
public ItemStack getOutputItem()
```

--------------------------------

### Get Text Input

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/01-anvilgui-class.md

Retrieves the text typed into the rename field.

```java
public String getText()
```

```java
String userInput = snapshot.getText();
```

--------------------------------

### Creating a GUI

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/README.md

Demonstrates minimal and full-featured builder patterns for initializing an AnvilGUI.

```java
// Minimal
new AnvilGUI.Builder()
    .plugin(plugin)
    .onClick((slot, snapshot) -> Collections.emptyList())
    .open(player);

// Full featured
new AnvilGUI.Builder()
    .plugin(plugin)
    .text("Initial text")
    .title("Custom Title")
    .itemLeft(new ItemStack(Material.PAPER))
    .onClick((slot, snapshot) -> handleClick(slot, snapshot))
    .onClose(snapshot -> handleClose(snapshot))
    .preventClose()
    .interactableSlots(AnvilGUI.Slot.INPUT_LEFT)
    .open(player);
```

--------------------------------

### Build the project

Source: https://github.com/wesjd/anvilgui/blob/master/CONTRIBUTING.md

Use this command to build the project with Java 21.

```bash
mvn clean install
```

--------------------------------

### Configure and open a GUI with the Builder pattern

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/README.md

Use the fluent builder to accumulate settings and open the GUI for a player.

```java
new AnvilGUI.Builder()
    .setting1(value1)
    .setting2(value2)
    .open(player);  // Creates and opens
```

--------------------------------

### Get Right Item

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/01-anvilgui-class.md

Retrieves the item in the right input slot (slot 1).

```java
public ItemStack getRightItem()
```

--------------------------------

### Get Left Item

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/01-anvilgui-class.md

Retrieves the item in the left input slot (slot 0).

```java
public ItemStack getLeftItem()
```

--------------------------------

### Initialize VersionMatcher

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/03-version-matcher.md

Instantiate the VersionMatcher and retrieve the appropriate VersionWrapper for the current server environment.

```java
VersionMatcher matcher = new VersionMatcher();
VersionWrapper wrapper = matcher.match();
```

--------------------------------

### Instantiate AnvilGUI

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/01-anvilgui-class.md

Create and open an anvil GUI using the Builder pattern. Requires a plugin instance and a player to open the interface.

```java
AnvilGUI gui = new AnvilGUI.Builder()
    .plugin(plugin)
    .text("Enter text here")
    .title("Anvil Title")
    .onClick((slot, snapshot) -> {
        // Handle clicks
        return Collections.emptyList();
    })
    .open(player);
```

--------------------------------

### Use StateSnapshot in events

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/04-types-and-enums.md

Example usage of StateSnapshot within onClick and onClose event handlers.

```java
builder.onClick((slot, snapshot) -> {
    if (slot != AnvilGUI.Slot.OUTPUT) {
        return Collections.emptyList();
    }
    
    String userInput = snapshot.getText();
    Player player = snapshot.getPlayer();
    ItemStack resultItem = snapshot.getOutputItem();
    
    if (userInput.length() > 20) {
        player.sendMessage(ChatColor.RED + "Name too long!");
        return Arrays.asList(
            ResponseAction.replaceInputText(userInput.substring(0, 20))
        );
    }
    
    return Arrays.asList(
        ResponseAction.close(),
        ResponseAction.run(() -> {
            // Save the name change
            player.sendMessage(ChatColor.GREEN + "Name saved: " + userInput);
        })
    );
});

builder.onClose(snapshot -> {
    String lastText = snapshot.getText();
    snapshot.getPlayer().sendMessage("You closed the anvil with text: " + lastText);
});
```

--------------------------------

### Get Bukkit Inventory

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/02-version-wrapper.md

Retrieves the Bukkit-wrapped inventory for the container to allow standard API manipulation.

```java
Inventory getBukkitInventory()
```

```java
Inventory inv = container.getBukkitInventory();
ItemStack output = inv.getItem(2);
```

--------------------------------

### Minimal AnvilGUI Implementation

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/00-API-reference-index.md

Create and open a basic anvil GUI using the builder pattern.

```java
new AnvilGUI.Builder()
    .plugin(plugin)
    .text("Enter your name")
    .title("Profile Setup")
    .onClick((slot, snapshot) -> {
        if (slot != AnvilGUI.Slot.OUTPUT) {
            return Collections.emptyList();
        }
        
        String name = snapshot.getText();
        snapshot.getPlayer().sendMessage("Hello, " + name);
        
        return Arrays.asList(ResponseAction.close());
    })
    .open(player);
```

--------------------------------

### Create an AnvilGUI instance

Source: https://github.com/wesjd/anvilgui/blob/master/README.md

Use the Builder pattern to define inventory behavior, including close actions and click responses. Requires a valid plugin instance and player object.

```java
new AnvilGUI.Builder()
    .onClose(stateSnapshot -> {
        stateSnapshot.getPlayer().sendMessage("You closed the inventory.");
    })
    .onClick((slot, stateSnapshot) -> {
        if(slot != AnvilGUI.Slot.OUTPUT) {
            return Collections.emptyList();
        }

        if(stateSnapshot.getText().equalsIgnoreCase("you")) {
            stateSnapshot.getPlayer().sendMessage("You have magical powers!");
            return Arrays.asList(AnvilGUI.ResponseAction.close());
        } else {
            return Arrays.asList(AnvilGUI.ResponseAction.replaceInputText("Try again"));
        }
    })
    .preventClose()
    .text("What is the meaning of life?")
    .title("Enter your answer")
    .plugin(plugin)
    .open(player);
```

--------------------------------

### VersionMatcher()

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/03-version-matcher.md

Constructor for the VersionMatcher class. Initializes the matcher instance to prepare for version detection.

```APIDOC
## VersionMatcher()

### Description
Creates a new instance of the VersionMatcher class.

### Signature
`public VersionMatcher()`

### Example
```java
VersionMatcher matcher = new VersionMatcher();
```
```

--------------------------------

### match()

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/03-version-matcher.md

Detects the current Minecraft server version and returns the appropriate VersionWrapper implementation.

```APIDOC
## match()

### Description
Detects the server's Minecraft version and returns the corresponding VersionWrapper implementation. This method is typically called during library initialization.

### Signature
`public VersionWrapper match()`

### Returns
- **VersionWrapper** - An implementation specific to the detected server version.

### Throws
- **IllegalStateException** - Thrown if the version is unsupported or if the wrapper fails to instantiate.

### Example
```java
VersionMatcher matcher = new VersionMatcher();
try {
    VersionWrapper wrapper = matcher.match();
} catch (IllegalStateException e) {
    System.err.println("Unsupported server version: " + e.getMessage());
}
```
```

--------------------------------

### open(Player)

Source: https://github.com/wesjd/anvilgui/blob/master/USAGE.md

Opens the configured anvil GUI for the specified player.

```APIDOC
## open(Player)

### Description
Opens the anvil GUI for the provided player. This method can be invoked multiple times on the same builder instance.

### Parameters
- **player** (Player) - Required - The player to open the GUI for.
```

--------------------------------

### Multi-Step Wizard

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/00-API-reference-index.md

Transitions the user to a subsequent menu while saving the current input state.

```java
.onClick((slot, snapshot) -> {
    if (slot == AnvilGUI.Slot.OUTPUT) {
        return Arrays.asList(
            ResponseAction.openInventory(nextMenu),
            ResponseAction.run(() -> saveStep(snapshot.getText()))
        );
    }
    return Collections.emptyList();
})
```

--------------------------------

### Click Handler Patterns

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/README.md

Shows how to handle clicks synchronously for simple logic or asynchronously for blocking operations like database queries.

```java
// Synchronous (simple operations)
.onClick((slot, snapshot) -> {
    if (slot == AnvilGUI.Slot.OUTPUT) {
        return Arrays.asList(ResponseAction.close());
    }
    return Collections.emptyList();
})

// Asynchronous (database, network)
.onClickAsync((slot, snapshot) -> {
    return CompletableFuture.supplyAsync(() -> {
        // Run on async thread
        String result = databaseQuery(snapshot.getText());
        return Arrays.asList(ResponseAction.close());
    });
})
```

--------------------------------

### Multi-Step Wizard Configuration

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/05-configuration-options.md

Transitions the player to a different inventory upon completing the anvil input step.

```java
Inventory step2Menu = Bukkit.createInventory(null, 27, "Step 2");

new AnvilGUI.Builder()
    .plugin(plugin)
    .text("Step 1: Enter Name")
    .title("Character Setup")
    .onClick((slot, snapshot) -> {
        if (slot != AnvilGUI.Slot.OUTPUT) return Collections.emptyList();
        String name = snapshot.getText();
        return Arrays.asList(
            ResponseAction.openInventory(step2Menu),
            ResponseAction.run(() -> saveStep1(name))
        );
    })
    .open(player);
```

--------------------------------

### AnvilGUI.Builder

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/README.md

The primary entry point for creating and configuring an anvil GUI instance.

```APIDOC
## AnvilGUI.Builder

### Description
Used to construct and display an anvil GUI to a player.

### Methods
- **plugin(Plugin plugin)**: Sets the plugin instance.
- **text(String text)**: Sets the initial text in the rename field.
- **title(String title)**: Sets the GUI title.
- **itemLeft(ItemStack item)**: Sets the item in the left input slot.
- **onClick(BiFunction<Slot, Snapshot, List<ResponseAction>> handler)**: Defines a synchronous click handler.
- **onClickAsync(BiFunction<Slot, Snapshot, CompletableFuture<List<ResponseAction>>> handler)**: Defines an asynchronous click handler.
- **onClose(Consumer<Snapshot> handler)**: Defines a handler for when the GUI is closed.
- **preventClose()**: Prevents the player from closing the GUI.
- **interactableSlots(Slot... slots)**: Defines which slots are interactable.
- **open(Player player)**: Opens the GUI for the specified player.
```

--------------------------------

### Initialize VersionMatcher in AnvilGUI

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/03-version-matcher.md

Static initialization of the version wrapper within the AnvilGUI class.

```java
private static final VersionWrapper WRAPPER = new VersionMatcher().match();
```

--------------------------------

### Unsupported Version Exception

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/03-version-matcher.md

Exception thrown when the required version wrapper class is missing for the detected server version.

```text
IllegalStateException: AnvilGUI does not support server version "1_7_R2"
Caused by: ClassNotFoundException: net.wesjd.anvilgui.version.Wrapper1_7_R2
```

--------------------------------

### AnvilGUI.Builder Methods

Source: https://github.com/wesjd/anvilgui/blob/master/USAGE.md

Methods available on the AnvilGUI.Builder instance to configure the GUI.

```APIDOC
## onClose(Consumer<StateSnapshot>)

### Description
Registers a callback that is executed when a player closes the anvil GUI.

## onClick(BiFunction<Integer, AnvilGUI.StateSnapshot, AnvilGUI.ResponseAction>)

### Description
Registers a synchronous callback for inventory clicks. Returns a list of ResponseAction objects to perform operations like closing the inventory, updating text, or updating the title.

## onClickAsync(ClickHandler)

### Description
Registers an asynchronous callback for inventory clicks, returning a CompletableFuture for non-blocking operations.

## allowConcurrentClickHandlerExecution()

### Description
Disables the default mechanism that prevents concurrent execution of asynchronous click handlers.

## interactableSlots(int... slots)

### Description
Configures which anvil slots allow user interaction (input/output).

## preventClose()

### Description
Prevents the user from closing the inventory by pressing the escape key.

## geyserCompat()

### Description
Toggles compatibility mode for Geyser (Bedrock edition).

## text(String)

### Description
Sets the initial text in the anvil's renaming field.

## itemLeft(ItemStack)

### Description
Sets the ItemStack to be placed in the left input slot.

## itemRight(ItemStack)

### Description
Sets the ItemStack to be placed in the right input slot.

## title(String)

### Description
Sets the inventory title (supported in Minecraft 1.14+).
```

--------------------------------

### Apply code formatting

Source: https://github.com/wesjd/anvilgui/blob/master/CONTRIBUTING.md

Run this command to automatically fix code formatting issues to meet project guidelines.

```bash
mvn spotless:apply
```

--------------------------------

### Response Actions

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/README.md

Lists available actions to perform in response to GUI interactions.

```java
ResponseAction.close()                                   // Close GUI
ResponseAction.replaceInputText("text")                // Change rename field
ResponseAction.updateTitle("title", true)              // Change title
ResponseAction.updateJsonTitle("{...}", true)          // Rich title
ResponseAction.openInventory(inventory)                // Open another inventory
ResponseAction.run(() -> { /* code */ })              // Execute code
```

--------------------------------

### Handle Bedrock Players

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/06-usage-examples.md

Demonstrates automatic Geyser compatibility and how to detect Bedrock players during interaction.

```java
new AnvilGUI.Builder()
    .plugin(plugin)
    .text("Works on Bedrock!")
    .title("Cross-platform")
    // Geyser compatibility is enabled by default
    // For Bedrock players with 0 experience:
    // - Experience is set to 20 during anvil interaction
    // - Restored to 0 when anvil closes
    .onClick((slot, snapshot) -> {
        if (slot == AnvilGUI.Slot.OUTPUT) {
            String isBedrock = snapshot.getPlayer().getClass()
                .getName().contains("Bedrock") ? "yes" : "no";
            
            return Arrays.asList(
                ResponseAction.close(),
                ResponseAction.run(() -> {
                    snapshot.getPlayer().sendMessage(
                        "Bedrock player: " + isBedrock
                    );
                })
            );
        }
        return Collections.emptyList();
    })
    .open(player);

// To disable Geyser compatibility if needed:
// .disableGeyserCompat()
```

--------------------------------

### Instantiation Failure Exception

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/03-version-matcher.md

Exception thrown when a version wrapper class is found but fails to instantiate during runtime.

```text
IllegalStateException: Failed to instantiate version wrapper for version 1_20_R1
Caused by: ReflectiveOperationException: ...
```

--------------------------------

### Check Bukkit Version String

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/03-version-matcher.md

Retrieve and print the Bukkit version string.

```java
String version = Bukkit.getBukkitVersion();
System.out.println("Bukkit version: " + version);
```

--------------------------------

### Version Support Errors

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/00-API-reference-index.md

Exception thrown when the server version is not supported by the library.

```text
IllegalStateException: AnvilGUI does not support server version "1_7_R2"
```

--------------------------------

### Set Plugin Instance

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/01-anvilgui-class.md

Required method to associate the GUI with a plugin instance before opening.

```java
public Builder plugin(Plugin plugin)
```

--------------------------------

### VersionMatcher Reflection Loading

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/07-architecture-and-internals.md

Mechanism used to dynamically instantiate the appropriate version-specific wrapper class.

```java
Class.forName("net.wesjd.anvilgui.version.Wrapper" + revision)
    .getDeclaredConstructor()
    .newInstance()
```

--------------------------------

### ResponseAction.openInventory(Inventory otherInventory)

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/04-types-and-enums.md

Opens a different inventory for the player.

```APIDOC
## ResponseAction.openInventory(Inventory otherInventory)

### Description
Creates an action that opens a different inventory for the player.

### Signature
`static ResponseAction openInventory(Inventory otherInventory)`

### Parameters
- **otherInventory** (Inventory) - The inventory to open

### Example
```java
Inventory nextMenu = Bukkit.createInventory(null, 27, "Choose an option");
return Arrays.asList(ResponseAction.openInventory(nextMenu));
```
```

--------------------------------

### sendPacketExperienceChange

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/02-version-wrapper.md

Sends the PacketPlayOutExperience packet to the player to adjust their experience level.

```APIDOC
## void sendPacketExperienceChange(Player player, int experienceLevel)

### Description
Sends the PacketPlayOutExperience packet to the player, setting their displayed experience level. Used for Geyser compatibility.

### Parameters
- **player** (Player) - The player to send the packet to
- **experienceLevel** (int) - The experience level to set (0-255)

### Returns
- **void**
```

--------------------------------

### Create Multi-Step Wizard

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/06-usage-examples.md

Chains multiple anvil instances by using ResponseAction.run to trigger the next step upon completion of the current one.

```java
// Step 1: Name Entry
new AnvilGUI.Builder()
    .plugin(plugin)
    .text("John Doe")
    .title("Step 1: Name")
    .onClick((slot, snapshot) -> {
        if (slot != AnvilGUI.Slot.OUTPUT) {
            return Collections.emptyList();
        }
        
        String name = snapshot.getText();
        
        return Arrays.asList(
            ResponseAction.run(() -> {
                openStep2Anvil(snapshot.getPlayer(), name);
            }),
            ResponseAction.close()
        );
    })
    .open(player);

// Helper method
private void openStep2Anvil(Player player, String name) {
    new AnvilGUI.Builder()
        .plugin(plugin)
        .text("john.doe@example.com")
        .title("Step 2: Email")
        .onClick((slot, snapshot) -> {
            if (slot != AnvilGUI.Slot.OUTPUT) {
                return Collections.emptyList();
            }
            
            String email = snapshot.getText();
            
            return Arrays.asList(
                ResponseAction.run(() -> {
                    completeSetup(snapshot.getPlayer(), name, email);
                }),
                ResponseAction.close()
            );
        })
        .open(player);
}
```

--------------------------------

### Check Version Detection

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/00-API-reference-index.md

Logs the server package name and Bukkit version to the console for debugging environment compatibility.

```java
String pkg = Bukkit.getServer().getClass().getPackage().getName();
String version = Bukkit.getBukkitVersion();
Bukkit.getLogger().info("Package: " + pkg);
Bukkit.getLogger().info("Version: " + version);
```

--------------------------------

### getBukkitInventory()

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/02-version-wrapper.md

Returns the Bukkit-wrapped inventory for this container.

```APIDOC
## Inventory getBukkitInventory()

### Description
Returns the Bukkit-wrapped inventory for this container, allowing manipulation via the standard Bukkit API.

### Returns
- **Inventory** - The Bukkit inventory representation of the anvil container.

### Example
```java
Inventory inv = container.getBukkitInventory();
ItemStack output = inv.getItem(2);
```
```

--------------------------------

### sendPacketOpenWindow

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/02-version-wrapper.md

Sends the PacketPlayOutOpenWindow packet to the player to open a new inventory window.

```APIDOC
## void sendPacketOpenWindow(Player player, int containerId, Object inventoryTitle)

### Description
Sends the PacketPlayOutOpenWindow packet to the player, opening a new inventory window on the client side with the specified title and container ID.

### Parameters
- **player** (Player) - The player to send the packet to
- **containerId** (int) - The ID of the container being opened
- **inventoryTitle** (Object) - The title as a version-specific ChatComponent object

### Returns
- **void**
```

--------------------------------

### Project File Statistics

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/MANIFEST.md

Displays the line counts for each documentation file in the project.

```text
README.md                          650 lines
00-API-reference-index.md          650 lines
01-anvilgui-class.md              650 lines
02-version-wrapper.md             550 lines
03-version-matcher.md             450 lines
04-types-and-enums.md             550 lines
05-configuration-options.md       550 lines
06-usage-examples.md              700 lines
07-architecture-and-internals.md  800 lines
MANIFEST.md (this file)           400 lines
---
Total:                           5,400 lines
```

--------------------------------

### Load Version Wrapper via Reflection

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/03-version-matcher.md

Dynamically instantiates the appropriate VersionWrapper class based on the determined revision string.

```java
return (VersionWrapper) Class.forName(getClass().getPackage().getName() + ".Wrapper" + rVersion)
    .getDeclaredConstructor()
    .newInstance();
```

--------------------------------

### Handle AnvilGUI version loading exception

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/02-version-wrapper.md

This exception is thrown when the server version is unsupported, the wrapper class is missing, or instantiation fails.

```java
IllegalStateException: AnvilGUI does not support server version "[version]"
```

--------------------------------

### Open Different Inventory

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/04-types-and-enums.md

Opens a different inventory for the player.

```java
Inventory nextMenu = Bukkit.createInventory(null, 27, "Choose an option");
return Arrays.asList(ResponseAction.openInventory(nextMenu));
```

--------------------------------

### Reuse AnvilGUI Builder

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/05-configuration-options.md

Shows how to reuse a single Builder instance to open GUIs for multiple players or with different configurations.

```java
AnvilGUI.Builder builder = new AnvilGUI.Builder()
    .plugin(plugin)
    .text("Enter name")
    .onClick((slot, snapshot) -> 
        Arrays.asList(ResponseAction.close())
    );

// Open for player 1
builder.open(player1);

// Open for same player again with different title
builder.title("New Title").open(player1);

// Open for different player
builder.open(player2);
```

--------------------------------

### Simple Text Input Configuration

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/05-configuration-options.md

Configures an anvil with custom text and title, processing input upon clicking the output slot.

```java
new AnvilGUI.Builder()
    .plugin(plugin)
    .text("Enter your name")
    .title("Profile Setup")
    .onClick((slot, snapshot) -> {
        if (slot != AnvilGUI.Slot.OUTPUT) return Collections.emptyList();
        String name = snapshot.getText();
        return Arrays.asList(
            ResponseAction.run(() -> saveUserName(name)),
            ResponseAction.close()
        );
    })
    .open(player);
```

--------------------------------

### Minimal Anvil GUI

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/06-usage-examples.md

Creates a basic anvil GUI that does not perform any actions upon interaction.

```java
new AnvilGUI.Builder()
    .plugin(plugin)
    .onClick((slot, snapshot) -> Collections.emptyList())
    .open(player);
```

--------------------------------

### Retrieve CraftBukkit Package Name

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/03-version-matcher.md

Fetches the package name of the server implementation class to identify the environment.

```java
String craftBukkitPackage = Bukkit.getServer().getClass().getPackage().getName();
```

--------------------------------

### onClick(BiFunction<Integer, StateSnapshot, List<ResponseAction>> clickHandler)

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/05-configuration-options.md

Sets a synchronous click handler that executes immediately when a slot is clicked.

```APIDOC
## Builder onClick(BiFunction)

### Description
Sets a synchronous click handler. The handler is called immediately when a slot is clicked.

### Parameters
- **clickHandler** (BiFunction<Integer, StateSnapshot, List<ResponseAction>>) - Required - The function to execute on click.

### Example
```java
builder.onClick((slot, snapshot) -> {
    if (slot == AnvilGUI.Slot.OUTPUT) {
        return Arrays.asList(ResponseAction.close());
    }
    return Collections.emptyList();
});
```
```

--------------------------------

### Open GUI for Player

Source: https://github.com/wesjd/anvilgui/blob/master/USAGE.md

Opens the anvil GUI for a specific player. Can be reused without creating a new builder instance.

```java
builder.open(player);
```

--------------------------------

### Perform Asynchronous Database Lookup with AnvilGUI

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/06-usage-examples.md

Uses onClickAsync to query a database without blocking the main server thread. Response actions are executed on the main thread once the future completes.

```java
new AnvilGUI.Builder()
    .plugin(plugin)
    .text("Enter username")
    .title("Player Lookup")
    .onClickAsync((slot, snapshot) -> {
        return CompletableFuture.supplyAsync(() -> {
            if (slot != AnvilGUI.Slot.OUTPUT) {
                return Collections.emptyList();
            }
            
            String username = snapshot.getText();
            
            // Run on async thread - can be slow
            PlayerData data = database.getPlayerData(username);
            
            if (data != null) {
                return Arrays.asList(
                    ResponseAction.close(),
                    ResponseAction.run(() -> {
                        displayPlayerInfo(snapshot.getPlayer(), data);
                    })
                );
            } else {
                return Arrays.asList(
                    ResponseAction.replaceInputText("Player not found")
                );
            }
        });
    })
    .open(player);
```

--------------------------------

### ResponseAction Run Method

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/01-anvilgui-class.md

Creates an action to execute arbitrary code.

```java
static ResponseAction run(Runnable runnable)
```

--------------------------------

### Configure Maven Shade Plugin

Source: https://github.com/wesjd/anvilgui/blob/master/README.md

Relocate the library to avoid classpath conflicts and ensure the entire library is included when minimizing the JAR.

```xml
<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-shade-plugin</artifactId>
      <version>${shade.version}</version> <!-- The version must be at least 3.5.0 -->
      <executions>
        <execution>
          <phase>package</phase>
          <goals>
            <goal>shade</goal>
          </goals>
          <configuration>
           <!--
             If multiple plugins use AnvilGUI but use different AnvilGUI versions,
             one of the plugins functionality may break. To avoid these classpath
             conflicts, relocate AnvilGUI to your plugin's namespace.
           -->              
            <relocations>
              <relocation>
                <pattern>net.wesjd.anvilgui</pattern>
                <shadedPattern>[YOUR_PLUGIN_PACKAGE].anvilgui</shadedPattern>
              </relocation>
            </relocations>
              
            <!-- 
              AnvilGUI works by loading the appropriate anvil implementation at
              runtime via reflection. When minimize JAR is enabled, the shade 
              plugin will see no usages of the anvil implementation classes and 
              omit them from the shaded artifacts. To solve this, add a filter 
              that always includes the entire library.
            -->
            <filters>
              <filter>
                <artifact>*:*</artifact>
                <excludeDefaults>false</excludeDefaults>
                <includes>
                  <include>net/wesjd/anvilgui/**</include>
                </includes>
              </filter>
            </filters>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>
```

--------------------------------

### Container State Variables

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/07-architecture-and-internals.md

Fields for tracking the unique container ID, NMS wrapper, and Bukkit inventory instance.

```java
private int containerId;
private VersionWrapper.AnvilContainerWrapper container;
private Inventory inventory;
```

--------------------------------

### Multiple Actions

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/06-usage-examples.md

Chains multiple response actions to be executed in sequence when the output slot is clicked.

```java
new AnvilGUI.Builder()
    .plugin(plugin)
    .text("Complete the task")
    .title("Task Manager")
    .onClick((slot, snapshot) -> {
        if (slot != AnvilGUI.Slot.OUTPUT) {
            return Collections.emptyList();
        }
        
        String taskName = snapshot.getText();
        
        return Arrays.asList(
            ResponseAction.run(() -> saveTask(taskName)),
            ResponseAction.close(),
            ResponseAction.run(() -> {
                snapshot.getPlayer().sendMessage("Task saved: " + taskName);
                playSound(snapshot.getPlayer());
            })
        );
    })
    .open(player);
```

--------------------------------

### Configure Click Handler

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/01-anvilgui-class.md

Sets a synchronous handler for slot clicks, returning a list of response actions.

```java
public Builder onClick(BiFunction<Integer, StateSnapshot, List<ResponseAction>> clickHandler)
```

```java
builder.onClick((slot, snapshot) -> {
    if (slot != AnvilGUI.Slot.OUTPUT) {
        return Collections.emptyList();
    }
    if ("magic".equals(snapshot.getText())) {
        return Arrays.asList(AnvilGUI.ResponseAction.close());
    }
    return Arrays.asList(AnvilGUI.ResponseAction.replaceInputText("Try again"));
});
```

--------------------------------

### Mock Testing a Click Handler in Java

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/06-usage-examples.md

Verifies click handler logic by manually creating a StateSnapshot and invoking the handler function.

```java
@Test
public void testClickHandler() {
    BiFunction<Integer, StateSnapshot, List<ResponseAction>> handler = 
        (slot, snapshot) -> {
            if (slot == AnvilGUI.Slot.OUTPUT) {
                return Arrays.asList(ResponseAction.close());
            }
            return Collections.emptyList();
        };
    
    // Create mock snapshot
    ItemStack output = new ItemStack(Material.PAPER);
    output.getItemMeta().setDisplayName("Test");
    StateSnapshot snapshot = new StateSnapshot(
        new ItemStack(Material.AIR),
        new ItemStack(Material.AIR),
        output,
        mockPlayer
    );
    
    // Call handler
    List<ResponseAction> actions = handler.apply(AnvilGUI.Slot.OUTPUT, snapshot);
    
    // Verify result
    assertEquals(1, actions.size());
}
```

--------------------------------

### plugin(Plugin plugin)

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/01-anvilgui-class.md

Sets the plugin instance that manages this anvil GUI. This is a required configuration step before opening the GUI.

```APIDOC
### Method
`public Builder plugin(Plugin plugin)`

### Parameters
- **plugin** (Plugin) - Required - The plugin instance managing the GUI.

### Returns
`Builder` - The builder instance for method chaining.
```

--------------------------------

### Define response actions for click events

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/README.md

Return a list of ResponseAction objects to execute sequential operations after a user click.

```java
return Arrays.asList(
    ResponseAction.replaceInputText("feedback"),
    ResponseAction.updateTitle("Step 2", true),
    ResponseAction.run(() -> saveData())
);
```

--------------------------------

### Construct StateSnapshot

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/01-anvilgui-class.md

Creates a state snapshot manually, though typically handled internally by AnvilGUI.

```java
public StateSnapshot(ItemStack leftItem, ItemStack rightItem, ItemStack outputItem, Player player)
```

--------------------------------

### Opening Another Inventory

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/06-usage-examples.md

Transitions the player to a different inventory menu upon clicking the output slot.

```java
Inventory nextMenu = createYourMenu();

new AnvilGUI.Builder()
    .plugin(plugin)
    .text("Click here to continue")
    .title("Confirmation")
    .onClick((slot, snapshot) -> {
        if (slot != AnvilGUI.Slot.OUTPUT) {
            return Collections.emptyList();
        }
        
        return Arrays.asList(
            ResponseAction.openInventory(nextMenu)
        );
    })
    .open(player);
```

--------------------------------

### ResponseAction.run(Runnable runnable)

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/04-types-and-enums.md

Executes arbitrary code on the main server thread.

```APIDOC
## ResponseAction.run(Runnable runnable)

### Description
Creates an action that executes arbitrary code. The code runs on the main server thread.

### Signature
`static ResponseAction run(Runnable runnable)`

### Parameters
- **runnable** (Runnable) - The code to execute

### Example
```java
return Arrays.asList(ResponseAction.run(() -> {
    snapshot.getPlayer().sendMessage("You entered: " + snapshot.getText());
}));
```
```

--------------------------------

### Match Version with Error Handling

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/03-version-matcher.md

Perform version matching within a try-catch block to handle potential IllegalStateException errors when a version is unsupported or fails to instantiate.

```java
VersionMatcher matcher = new VersionMatcher();
try {
    VersionWrapper wrapper = matcher.match();
    // Use wrapper for version-specific operations
} catch (IllegalStateException e) {
    System.err.println("Unsupported server version: " + e.getMessage());
}
```

--------------------------------

### Implement getText logic

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/04-types-and-enums.md

Internal implementation for retrieving the rename text from the output item.

```java
return outputItem.hasItemMeta() ? outputItem.getItemMeta().getDisplayName() : "";
```

--------------------------------

### Async Database Lookup Configuration

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/05-configuration-options.md

Uses onClickAsync to perform non-blocking database operations, preventing main thread stalls.

```java
new AnvilGUI.Builder()
    .plugin(plugin)
    .text("Enter code")
    .title("Enter Redemption Code")
    .onClickAsync((slot, snapshot) -> {
        return CompletableFuture.supplyAsync(() -> {
            if (slot != AnvilGUI.Slot.OUTPUT) {
                return Collections.emptyList();
            }
            String code = snapshot.getText();
            if (database.isValidCode(code)) {
                database.redeemCode(code);
                return Arrays.asList(
                    ResponseAction.close(),
                    ResponseAction.run(() -> 
                        snapshot.getPlayer().sendMessage("Code redeemed!")
                    )
                );
            } else {
                return Arrays.asList(
                    ResponseAction.replaceInputText("Invalid code")
                );
            }
        });
    })
    .open(player);
```

--------------------------------

### Implement Item Selection Interface

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/06-usage-examples.md

Configures item slots and uses the slot index in the onClick handler to determine which item was selected.

```java
ItemStack iron = new ItemStack(Material.IRON_INGOT);
ItemStack gold = new ItemStack(Material.GOLD_INGOT);
ItemStack diamond = new ItemStack(Material.DIAMOND);

new AnvilGUI.Builder()
    .plugin(plugin)
    .itemLeft(iron)
    .itemRight(gold)
    .itemOutput(diamond)
    .title("Select Material")
    .text("Choose one")
    .onClick((slot, snapshot) -> {
        Material chosen = switch(slot) {
            case 0 -> Material.IRON_INGOT;
            case 1 -> Material.GOLD_INGOT;
            case 2 -> Material.DIAMOND;
            default -> null;
        };
        
        if (chosen != null) {
            return Arrays.asList(
                ResponseAction.close(),
                ResponseAction.run(() -> {
                    givePlayerMaterial(snapshot.getPlayer(), chosen);
                })
            );
        }
        return Collections.emptyList();
    })
    .open(player);
```

--------------------------------

### Modify AnvilGUI at Runtime

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/05-configuration-options.md

Demonstrates how to update the title, inventory items, and close the GUI after it has been opened.

```java
AnvilGUI gui = builder.open(player);

// Change title at runtime
gui.setTitle("New Title", true);

// Change title with JSON
gui.setJsonTitle("{\"text\":\"New Title\",\"color\":\"blue\"}", true);

// Get inventory and modify items
Inventory inv = gui.getInventory();
inv.setItem(AnvilGUI.Slot.INPUT_LEFT, newItem);

// Close the GUI
gui.closeInventory();
```

--------------------------------

### getInventory()

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/01-anvilgui-class.md

Retrieves the Bukkit inventory object associated with the AnvilGUI.

```APIDOC
## Inventory getInventory()

### Description
Returns the Bukkit inventory object backing this anvil GUI. Allows direct manipulation of inventory items.

### Returns
- **Inventory** - The Bukkit inventory for this anvil GUI
```

--------------------------------

### Builder Factory Pattern

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/06-usage-examples.md

Create a factory method to standardize the creation and opening of specific anvil dialogs.

```java
public AnvilGUI openNameDialog(Player player, Consumer<String> onAccept) {
    return new AnvilGUI.Builder()
        .plugin(plugin)
        .text("Enter name")
        .title("Name")
        .onClick((slot, snapshot) -> {
            if (slot != AnvilGUI.Slot.OUTPUT) {
                return Collections.emptyList();
            }
            onAccept.accept(snapshot.getText());
            return Arrays.asList(ResponseAction.close());
        })
        .open(player);
}

// Use it:
openNameDialog(player, name -> {
    savePlayerName(player, name);
});
```

--------------------------------

### Packet Sending Version Differences

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/07-architecture-and-internals.md

Comparison of NMS packet sending syntax between different Minecraft version wrappers.

```text
Wrapper1_20_R1:
  toNMS(player).c.a(new PacketPlayOutOpenWindow(...))

Wrapper1_21_R7:
  toNMS(player).connection.send(new PacketPlayOutOpenWindow(...))
```

--------------------------------

### Set Initial Text

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/01-anvilgui-class.md

Defines the text displayed in the rename field.

```java
public Builder text(String text)
```

--------------------------------

### Verify CraftBukkit Package

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/03-version-matcher.md

Programmatically retrieve and print the CraftBukkit package name for debugging.

```java
String pkg = Bukkit.getServer().getClass().getPackage().getName();
System.out.println("CraftBukkit package: " + pkg);
```

--------------------------------

### Define Version Wrapper Naming Convention

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/02-version-wrapper.md

The naming pattern for version-specific wrapper classes.

```text
net.wesjd.anvilgui.version.Wrapper<VERSION>
```

--------------------------------

### Builder Validation Errors

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/00-API-reference-index.md

Exceptions thrown when required parameters are missing during builder initialization.

```text
Plugin cannot be null
click handler cannot be null
Player cannot be null
```

--------------------------------

### Accessing State

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/README.md

Retrieves information from the GUI snapshot during interaction events.

```java
snapshot.getText()        // The text player entered
snapshot.getPlayer()      // The player
snapshot.getLeftItem()    // Item in slot 0
snapshot.getRightItem()   // Item in slot 1
snapshot.getOutputItem()  // Item in slot 2
```

--------------------------------

### Execute Custom Runnable

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/04-types-and-enums.md

Executes arbitrary code on the main server thread.

```java
return Arrays.asList(
    ResponseAction.run(() -> {
        snapshot.getPlayer().sendMessage("You entered: " + snapshot.getText());
    }),
    ResponseAction.close()
);
```

--------------------------------

### Create literal chat component

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/02-version-wrapper.md

Generates a chat component from plain text. Use this for simple titles without formatting.

```java
Object literalChatComponent(String content)
```

```java
Object titleComponent = wrapper.literalChatComponent("Rename Item");
```

```text
Returns: IChatBaseComponent.b(content)
```

--------------------------------

### Handle inventory clicks

Source: https://github.com/wesjd/anvilgui/blob/master/USAGE.md

Defines logic for slot interactions and returns a list of response actions to perform.

```java
builder.onClick((slot, stateSnapshot) -> {
    if (slot != AnvilGUI.Slot.OUTPUT) {
        return Collections.emptyList();
    }

    if (stateSnapshot.getText().equalsIgnoreCase("you")) {
        stateSnapshot.getPlayer().sendMessage("You have magical powers!");
        return Arrays.asList(
            AnvilGUI.ResponseAction.close(),
            AnvilGUI.ResponseAction.run(() -> myCode(stateSnapshot.getPlayer()))
        );
    } else {
        return Arrays.asList(AnvilGUI.ResponseAction.replaceInputText("Try again"));
    }
});
```

--------------------------------

### onClose(Consumer<StateSnapshot> closeListener)

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/05-configuration-options.md

Sets a listener that is invoked when the GUI is closed.

```APIDOC
## Builder onClose(Consumer<StateSnapshot>)

### Description
Sets a listener called when the GUI closes.

### Parameters
- **closeListener** (Consumer<StateSnapshot>) - Optional - The listener to execute upon closure.

### Example
```java
builder.onClose(snapshot -> {
    snapshot.getPlayer().sendMessage("You closed the anvil!");
});
```
```

--------------------------------

### Create new anvil container

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/02-version-wrapper.md

Instantiates a server-side AnvilContainerWrapper for a player with a specified title.

```java
AnvilContainerWrapper newContainerAnvil(Player player, Object title)
```

--------------------------------

### Determine Version String for Modern and Legacy Servers

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/03-version-matcher.md

Logic to extract the version string based on the presence of the '.v' segment in the package name.

```java
if (!craftBukkitPackage.contains(".v")) {
    final String version = Bukkit.getBukkitVersion().split("-")[0];
    rVersion = VERSION_TO_REVISION.getOrDefault(version, FALLBACK_REVISION);
}
```

```java
else {
    rVersion = craftBukkitPackage.split("\\.")[3].substring(1);
}
```

--------------------------------

### Define AnvilGUI Builder Class

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/01-anvilgui-class.md

The base class signature for the fluent builder.

```java
public static class AnvilGUI.Builder
```

--------------------------------

### Send Open Window Packet

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/02-version-wrapper.md

Opens a new inventory window on the client side using a specific container ID and title.

```java
void sendPacketOpenWindow(Player player, int containerId, Object inventoryTitle)
```

--------------------------------

### Validate Builder Inputs

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/07-architecture-and-internals.md

Ensures required components are present before GUI creation in the open() method.

```java
Validate.notNull(plugin, "Plugin cannot be null");
Validate.notNull(clickHandler, "click handler cannot be null");
Validate.notNull(player, "Player cannot be null");
```

--------------------------------

### Set JSON Title

Source: https://github.com/wesjd/anvilgui/blob/master/USAGE.md

Sets the GUI title using JSON-serialized rich text components. Requires Minecraft 1.14 or higher.

```java
builder.jsonTitle("{\"text\":\"Enter your answer\",\"color\":\"green\"}")
```

--------------------------------

### Define a simple colored title

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/04-types-and-enums.md

Use this structure to set a basic text label with a specific color.

```json
{
  "text": "Enter your name",
  "color": "blue"
}
```

--------------------------------

### Define a title with a click event

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/04-types-and-enums.md

Attach interactive actions like opening a URL to a text element.

```json
{
  "text": "Click me!",
  "color": "blue",
  "underlined": true,
  "clickEvent": {
    "action": "open_url",
    "value": "https://example.com"
  }
}
```

--------------------------------

### Set Plugin Instance

Source: https://github.com/wesjd/anvilgui/blob/master/USAGE.md

Registers the plugin instance required for listener registration.

```java
builder.plugin(pluginInstance);
```

--------------------------------

### Set Output Item

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/01-anvilgui-class.md

Places an ItemStack in the output slot.

```java
public Builder itemOutput(ItemStack item)
```

--------------------------------

### ResponseAction

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/README.md

Actions that can be returned from click handlers to manipulate the GUI state.

```APIDOC
## ResponseAction

### Description
Static factory methods to define actions performed after a click event.

### Available Actions
- **close()**: Closes the GUI.
- **replaceInputText(String text)**: Updates the text in the rename field.
- **updateTitle(String title, boolean force)**: Updates the GUI title.
- **updateJsonTitle(String json, boolean force)**: Updates the GUI title using JSON format.
- **openInventory(Inventory inventory)**: Opens a different inventory.
- **run(Runnable runnable)**: Executes arbitrary code.
```

--------------------------------

### isCustomTitleSupported()

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/02-version-wrapper.md

Checks if the current Minecraft version supports custom anvil titles.

```APIDOC
### boolean isCustomTitleSupported()

Checks whether the current Minecraft version supports custom anvil titles.

#### Returns
- **boolean** - true if custom titles are supported, false otherwise
```

--------------------------------

### AnvilGUI Main Class Fields

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/07-architecture-and-internals.md

Core fields defining the state, configuration, and event handling components of the AnvilGUI instance.

```java
private static final VersionWrapper WRAPPER = new VersionMatcher().match();
private static final ItemStack AIR = new ItemStack(Material.AIR);
private final Plugin plugin;
private final Player player;
private final Executor mainThreadExecutor;
private final Object titleComponent;
private final ItemStack[] initialContents;
private final boolean preventClose;
private final boolean geyserCompatibility;
private final Set<Integer> interactableSlots;
private final Consumer<StateSnapshot> closeListener;
private final boolean concurrentClickHandlerExecution;
private final ClickHandler clickHandler;
private int containerId;
private Inventory inventory;
private final ListenUp listener = new ListenUp();
private boolean open;
private VersionWrapper.AnvilContainerWrapper container;
```

--------------------------------

### Update Maven Repository Configuration

Source: https://github.com/wesjd/anvilgui/blob/master/README.md

Replace the deprecated CodeMC snapshot repository with the new official repository URL.

```xml
<repository>
  <id>codemc-snapshots</id>
  <url>https://repo.codemc.io/repository/maven-snapshots/</url>
</repository>
```

```xml
<repository>
  <id>mvn-wesjd-net</id>
  <url>https://mvn.wesjd.net/</url>
</repository>
```

--------------------------------

### ResponseAction Method Signature

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/04-types-and-enums.md

The functional method signature that receives the GUI instance and the interacting player.

```java
void accept(AnvilGUI gui, Player player)
```

--------------------------------

### Set initial text

Source: https://github.com/wesjd/anvilgui/blob/master/USAGE.md

Sets the initial text displayed in the anvil renaming field.

```java
builder.text("What is the meaning of life?");
```

--------------------------------

### Implement Redemption Code System

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/06-usage-examples.md

Validates and redeems codes asynchronously, providing feedback via input text replacement or reward application.

```java
new AnvilGUI.Builder()
    .plugin(plugin)
    .text("ENTER-CODE-HERE")
    .title("Redeem Code")
    .onClickAsync((slot, snapshot) -> {
        return CompletableFuture.supplyAsync(() -> {
            if (slot != AnvilGUI.Slot.OUTPUT) {
                return Collections.emptyList();
            }
            
            String code = snapshot.getText().toUpperCase();
            
            // Check code validity
            if (!codeManager.isValidCode(code)) {
                return Arrays.asList(
                    ResponseAction.replaceInputText("Invalid code")
                );
            }
            
            // Check if already used
            if (codeManager.isUsed(code, snapshot.getPlayer().getUniqueId())) {
                return Arrays.asList(
                    ResponseAction.replaceInputText("Already redeemed")
                );
            }
            
            // Redeem the code
            Reward reward = codeManager.getReward(code);
            codeManager.markAsUsed(code, snapshot.getPlayer().getUniqueId());
            
            return Arrays.asList(
                ResponseAction.close(),
                ResponseAction.run(() -> {
                    applyReward(snapshot.getPlayer(), reward);
                    snapshot.getPlayer().sendMessage(
                        ChatColor.GREEN + "Reward: " + reward.getName()
                    );
                })
            );
        });
    })
    .open(player);
```

--------------------------------

### Handle Async Exceptions in AnvilGUI

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/06-usage-examples.md

Use CompletableFuture to execute blocking database calls and catch exceptions to provide user feedback or log errors.

```java
new AnvilGUI.Builder()
    .plugin(plugin)
    .text("Query database")
    .title("Database Lookup")
    .onClickAsync((slot, snapshot) -> {
        return CompletableFuture.supplyAsync(() -> {
            if (slot != AnvilGUI.Slot.OUTPUT) {
                return Collections.emptyList();
            }
            
            String query = snapshot.getText();
            
            try {
                Result result = database.executeQuery(query);
                
                if (result.isEmpty()) {
                    return Arrays.asList(
                        ResponseAction.replaceInputText("No results")
                    );
                }
                
                return Arrays.asList(
                    ResponseAction.close(),
                    ResponseAction.run(() -> {
                        displayResults(snapshot.getPlayer(), result);
                    })
                );
            } catch (DatabaseException e) {
                // Log the error, notify player
                plugin.getLogger().log(Level.SEVERE, "Query failed", e);
                
                return Arrays.asList(
                    ResponseAction.replaceInputText("Error occurred"),
                    ResponseAction.run(() -> {
                        snapshot.getPlayer().sendMessage(
                            ChatColor.RED + "Database error"
                        );
                    })
                );
            }
        });
    })
    .open(player);
```

--------------------------------

### text(String text)

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/01-anvilgui-class.md

Sets the initial text displayed in the anvil's rename field.

```APIDOC
### Method
`public Builder text(String text)`

### Parameters
- **text** (String) - Required - The initial text to display.
```

--------------------------------

### Define a bold green title

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/04-types-and-enums.md

Apply bold formatting and color to a title string.

```json
{
  "text": "Rename Item",
  "color": "green",
  "bold": true
}
```

--------------------------------

### ResponseAction UpdateJsonTitle Method

Source: https://github.com/wesjd/anvilgui/blob/master/_autodocs/01-anvilgui-class.md

Creates an action to update the GUI title using JSON-formatted rich text.

```java
static ResponseAction updateJsonTitle(String json, boolean preserveRenameText)
```
Tokens:
Raw