DOCSEARCHbyAlgolia
Submit Docs

Floodgate Documentation

repository·master·Indexed 20 days ago

https://github.com/geysermc/floodgate

Floodgate is a plugin that enables Bedrock Edition players using Geyser to connect to Java Edition servers in online mode by handling authentication and identity mapping. It allows Bedrock players to join online-mode servers without requiring a Java Edition account and provides tools for linking Java and Bedrock accounts, managing Bedrock whitelists via fwhitelist, and performing firewall connectivity checks.

Tokens
2.4K
Snippets
10
Records
12
Agent score
67%

What's inside Floodgate

  1. What is Floodgate and when to use it

    master
    Floodgate is a hybrid mode plugin designed to allow connections from Geyser to join Minecraft servers that are running in online-mode. It acts as a bridge that enables Bedrock Edition players (via Geyser) to authenticate and join online-mode Java Edition servers without requiring them to own a Java Edition account.

  3. Use the /linkaccount command to link Java and Bedrock accounts

    master

    The /linkaccount command allows players to link their Java Edition account with their Bedrock Edition account. The usage pattern depends on whether the player is currently on a Java or Bedrock account.

    For Java Players (Initiating a link)

    To start the linking process, a Java player must target a Bedrock player. This creates a link request and generates a code that the Bedrock player must use.

    Command: /linkaccount <player>

    For Bedrock Players (Completing a link)

    To complete the link, a Bedrock player must use the code generated by the Java player's request.

    Command: /linkaccount <player> <code>

    Requirements and Constraints

    • Permissions: Requires the Permission.COMMAND_LINK permission.
    • Configuration: The command is only registered if getPlayerLink().isEnabled() is true and either isEnableOwnLinking() or isEnableGlobalLinking() is enabled in the Floodgate configuration.
    • Targeting: The <player> argument accepts any username (both Java and Bedrock).
    # Java player initiates request for Bedrock player 'PlayerName'
/linkaccount PlayerName

# Bedrock player completes request using the provided code
/linkaccount JavaPlayerName 12345

  5. Implement the FloodgateCommand interface

    master

    To add a new command to the Floodgate platform, implement the FloodgateCommand interface. This interface provides two primary methods for command lifecycle management:

    1. buildCommand(CommandManager<UserAudience> commandManager): This is the required method where you define the command's structure, arguments, and logic using the provided CommandManager. The command must return a Command<? extends UserAudience>.
    2. shouldRegister(FloodgateConfig config): An optional method that allows you to conditionally register the command based on the current FloodgateConfig. By default, it returns true.
    public class MyCustomCommand implements FloodgateCommand {
    @Override
    public Command<? extends UserAudience> buildCommand(CommandManager<UserAudience> commandManager) {
        // Define your command logic here using the commandManager
        return commandManager.command("mycommand")
            .handler(ctx -> {
                // Handle command execution
            });
    }

    @Override
    public boolean shouldRegister(FloodgateConfig config) {
        // Return false if you want to disable this command via config
        return true;
    }
}

  6. Implement a Floodgate subcommand

    master

    To add a new command to the Floodgate platform, extend the FloodgateSubCommand abstract class. You must implement four methods to define the command's identity, documentation, security requirements, and logic:

    • name(): Returns the string used to invoke the command.
    • description(): Returns a brief explanation of what the command does.
    • permission(): Returns a Permission object defining the required authorization level to execute the command.
    • execute(CommandContext<UserAudience> context): Contains the core logic. The context provides access to the UserAudience, which represents the player or entity executing the command.
    public class MyCustomCommand extends FloodgateSubCommand {
    @Override
    public String name() {
        return "mycommand";
    }

    @Override
    public String description() {
        return "A description of my custom command";
    }

    @Override
    public Permission permission() {
        return Permission.OP; // Example permission
    }

    @Override
    public void execute(CommandContext<UserAudience> context) {
        // Command logic goes here
    }
}

  7. Manage the Floodgate whitelist with fwhitelist

    master

    The fwhitelist command provides an easy way to whitelist or remove Bedrock players from your server. This command is available on platforms that support a built-in whitelist (such as Spigot) but is not registered if using a Proxy configuration (ProxyFloodgateConfig).

    Usage

    Add a player to the whitelist: fwhitelist add <player> (or fwhitelist a <player>)

    Remove a player from the whitelist: fwhitelist remove <player> (or fwhitelist r <player>)

    Arguments

    • <player>: The identifier for the Bedrock player. The command supports various Bedrock identifiers via the PlayerAudienceArgument.
    # Examples
fwhitelist add <player_name_or_uuid>
fwhitelist remove <player_name_or_uuid>
fwhitelist a <player_name_or_uuid>
fwhitelist r <player_name_or_uuid>

  8. Use the /floodgate command and subcommands

    master

    The floodgate command serves as the primary entry point for Floodgate-related actions. Running the base /floodgate command without arguments will display a help message listing all available subcommands that the user has permission to access.

    Available subcommands include:

    • firewallcheck: Performs a firewall check.
    • version: Displays the current version information.
    /floodgate
/floodgate firewallcheck
/floodgate version

  9. Unlink a Java account from a Bedrock account using /unlinkaccount

    master

    The /unlinkaccount command allows a Bedrock player to disconnect their linked Java Edition account from their Floodgate account.

    Requirements:

    • The player must have the Permission.COMMAND_UNLINK permission.
    • The player linking feature must be enabled in the FloodgateConfig (player-link.enabled must be true).
    • Either enable-own-linking or enable-global-linking must be enabled in the configuration.

    Behavior:

    • If the player is not currently linked, they will receive a NOT_LINKED message.
    • If the unlinking process fails, they will receive an UNLINK_ERROR message.
    • Upon success, they will receive an UNLINK_SUCCESS message.
    • If using Global Linking with a database implementation, a notice regarding linking information will be displayed.
    /unlinkaccount

  10. Use the version command to check Floodgate status

    master

    The /version subcommand displays information about your current Floodgate installation, including the current version, the git branch, and whether a newer build is available.

    If you are running a standard build on the main branch, the command will attempt to fetch the latest build information from the remote repository to notify you if you are behind. If you are running a custom version or a non-main branch, certain version-checking features may be unavailable.

    /version

  11. Use the floodgate-test command

    master

    The floodgate-test command is a debug utility used to verify Floodgate functionality. When executed, it retrieves the current number of Floodgate players via the FloodgateApi and sends the count as a message to the command sender.

    Note: This command is only registered and available if DEBUG_MODE is enabled in the Floodgate configuration.

    /floodgate-test

  12. Check firewall connectivity with the firewall subcommand

    master

    The /floodgate firewall subcommand checks if your outgoing firewall allows Floodgate to function correctly by attempting to connect to necessary endpoints (such as the global API health URL).

    When executed, the command will:

    1. Test connectivity to specific services (e.g., global api).
    2. Report success or failure for each test in the chat.
    3. Provide a summary of how many checks passed versus the total number of checks performed.

    If a check fails, the command will output the error details/stack trace to help diagnose which network path or endpoint is being blocked.

    /floodgate firewall