Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Channels Config

The channels.conf file configures the in-game channel system and RagnaSync integration settings. This file is located in your rAthena server's conf/channels.conf.

RagnaSync Discord Integration

The discord block contains all RagnaSync-specific settings for connecting your Ragnarok server to Discord.

Connection Settings

Core settings for connecting to the RagnaSync service.

discord: {
    // RagnaSync Service Host
    ragnasync_host_name: "ragnasync.com"

    // Discord Server Settings
    ragnasync_discord_id: "123456789012345678"
    ragnasync_discord_guid: "a1b2c3d4e5f6789012345678abcdef00"

    // Ragnarok Server Client Settings
    ragnasync_client_guid: "f0e1d2c3b4a5678901234567fedcba99"

    // Connection Settings
    ragnasync_enabled: true
    ragnasync_retry_first: 300
    ragnasync_retry_delay: 1800
    ragnasync_retry_max: 3
}
Setting
Type
Default
Description

ragnasync_host_name

string

"ragnasync.com"

RagnaSync service hostname

ragnasync_discord_id

string

""

Discord server ID (17-19 digit snowflake)

ragnasync_discord_guid

string

""

Discord server security key (32 hex chars, issued with your ragnasync_discord_id)

ragnasync_client_guid

string

""

Ragnarok client security key (32 hex chars, from dashboard)

ragnasync_enabled

bool

true

Auto-connect when server starts

ragnasync_retry_first

int

300

First retry delay in seconds (5 minutes)

ragnasync_retry_delay

int

1800

Delay between subsequent retries (30 minutes)

ragnasync_retry_max

int

3

Maximum retry attempts (0 = unlimited)

The retry defaults decide how long your relay stays down.

If the connection drops — a network blip, or RagnaSync restarting for an update — your server waits ragnasync_retry_first seconds before its first reconnect attempt. At the default of 300 that is a full five minutes with no chat relay in either direction, even though the service is back within seconds.

If that first attempt misses, the next one is ragnasync_retry_delay away — another 30 minutes by default.

Lowering the first retry costs nothing and closes most of that gap:

Both values are read from this file when your server starts, so a restart of your Ragnarok server is all that is needed — no recompile. Avoid going below ~10 seconds: very aggressive retries add load without reconnecting meaningfully faster.

@Command Logging

Log GM commands to a Discord channel for moderation and audit purposes.

Setting
Type
Default
Description

ragnasync_at_command_log_enabled

bool

false

Enable @command logging

ragnasync_at_command_log_channel_id

string

""

Discord channel ID for command logs

ragnasync_at_command_log_group_min

int

1

Minimum GM group level to log

ragnasync_at_command_log_group_max

int

99

Maximum GM group level to log

Tip: Set group_min: 99 to only log admin commands, or group_min: 1 to log all staff.

Mob Item Drop Logging

Log rare item drops from monsters to Discord.

Setting
Type
Default
Description

ragnasync_mob_item_drop_log_enabled

bool

false

Enable drop logging

ragnasync_mob_item_drop_log_channel_id

string

""

Discord channel for drop logs

ragnasync_mob_item_drop_log_min_rate

int

500

Minimum rate to log (see drop rates below)

ragnasync_mob_item_drop_log_types

string

"all"

Item categories to log (see Item Drop Types)

Drop Rate Values:

Value
Rate

10000

100%

1000

10%

500

5%

100

1%

10

0.1%

Homunculus Item Drop Logging

Log item drops from Homunculus kills.

Setting
Type
Default
Description

ragnasync_hom_item_drop_log_enabled

bool

false

Enable drop logging

ragnasync_hom_item_drop_log_channel_id

string

""

Discord channel for drop logs

ragnasync_hom_item_drop_log_min_rate

int

500

Minimum rate to log

ragnasync_hom_item_drop_log_types

string

"all"

Item categories to log (see Item Drop Types)

Mercenary Item Drop Logging

Log item drops from Mercenary kills.

Setting
Type
Default
Description

ragnasync_merc_item_drop_log_enabled

bool

false

Enable drop logging

ragnasync_merc_item_drop_log_channel_id

string

""

Discord channel for drop logs

ragnasync_merc_item_drop_log_min_rate

int

500

Minimum rate to log

ragnasync_merc_item_drop_log_types

string

"all"

Item categories to log (see Item Drop Types)

Mob Death Logging

Log when specific mob types are killed (MVP, Mini-boss, or normal mobs).

Setting
Type
Default
Description

ragnasync_mob_death_log_enabled

bool

false

Enable death logging

ragnasync_mob_death_log_channel_id

string

""

Discord channel for death logs

ragnasync_mob_death_log_types

string

"all"

Mob classes to log (see Mob Death Types)

Container Logging

Log when players open containers like Card Albums and Gift Boxes.

Setting
Type
Default
Description

ragnasync_container_log_enabled

bool

false

Enable container logging

ragnasync_container_log_channel_id

string

""

Discord channel for container logs

ragnasync_container_log_types

string

"all"

Container types to log (see Container Types)

ragnasync_container_log_group_min

int

0

Minimum GM group level to log

ragnasync_container_log_group_max

int

99

Maximum GM group level to log

Tip: Set group_min: 0 and group_max: 0 to only log regular players (no GMs).

Shop Logging

Log NPC shop buy/sell transactions.

Setting
Type
Default
Description

ragnasync_shop_log_enabled

bool

false

Enable NPC shop logging

ragnasync_shop_log_channel_id

string

""

Discord channel for shop logs

ragnasync_shop_log_buy_enabled

bool

true

Log buy transactions

ragnasync_shop_log_sell_enabled

bool

true

Log sell transactions

ragnasync_shop_log_min_zeny

int

0

Minimum zeny to log (0 = log all)

ragnasync_shop_log_group_min

int

0

Minimum GM group level to log

ragnasync_shop_log_group_max

int

99

Maximum GM group level to log

Vending Logging

Log player-to-player vending transactions and shop openings.

Setting
Type
Default
Description

ragnasync_vending_log_enabled

bool

false

Enable vending logging

ragnasync_vending_log_channel_id

string

""

Discord channel for vending logs

ragnasync_vending_log_min_zeny

int

0

Minimum zeny to log (0 = log all)

ragnasync_vending_log_group_min

int

0

Minimum GM group level to log

ragnasync_vending_log_group_max

int

99

Maximum GM group level to log

Note: This setting also controls vending_item messages sent when a player opens their shop.

Refine Logging

Log equipment refining attempts (success/failure/downgrade).

Setting
Type
Default
Description

ragnasync_refine_log_enabled

bool

false

Enable refine logging

ragnasync_refine_log_channel_id

string

""

Discord channel for refine logs

ragnasync_refine_log_min_level

int

0

Minimum refine level to log (0 = log all)

ragnasync_refine_log_group_min

int

0

Minimum GM group level to log

ragnasync_refine_log_group_max

int

99

Maximum GM group level to log

Tip: Set min_level: 7 to only log high-refine attempts where things get exciting!

Population Logging

Send periodic server population statistics to Discord.

Setting
Type
Default
Description

ragnasync_population_log_enabled

bool

false

Enable population stats

ragnasync_population_log_channel_id

string

""

Discord channel for population logs

ragnasync_population_log_interval

int

3600

Update interval in seconds (min 60)

Ticket Support System

Enable player support tickets via PM @Support or @request command.

Setting
Type
Default
Description

ragnasync_ticket_support_system_enabled

bool

false

Enable ticket support system

ragnasync_ticket_support_system_close_on_logout

bool

false

Auto-close ticket when player logs out

Log Type Filters

The *_log_types keys all take a comma-separated, case-insensitive list of tokens. Common behavior across every filter:

  • all (or an empty string) disables the filter — everything is logged.

  • Unknown tokens are skipped with a [Warning]: Unknown ... type '...' line printed at map-server startup.

  • If every token in your list is invalid, the mask is empty — which currently falls back to "log everything." If your filter isn't doing anything, check the map-server startup log first.

Each filter key accepts a different set of tokens. Mixing them up is the most common configuration mistake: for example, ragnasync_mob_item_drop_log_types is filtered by item category, not by the class of mob that dropped it, so "mvp,miniboss" is silently invalid and logs nothing specific.

Item Drop Types

Used by ragnasync_mob_item_drop_log_types, ragnasync_hom_item_drop_log_types, and ragnasync_merc_item_drop_log_types. Filters which item categories are announced when a monster drops them.

Token
Filters drops of

all

Every item category (default)

healing

Healing items (potions, herbs, food)

usable

Consumables / usable items

etc

Miscellaneous / crafting materials

armor

Armor pieces

weapon

Weapons

card

Monster cards

petegg

Pet eggs

petarmor

Pet equipment

ammo

Arrows, bullets, other ammunition

shadowgear

Shadow equipment

cash

Cash shop items

There is currently no way to filter item-drop logs by the mob class that dropped the item (e.g. "only log drops from MVPs"). A value like "mvp,miniboss" here will be rejected and log nothing — use min_rate to narrow drops, or route messages through the dashboard if you need MVP-specific alerts.

Mob Death Types

Used by ragnasync_mob_death_log_types. Filters which mob classes fire a death log when killed.

Token
Filters kills of

all

Every mob class (default)

normal

Regular mobs — logs every kill, very spammy

miniboss

Mini-boss monsters

mvp

MVPs

Container Types

Used by ragnasync_container_log_types. Filters which container items fire a log when opened.

Token
Filters openings of

all

Every container type (default)

card_album

Card Albums (Old Card Album, variants)

giftbox

Gift boxes (note: one word, no underscore)

misc_box

Other miscellaneous container items

Channel Discord Linking

Any in-game channel can be linked to Discord by adding the discord_channel_id property to its configuration.

Public Channel Example

Private Channel Default

Private channels can also have a default Discord link:

Notes:

  • Only channels with discord_channel_id configured will send/receive Discord messages

  • Messages from in-game appear in Discord and vice versa

Channel Types

Type
Description

CHAN_TYPE_PUBLIC

Open channels anyone can join

CHAN_TYPE_ALLY

Guild alliance channels

CHAN_TYPE_MAP

Map-specific local channels

Available Colors

GM Commands

These in-game commands allow GMs to manage the RagnaSync service connection.

@startsync

Starts the RagnaSync service if it was stopped.

Notes:

  • Reloads configuration from channels.conf before connecting

  • Resets retry counter

  • No effect if service is already running

@stopsync

Stops the RagnaSync service and disconnects from the server.

Notes:

  • Gracefully disconnects from RagnaSync

  • Service will not auto-reconnect until manually started

  • Useful for maintenance or debugging

@reloadsync

Reloads the RagnaSync configuration and reconnects to the service.

Aliases: @syncreload

Notes:

  • Reads fresh settings from channels.conf

  • Reconnects with new configuration

  • Use after modifying any RagnaSync settings

  • Displays current retry settings after reload

@syncstatus

Displays the current RagnaSync connection status.

Output includes:

  • Connection state (connected/disconnected/stopped)

  • Retry attempt count (if applicable)

  • Current configuration summary

Getting Your Discord IDs

See Installation for instructions on obtaining your Discord Server ID and Channel IDs.

The ragnasync_discord_guid and ragnasync_client_guid are provided by RagnaSync during installation.

ragnasync_discord_id and ragnasync_discord_guid are a matched pair — the GUID belongs to that one Discord server. Your server is turned away at connect time if they don't match, so if you move to a different Discord server, ask support to reissue both together. Copying a channels.conf from another server won't work for the same reason.

Using conf/import/channels.txt

Running multiple environments? This section is for you.

If you run both a live server and a test server from the same codebase, you'll want each environment to have its own ragnasync_client_guid. The problem is that conf/channels.conf is typically committed to git — so any GUID you set there gets shared across all environments.

The solution: use conf/import/channels.txt instead.

Why channels.txt?

File
Git tracked?
Best for

conf/channels.conf

Yes (committed)

Shared settings like channel colors, types, Discord channel IDs

conf/import/channels.txt

No (gitignored)

Per-environment settings like ragnasync_client_guid

Most rAthena and Hercules setups gitignore the conf/import/ folder by default. This makes it the perfect place for settings that differ between your live and test servers.

How to set it up

Create or edit conf/import/channels.txt on each server and add your environment-specific GUID:

That's it! Settings in conf/import/channels.txt override anything in conf/channels.conf, so each environment gets its own identity on RagnaSync.

Example: Live + Test setup

Live server (conf/import/channels.txt):

Test server (conf/import/channels.txt):

Each server now has its own dashboard, crash logs, metrics, and status tracking on RagnaSync — completely independent.

Tip: You can leave ragnasync_client_guid empty in conf/channels.conf and only set it in conf/import/channels.txt on each server. A GUID is generated automatically on first connect if you don't set one.

PreviousInstallation
NextMessage Sync

Last updated