Documentation

How to connect an ARK cluster to SatayaLib: the plugin, the panel, Discord and Telegram bridges, the API.

What it is

SatayaLib is cross-server chat and a panel for an ARK cluster (ARK: Survival Ascended and ARK: Survival Evolved). Players on every map talk to each other, tribes keep their private chat across maps, and you get a panel with history, players, a map and bridges to Discord and Telegram.

You do not run a shared database or merge configs. One small plugin goes on each map with a key and an address, the map connects to us on its own, and you approve it in the panel.

Quick start

1. Sign in at the panel. There is no password: type your email, a one-time code arrives, enter it.
2. Create a project and a cluster. A project is your team: the people who manage your servers. A cluster is a group of maps that share one chat. One project can hold several clusters.
3. Issue a key on the Keys page. The key is shown once, copy it. One key is enough for all your machines and maps.
4. Download the plugin on the Plugin page, for ASA or ASE. Unpack it into the ArkApi plugins folder of the map and put the key and the panel address into config.json. The Keys page gives you a ready config.json to copy.
5. Start the map. It shows up on the Servers page as “awaiting approval”. Approve it and pick the cluster it belongs to.
6. Repeat for every map. Chat flows between maps that are approved, enabled, online and in the same cluster.

The plugin

Requirements

• ASA: the map runs with AsaApi (Ark Server API). ASE: the map runs with ArkApi. SatayaLib is a plugin for that loader.
• Windows server. ASE with the plugin works on Windows only.

Install

1. Unpack the archive into ArkApi/Plugins/SatayaLib next to the other plugins.
2. Open ArkApi/Plugins/SatayaLib/config.json and fill in two fields:

{
  "key": "your project key from the Keys page",
  "url": "wss://satayalib.com/plugin/connect"
}

3. Start the map. Nothing else is needed on the server side.

Good to know

• The connection goes from your server to us, over one WebSocket. No open ports, no RCON, no database.
• The plugin never blocks the game: if the panel is unreachable, the map keeps running and reconnects on its own.
• The Servers page shows the plugin version of every map and warns when a map runs an older build than the one published on the Plugin page. Updating is replacing the library and restarting the map; the config and the approval stay.
• Certificates: the plugin trusts the Windows certificate store. If your server has a custom CA, point ca_file in config.json at it.

Servers and clusters

Every map is a row on the Servers page. A row has three independent switches:

• Approving, moving a map to another cluster and the enabled switch apply within a second, without restarting the map.
• A map is identified by key, port, map name and game. If you change the map on a server, it appears as a new row and waits for approval again.
• Deleting a row disconnects the plugin until the next restart; chat history stays.
• Each map can have its own display name and colour for the chat line: the tag icon next to the map name.

Clusters

A cluster is one chat. Its settings live on the Clusters page: the command word for players (default st), the chat line template (what the prefix with the map and nickname looks like), the language of bot replies to players, the word filter and automatic tribe linking.

Chat

• The Chat page shows the cluster chat live and lets you write into the game as the panel. Your line reaches every map of the cluster.
• History is kept per cluster for as many days as your plan allows.
• The filter of forbidden words works on our side: the word is masked on the other maps, in the panel and in the API. On the author’s own map the game draws the line, so the author still sees it. Your own words and exceptions are set on the Clusters page.
• Emotes typed in the game arrive outside the game as ordinary smileys and go back into the game as pictures.

Tribes across maps

A tribe lives on one map. SatayaLib links tribes of different maps into one group, so tribe chat and the tribe log flow between maps.

• By command. A tribe owner or admin types /st link on one map and gets a code. On the other map a member of the same tribe types /st link <code>. The code lives one hour.
• In the panel. On the Players page, Tribes tab, select tribes of different maps and press “Link”. Unlinking is there too.
• Automatically. Turn on “auto link by owner” on the cluster: tribes whose owner is the same player are linked on their own. Manual links are never touched by the automatic one.
• The tribe log (kills, tames, structures) is collected from every map and shown on the Players page, Tribes tab, below the tribe lists. It also goes to the tribe’s own Discord or Telegram channel (see below).

In-game commands

Players type commands in the chat. The word st and the names of subcommands can be changed per cluster. Anything that starts with a slash never reaches the cross-server chat.

Colours are shown on the other maps and in the panel; messengers do not show colours. On the player’s own map the game draws the line as usual. Whether players may pick colours themselves depends on the plan and on the groups you set up.

Players, groups, mutes

• Players page. Who is online on each map right now, and everyone the cluster has seen: character, level, tribe, last visit, platform. Colours can be set from here too.
• Groups. VIP-style groups per project: a name shown in the chat line with a colour, permissions such as “may pick own nickname colour”, members by Steam or EOS ID with a term, a delayed start and one-time options. You can add a member before they ever joined the server.
• Mutes. A mute is issued by platform ID with a reason and a term, works on every map of the project and survives a change of map. The message is stopped before it reaches the other maps, and on the author’s own map the plugin hides it. The history of punishments stays on the player.

Map

• The Map page shows where players are on the chosen map: online players live, offline bodies after a scan.
• “Start collection” asks the plugin to walk the map once and report sleeping bodies and dead characters. It reads the live world, not the save files, and it is light enough to run with players online.
• Map images are the official ones; without an image you still get a grid with coordinates.

Discord and Telegram

Our bots: SatayaLib in Discord and @satayalib_bot in Telegram. A bridge connects one channel with one cluster chat, in both directions.

Cluster channel

1. Bots page, “Create bridge”: pick the cluster, the messenger and what to send (chat, joins and leaves, map status, alerts).
2. The panel shows a one-time code (valid one hour) and a button to invite the bot.
3. Invite the bot to your server or group, open the channel and type /connect <code> (in Discord: /connect code:<code>). Only server or group admins can bind and unbind.

From then on messages from the channel go into the game with a [Discord] or [Telegram] tag, and game chat goes into the channel. Templates for both directions are editable on the bridge.

Tribe channel

1. In the game, the tribe owner or admin types /st bridge and receives a code privately.
2. In the tribe’s own channel someone types /tribe <code>. The channel now carries the tribe chat and the tribe log, and replies go back to the tribe in the game.

• One channel belongs to one bridge. A tribe code never takes over a channel that is already bound, so nobody can hijack the cluster channel with a tribe code.
• /disconnect in the channel unbinds it (admins only). The bridge can also be removed in the panel.
• Discord admins can restrict the /tribe command to certain channels or roles in Server Settings → Integrations → SatayaLib.
• Your own bot: on paid plans a bridge can run under your bot’s name and avatar. Put its token on the Bots page; it is stored encrypted.

Map watch

If a map goes silent and does not come back within 15 minutes, you get told. A short restart does not trigger anything.

• In Discord or Telegram: turn on “alerts” on a bridge. For a quiet admin-only channel, create a second bridge of the same cluster in a private channel with only “alerts” enabled; in Discord you can add a role to mention.
• By email: the project owner gets one message per map per day, at most three per project per day. When the whole cluster is down you get one message with the list of maps.
• When the map is back, the channel says so.

Map health

The Health page shows how each map actually runs: the game frame time from inside the server, players online, outages and alerts on one time axis. Nobody outside the process can see the frame time, so this is the place to settle “is it the server or the network”.

• Per map: average and worst frame time, players online, the alert threshold, and marks for every outage and alert. Periods: a day, a week, 30 days.
• Availability: share of time online, number of outages, the longest one and the typical time to come back.
• Players by hour of the week: when the cluster is busiest, for planning events and restarts.
• Lag alert: if the frame time stays above 100 ms for five minutes, bridges with alerts enabled get a message; when it settles, another one. No email for lag.

The page is part of the Pro plan.

Open API

• Integrations page: issue a token with the scopes you need (read chat, write chat, tribe chat, servers, events). The token is shown once.
• Send it as Authorization: Bearer <token>. The reference with every route is at /api/v1/docs.
• The event stream is a WebSocket with chat, joins and leaves, map status, presence, tribe links and map watch alerts. Bots, overlays and statistics live on it.

Plans and limits

The plan lives on the account of the project owner and covers all their projects. It limits the number of projects, approved maps and days of chat history, and turns features on: colours, moderation, the map, offline collection, your own command word, the open API, your own bot. The Plan page shows what you have and what is on offer.

Switching plans is done by hand for now: write to us in Discord. Want to try everything? Ask there and we enable every feature for three months.

Troubleshooting

The map does not appear on the Servers page

• Check url and key in config.json: the key must be a live key of your project, the address must be the one from the Keys page.
• Look at the ArkApi log on the server: the plugin writes why it cannot connect, in English.
• “key revoked” or 401 in the log: the key was revoked; issue a new one.
• 426 in the log: the plugin is too old for the panel; download the current build.

Certificate error in the log

The plugin verifies the certificate of the panel through the Windows certificate store. Update the root certificates of the server, or put a CA bundle on the server and point ca_file in config.json at it.

Maps are online but chat does not flow

Both maps must be approved, enabled, online and in the same cluster. A map awaiting approval or turned off stays silent.

The bot does not answer /connect

• The bot must be in the channel with the right to read and write. In Telegram, only group administrators may bind.
• The code is one-time and lives one hour; get a fresh one on the Bots page.
• “This code is a tribe code” means you used /connect with a code from the game; tribe codes go with /tribe.

Players do not see colours on their own map

By design: on the author’s map the game draws the line. Colours are visible on the other maps and in the panel. Messengers do not show colours at all.

Two machines with the same key

That is fine. Maps are told apart by port, map name and address, and each new one waits for approval.

Support

Questions, tickets and feature requests go to our Discord. Open a ticket in the support channel: it creates a private channel for you and the team. Never post keys, tokens or codes in public channels.