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

Download the latest build for the server's release channel and restart the server if it was running.

Emit:

socket.emit("update:apply");

Response: update:status events (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
}