# API Reference

# API Reference

Technical reference for plugin developers. Provides programmatic access to the Citizen and Dialog systems through the unified CoreAPI facade.

:::info Module
The CoreAPI is provided by the Core mod (`KyuubiSoftCore-2.9.9.jar`). Ensure the Core mod is loaded before calling any API methods.
:::

## Getting the API Instance

```java
import com.kyuubisoft.core.api.CoreAPI;

// Availability check (recommended)
if (CoreAPI.isAvailable()) {
    CoreAPI api = CoreAPI.getInstance();
    // ...
}

// Or direct (returns null if Core is not loaded)
CoreAPI api = CoreAPI.getInstance();
if (api == null) {
    // Core plugin not loaded
    return;
}
```

## Citizen Methods

| Method | Return Type | Description |
|--------|-------------|-------------|
| `getCitizen(String id)` | `CitizenData` | Get CitizenData by ID, or `null` if not found |
| `getAllCitizens()` | `Collection<CitizenData>` | Get all registered citizens (never `null`) |
| `getCitizensByGroup(String group)` | `List<CitizenData>` | Get citizens matching a group (never `null`) |
| `addCitizenListener(CitizenListener)` | `void` | Add a citizen lifecycle listener |
| `removeCitizenListener(CitizenListener)` | `void` | Remove a citizen lifecycle listener |
| `addDialogInterceptor(CitizenDialogInterceptor)` | `void` | Add a dialog interceptor (checked before default dialogs) |
| `removeDialogInterceptor(CitizenDialogInterceptor)` | `void` | Remove a dialog interceptor |
| `dispatchCitizenInteract(Player, String citizenId)` | `void` | Trigger a citizen interaction event programmatically |
| `pauseCitizenMovement(CitizenData, Player)` | `void` | Pause NPC movement (e.g., during dialog) |
| `resumeCitizenMovement(String citizenId)` | `void` | Resume NPC movement after interaction |
| `isCitizenPaused(String citizenId)` | `boolean` | Check if an NPC is currently paused |

## Dialog Methods

| Method | Return Type | Description |
|--------|-------------|-------------|
| `openDialog(Player, PlayerRef, Ref, Store, String dialogId, String citizenId)` | `void` | Open a dialog by its ID |
| `openDialogFromTree(Player, PlayerRef, Ref, Store, DialogTree, String citizenId)` | `void` | Open a dialog from a pre-built DialogTree object |
| `addDialogConditionProvider(DialogConditionProvider)` | `void` | Register a custom condition provider for dialog branching |
| `removeDialogConditionProvider(DialogConditionProvider)` | `void` | Remove a condition provider |

## Interfaces

### CitizenListener

Implement this interface to receive citizen lifecycle events. All methods have default no-op implementations, so you only need to override what you need.

```java
import com.kyuubisoft.core.citizen.CitizenListener;

public interface CitizenListener {
    /** Player interacts with an NPC (before dialog opens) */
    default void onCitizenInteract(Player player, String citizenId) {}

    /** Player selects a dialog choice */
    default void onDialogChoice(Player player, String dialogId, int choiceIndex, String choiceText) {}

    /** Dialog chain is fully completed */
    default void onDialogComplete(Player player, String dialogId) {}

    /** Player enters text input during a dialog */
    default void onDialogInput(Player player, String dialogId, String input) {}
}
```

### CitizenDialogInterceptor

Implement this interface to intercept NPC interactions before the default dialog system runs. If your interceptor returns `true`, no further dialog processing occurs.

```java
import com.kyuubisoft.core.citizen.CitizenDialogInterceptor;

public interface CitizenDialogInterceptor {
    /**
     * Attempt to intercept the dialog for a citizen.
     *
     * @return true if this interceptor handled the interaction (no further dialog will open)
     */
    boolean interceptDialog(Player player, PlayerRef playerRef,
                            Ref<EntityStore> ref, Store<EntityStore> store,
                            String citizenId);
}
```

### DialogConditionProvider

Implement this interface to provide custom conditions for dialog branching. Used by the Quest mod, Achievement mod, and others to enable conditional dialog flows.

```java
import com.kyuubisoft.core.dialog.DialogConditionProvider;

public interface DialogConditionProvider {
    /** Whether this provider handles the given condition type. */
    boolean handles(String conditionType);

    /** Evaluate the condition for a player. */
    boolean evaluate(Player player, String conditionType, String value, boolean negate);
}
```

## Usage Examples

### Get Citizen Data

```java
CoreAPI api = CoreAPI.getInstance();

CitizenData citizen = api.getCitizen("blacksmith_npc");
if (citizen != null) {
    String name = citizen.getDisplayName();
    boolean hasShop = citizen.shopId != null;
    LOGGER.info("Citizen: " + name + ", shop: " + hasShop);
}

// Get all citizens in a group
List<CitizenData> guards = api.getCitizensByGroup("town_guards");
LOGGER.info("Found " + guards.size() + " town guards");
```

### React to Citizen Interactions (Interceptor)

```java
CoreAPI api = CoreAPI.getInstance();

api.addDialogInterceptor((player, playerRef, ref, store, citizenId) -> {
    if ("quest_giver".equals(citizenId)) {
        // Open custom quest UI instead of default dialog
        openQuestUI(player, playerRef, ref, store);
        return true; // Intercepted — no default dialog
    }
    return false; // Let default dialog system handle it
});
```

### Open a Dialog Programmatically

```java
CoreAPI api = CoreAPI.getInstance();

// Open a specific dialog for a citizen
// (typically called from within a command or event handler that has access to PlayerRef/Ref/Store)
api.openDialog(player, playerRef, ref, store, "greeting_dialog", "merchant_npc");
```

### Pause and Resume NPC Movement

```java
CoreAPI api = CoreAPI.getInstance();

CitizenData npc = api.getCitizen("patrol_guard");
if (npc != null && !api.isCitizenPaused("patrol_guard")) {
    // Pause the NPC while player interacts
    api.pauseCitizenMovement(npc, player);

    // ... do interaction ...

    // Resume movement when done
    api.resumeCitizenMovement("patrol_guard");
}
```

### Register a Dialog Condition Provider

```java
CoreAPI api = CoreAPI.getInstance();

api.addDialogConditionProvider(new DialogConditionProvider() {
    @Override
    public boolean handles(String type) {
        return "quest_active".equals(type) || "quest_completed".equals(type);
    }

    @Override
    public boolean evaluate(Player player, String type, String value, boolean negate) {
        boolean result = switch (type) {
            case "quest_active" -> questService.isQuestActive(player, value);
            case "quest_completed" -> questService.isQuestCompleted(player, value);
            default -> false;
        };
        return negate ? !result : result;
    }
});
```

## Thread Safety

- The API uses `CopyOnWriteArrayList` for all listener and interceptor lists (thread-safe registration/removal)
- All query methods (`getCitizen`, `getAllCitizens`, `getCitizensByGroup`, `isCitizenPaused`) can be called from any thread
- `pauseCitizenMovement` and `resumeCitizenMovement` involve entity operations and should be called within `world.execute()` when possible
- Dialog opening methods (`openDialog`, `openDialogFromTree`) involve UI operations and should be called from the main thread or within `world.execute()`

## Java Package Structure

```
com.kyuubisoft.core.citizen/
├── CitizenData.java                - NPC data model
├── CitizenService.java             - Citizen lifecycle management
├── CitizenListener.java            - Lifecycle event interface
├── CitizenDialogInterceptor.java   - Dialog intercept interface

com.kyuubisoft.core.dialog/
├── DialogService.java              - Dialog management
├── DialogTree.java                 - Dialog tree model
├── DialogNode.java                 - Dialog node model
├── DialogConditionProvider.java    - Condition provider interface
```