Impulse

Impulse is a plugin for the Minecraft server proxy Velocity. It adds the ability to dynamically start and stop servers on demand as players join and leave. Why run a server that is only used for a few hours a day?

Key Features

Impulse has many features to make managing your servers easy! Some highlights include:

• Dynamic server creation and destruction - only run servers when your players are connected
• First and third party brokers - Cores to drive your servers no matter how they are deployed, via Docker, JAR files, or something else. We are actively working on expanding our selection but you can find the full list here
• Automatic hot reload of configuration - update how impulse runs a server automatically, without a reload command!
• Unmanaged server support - plays nice with any static servers you have configured in Velocity
• Custom events - broadcasts custom events that allow you to extend Impulse's functionality
• Third party Broker support - Implement your own Broker or use someone else's to manage your servers
• FOSS - Impulse is commited to being free and open source always

Documentation

For more detailed information on how to use Impulse, see our documentation. For API documentation, see our KDocs.

Installation

In short, download our latest release from one of our sources and place it in your Velocity plugins folder. For more detailed instructions see our installation guide.

Sources:

• Modrinth
• Hangar
• GitHub Releases

Quick Start

The following configuration should get you started with a simple lobby server.

Step 1: Configure Velocity

Simply add the server to your velocity config as normal.

player-info-forwarding = "modern"

[servers]
lobby = "127.0.0.1:25566"

try = ["lobby"]

Step 2: Configure Impulse

Configure impulse so it know how to manage your server

instanceName: Bones
servers:
  - name: lobby
    inactiveTimeout: 300
    type: docker
    docker:
      image: itzg/minecraft-server
      portBindings:
        - "25566:25565"
      env:
        ONLINE_MODE: "FALSE"
        TYPE: "FABRIC"
        EULA: "TRUE"
        MODRINTH_PROJECTS: "fabricproxy-lite"
        DIFFICULTY: "PEACEFUL"
        ALLOW_NETHER: "FALSE"
        MODE: "adventure"
      volumes:
        - "/srv/lobby:/data"

Step 3: Configure the MC Server

Add some config to allow for modern forwarding

# create the file /srv/lobby/config/FabricProxy-Lite.toml
hackOnlineMode = true
hackEarlySend = false
hackMessageChain = true
disconnectMessage = "This server requires you to connect through the proxy."
secret = "<YOUR SECRET FROM forwarding.secret FILE>"

Step 4: Connect

Simply start your velocity proxy and connect to it from your Minecraft client. If you run into issues check our documentation or open an issue!

Getting Help

If your having problems with Impulse, experiencing a bug, or just want to recommend a feature, feel free to open an issue! I will do my best to respond.

Contributing

All contributions are welcome! For more specific instructions see our contributing page.

For specifics on adding creating your own broker to integrate with another server platform see our guide.

Overview

Impulse is a relatively simple program to get started with. In this guide we will walk you through how to set up a simple survival multiplayer (SMP) server running on fabric. We will configure our main server to start on an initial user connection and to automatically stop after 5 minutes of inactivity. Below is an outline of what each section covers. If you are new to Impulse we recommend reading through the entire guide.

1. Prerequisites - Covers the software and configuration needed to get started with Impulse
2. Installation - Covers how to install Impulse into your Velocity proxy
3. Velocity Configuration - Config needed in velocity
4. Impulse Configuration - How to configure Impulse to manage the server
5. Connecting and Exploring - A quick tour of the features Impulse adds to Velocity and your server

Prerequisites

Velocity

This guide assumes you already have a working velocity server. If you are setting up from scratch, you can follow Velocity's getting started guide. Once configured, you can proceed with setting up Impulse. Additionally, this guide will assume you have configured player forwarding and are running your proxy in online mode.

Brokers

Later in this guide we will be configuring our backed servers using one of Impulse's broker implementations. Depending on which broker you choose, you may need to install additional software on your backend servers.

Docker

Currently Docker is the only broker implementation available. Any computer you would like Impulse to run servers on via this broker must have docker installed. You can follow the official docker installation guide.

In this example, are running our backend servers on the same machine as our proxy.

JAR

The JAR broker simply requires the Java Runtime to be installed. Since it can only manage servers on the same machine as Velocity, this should already be installed. You will also need to download the server JAR file you plan to run. In this example, we will be using the Fabric server.

Installation

Download

The Impulse jar file can be downloaded from serveral sources:

• Modrinth
• Hangar
• Offical Github Releases

For people that need it in a package format, we also publish to the Github Maven Repository.

Installation

To install Impulse simply place the jar file in your Velocity server's plugins folder and restart Velocity if it is running. You can verify Impulse is running by checking the console for the following messages:

[18:52:15 INFO] [Impulse]: Initializing Impulse
[18:52:15 INFO] [Impulse]: Configuration reloaded

Alternative Versions

Pre-Release

We will publish pre-release builds to our Github Releases page and Hangar Snapshots channel. These are often release candidates that have not yet been fully tested, or that we are looking for feedback on. They are the most stable of our alternative versions since in theory any one could be promoted to a full release.

Nightly

We maintain a nightly build channel. As the name implies this is a nightly build of main bugs and all. You can find obtain these from our Github Actions page. These are the least stable of our versions.

Advanced Installation

For more advanced installation options, such as custom brokers or using our "minimal" jar, see the Advanced Installation guide.

Velocity Configuration

Velocity's configuration is stored in the velocity.toml file. For more information on all the available options, see Velocity's configuration documentation.

For this guide we will only need to touch a few options.

Servers

Due to some limitations in the Velocity API, you need to define any server you would like to directly connect to through either the try or forced-hoses blocks in the velocity.toml file. We are going to add the connection information for our SMP server since we want all players to connect to it by default. We will later configure Impulse to adopt the server reference that velocity creates here.

[servers]
smp = "127.0.0.1:25566"

Try

The easiest way to get all our players to connect to our SMP by default is to set it as the first (and only) option in the try block. Impulse is not affected by this or the forced-hosts settings.

try = ["smp"]

Player Info Forwarding

Since we are running Velocity in online mode, we can set up player info forwarding to our SMP server so that people get their skins and correct usernames. Simply change the following option:

player-info-forwarding = "modern"

That is it for the Velocity configuration! Save the file and either reload it with /velocity reload or restart the proxy.

Impulse Configuration

Impulse maintains its own configuration file named config.yaml. It can be found in the plugins/impulse directory. If it does not exist you can create it. For our simple SMP we can keep most of the defaults. For now lets set our instanceName.

plugins/impulse/config.yaml:

instanceName: MyCoolSMP

The instance name is used internally by Impulse to identify your Velocity server. This is necessary for some brokers that may be managing servers for multiple Velocity instances. It should be unique per Velocity server.

Selecting a Broker

In Velocity a "broker" is an interface that Impulse uses to actually interact with different platforms that can host minecraft servers. For the next step select which broker you would like to use, and follow the instructions for that broker. You can find a basic description of each broker below with pros and cons. For more in depth information see the brokers documentation.

Docker

The Docker broker is a good choice for most users. It offers a good balance of flexibility and ease of setup. It also allows for running servers on multiple machines.

Continue to Docker Broker Setup

JAR

The JAR broker is the simplest broker. It primarily designed for a single server setup and development. It only supports running servers on the same machine as Velocity.

Continue to JAR Broker Setup

Kubernetes

The Kubernetes broker is for advanced setups and those already familiar with Kubernetes. It is the most powerful broker, but also significantly more complex to setup.

NOT YET AVAILABLE

Docker

To configure our SMP server to be managed by Docker, we simply need to add a few lines to our config.yaml file.

plugins/impulse/config.yaml

instanceName: MyCoolSMP
servers:
  - name: smp
    type: docker
    lifecycleSettings:
      timeouts:
        inactiveGracePeriod: 300
    docker:
      image: "itzg/minecraft-server:latest"
      portBindings:
        - "25566:25565"
      env:
        ONLINE_MODE: "FALSE"
        TYPE: "FABRIC"
        EULA: "TRUE"
        MODRINTH_PROJECTS: "fabricproxy-lite"
      volumes:
        - "/srv/smp:/data"

Let's break that down a bit!

servers section

This is where we can define a list of servers that we want Impulse to manage. In this case, we are defining a single server named smp.

name provides a unique identifier for the server.

exactly. If it does not you will get unexpected behaviour!

lifecycleSettings is where we can set all the config properties related to how a server runs. For our SMP server we are setting the amount of time the server will wait before shutting down after the last player has left to 5 min.

type specifies which broker is managing this server. In this case, we are using the docker broker.

docker section

This section contains all the configuration specific to the Docker broker. If you are familiar with Docker Compose or Kubernetes many of these options may look familiar. If not, never fear! We will explain them all.

image specifies the Docker image that we want to use for this server. In this case, we are using the itzg/minecraft-server image. This image is a very popular image for running Minecraft servers in Docker containers and is the default. Documentation can be found here. Impulse will work with any image, so feel free to change this as needed.

portBindings allows us to define how we want to map ports from the host to the container. In this case, we are mapping all traffic on the host port 25566 to the container port 25565.

env allows us to define environment variables that will be passed to the container. The itzg/minecraft-server image has many environment variables that can be used to configure your MC server. In this case, we are setting up a Fabric server with the fabricproxy-lite mod. It is also set to offline mode as required by Velocity.

volumes allows us to define which directories on the host we want to mount into the container. In this case, we are mounting the /srv/smp directory on the host to the /data directory in the container. This is where the Minecraft server data will be saved. The source directory can be any directory on the host, but it must be mounted to /data for this image.

Configuring Identity Forwarding

Since Velocity is set up with "modern" forwarding and in online mode, we need a bit of configuration on our server before players will be able to connect. Luckily this is very simple! We just need to add a file to the /srv/smp directory that we mounted into the container.

/srv/smp/config/FabricProxy-Lite.toml

hackOnlineMode = true
hackEarlySend = false
hackMessageChain = true
disconnectMessage = "This server requires you to connect with Velocity."
secret = "<YOUR SECRET FROM forwarding.secret HERE>"

You can find the forwarding.secret file next to your velocity.toml.

Pre-pulling the Docker Image

docker pull itzg/minecraft-server:latest

JAR

The JAR broker is simple to configure. For our SMP server the following will provide a minimal working configuration.

plugins/impulse/config.yaml

instanceName: MyCoolSMP
servers:
  - name: smp
    type: jar
    lifecycleSettings:
      timeouts:
        inactiveGracePeriod: 300
    jar:
      workingDirectory: /srv/smp
      jarFile: fabric.jar
      javaFlags:
        - -Xms4G
        - -Xmx4G
      flags:
        - --nogui

Let's break that down a bit!

instanceName

Here we give a unique identifier to our Velocity server. This is not used by the JAR broker, but others may use it to identify different Velocity instances that they are managing servers for.

servers section

This is where we can define a list of servers that we want Impulse to manage. In this case, we are defining a single server named smp.

name provides a unique identifier for the server.

lifecycleSettings is where we can set all the config properties related to how a server runs. For our SMP server we are setting the amount of time the server will wait before shutting down after the last player has left to 5 min.

type specifies which broker is managing this server. In this case, we are using the jar broker.

jar section

This section contains all the configuration specific to the JAR broker. If you are familiar with running a Minecraft servers from the command line this may look familiar.

workingDirectory specifies the directory that the server will be run from. This should be the directory that contains the server jar.

jarFile specifies the server jar file to run.

javaFlags allows us to specify flags to pass to the JVM when starting the server. In this case, we are setting the max and min heap size to 4G.

flags allows us to specify flags to pass to the server jar. In this case, we are telling the server to run in nogui mode.

This configuration will cause the server to be run as if you had run the following command from the /srv/smp directory:

java -Xms4G -Xmx4G -jar fabric.jar --nogui

Configuring the Server

We will need to handle some configuration of our server if we want it to be able to connect to our Velocity proxy.

server.properties

Because Velocity is running on port 25565 we will need to change the server port in the server.properties file to 25566.

server-port=25566

eula.txt

You will also need to agree to the Minecraft EULA. Open the eula.txt file and change eula=false to eula=true.

eula=true

Identity Forwarding

Since Velocity is set up with "modern" forwarding and in online mode, we need a bit of configuration on our server before players will be able to connect. Luckily this is very simple! We just need to add a file to the /srv/smp and install a mod.

First download the FabricProxy-Lite mod and place it in your mods folder. Once that is installed you can add the following file to the /srv/smp/config directory.

/srv/smp/config/FabricProxy-Lite.toml

hackOnlineMode = true
hackEarlySend = false
hackMessageChain = true
disconnectMessage = "This server requires you to connect with Velocity."
secret = "<YOUR SECRET FROM forwarding.secret HERE>"

You can find the forwarding.secret file next to your velocity.toml.

Connecting and Exploring

Velocity is set up to hot reload its configuration when it changes. This means you should not have to restart Velocity. You can verify that your configuration is loaded by looking for the following log message in the Velocity log:

[18:52:15 INFO] [Impulse]: Configuration reloaded
[18:52:16 INFO] [Impulse]: ServerManager: server smp reconciled

Connecting to the server

If you see this then you should be all set to connect to velocity as normal! When connecting you should notice that you stay on the join screen for longer than normal. This is because Impulse is starting the server in the background. Once the server is started you will be connected to it automatically.

The join screen will look like this while the server is starting

If the server takes longer to start than your configured timeout you will be disconnected with an error message. The server will still attempt to start in the background. Try and reconnect after a few seconds. If the error persists see the debugging section.

Error screen if the server start exceeds the timeout

All connections after the first "cold" start should be much faster as the server is already running. Only the first player to connect after the server has stopped will experience the delay.

Trying out the commands

Now that we are on the server lets take a look at some of the commands that Impulse provides. The full command list and documentation can be found here.

impulse status

If you run the status command it will give you the current status of all servers that Impulse is managing. You can also request the status of a specific server by passing the server name as an argument.

impulse start

This command will start a server that is currently stopped. If the server is already running it will do nothing.

impulse stop

This command will stop a server that is currently running. This includes the server that you are currently on.

Leaving the server

When you are done exploring the server you can disconnect. If you are the only player on the server Impulse will stop the server after the configured timeout. Be default this is 5 minutes. You can see this in the logs when a server is stopped:

[05:19:04 INFO] [impulse]: Server smp has no players, stopping

Debugging

If you are using the docker broker you can check the container status by running the following command:

docker ps -a

you should see a container with the name smp and the status Up. If the status is Exited then the server has crashed for some reason. If the docker status is Up, but you are still having issues connecting to the server it may still be starting. For either case you can check the logs of the container by running:

docker logs smp

If using the JAR broker you can check the log outputs directly for any errors.

Look for any errors in the logs, or wait for the server to finish starting. If you are still having issues feel free to open an issue on the GitHub repository

At this point you should be able to continue to set up your server as you see fit.

Configuration

Impulse exposes a lot of options so you can tweak its behavior to your liking. The configuration file is located at plugins/impulse/config.yaml. When a change is detected in the configuration file, Impulse will automatically reload its configutaion and apply the changes. This even extends to the server configurations! Impulse will trigger a reconciliation event for each server that has changed, keeping things up to date for you.

Velocity Configuration

Impulse has two methods of exposing servers to Velocity, either through a static binding or a dynamic binding. The difference between the two is outlined below. "Hot" reconciliation of binding is not supported but they can be refreshed live by removing the server from the impulse configuration, waiting for reconciliation to complete, and then re-adding the new server configuration.

Static Binding

In this method you add your server configuration to the velocity.toml file as normal. Impulse will then adopt the server reference in Velocity when it creates the server. This method mostly exists due to current limitations in the Velocity API.

When to Use:

• You need to reference the server in the try block of Velocity's configuration
• You need to reference the server in the forced-hosts section of Velocity's configuration
• You want Velocity to always present the server in the server list, even if it is not in Impulse's configuration at all

Dynamic Binding

If no server ref is found in the velocity.toml impulse will dynamically create one at runtime. Each broker will have its own method of specifying the server address, so please refer to the appropriate broker documentation for more information on how to configure this. For example with the Docker broker you would set the address key in its configuration.

When to Use:

• You do not need anything mentioned in Static Binding
• Servers that will only be transferred to from another server (e.g. a mini games server only accessible from the lobby)

Impulse Configuration Options

Global Configuration

Impulse has a few global configuration options to be aware of. You can tweak these settings to adjust how Impulse behaves. They are as follows:

Messages

Impulse has a few messages that it will send to players on various events. These messages can be customized to your liking. All messages support MiniMessage formatting.

Server Configuration

This is where you will define the servers that Impulse will manage. Each server has its own configuration, and the keys are as follows:

Lifecycle Settings

Timeouts

Broker Specific Configuration

Each broker will inject its own configuration key into the server configuration. Please see the appropriate broker documentation for more information on its configuration.

• Docker Broker

Commands

Impulse provides several commands to help you manage your servers both in-game and in the console. The following is a list of each command and a brief description. For more information on a specific command, see its respective page.

• impulse start <server> -- Start a server if it is not already running.
• impulse stop <server> -- Stop a server if it is running.
• impulse remove <server> -- Stop a server and remove its underlying resources (excluding save data).
• impulse reconcile <server> -- Reconcile a server's configuration with its current state.
• impulse status Optional<server> -- Get the status of a server or all servers.
• impulse pin <server> -- Pin a server to prevent it from being stopped automatically.
• impulse unpin <server> -- Unpin a server to allow it to be stopped automatically.

start

The start command is used to start a configured server without a client connecting.

impulse start <server>

This is useful for scripts or times where you would like to a server to start and prepare things before batch connecting clients (for instance a minigame instance).

Specify a server

The server argument is the name of the server you would like to start. This is the name you defined in the servers section of the config.yaml file.

Aliases

• impulse warm

Examples

impulse start smp

Permission Scope

Use the impulse.server.warm permission scope to control who can use this command.

stop

The stop command is used to stop a running server.

impulse stop <server>

This is useful for stopping a server that is running in the background or to stop a server that is no longer needed. This also works for servers with an inactiveTimeout of 0 that would otherwise never stop.

Specify a server

The server argument is the name of the server you would like to stop. This is the name you defined in the servers section of the config.yaml file.

Examples

impulse stop smp

Permission Scope

Use the impulse.server.stop permission scope to control who can use this command.

remove

The remove command is used to stop a server and free its underlying resources.

impulse remove <server>

This is useful for making sure that the servers resources are completely freed up and that the server is no longer running. This command also works for servers with an inactiveTimeout of 0 that would otherwise never stop. The tradeoff is slower startup times as compared with the stop command.

Specify a server

The server argument is the name of the server you would like to remove. This is the name you defined in the servers section of the config.yaml file.

Examples

impulse remove smp

Permission Scope

Use the impulse.server.remove permission scope to control who can use this command.

reconcile

The reconcile command is used to force a server to reload its configuration and trigger a restart if needed.

impulse reconcile <server>

Although reconciliation normally happens automatically, this command can be helpful if you have forceServerReconciliation set to false. It will trigger the reconciliation immediately rather than waiting for a natural stop and start cycle. This is particularly helpful for long-lived lobbies.

Specify a server

The server argument is the name of the server you would like to reconcile. This is the name you defined in the servers section of the config.yaml file.

Examples

impulse reconcile smp

Permission Scope

Use the impulse.server.reconcile permission scope to control who can use this command.

status

The status command is used to check the status of a servers.

impulse status Optional<server>

If not provided with a server name, this command will return the status of all servers. If a server name is provided, it will return the status of that server only.

Specify a server

The server argument is the name of the server you would like to check the status of. This is the name you defined in the servers section of the config.yaml file.

Examples

Get the status of all servers:

impulse status

Get the status of a specific server:

impulse status smp

Permission Scope

Use the impulse.server.status permission scope to control who can use this command.

pin

The pin command is used to ensure that a server is not stopped or removed by Impulse.

impulse pin <server>

This is useful for servers that you want to prevent auto shutdown on temporarily. For long term static servers, use the allowAutoStop setting in the server configuration.

Specify a server

The server argument is the name of the server you would like to start. This is the name you defined in the servers section of the config.yaml file.

Examples

impulse pin smp

Permission Scope

Use the impulse.server.pin permission scope to control who can use this command.

unpin

The unpin command is used to allow Impulse to stop or remove a server that was previously pinned.

impulse unpin <server>

Specify a server

The server argument is the name of the server you would like to start. This is the name you defined in the servers section of the config.yaml file.

Examples

impulse unpin smp

Permission Scope

Use the impulse.server.unpin permission scope to control who can use this command.

Brokers

Impulse offloads the low level server management to a "broker". These brokers deal with implementing the server abstractions from Impulse into a specific platform. This allows Impulse itself to be smaller. You only need to include the brokers you will be using. The docker broker is included in the default distribution. The "lite" distribution does not include any brokers.

Dynamic Broker Loading

Impulse is capable of dynamically loading additional brokers at startup. To add a broker, place the jar in Impulse's data directory (normally plugins/impulse). Hot reloading is not currently supported. You will need to restart Velocity to update add a new broker or update an existing one.

First Party Brokers

We provide several first party brokers. You can find more information on each broker below.

• Docker
• JAR
• Kubernetes

Third Party Brokers

Additionally, you can create your own broker or source them from others. For more information see our guide on creating a broker. Here is a list of some notable third party brokers:

• Crafty Controller

Docker Broker

The docker broker connects directly to a Docker daemon. It is a good choice for small to medium-sized deployments since it is relatively easy to set up while still having a good amount of advanced options for configuration. It is included in the default Impulse distribution.

The docker broker is capable of connecting to a remote docker daemon. This is useful for advanced setups where you want to run the servers on a different machine. You can find instructions on how to set up a remote docker daemon here.

Configuration

Docker broker specific configuration values. These should be nested under the docker key in the server configuration.

TLS Configuration

Image Pull Policy

The image pull policy controls when we should attempt to pull the configured image. The following policies are available:

• Always: Always attempt to pull the image before starting the container
• Never: Never attempt to pull the image before starting the container
• IfNotPresent: Only attempt to pull the image if it is not already present on the host

Reconciliation Behavior

Most changes under the docker configuration key will require a server recreation to take effect. The docker broker will automatically stop, remove, and recreate the server container as needed. Because of this behavior, it is important to make sure any data you want to keep is stored in a volume. If not it will be lost during a reconciliation event. This can normally be accomplished by mounting a volume to the /data directory in the container.

Using TLS

Docker uses TLS to secure connections the the daemon over TCP. If you are using a remote docker daemon, it is highly encouraged to use TLS to secure the connection. The following instuctions will go over how to generate the keystore for Impulse from your PKI. To set up the certificates and keys in the first place follow docker's guide

Generating the Keystore

First, If you need to convert your client credentials to PKCS12 format you can use the following command. Replace <your_keystore_password> with a real password.

openssl pkcs12 -export -in client.crt -inkey client.key \
-out client-keystore.p12 -name client-cert -passout pass:<your_keystore_password>

Next generate the keystore by importing the client certificate and key.

keytool -importkeystore -srckeystore docker-keystore.p12 -srcstoretype PKCS12 \
-srcstorepass <your_keystore_password> -destkeystore docker-keystore.p12 -deststoretype PKCS12 \
-deststorepass <your_keystore_password>

Lastly, inject the CA certificate into the keystore.

keytool -importcert -alias ca-cert -file ca.crt \
-keystore docker-keystore.p12 -storepass your_keystore_password -noprompt

Your keystore should now be set up and ready to use with Impulse.

Example Configuration

servers:
  - name: "lobby"
    type: "docker"
    docker:
      portBindings:
        - "25566:25565"
      volumes:
        - "/path/to/host/data:/data"
      env:
        ONLINE_MODE: "false"
        EULA: "true"

Command Broker

The command broker allows you to execute arbitrary commands on the host machine in order to start a server. Impulse will then manage the associated process, assuming it is a minecraft server. This should be used with caution, or to integrate new server types for testing. For production you should use or create a broker.

Configuration

Command broker specific configuration values. These should be nested under the cmd key in the server configuration.

JAR Broker

The JAR broker is a specialization of the generic command broker. It is designed to give a better config interface when starting java based minecraft servers. As such its capabilities and limitations are the same as the command broker.

Configuration

JAR broker specific configuration values. These should be nested under the jar key in the server configuration.

Reconciliation

In Impulse, reconciliation is the process of ensuring that a servers configuration matches its running state. If they do not then action is taken to bring them back into alignment. The exact behavior of reconciliation is broker specific, but in general it will involve stopping the server, applying the new configuration, and restarting automatically. You can control this behavior by setting the reconciliationBehavior and reconciliationGracePeriod keys in the server configuration.

Reconciliation Behavior

FORCE

When the reconciliation behavior is set to FORCE Impulse will immediately trigger a server restart to reconcile. The players are given a configurable grace period to finish up before the server is stopped. Duting this time a warning banner will be displayed to the players.

ON_STOP

When the reconciliation behavior is set to ON_STOP Impulse will only reconcile the server when it naturally restarts,

Reconciliation Grace Period

This is the amount of time in seconds that Impulse will wait before stopping a server during a reconciliation event.

Custom Events

Impulse fires a few custom events that you can listen for in your own plugins.

ConfigReloadEvent

This is fired whenever Impulse reloads its configuration. You can listen for this event to inject your own logic into the resulting configuration.

Advanced Installation

The default distribution of Impulse includes several default brokers. This is useful for getting started quickly, but not optimal for production environments. This section will outline how to use the "lite" distribution of Impulse to set up your server with just the brokers you need. Some benefits of this approach include:

• Smaller jar size: The default distribution includes several brokers, which can be quite large. The "lite" distribution includes only the brokers you need.
• Faster startup time: No need to initialize brokers you don't need.
• Smaller attack surface: Fewer brokers means fewer potential vulnerabilities.

Downloading the "Lite" Distribution

You can find the "lite" distribution of Impulse on the releases page or under the "Lite" channel on Hangar. Download the jar file and place it in the plugins folder for Velocity.

Adding a Broker

To add a broker to your server, you will need to download the broker jar file and place it in the plugins/impulse folder in Velocity. The broker will be loaded automatically when the server starts. You can find first party brokers on the releases page.

KDocs

The generated KDocs for Impulse can be found here. This will give you a detailed look at the Impulse API and how to use it.

Contributing

We are happy to accept contributions from people with all levels of experience. If you have a feature you would like to see, or a bug you would like fix, feel free tp open an PR. If you are new to the project take a look at our issues tagged with good first issue.

Beyond that there are a few guidelines we would like you to follow:

• If it is a particularly large feature, please open an issue first so we can discuss the implementation.
• Make sure you cover your contributions with tests as much as possible
• Once approved to run, make sure your code passes all tests and linters

By contributing to this project, you agree that your contributions will be licensed under the project's license ( AGPLv3). We do not require a CLA, so you retain the copyright to your contributions.

Creating a Broker

Creating a custom broker for Impulse is a simple process! This guide will walk you through the steps to create a broker for your favorite server software.

Including the API

The first step is to include the Impulse API in your project. We publish to the GitHub Package Registry, so you just have to add the following to your build.gradle file:

dependencies {
    implementation 'club.arson.impulse:impulse-api'
}

repositories {
    maven {
        name = "Impulse"
        url = uri("https://maven.pkg.github.com/Arson-Club/Impulse")
    }
}

The Broker Interface

The core component of a broker is its implementation of the Broker interface (club.arson.impulse.api.server.Broker). Here you will implement all the functions required for impulse to interact with the server software. For specifics on what each function does, refer to the KDocs.

The Broker Configuration

Most brokers will require some sort of configuration to be able to set up and manage servers properly. To do this, simply create a data class and annotate it with @BrokerConfig("your-broker-id"). Impulse will handle loading your configuration for you. Make sure to include a @Serializable annotation on the class as well.

The Broker Factory

The final step is to implement the BrokerFactory interface (club.arson.impulse.api.server.BrokerFactory). This is used by Impulse to create instances of your broker as needed. The most important thing here is the NAME field. It will be used to identify your broker in the configuration file, and to link it to your Configuration class.

Licensing

Impulse is licensed under AGPL-3.0. You can find the full license text in the LICENSE file.

External Libraries

Impulse distributes the following libraries. You can find more information about their licensing on their respective pages.

Impulse App

Docker Broker

Documentation

This documentation also uses the following technologies and libraries: