Skip to content

Instance

Jump to bottom
Moritz edited this page Nov 7, 2025 · 2 revisions

Galactic Logo

Getting Started: Instance

The Instance class in galactic.ts serves as a foundational component for managing Discord bot clusters and shards. It provides the necessary infrastructure to run multiple clusters, each handling a subset of shards, allowing for efficient scaling and resource management.

Overview

An Instance can operate in two primary modes:

  • Standalone Instance: Runs multiple clusters on a single machine, managing shard distribution and cluster lifecycle internally.
  • Managed Instance: Connects to a central Bridge server, which assigns clusters and shards to the instance, enabling horizontal scaling across multiple machines.

Key Features

  • Cluster Management: Automatically handles the creation, monitoring, and restarting of clusters.
  • Shard Distribution: Distributes shards evenly across clusters to optimize performance.
  • Event Handling: Provides hooks for monitoring cluster status and performance.
  • Integration with discord.js: Seamlessly integrates with discord.js clients for easy bot development.
  • Scalability: Supports scaling from a single machine to multiple instances across different servers.
  • Custom Metadata: Allows passing custom metadata to managed instances for better identification and management.
  • Dev Mode: Supports a development mode for easier testing and debugging.
  • Flexible Configuration: Offers various configuration options for tailoring instance behavior to specific needs.
  • Logging and Monitoring: Built-in support for logging cluster activities and monitoring performance metrics.
  • Extensibility: Designed to be extensible, allowing developers to build custom functionality on top of the Instance class.

Usage

To create and start an Instance, go to the Standalone Instance or Managed Instance documentation for detailed guides and examples.

Events

Name Signature Occurance
'request' (client: ClusterProcess, message: unknown, resolve: (data: unknown) => void, reject: (error: any) => void) => void When a cluster process sends a request message.
'message' (client: ClusterProcess, message: unknown) => void When a cluster process sends a message.
PROCESS_KILLED (client: ClusterProcess, reason: string, processKilled: boolean) => void When a cluster process is killed, providing the reason and whether it was expected.
PROCESS_SPAWNED (client: ClusterProcess) => void When a cluster process is successfully spawned.
PROCESS_ERROR (client: ClusterProcess, error: unknown) => void When a cluster process encounters an error
CLUSTER_READY (client: ClusterProcess) => void When a cluster process reports that it is ready.
CLUSTER_ERROR (client: ClusterProcess, error: unknown) => void When a cluster process reports an error.
CLUSTER_RECLUSTER (client: ClusterProcess) => void When a cluster process requests to be reclustered.
ERROR (error: string) => void When the instance encounters a general error.
BRIDGE_CONNECTION_ESTABLISHED () => void When the connection to the bridge is successfully established.
BRIDGE_CONNECTION_CLOSED (reason: string) => void When the connection to the bridge is closed, providing the reason.
BRIDGE_CONNECTION_STATUS_CHANGE (status: number) => void
INSTANCE_STOP () => void When the instance is stopping.
INSTANCE_STOPPED () => void When the instance has fully stopped.
SELF_CHECK_SUCCESS () => void When a self-check operation completes successfully.
SELF_CHECK_ERROR (error: string) => void When a self-check operation encounters an error.
SELF_CHECK_RECEIVED (data: { clusterList: number[] }) => void When a self-check response is received, providing the list of active clusters.

Clone this wiki locally