Socket Events Reference

Real-time communication uses Socket.IO. All events require authentication.

Connection

import { io } from "socket.io-client";

const socket = io("http://localhost:3000", {
  auth: { token: "your-jwt-token" },
});

Server Control Events

command

Send a command to the server console.

Emit:

socket.emit("command", "/help");

Response: command-result

socket.on("command-result", (result) => {
  // { cmd: '/help', success: true }
});

start

Start the server container.

Emit:

socket.emit("start");

Response: action-status

socket.on("action-status", (result) => {
  // { action: 'start', success: true }
});

stop

Stop the server container.

Emit:

socket.emit("stop");

Response: action-status

restart

Restart the server container.

Emit:

socket.emit("restart");

Response: action-status

download

Trigger server file download (x64 only).

Emit:

socket.emit("download");

Response: Multiple download-progress events, then download-complete

wipe

Delete all server data.

Emit:

socket.emit("wipe");

Response: action-status

Log Events

logs:more

Request additional log history.

Emit:

socket.emit("logs:more", {
  currentCount: 100,
  batchSize: 200,
});

Response: logs:history

socket.on("logs:history", (data) => {
  // { logs: string[], initial: false, hasMore: true }
});

log (receive)

Real-time log streaming.

socket.on("log", (line: string) => {
  console.log("New log:", line);
});

File Events

files:list

List directory contents.

Emit:

socket.emit("files:list", "/mods");

Response: files:list-result

socket.on("files:list-result", (result) => {
  // { success: true, files: [...], path: '/mods' }
});

files:read

Read file contents.

Emit:

socket.emit("files:read", "/config.json");

Response: files:read-result

socket.on("files:read-result", (result) => {
  // { success: true, content: '...', path: '/config.json' }
});

files:save

Save file contents.

Emit:

socket.emit("files:save", {
  path: "/config.json",
  content: '{"key": "value"}',
  createBackup: true,
});

Response: files:save-result

files:mkdir

Create a directory.

Emit:

socket.emit("files:mkdir", "/mods/custom");

Response: files:mkdir-result

files:delete

Delete a file or directory.

Emit:

socket.emit("files:delete", "/mods/old-mod.jar");

Response: files:delete-result

files:rename

Rename a file or directory.

Emit:

socket.emit("files:rename", {
  oldPath: "/mods/mod.jar",
  newPath: "/mods/mod-renamed.jar",
});

Response: files:rename-result

check-files

Check if server files exist.

Emit:

socket.emit("check-files");

Response: files and downloader-auth

Mod Events

mods:list

List installed mods.

Emit:

socket.emit("mods:list");

Response: mods:list-result

socket.on("mods:list-result", (result) => {
  // { success: true, mods: [...] }
});

mods:search

Search Modtale for mods.

Emit:

socket.emit("mods:search", {
  query: "example",
  classification: "MOD",
  page: 1,
  pageSize: 20,
});

Response: mods:search-result

mods:get

Get mod details from Modtale.

Emit:

socket.emit("mods:get", "project-id");

Response: mods:get-result

mods:install

Install a mod from Modtale.

Emit:

socket.emit("mods:install", {
  projectId: "project-id",
  versionId: "version-id",
  metadata: {
    versionName: "1.0.0",
    projectTitle: "Example Mod",
    classification: "MOD",
  },
});

Response: mods:install-status (progress), then mods:install-result

mods:uninstall

Uninstall a mod.

Emit:

socket.emit("mods:uninstall", "mod-id");

Response: mods:uninstall-result

mods:enable / mods:disable

Enable or disable a mod.

Emit:

socket.emit("mods:enable", "mod-id");
socket.emit("mods:disable", "mod-id");

Response: mods:enable-result / mods:disable-result

mods:check-updates

Check for mod updates.

Emit:

socket.emit("mods:check-updates");

Response: mods:check-updates-result

socket.on("mods:check-updates-result", (result) => {
  // { success: true, updates: [...] }
});

mods:update

Update a mod to a new version.

Emit:

socket.emit("mods:update", {
  modId: "mod-id",
  versionId: "new-version-id",
  metadata: {
    versionName: "1.1.0",
  },
});

Response: mods:update-status (progress), then mods:update-result

mods:check-config

Check if Modtale is configured.

Emit:

socket.emit("mods:check-config");

Response: mods:config-status

socket.on("mods:config-status", (result) => {
  // { configured: true }
});

mods:classifications

Get available mod classifications.

Emit:

socket.emit("mods:classifications");

Response: mods:classifications-result

Server Update Events

update:check

Check whether a newer server build is available on the server's release channel. The backend runs hytale-downloader -print-version inside the container and compares it against the installed version.

Emit:

socket.emit("update:check");

Response: update:check-result

socket.on("update:check-result", (result) => {
  // {
  //   success: true,
  //   lastUpdate: "2026-07-01T12:00:00.000Z",
  //   daysSinceUpdate: 10,
  //   hasFiles: true,
  //   currentVersion: "2026.06.01-def5678",
  //   latestVersion: "2026.07.01-abc1234",
  //   updateAvailable: true // null when versions cannot be determined
  // }
});

update:apply

Back up the server (unless backupBeforeUpdate is false in the server config), download the latest build for the server's release channel and restart the server if it was running. If the backup fails, the update is aborted with an error status and nothing is downloaded.

Emit:

socket.emit("update:apply");

Response: update:status events (backing-up, downloading, restarting, complete, error)

Backup Events (v1.4.0+)

backup:create

Create a manual backup of the server.

Emit:

socket.emit("backup:create");

Response: backup:status (creating), then backup:create-result

socket.on("backup:create-result", (result) => {
  // { success: true, backup: { id, filename, createdAt, size } }
});

backup:list

List available backups.

Emit:

socket.emit("backup:list");

Response: backup:list-result

socket.on("backup:list-result", (result) => {
  // { success: true, backups: [...] }
});

backup:restore

Restore server from a backup. Server must be stopped.

Emit:

socket.emit("backup:restore", "backup-id");

Response: backup:status (restoring), then backup:restore-result

backup:delete

Delete a specific backup.

Emit:

socket.emit("backup:delete", "backup-id");

Response: backup:delete-result

backup:config

Get or update backup configuration.

Emit (get):

socket.emit("backup:config");

Emit (update):

socket.emit("backup:config", {
  enabled: true,
  intervalMinutes: 60,
  maxBackups: 10,
  maxAgeDays: 7,
  onServerStart: true,
});

Response: backup:config-result

socket.on("backup:config-result", (result) => {
  // { success: true, config: {...} }
});

Status Events

status (receive)

Server status updates (sent every 5 seconds).

socket.on("status", (status) => {
  // { running: true, uptime: 3600, ... }
});

Response Format

All event responses follow this pattern:

interface EventResult {
  success: boolean;
  error?: string;
  // ... additional data
}