### Retrieve FasterCrystals API Instance

Source: https://context7.com/mcpvp-club/fastercrystals/llms.txt

Use `getInstance()` to get the API. Always guard calls with `isAvailable()` to ensure the plugin is loaded.

```java
import xyz.reknown.fastercrystals.api.FasterCrystalsAPI;
import org.bukkit.entity.Player;

public class MyPlugin extends JavaPlugin {

    public void checkCrystalState(Player player) {
        // Guard: only proceed if FasterCrystals is loaded and enabled
        if (!FasterCrystalsAPI.isAvailable()) {
            getLogger().warning("FasterCrystals API is not available.");
            return;
        }

        FasterCrystalsAPI api = FasterCrystalsAPI.getInstance();
        boolean enabled = api.isFastCrystalsEnabled(player);
        // Output: "Steve has FasterCrystals: true"
        getLogger().info(player.getName() + " has FasterCrystals: " + enabled);
    }
}
```

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

### config.yml Default Settings

Source: https://context7.com/mcpvp-club/fastercrystals/llms.txt

Configure the default toggle state for new players and customize the feedback text using MiniMessage formatting in config.yml.

```yaml
# config.yml (default)

# Whether FasterCrystals is enabled by default for players who have never toggled it
default-state: true

# MiniMessage strings shown as the <state> placeholder in the text below
state:
  'on':  '<yellow>on</yellow>'
  'off': '<yellow>off</yellow>'

# MiniMessage text sent to the player after toggling
text: '<gold>Turned</gold> <state> <gold>your FasterCrystals setting.</gold>'
```

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

### FasterCrystalsAPI.getInstance()

Source: https://context7.com/mcpvp-club/fastercrystals/llms.txt

Retrieves the singleton API instance for FasterCrystals. It's recommended to guard calls with isAvailable() to ensure the plugin is loaded.

```APIDOC
## FasterCrystalsAPI.getInstance()

### Description
Retrieves the singleton API instance for FasterCrystals. Throws IllegalStateException if called before FasterCrystals has been enabled. Always guard with isAvailable() when calling from an external plugin.

### Method
`static FasterCrystalsAPI getInstance()`

### Parameters
None

### Returns
`FasterCrystalsAPI` - The singleton API instance.

### Throws
`IllegalStateException` - If called before FasterCrystals has been enabled.

### Example
```java
import xyz.reknown.fastercrystals.api.FasterCrystalsAPI;

if (FasterCrystalsAPI.isAvailable()) {
    FasterCrystalsAPI api = FasterCrystalsAPI.getInstance();
    // Use the API
}
```
```

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

### /fastercrystals command

Source: https://context7.com/mcpvp-club/fastercrystals/llms.txt

The in-game command that allows players to toggle their FasterCrystals setting. Supports forcing states on/off and reloading configuration.

```APIDOC
## /fastercrystals command

### Description
Allows players to toggle their own FasterCrystals setting. Supports forcing states on/off and reloading configuration. Requires the `fastercrystals.reload` permission for the `reload` subcommand.

### Usage
- `/fastercrystals` - Toggles the player's current FasterCrystals state.
- `/fastercrystals on` - Forces FasterCrystals to be enabled for the player.
- `/fastercrystals off` - Forces FasterCrystals to be disabled for the player.
- `/fastercrystals reload` - Reloads the `config.yml` file (requires `fastercrystals.reload` permission).

### Permissions
- `fastercrystals.use` - Allows players to use the `/fastercrystals` command to toggle their own state.
- `fastercrystals.reload` - Allows players to use the `/fastercrystals reload` subcommand.

### Example
```
/fastercrystals
/fastercrystals on
/fastercrystals off
/fastercrystals reload
```
```

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

### FasterCrystals Commands

Source: https://context7.com/mcpvp-club/fastercrystals/llms.txt

Commands to control the FasterCrystals plugin. Use these in-game to toggle, force states, or reload the configuration.

```plaintext
/fastercrystals
/fastercrystals on
/fastercrystals true
/fastercrystals off
/fastercrystals false
/fastercrystals reload
```

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

### PlaceholderAPI Placeholder for Crystal State

Source: https://context7.com/mcpvp-club/fastercrystals/llms.txt

Integrate the %fastercrystals_toggle% placeholder into plugins like TAB or CMI to display the player's current FasterCrystals state.

```yaml
tablist:
  header: "&6FasterCrystals: &e%fastercrystals_toggle%"
scoreboard:
  lines:
    - "&7Crystals: &f%fastercrystals_toggle%"
```

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

### Programmatic Placeholder Resolution

Source: https://context7.com/mcpvp-club/fastercrystals/llms.txt

Resolve the %fastercrystals_toggle% placeholder programmatically within other plugins using PlaceholderAPI.

```java
// Programmatic resolution (e.g. in another plugin)
String value = PlaceholderAPI.setPlaceholders(player, "%fastercrystals_toggle%");
// value → "On"  or  "Off"
```

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

### Reload Configuration

Source: https://context7.com/mcpvp-club/fastercrystals/llms.txt

Reload the FasterCrystals configuration at runtime without requiring a server restart.

```plaintext
/fastercrystals reload
```

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

### FasterCrystalsAPI.isFastCrystalsEnabled(Player)

Source: https://context7.com/mcpvp-club/fastercrystals/llms.txt

Checks if FasterCrystals is currently active for a given player. Falls back to the server's default-state configuration if no player-specific preference is saved.

```APIDOC
## FasterCrystalsAPI.isFastCrystalsEnabled(Player)

### Description
Checks if FasterCrystals is currently active for the given player. Falls back to the server's `default-state` config value (default: `true`) when no player-specific preference has been saved yet.

### Method
`boolean isFastCrystalsEnabled(Player player)`

### Parameters
- **player** (Player) - The player to check the state for.

### Returns
`boolean` - `true` if FasterCrystals is enabled for the player, `false` otherwise.

### Example
```java
FasterCrystalsAPI api = FasterCrystalsAPI.getInstance();
Player player = Bukkit.getPlayer("Steve");

if (player != null) {
    boolean active = api.isFastCrystalsEnabled(player);
    // Use the active status
}
```
```

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

### FasterCrystalsAPI.setFastCrystals(Player, boolean)

Source: https://context7.com/mcpvp-club/fastercrystals/llms.txt

Sets the per-player toggle state for FasterCrystals, persisting the setting across server restarts.

```APIDOC
## FasterCrystalsAPI.setFastCrystals(Player, boolean)

### Description
Sets the enabled/disabled flag directly to the player's `PersistentDataContainer`. This setting persists across sessions and server restarts.

### Method
`void setFastCrystals(Player player, boolean enabled)`

### Parameters
- **player** (Player) - The player whose state is being set.
- **enabled** (boolean) - `true` to enable FasterCrystals, `false` to disable.

### Returns
None

### Example
```java
FasterCrystalsAPI api = FasterCrystalsAPI.getInstance();
Player player = Bukkit.getPlayer("Steve");

if (player != null) {
    // Disable FasterCrystals for this player
    api.setFastCrystals(player, false);
    // Enable FasterCrystals for this player
    api.setFastCrystals(player, true);
}
```
```

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

### FasterCrystalsAPI.toggleFastCrystals(Player)

Source: https://context7.com/mcpvp-club/fastercrystals/llms.txt

Toggles the current FasterCrystals state for a player, switching between enabled and disabled.

```APIDOC
## FasterCrystalsAPI.toggleFastCrystals(Player)

### Description
Flips the player's current FasterCrystals state: if enabled it disables, if disabled it enables. This is identical to what the in-game `/fastercrystals` command does when called with no arguments.

### Method
`void toggleFastCrystals(Player player)`

### Parameters
- **player** (Player) - The player whose state is to be toggled.

### Returns
None

### Example
```java
FasterCrystalsAPI api = FasterCrystalsAPI.getInstance();
Player player = Bukkit.getPlayer("Steve");

if (player != null) {
    api.toggleFastCrystals(player);
}
```
```

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

### Programmatic Crystal Spawning

Source: https://context7.com/mcpvp-club/fastercrystals/llms.txt

Internal method for safe End Crystal placement, including block validation and item consumption. Invoked by InteractEntityListener.

```java
// Internal usage within InteractEntityListener (packet-driven crystal placement)
FoliaScheduler.getRegionScheduler().run(plugin, eyeLoc, task -> {
    // Validate ray-trace against obsidian/bedrock beneath the targeted crystal
    RayTraceResult result = eyeLoc.getWorld().rayTraceBlocks(
            eyeLoc, direction, blockInteractionRange.getValue());
    if (result == null || result.getHitBlock() == null) return;
    if (!ALLOWED_BLOCKS.contains(result.getHitBlock().getType())) return;

    // Spawn crystal at the entity's location with item consumption
    plugin.spawnCrystal(entity.getLocation(), player, item);
    // → Spawns an EnderCrystal with setShowingBottom(false),
    //   deducts 1 End Crystal from player's hand (non-creative/spectator)
});
```

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

### Toggle Per-Player FasterCrystals State

Source: https://context7.com/mcpvp-club/fastercrystals/llms.txt

Flips the current FasterCrystals state for a player, mirroring the behavior of the in-game command without arguments.

```java
FasterCrystalsAPI api = FasterCrystalsAPI.getInstance();
Player player = Bukkit.getPlayer("Steve");

if (player != null) {
    boolean before = api.isFastCrystalsEnabled(player); // e.g. true
    api.toggleFastCrystals(player);
    boolean after = api.isFastCrystalsEnabled(player);  // now false
    player.sendMessage("Toggled! Was: " + before + " → Now: " + after);
}
```

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

### Check Per-Player FasterCrystals State

Source: https://context7.com/mcpvp-club/fastercrystals/llms.txt

Checks if FasterCrystals is active for a player. Falls back to the server's default if no player preference is saved.

```java
FasterCrystalsAPI api = FasterCrystalsAPI.getInstance();
Player player = Bukkit.getPlayer("Steve");

if (player != null) {
    boolean active = api.isFastCrystalsEnabled(player);
    player.sendMessage("Your FasterCrystals status: " + (active ? "ON" : "OFF"));
    // Expected message to player: "Your FasterCrystals status: ON"
}
```

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

### Packet-Level Crystal Destruction

Source: https://context7.com/mcpvp-club/fastercrystals/llms.txt

Handles immediate server-side player.attack(entity) on End Crystals triggered by ANIMATION packets, with checks for attack modifiers and recent spawns.

```java
// Illustrative flow inside AnimationListener.onPacketPlayReceive()
if (event.getPacketType() != PacketType.Play.Client.ANIMATION) return;
if (isAttackDamageReduced(player)) return; // Weakness > Strength → skip

// Ray-trace for an End Crystal in entity interaction range
RayTraceResult result = eyeLoc.getWorld().rayTraceEntities(
        eyeLoc, direction, entityInteractionRange.getValue(), 0.0,
        entity -> entity.getType() == EntityType.END_CRYSTAL /* simplified */);

if (result != null && result.getHitEntity() != null) {
    // Guard: skip crystals spawned this tick to prevent double-pop
    if (result.getHitEntity().getTicksLived() == 0) return;
    player.attack(result.getHitEntity()); // → crystal explodes immediately
}
```

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

### Set Per-Player FasterCrystals State

Source: https://context7.com/mcpvp-club/fastercrystals/llms.txt

Persistently enables or disables FasterCrystals for a specific player by writing to their PersistentDataContainer.

```java
FasterCrystalsAPI api = FasterCrystalsAPI.getInstance();
Player player = Bukkit.getPlayer("Steve");

if (player != null) {
    // Force-disable FasterCrystals for this player (e.g., during a tournament mode)
    api.setFastCrystals(player, false);
    player.sendMessage("FasterCrystals has been disabled for you.");

    // Force-enable it again later
    api.setFastCrystals(player, true);
    player.sendMessage("FasterCrystals has been re-enabled for you.");
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.