Skip to main content

Geyser API

Geyser has an API to extend what is possible with Geyser, and to allow you to interact with Geyser in your own plugins, mods, or extensions.

Where can I use the Geyser API?​

You could use the Geyser API in:

  • A plugin for Paper/Spigot, Velocity, Waterfall/BungeeCord, etc.
  • A mod for Fabric or NeoForge
  • A Geyser Extension

Accessing the Geyser API​

See here for how to include the Geyser API dependency in your project.

Documentation​

The Geyser API offers events to subscribe to, or information on whether a player is joining through Geyser, and gives you the ability to enhance what is possible with Geyser (i.e. register custom items). (soon, blocks and entities too). It can be used easily in Geyser Extensions, see here for details on those.

Quick overview:

info

Javadocs can be found here.

GeyserApi:​

The GeyserApi interface serves as a central access point to various functionalities provided by the Geyser API, providing methods to e.g. interact with player connections. It extends the Base API interface, which provides basic information about individual players.

The class GeyserApi is the base class of the API and you need to use it to access any part of the API.
To access it, you simply type:

GeyserApi.api();

After you got the instance, you have access to all the methods.
Use the documentation in the API module to see (and get info about) every single method available.
Most API methods have a simple explanation. Since the Geyser API extends the Base API that is shared across Floodgate and Geyser, you can also use the methods from the Base API.

We'll highlight a few to get you started quickly:​

GeyserApi#isBedrockPlayer(UUID)
Used to check if the given UUID of an online player is a Bedrock player.

GeyserApi#connectionByUuid(UUID)
Used to get the Connection of an online player.
This method will return null if the player is not a Bedrock player.

info

You don't need to wait until the Bedrock player is online to use the getPlayer and isBedrockPlayer methods.
You can even use them in the pre-login events.

GeyserApi#sendForm(UUID, Form(Builder))
Used to send a form to the Bedrock player with the given UUID.
Click here to get more information about Forms.

GeyserApi#onlineConnectionsCount()
Used to get the amount of online Bedrock players.

Short Overview of the Geyser API​

Cumulus​

While technically not directly in the Geyser API, the Cumulus library is also provided by the Geyser API. It allows you to send Bedrock edition forms to players. See Cumulus for more information.

Events​

The event package contains all the events that Geyser fires. See here for detailed information on how to listen to Geyser events.

Command​

This package contains classes and interfaces related to commands in Geyser, which allows Geyser Extensions to register custom commands.

Entity​

The Entity package contains classes and interfaces related to entities in Geyser, like the GeyserPlayerEntity interface, which represents a player entity in Geyser. This interface extends the GeyserEntity interface, while providing additional functionality specifically for player entities, like currently, showing emotes.

Item​

The item package contains classes and interfaces related to items in Geyser. You can create custom items and register them using the Geyser API. See here for detailed information on how to register custom items.

Block​

The block package contains classes and interfaces related to blocks in Geyser. You can create custom blocks using this package, and register them in using the GeyserDefineCustomBlocksEvent. See here for detailed information.

Network​

The network package contains basic information about the remote server via the RemoteServer interface, such as the server's IP address and port, and the protocol version of the remote server. Or the auth type. You can also get the port/IP that Geyser listens to via the BedrockListener interface.

Skin​

The skin package contains some records representing skin data. If you want to change the skin of players, you can listen to the SessionSkinApplyEvent, and set a new skin, skin geometry or cape there.

Pack​

The pack package contains classes and interfaces related to resource packs in Geyser. You can create custom resource packs and send them to individual sessions before they log in using the SessionLoadResourcePacksEvent. If you wish to send a resource pack to all sessions, you can use the GeyserLoadResourcePacksEvent.

Packs can be created using a PackCodec, such as the provided PathPackCodec. This allows you to load a Bedrock resource pack from a file path:

ResourcePack pack = ResourcePack.create(PackCodec.path(path));

Extension​

This package provides the necessary components to create and manage extensions. For a more detailed explanation of extensions, see here.