---
title: "Category config"
description: "Keys for overrideCategoryConfig and runtime selection overrides."
canonical: "https://developers.fnlb.net/docs/sdk/category-config"
markdown: "/docs/sdk/category-config.md"
---

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

# Category config

---
title: "Category config"
sidebarTitle: "Category config"
description: "Every key accepted by overrideCategoryConfig and by addCategories, addBots, and setBots."
icon: "sliders"
---

`overrideCategoryConfig` on [`start()`](/docs/self-hosting/sdk-node.md#override-category-settings-at-start) replaces category settings for that run. The same keys are accepted as the optional overrides argument on `addCategories`, `addBots`, and `setBots`.

```ts
overrideCategoryConfig?: {
  all?: Partial<ICategoryConfig>;
  categories?: Record<string, Partial<ICategoryConfig>>;
  bots?: Record<string, Partial<ICategoryConfig>>;
}
```

Only set the keys you want to override. Unspecified keys keep the config pulled from FNLB, and defaults fill any gaps after that.

**Merge order (later wins):** pulled config, then `all`, then `categories[categoryId]`, then `bots[botId]`.

Types and enums come from `@fnlb-project/shared/types`: `ICategoryConfig`, `CategoryConfigPartyPrivacy`, `CategoryConfigStatusType`, and the trigger types below. The `start()` option itself is [`StartConfig.overrideCategoryConfig`](/sdk?symbol=StartConfig).

`CategoryConfigPartyPrivacy` is numeric: `0` public, `1` private. That is the dashboard enum. Live party privacy after the bot is in a lobby uses [`PartyPrivacy`](/sdk?symbol=PartyPrivacy) on `bot.party.setPrivacy`, documented in [Bots and parties](/docs/sdk/parties.md#lobby-controls). One sets the saved config. The other patches the party the bot is in right now.

```ts
import FNLB from 'fnlb';
import { CategoryConfigPartyPrivacy, CategoryConfigStatusType } from '@fnlb-project/shared/types';

const fnlb = new FNLB();

await fnlb.start({
  token: 'FNLB_...',
  categories: ['category-id'],
  overrideCategoryConfig: {
    all: {
      acceptFriendRequests: false,
      privacy: CategoryConfigPartyPrivacy.Private,
      statusType: CategoryConfigStatusType.Online,
      statusText: ['Lobby bot']
    },
    bots: {
      'bot-id': {
        startOutfit: [{ id: 'CID_028_Athena_Commando_F' }]
      }
    }
  }
});
```

The same object can be passed as the second argument to `addCategories`, `addBots`, or `setBots` after `start()`. Those methods are covered on the [Node.js SDK](/docs/self-hosting/sdk-node.md#update-your-selection-without-restarting) page. Overrides stored that way are removed when `removeCategories` or `removeBots` drops the id, or when `setCategories` or `setBots` replaces the list without that id.

## General

| Key | Type | Description |
| :--- | :--- | :--- |
| `searchLangs` | `APILocales[]` | Languages used when searching cosmetics. |
| `platform` | `('WIN' \| 'MAC' \| 'PSN' \| 'XBL' \| 'SWT' \| 'SWT2' \| 'IOS' \| 'AND' \| 'PS5' \| 'XSX')[]` | Platform icon or icons. |
| `privacy` | `CategoryConfigPartyPrivacy` (`0` Public, `1` Private) | Default party privacy. |
| `prefixes` | `string[]` | Command prefixes. |
| `statusType` | `CategoryConfigStatusType` (`0` Auto, `1` Online, `2` Away) | Online presence mode. |
| `statusText` | `string[]` | Rotating status messages. |
| `statusInterval` | `number` | Status rotation interval, in seconds. |
| `level` | `number[]` | Cosmetic account level options. |
| `bpLevel` | `number[]` | Cosmetic battle pass level options. |

## User management

User entries are `{ id?: string; name?: string }`.

| Key | Type | Description |
| :--- | :--- | :--- |
| `extraOwners` | `ICategoryConfigUser[]` | Extra users with full command access. |
| `admins` | `ICategoryConfigUser[]` | Admin users. |
| `whitelistUsers` | `ICategoryConfigUser[]` | Whitelisted users. |
| `blacklistUsers` | `ICategoryConfigUser[]` | Blacklisted or banned users. |
| `excludedAutoAddFriends` | `ICategoryConfigUser[]` | Users the bot will not auto-add as friends. |
| `otherBots` | `ICategoryConfigUser[]` | Foreign bots to ignore. |

## Limits and behavior

| Key | Type | Description |
| :--- | :--- | :--- |
| `inviteTimeout` | `number` | Re-invite cooldown, in seconds. |
| `maxBotsPerLobby` | `number` | Max bots per party. |
| `maxBotsPerLobbyWithOwner` | `number` | Max bots when an owner is present. |
| `maxBotsPerLobbyWithAdmin` | `number` | Max bots when an admin is present. |
| `maxBotsPerLobbyWithWhitelistUser` | `number` | Max bots when a whitelisted user is present. |
| `allowMatchmaking` | `boolean` | Allow matchmaking. |
| `leaveAfterMatchmaking` | `boolean` | Leave the party after matchmaking starts. |
| `disableMatchmakingChecks` | `boolean` | Disable matchmaking cooldown checks. |
| `disablePlaylistChecks` | `boolean` | Allow non-standard playlists. |
| `disableJoinMessages` | `boolean` | Disable join messages. |
| `disableAutomaticMessages` | `boolean` | Disable automatic messages. |
| `acceptFriendRequests` | `boolean` | Auto-accept friend requests. |
| `sendFriendRequestOnJoinParty` | `boolean` | Friend party members when the bot joins. |
| `sendFriendRequestOnMemberJoinParty` | `boolean` | Friend members when they join. |
| `runCommandsWithoutPrefix` | `boolean` | Allow commands without a prefix. |
| `setCosmeticsWithoutCommands` | `boolean` | Set cosmetics by typing the name in party chat. |
| `setCosmeticsWithPrefix` | `boolean` | Set cosmetics with a prefix, such as `!floss`. |
| `acceptInvites` | `boolean` | Auto-accept party invites and join requests. |
| `startBannedBots` | `boolean` | Start bots even if they are matchmaking-banned. |

## Triggers

| Key | Type | Description |
| :--- | :--- | :--- |
| `triggers` | `ICategoryConfigTrigger[]` | Event, custom-command, or scheduled trigger trees. |

Each trigger has a name, optional flags, and an `actions` tree. Actions can run commands, call functions, or use control-flow statements.

- **Event** fires on a `CategoryConfigTriggerEventType`, such as a party member joining.
- **Custom command** fires when a custom command string is used.
- **Scheduled** fires on a cron-style `interval`.

## Command restrictions

Values are command name arrays.

| Key | Type | Description |
| :--- | :--- | :--- |
| `onlyOwnerCommands` | `string[]` | Owner-only commands. |
| `onlyAdminCommands` | `string[]` | Admin and owner commands. |
| `onlyWhitelistUsersCommands` | `string[]` | Whitelist, admin, and owner commands. |
| `onlyFriendsCommands` | `string[]` | Friends-only commands. |
| `onlyPartyMembersCommands` | `string[]` | Party-member-only commands. |
| `onlyWhisperCommands` | `string[]` | Whisper and DM commands. |

## Cosmetics

Outfit, backpack, pickaxe, shoes, and sidekick slots use `{ id?: string; variants?: number[] }[]`. Banner and banner color slots use `{ id?: string }[]`. Emote slots (`joinEmote`, `memberJoinEmote`) accept emotes, emojis, or jam tracks. Backpack slots accept backpacks or pet carriers.

| Key | When it applies |
| :--- | :--- |
| `startOutfit`, `startBackpack`, `startPickaxe`, `startShoes`, `startSidekick`, `startBanner`, `startBannerColor` | Bot start. |
| `joinOutfit`, `joinBackpack`, `joinPickaxe`, `joinEmote`, `joinShoes`, `joinSidekick`, `joinBanner`, `joinBannerColor` | Bot joins a party. |
| `memberJoinOutfit`, `memberJoinBackpack`, `memberJoinPickaxe`, `memberJoinEmote`, `memberJoinShoes`, `memberJoinSidekick`, `memberJoinBanner`, `memberJoinBannerColor` | Another member joins the party. |

Changing a cosmetic on a bot that is already in a party is `party.setOutfit` and the other member methods, not these lists. See [Bots and parties](/docs/sdk/parties.md#lobby-controls).

## Related

| Topic | Where |
| :--- | :--- |
| Apply overrides at `start()` | [Node.js SDK](/docs/self-hosting/sdk-node.md#override-category-settings-at-start) |
| Change the include list while shards are running | [Node.js SDK](/docs/self-hosting/sdk-node.md#update-your-selection-without-restarting) |
| Option type | [`StartConfig`](/sdk?symbol=StartConfig) |
| Live party privacy and cosmetics | [Bots and parties](/docs/sdk/parties.md) |