Getting Started

Get Fluxer4J installed and your first bot running in minutes.

Installation

Fluxer4J is published to the GitLab Package Registry. Add the repository and dependency to your build file.

1. Add the Repository

<repositories>
  <repository>
    <id>gitlab-maven</id>
    <url>https://gitlab.nexusrealms.de/api/v4/projects/35/packages/maven</url>
  </repository>
</repositories>

repositories {
    maven {
        url = uri("https://gitlab.nexusrealms.de/api/v4/projects/35/packages/maven")
        name = "gitlab-maven"
    }
}

repositories {
    maven {
        url "https://gitlab.nexusrealms.de/api/v4/projects/35/packages/maven"
        name "gitlab-maven"
    }
}

2. Add the Dependency

<dependency>
    <groupId>fluxer4j</groupId>
    <artifactId>fluxer4j</artifactId>
    <version>1.0.4</version>
</dependency>

implementation("fluxer4j:fluxer4j:1.0.4")

implementation 'fluxer4j:fluxer4j:1.0.4'

Build from Source

git clone https://gitlab.nexusrealms.de/Flexhd/fluxer4j.git
cd fluxer4j
mvn install

Quick Start (Recommended)

The easiest way to build a bot is with Fluxer4JBot, which combines the API client, gateway, and command service into a single builder.

import fluxer4j.Fluxer4JBot;
import fluxer4j.FluxerConfig;

public class MyBot {
    public static void main(String[] args) throws Exception {

        Fluxer4JBot bot = Fluxer4JBot.builder("Bot YOUR_TOKEN")
            .config(FluxerConfig.builder()
                .reconnectAttemptDelay(2)
                .enableRateLimiting(true)
                .build())
            .commandPrefix('!')
            .addCommandModule(BasicCommands.class)
            .build();

        // Listen for messages
        bot.onMessageCreate(msg -> {
            if (msg.getAuthor() != null) {
                System.out.println(msg.getAuthor().getUsername()
                    + ": " + msg.getContent());
            }
        });

        // Listen for the READY event
        bot.getGateway().addReadyListener(ready -> {
            System.out.println("Bot is online!");
        });

        // Connect and block
        bot.start().join();
        Thread.currentThread().join();
    }
}

⚠

Never commit your token! Store it in a config file, environment variable, or secret manager. Tokens prefixed with Bot are bot tokens; user tokens start with flx_.

Manual Wiring

For full control, use ApiClient and GatewayClient directly.

import fluxer4j.ApiClient;
import fluxer4j.FluxerConfig;
import fluxer4j.gateway.GatewayClient;

FluxerConfig config = new FluxerConfig();
config.setReconnectAttemptDelay(2);
config.setEnableRateLimiting(true);

ApiClient api = new ApiClient("Bot YOUR_TOKEN", config);
GatewayClient gateway = new GatewayClient("Bot YOUR_TOKEN", config);

gateway.addMessageCreateListener(msg ->
    System.out.println(msg.getContent())
);

gateway.connectAsync().join();

Configuration

FluxerConfig controls behavior for both the API client and gateway.

Property	Type	Default	Description
`reconnectAttemptDelay`	int	10	Seconds between reconnect attempts
`fluxerApiBaseUrl`	String	`https://api.fluxer.app/v{v}`	Base URL for REST API
`version`	int	1	API version (replaces `{v}` in URL)
`fluxerGatewayUrl`	String	`wss://gateway.fluxer.app/...`	Gateway WebSocket URL
`enableRateLimiting`	boolean	true	Enable client-side rate limiting
`ignoredGatewayEvents`	List<String>	empty	Gateway event names to ignore
`presence`	PresenceUpdateGatewayData	null	Initial bot presence/status
`httpClient`	HttpClient	auto	Custom HTTP client instance
`logger`	Logger	auto	Custom SLF4J logger

Builder Pattern

FluxerConfig config = FluxerConfig.builder()
    .reconnectAttemptDelay(5)
    .enableRateLimiting(true)
    .ignoredGatewayEvents(List.of("PRESENCE_UPDATE", "TYPING_START"))
    .build();

Project Structure

fluxer4j/
├── ApiClient.java           // REST API client (150+ endpoints)
├── Fluxer4JBot.java         // High-level bot wrapper
├── FluxerConfig.java        // Configuration
├── FluxerApiException.java  // Custom exception
├── commands/                // Command framework (28 files)
│   ├── CommandService.java
│   ├── ModuleBase.java
│   ├── CommandContext.java
│   └── attributes/          // @CommandAttribute, @AliasAttribute, ...
├── data/
│   ├── models/              // 55+ DTOs (User, Message, Channel, ...)
│   └── enums/               // 19 enums (Permissions, ChannelType, ...)
├── embed/                   // EmbedBuilder + field/author/footer builders
├── gateway/                 // GatewayClient + 49 event payloads
├── ratelimit/               // Sliding-window rate limiter
└── voice/                   // VoiceManager, UDP & LiveKit connections

Example Project

A full runnable example is included in examples/basic-bot/ with:

ExampleBot.java — Main entry point with config loading and bot setup
BasicCommands.java — Command module with ping, hello, info, embed, echo, add
MusicCommands.java — Voice channel commands (join, leave, play, stop)
ConfigLoader.java — YAML config file loading
config.yml — Token configuration file

Run it with mvn exec:java from the examples/basic-bot directory after setting your token.