> ## Documentation Index
> Fetch the complete documentation index at: https://docs.humalike.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Provider API

> Reference for server and client provider registration exports.

The current provider API version is `1`. Provider names must be lowercase, at
most 64 characters, and contain only letters, digits, `_`, `.`, or `-`.
Priorities must be finite numbers between `-100000` and `100000`.

## Register a server provider

```lua theme={null}
local ok, errorMessage = exports.humalike:RegisterProvider(domain, descriptor)
```

`domain` is `player`, `inventory`, `dispatch`, or `actions`. Registration must
come from an external resource. It returns `true` on success or `false` plus a
stable, human-readable reason when the descriptor is rejected.

Every descriptor requires:

| Field        | Type               | Description                                                                   |
| ------------ | ------------------ | ----------------------------------------------------------------------------- |
| `name`       | string             | Provider name used by its selection convar.                                   |
| `apiVersion` | number             | Must be `1`.                                                                  |
| `priority`   | number             | Higher available priority wins in `auto`.                                     |
| `Available`  | function, optional | Return `true` when dependencies are ready; optionally return `false, reason`. |

### Player descriptor

| Callback                             | Required | Contract                                                                         |
| ------------------------------------ | -------- | -------------------------------------------------------------------------------- |
| `GetCharacterId(source)`             | Yes      | Return a stable active-character id or `nil`.                                    |
| `GetCharacterName(source)`           | Yes      | Return the active character's display name or `nil`.                             |
| `IsCharacterLoaded(source)`          | Yes      | Return exactly `true` when gameplay state is ready.                              |
| `HasJob(source, names, requireDuty)` | No       | Return exactly `true` when one requested job matches and duty requirements pass. |
| `Notify(source, message, kind)`      | No       | Display a notification to the player.                                            |

`kind` may be `success`, `error`, `warning`, or `inform`. Treat unknown kinds as
informational.

### Inventory descriptor

```lua theme={null}
exports.humalike:RegisterProvider('inventory', {
    name = 'my_inventory',
    apiVersion = 1,
    priority = 100,
    AddItem = function(source, itemName, quantity, metadata)
        return true
    end,
})
```

`AddItem` must return exactly `true` after accepting the operation. Return
`false` for a full inventory, unknown item, invalid metadata, or any other
rejection.

### Dispatch descriptor

```lua theme={null}
exports.humalike:RegisterProvider('dispatch', {
    name = 'my_dispatch',
    apiVersion = 1,
    priority = 100,
    Report = function(kind, payload)
        return true
    end,
})
```

Translate the neutral `kind` and `payload` into your dispatch resource. Return
`false` only when the report was rejected; `nil` counts as accepted after a
successful callback.

### Action descriptor

```lua theme={null}
exports.humalike:RegisterProvider('actions', {
    name = 'my_actions',
    apiVersion = 1,
    priority = 100,
    SupportedActions = { 'hand_over_money' },
    RunAction = function(action, source, npcCoords, params)
        return true
    end,
})
```

Action keys must start with a lowercase letter, contain only lowercase letters,
digits, and `_`, and be at most 64 characters. `RunAction` must return exactly
`true` after completing or accepting the action.

Validate `source`, distance from `npcCoords`, permissions, identifiers, amounts,
and all `params` on the server. The action name is not authorization.

## Unregister a server provider

```lua theme={null}
local ok, errorMessage = exports.humalike:UnregisterProvider(domain, name)
```

Only the owner resource can unregister its provider. Stopping the owner performs
this cleanup automatically.

## Server status

```lua theme={null}
local status = exports.humalike:GetProviderStatus()
```

The result contains:

* `apiVersion` and `runtimeEpoch`;
* `selected`, a compact map by domain;
* `domains`, including each setting, state, reason, selected provider, and all
  registered candidates.

States are `selected`, `disabled`, `unavailable`, `ambiguous`, or `degraded`.
A callback failure degrades the selected provider; a later successful callback
clears the failure state.

## Register a client interaction provider

```lua theme={null}
local ok, errorMessage = exports.humalike:RegisterInteractionProvider({
    name = 'my_target',
    apiVersion = 1,
    priority = 100,
    Available = function() return true end,
    watchedResources = { 'my-target' },
    Add = function(id, entity, options) return true end,
    Remove = function(id) end,
    Progress = function(durationMs, label) return true end,
})
```

`Add` and `Remove` are required. `Progress` is optional. `Add` must return
exactly `true` when registration succeeds. `Progress` returns exactly `true`
when completed and `false` when cancelled or failed.

`watchedResources` lists dependencies whose start/stop should trigger provider
reevaluation.

```lua theme={null}
exports.humalike:UnregisterInteractionProvider('my_target')
local status = exports.humalike:GetInteractionProviderStatus()
```

Client status reports `apiVersion`, `runtimeEpoch`, setting, state, reason, and
the selected provider.

## Ready event

```lua theme={null}
AddEventHandler('humalike:integration:ready', function(info)
    print(info.apiVersion, info.runtimeEpoch)
end)
```

The event is local and emitted independently on server and client after each
HumaLike start. Register the providers for that side again when it fires.

## Next

* [Implement the complete bridge example](/ai-npc/integrations/custom-bridge).
* [Report player events](/ai-npc/integrations/world-events).
* [Review the compact public reference](/ai-npc/reference).