API & extension docs & Geyser system property docs (#159)
* initial start on api docs * oops * oops #2 * oops #3 * move global api info to global-api.md page, fix typo * Initial setup page * the extensions template and list is now in the geysermc org * add fabric event subscribe example * fix outdated naming * the extensions template and list is now in the geysermc org, and therefore official * spigot/paper plugin geyser-api docs * minor tweaks * the setup guide should be in a separate PR, oops * Updated docs for resource packs PR * document system properties * Apply suggestions from code review Co-authored-by: Redned <redned235@gmail.com> * move and shuffle pages, address review * -DGeyser.BedrockNetworkThreads exists too, apparently * turn notes into banners * be more specific to indicate this to be advanced stuff * adjust texts & address camotoy's review * nms good dont disable * add chapter on event priorities * remove whitespace * main instead of maven-snapshots; floodgate-api 2.2.2 * Move around pages in toc.yml, no need to fully copy event priorities * Apply suggestions from code review Co-authored-by: Tim203 <mctim203@gmail.com> * apply command suggestion Co-authored-by: Tim203 <mctim203@gmail.com> * reduce command comments * specify that this is the Geyser API * Apply suggestions from code review Co-authored-by: Redned <redned235@gmail.com> * dont repeat that the bulk of code would go into a post init event; we already say that * adress review * extensions currently target Base API version --------- Co-authored-by: JensC <jenscollaertyprive@hotmail.com> Co-authored-by: Redned <redned235@gmail.com> Co-authored-by: Tim203 <mctim203@gmail.com>
This commit is contained in:
13 files changed
+516
-95
No files matched your search
+53
-39
@@ -1,47 +1,41 @@
|
||||
- title: Geyser Documentation
|
||||
url: "geyser/"
|
||||
links:
|
||||
- title: "Setup"
|
||||
- title: Setting up Geyser
|
||||
url: "geyser/setup/"
|
||||
children:
|
||||
- title: Plugin Setup
|
||||
url: "geyser/setup/#plugin-setup"
|
||||
- title: Videos
|
||||
url: "geyser/setup/#setup-videos"
|
||||
- title: "Standalone"
|
||||
- title: Supported Hosting Providers
|
||||
url: "geyser/supported-hosting-providers/"
|
||||
- title: Using Geyser with Consoles
|
||||
url: "geyser/using-geyser-with-consoles/"
|
||||
- title: Using playit.gg with Geyser
|
||||
url: "geyser/playit-gg/"
|
||||
- title: Setting up Geyser-Standalone
|
||||
url: "geyser/standalone/"
|
||||
children:
|
||||
- title: Termux (Android)
|
||||
url: "geyser/standalone/#termux-android"
|
||||
- title: NewTerm 2 (iOS)
|
||||
url: "geyser/standalone/#newterm-2-ios"
|
||||
- title: FAQ
|
||||
url: "geyser/faq/"
|
||||
- title: Creating a Startup Script
|
||||
url: "geyser/creating-a-startup-script/"
|
||||
- title: Common Issues
|
||||
url: "geyser/common-issues/"
|
||||
children:
|
||||
- title: Fixing 'Unable to Connect to World'
|
||||
url: "geyser/fixing-unable-to-connect-to-world/"
|
||||
- title: Understanding the Config
|
||||
- title: Configuring Geyser
|
||||
url: "geyser/understanding-the-config/"
|
||||
- title: Standalone Command Line Arguments
|
||||
url: "geyser/standalone-command-line-arguments/"
|
||||
- title: Creating a Startup Script
|
||||
url: "geyser/creating-a-startup-script/"
|
||||
- title: Commands
|
||||
url: "geyser/commands/"
|
||||
- title: Supported Hosting Providers
|
||||
url: "geyser/supported-hosting-providers/"
|
||||
- title: Using Geyser with Consoles
|
||||
url: "geyser/using-geyser-with-consoles/"
|
||||
- title: Anticheat Compatibility
|
||||
url: "geyser/anticheat-compatibility/"
|
||||
- title: Using Geyser or Floodgate as a dependency
|
||||
url: "geyser/using-geyser-or-floodgate-as-a-dependency/"
|
||||
- title: Current Limitations
|
||||
url: "geyser/current-limitations/"
|
||||
- title: Using playit.gg with Geyser
|
||||
url: "geyser/playit-gg/"
|
||||
children:
|
||||
- title: Commands
|
||||
url: "geyser/commands/"
|
||||
- title: Geyser Command Line Arguments and System Properties
|
||||
url: "geyser/geyser-command-line-arguments-and-system-properties/"
|
||||
- title: FAQ
|
||||
url: "geyser/faq/"
|
||||
children:
|
||||
- title: Anticheat Compatibility
|
||||
url: "geyser/anticheat-compatibility/"
|
||||
- title: Current Limitations
|
||||
url: "geyser/current-limitations/"
|
||||
- title: Custom items with Geyser
|
||||
url: "geyser/custom-items/"
|
||||
children:
|
||||
@@ -51,6 +45,27 @@
|
||||
url: "geyser/custom-items/#geyser-extensions"
|
||||
- title: Resource pack
|
||||
url: "geyser/custom-items/#resource-pack"
|
||||
- title: Geyser API
|
||||
url: "geyser/api/"
|
||||
children:
|
||||
- title: Getting Started
|
||||
url: "geyser/getting-started-with-the-api/"
|
||||
- title: Overview
|
||||
url: "geyser/api/#short-overview-of-the-api"
|
||||
- title: Events
|
||||
url: "geyser/events/"
|
||||
- title: Forms and Cumulus
|
||||
url: "geyser/forms/"
|
||||
- title: Geyser Extensions
|
||||
url: "geyser/extensions/"
|
||||
children:
|
||||
- title: Main class
|
||||
url: "geyser/extensions/#creating-the-main-class"
|
||||
- title: Creating Commands
|
||||
url: "geyser/extensions/#creating-commands-with-geyser-extensions"
|
||||
- title: Global API
|
||||
url: "geyser/global-api/"
|
||||
|
||||
- title: Floodgate Documentation
|
||||
url: "floodgate/"
|
||||
links:
|
||||
@@ -63,14 +78,17 @@
|
||||
children:
|
||||
- title: Whitelist command
|
||||
url: "floodgate/features/#whitelist-command"
|
||||
- title: Global Api
|
||||
url: "floodgate/features/#what-is-the-global-api"
|
||||
- title: "Commands"
|
||||
url: "floodgate/commands/"
|
||||
- title: Skin Uploading
|
||||
url: "floodgate/features/#what-is-skin-uploading"
|
||||
- title: "Floodgate API"
|
||||
url: "floodgate/api/"
|
||||
- title: "FloodgatePlayer"
|
||||
url: "floodgate/player/"
|
||||
children:
|
||||
- title: "FloodgatePlayer"
|
||||
url: "floodgate/player/"
|
||||
- title: "Forms and Cumulus"
|
||||
url: "geyser/forms/"
|
||||
- title: "Linking"
|
||||
url: "floodgate/linking/"
|
||||
children:
|
||||
@@ -78,10 +96,6 @@
|
||||
url: "floodgate/linking/#what-is-global-linking"
|
||||
- title: Local Linking
|
||||
url: "floodgate/linking/#local-linking"
|
||||
- title: "Forms and Cumulus"
|
||||
url: "floodgate/forms/"
|
||||
- title: "Commands"
|
||||
url: "floodgate/commands/"
|
||||
- title: Other
|
||||
url: "other/"
|
||||
links:
|
||||
@@ -91,11 +105,11 @@
|
||||
url: "other/hurricane/"
|
||||
- title: "GeyserConnect"
|
||||
url: "other/geyserconnect/"
|
||||
- title: "Community Geyser Projects"
|
||||
url: "other/community-geyser-projects/"
|
||||
- title: "Test Server"
|
||||
url: "other/test-server/"
|
||||
- title: "Developer Guide"
|
||||
url: "other/developer-guide/"
|
||||
- title: "Community Geyser Projects"
|
||||
url: "other/community-geyser-projects/"
|
||||
- title: "Geyser Discord Bot Usage"
|
||||
url: "other/discord-bot-usage/"
|
||||
+7
-17
@@ -2,27 +2,13 @@
|
||||
title: Floodgate API
|
||||
---
|
||||
|
||||
### Floodgate has an API to extend what is possible and allow servers to get information about the Bedrock client. It also allows other plugins access to [Cumulus](/floodgate/forms/)
|
||||
### Floodgate has an API to extend what is possible and allow servers to get information about the Bedrock client. It also allows other plugins access to [Cumulus](/geyser/forms/)
|
||||
|
||||
This page will contain information about class FloodgateApi.<br>
|
||||
See the sidebar for more information about other parts of the API.
|
||||
|
||||
### Accessing the Floodgate API
|
||||
|
||||
Floodgate uses the open collaboration repo. The following example is for Maven, but the same concept applies for Gradle etc.
|
||||
```xml
|
||||
<repository>
|
||||
<id>opencollab-snapshot</id>
|
||||
<url>https://repo.opencollab.dev/maven-snapshots/</url>
|
||||
</repository>
|
||||
|
||||
<dependency>
|
||||
<groupId>org.geysermc.floodgate</groupId>
|
||||
<artifactId>api</artifactId>
|
||||
<version>2.2.0-SNAPSHOT</version>
|
||||
<scope>provided</scope>
|
||||
</dependency>
|
||||
```
|
||||
See [here](/geyser/getting-started-with-the-api) for how to include the Floodgate API in your project.
|
||||
|
||||
The Floodgate API has changed in Floodgate 2.0. The most important change is that the API methods are no longer static and instead instance-based, as shown below.
|
||||
---
|
||||
@@ -37,6 +23,10 @@ After you got the instance, you have access to all the methods.<br>
|
||||
Use the documentation in the API module to see (and get info about) every single method available.
|
||||
Most [API methods have a simple explanation](https://github.com/GeyserMC/Floodgate/tree/master/api/src/main/java/org/geysermc/floodgate/api).
|
||||
|
||||
<div class="alert alert-info" role="alert">
|
||||
Note: To see full, detailed documentation, see the <a href="https://repo.opencollab.dev/javadoc/maven-snapshots/org/geysermc/floodgate/api/2.2.2-SNAPSHOT">javadocs</a>.
|
||||
</div>
|
||||
|
||||
#### We'll highlight a few to get you started quickly:
|
||||
`FloodgateApi#isFloodgatePlayer(UUID)`<br>
|
||||
Used to check if the given UUID of an **online** player is a Bedrock player.
|
||||
@@ -54,7 +44,7 @@ Click [here](/floodgate/linking/) to get more information about the PlayerLink c
|
||||
|
||||
`FloodgateApi#sendForm(UUID, Form(Builder))`<br>
|
||||
Used to send a form to the Bedrock player with the given UUID.<br>
|
||||
Click [here](/floodgate/forms/) to get more information about Forms.
|
||||
Click [here](/geyser/forms/) to get more information about Forms.
|
||||
|
||||
### Using the API on backend servers
|
||||
In order to successfully use the API on backend Spigot servers when using a proxy, `send-floodgate-data` must be set to `true` on the proxy Floodgate's config, and the `key.pem` file must be identical between all Floodgate instances.
|
||||
@@ -12,11 +12,6 @@ You can also specify a UUID: `fwhitelist add 00000000-0000-0000-0009-01f64f65c7c
|
||||
|
||||
The permission node is `floodgate.command.fwhitelist`.
|
||||
|
||||
## What is the Global Api?
|
||||
The Global Api is an API that is available for every server. It currently includes: [Global Linking](#what-is-global-linking), [skin uploading](#what-is-skin-uploading), getting a xuid by gamertag, and getting a gamertag by xuid.
|
||||
We don't store anything else than you can access by the Global Api, except for some non-identifiable metrics. The source code of the Global Api is available [here](https://github.com/GeyserMC/global_api) and the source code of the Global Linking server is available [here](https://github.com/GeyserMC/GlobalLinkServer).
|
||||
|
||||
|
||||
## What is skin uploading?
|
||||
Skins of Bedrock player should be visible to Java players on servers with Floodgate 2.0 installed.
|
||||
If they aren't, it's most likely that the skin uploading queue has grown too large and can take a while to upload your skin.
|
||||
|
||||
@@ -10,5 +10,5 @@ This is something you install in addition to Geyser. Unlike Geyser, Floodgate ca
|
||||
|
||||
## What has Floodgate 2.0 to offer?
|
||||
Floodgate 2.0 is a rewrite of Floodgate 1.0, with various bugfixes and improvements. It also introduces new features: being able to [see Bedrock player skins on Java edition](/floodgate/features/#what-is-skin-uploading),
|
||||
being able to [use Bedrock forms](/floodgate/forms/), link your account once and login on every server that has [Global Linking](/floodgate/features/#what-is-global-linking) enabled,
|
||||
being able to [use Bedrock forms](/geyser/forms/), link your account once and login on every server that has [Global Linking](/floodgate/features/#what-is-global-linking) enabled,
|
||||
and the [Global Api](/floodgate/features/#what-is-the-global-api).
|
||||
@@ -0,0 +1,102 @@
|
||||
---
|
||||
title: 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 Forge
|
||||
- A Geyser Extension
|
||||
|
||||
### Accessing the Geyser API
|
||||
See [here](/geyser/getting-started-with-the-api) 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](/other/extensions) for details on those.
|
||||
|
||||
**Quick overview:** <br>
|
||||
<div class="alert alert-info" role="alert">
|
||||
Note: To see full, detailed documentation, see the <a href="https://repo.opencollab.dev/javadoc/maven-snapshots/org/geysermc/geyser/api/2.1.2-SNAPSHOT">javadocs</a>.
|
||||
</div>
|
||||
|
||||
#### [GeyserApi](https://github.com/GeyserMC/Geyser/blob/master/api/src/main/java/org/geysermc/geyser/api/GeyserApi.java):
|
||||
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](https://github.com/GeyserMC/api/blob/master/base/src/main/java/org/geysermc/api/GeyserApiBase.java) 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.<br>
|
||||
To access it, you simply type:
|
||||
```java
|
||||
GeyserApi.api();
|
||||
```
|
||||
|
||||
After you got the instance, you have access to all the methods.<br>
|
||||
Use the documentation in the API module to see (and get info about) every single method available.
|
||||
Most [API methods have a simple explanation](https://github.com/GeyserMC/Geyser/blob/master/api/src/main/java/org/geysermc/geyser/api/GeyserApi.java).
|
||||
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](https://github.com/GeyserMC/api/blob/master/base/src/main/java/org/geysermc/api/GeyserApiBase.java).
|
||||
|
||||
|
||||
#### We'll highlight a few to get you started quickly:
|
||||
`GeyserApi#isBedrockPlayer(UUID)`<br>
|
||||
Used to check if the given UUID of an **online** player is a Bedrock player.
|
||||
|
||||
`GeyserApi#connectionByUuid(UUID)`<br>
|
||||
Used to get the [Connection](https://github.com/GeyserMC/api/blob/master/base/src/main/java/org/geysermc/api/connection/Connection.java) of an **online** player.<br>
|
||||
This method will return null if the player is not a Bedrock player.
|
||||
|
||||
<div class="alert alert-info" role="alert">
|
||||
You don't need to wait until the Bedrock player is online to use the getPlayer and isBedrockPlayer methods.<br>
|
||||
You can even use them in the pre-login events.
|
||||
</div>
|
||||
|
||||
`GeyserApi#sendForm(UUID, Form(Builder))`<br>
|
||||
Used to send a form to the Bedrock player with the given UUID.<br>
|
||||
Click [here](/floodgate/forms/) to get more information about Forms.
|
||||
|
||||
`GeyserApi#onlineConnectionsCount()`<br>
|
||||
Used to get the amount of online Bedrock players.
|
||||
|
||||
### Short Overview of the Geyser API
|
||||
|
||||
#### [Cumulus](https://github.com/GeyserMC/Cumulus/tree/master/src/main/java/org/geysermc/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](/floodgate/forms/) for more information.
|
||||
|
||||
#### [Events](https://github.com/GeyserMC/Geyser/tree/master/api/src/main/java/org/geysermc/geyser/api/event)
|
||||
The event package contains all the events that Geyser fires. See [here](/geyser/events) for detailed information on how to listen to Geyser events.
|
||||
|
||||
#### [Command](https://github.com/GeyserMC/Geyser/tree/master/api/src/main/java/org/geysermc/geyser/api/command)
|
||||
This package contains classes and interfaces related to commands in Geyser, which allows [Geyser Extensions](/geyser/extensions) to register custom commands.
|
||||
|
||||
#### [Entity](https://github.com/GeyserMC/Geyser/tree/master/api/src/main/java/org/geysermc/geyser/api/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](https://github.com/GeyserMC/Geyser/tree/master/api/src/main/java/org/geysermc/geyser/api/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](/geyser/custom-items) for detailed information on how to register custom items.
|
||||
|
||||
#### [Network](https://github.com/GeyserMC/Geyser/tree/master/api/src/main/java/org/geysermc/geyser/api/network)
|
||||
The network package contains basic information about the remote server via the
|
||||
[RemoteServer](https://github.com/GeyserMC/Geyser/blob/master/api/src/main/java/org/geysermc/geyser/api/network/RemoteServer.java)
|
||||
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](https://github.com/GeyserMC/Geyser/blob/master/api/src/main/java/org/geysermc/geyser/api/network/BedrockListener.java) interface.
|
||||
|
||||
#### [Pack](https://github.com/GeyserMC/Geyser/tree/master/api/src/main/java/org/geysermc/geyser/api/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](https://github.com/GeyserMC/Geyser/blob/master/api/src/main/java/org/geysermc/geyser/api/event/bedrock/SessionLoadResourcePacksEvent.java).
|
||||
If you wish to send a resource pack to all sessions, you can use the [GeyserLoadResourcePacksEvent](https://github.com/GeyserMC/Geyser/blob/master/api/src/main/java/org/geysermc/geyser/api/event/lifecycle/GeyserLoadResourcePacksEvent.java).
|
||||
|
||||
Packs can be created using a [PackCodec](https://github.com/GeyserMC/Geyser/blob/master/api/src/main/java/org/geysermc/geyser/api/pack/PackCodec.java), such as the provided [PathPackCodec](https://github.com/GeyserMC/Geyser/blob/master/api/src/main/java/org/geysermc/geyser/api/pack/PathPackCodec.java).
|
||||
This allows you to load a Bedrock resource pack from a file path:
|
||||
```java
|
||||
ResourcePack pack = ResourcePack.create(PackCodec.path(path));
|
||||
```
|
||||
|
||||
#### [Extension](https://github.com/GeyserMC/Geyser/tree/master/api/src/main/java/org/geysermc/geyser/api/extensions)
|
||||
This package provides the necessary components to create and manage extensions.
|
||||
For a more detailed explanation of extensions, see [here](/geyser/extensions).
|
||||
@@ -117,11 +117,11 @@ NonVanillaCustomItemData data = NonVanillaCustomItemData.builder()
|
||||
.javaId(1)
|
||||
```
|
||||
2. There are many other options you can set to match the behavior that you require for your item. You can see them [here](https://github.com/GeyserMC/Geyser/blob/master/api/geyser/src/main/java/org/geysermc/geyser/api/item/custom/NonVanillaCustomItemData.java)
|
||||
3. Register your item in the pre init event:
|
||||
3. Register your item in the GeyserDefineCustomItems event:
|
||||
```java
|
||||
@Subscribe
|
||||
public void onGeyserPreInitializeEvent(GeyserDefineCustomItemsEvent event) {
|
||||
event.registerCustomItem(data);
|
||||
public void onGeyserDefineCustomItemsEvent(GeyserDefineCustomItemsEvent event) {
|
||||
event.register(data);
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@@ -0,0 +1,102 @@
|
||||
---
|
||||
title: Geyser Events
|
||||
---
|
||||
|
||||
# Geyser Events
|
||||
Geyser has a powerful event system that allows you to listen to events that are sent by Geyser. Events are at the heart of Geyser Extensions, and can be used by plugins and mods as well.
|
||||
|
||||
Full documentation can be found [here](https://github.com/GeyserMC/Geyser/tree/master/api/src/main/java/org/geysermc/geyser/api/event).
|
||||
|
||||
## Event Categories
|
||||
To use events in a Spigot/Paper plugin or a Fabric mod, you need to register the Geyser Event Bus as a listener and then subscribe to the events you want to listen to.
|
||||
Extensions can use the @Subscribe annotation.
|
||||
|
||||
Events are categorized into the following categories:
|
||||
- [Bedrock](https://github.com/GeyserMC/Geyser/tree/master/api/src/main/java/org/geysermc/geyser/api/event/bedrock): Events that are sent for each connecting Bedrock client,
|
||||
for example the ClientEmoteEvent that is sent when a Bedrock player uses an emote - or the SessionLoginEvent that is sent when a Bedrock player logged in and is about to join a server.
|
||||
- [Java](https://github.com/GeyserMC/Geyser/tree/master/api/src/main/java/org/geysermc/geyser/api/event/java): Events that are sent for the java server, for example
|
||||
the ServerDefineCommandsEvent - it is fired when the Java sends the commands to show for Bedrock players.
|
||||
- [Connection](https://github.com/GeyserMC/Geyser/tree/master/api/src/main/java/org/geysermc/geyser/api/event/connection): Connection-related events, such as a ping event to return e.g. a custom MOTD.
|
||||
- [Lifecycle](https://github.com/GeyserMC/Geyser/tree/master/api/src/main/java/org/geysermc/geyser/api/event/lifecycle): Events that are sent during Geyser's lifecycle, such as the loading of custom items, resource packs, or Geyser commands.
|
||||
|
||||
To see all the events in the respective categories, click on the links above.
|
||||
|
||||
## Usage Examples:
|
||||
|
||||
Each method that you want to subscribe to an event needs to be annotated with the @Subscribe annotation (from the GeyserMC events package).
|
||||
```java
|
||||
@Subscribe
|
||||
public void onGeyserLoadResourcePacksEvent(GeyserLoadResourcePacksEvent event) {
|
||||
logger().info("Loading: " + event.resourcePacks().size() + " resource packs.");
|
||||
// you could add a resource pack with event.resourcePacks().add(path-to-pack)
|
||||
}
|
||||
```
|
||||
If you wish to listen to events in a Spigot/Paper plugin or a Fabric mod, you need to register the Geyser Event Bus as a listener first. Just make sure you implement `EventRegistrar` in the main class of your mod or plugin.
|
||||
Extensions do not need to do that - they are automatically registered, so a simple @Subscribe annotation is enough.
|
||||
|
||||
**Fabric mod example:**
|
||||
```java
|
||||
public class ExampleMod implements ModInitializer, EventRegistrar {
|
||||
public static final Logger LOGGER = LoggerFactory.getLogger("modid");
|
||||
|
||||
@Override
|
||||
public void onInitialize() {
|
||||
ServerLifecycleEvents.SERVER_STARTING.register((server) -> {
|
||||
GeyserApi.api().eventBus().register(this, ExampleMod.class); // register your mod & this class as a listener
|
||||
});
|
||||
|
||||
LOGGER.info("Geyser is cool!");
|
||||
}
|
||||
|
||||
// here an event, we subscribe as usual with the @Subscribe annotation
|
||||
@Subscribe
|
||||
public void onGeyserPostInitializeEvent(GeyserPostInitializeEvent eventad {
|
||||
LOGGER.info("Geyser started!");
|
||||
}
|
||||
}
|
||||
```
|
||||
<div class="alert alert-info" role="alert">
|
||||
Do note: We cannot directly register the event bus in the mod initializer, since the Geyser API would not be loaded yet.
|
||||
</div>
|
||||
|
||||
Therefore, we register it in the server starting event provided by the Fabric API.
|
||||
|
||||
**Paper/Spigot plugin example:**
|
||||
|
||||
1. In your plugin.yml, add the following lines:
|
||||
```yaml
|
||||
depend: ["Geyser-Spigot"]
|
||||
```
|
||||
This ensures that your plugin loads after Geyser has, so the Geyser API would be available.
|
||||
|
||||
2. In your main class, implement the EventRegistrar interface and register the event bus in the onEnable method:
|
||||
```java
|
||||
public class ExamplePlugin extends JavaPlugin implements EventRegistrar {
|
||||
|
||||
@Override
|
||||
public void onEnable(){
|
||||
getLogger().info("Registering Geyser event bus!");
|
||||
GeyserApi.api().eventBus().register(this, this); // register your plugin & this class as a listener
|
||||
}
|
||||
|
||||
// here an event, we subscribe as usual with the @Subscribe annotation
|
||||
@Subscribe
|
||||
public void onGeyserPostInitializeEvent(GeyserPostInitializeEvent event) {
|
||||
getLogger().info("Geyser started!");
|
||||
}
|
||||
}
|
||||
```
|
||||
3. If you want to provide your event with a consumer, rather than annotating it, you can also manually subscribe your method to the event bus:
|
||||
```java
|
||||
// replace GeyserEvent.class with the event class you want to listen to
|
||||
GeyserApi.api().eventBus().subscribe(this, GeyserEvent.class, this::yourMethod);
|
||||
```
|
||||
|
||||
## Event Priority
|
||||
Events can have a priority, which is used to determine the order in which the listeners are called. The default priority is NORMAL.
|
||||
To (optionally) set the priority of your event listener, you can add the priority to the `@Subscribe` annotation:
|
||||
```java
|
||||
@Subscribe(postOrder = PostOrder.EARLY)
|
||||
```
|
||||
If you do not specify a priority, the default priority is used. For all available priorities, see
|
||||
[here](https://github.com/GeyserMC/Events/blob/master/src/main/java/org/geysermc/event/PostOrder.java).
|
||||
@@ -0,0 +1,123 @@
|
||||
---
|
||||
title: Geyser Extensions
|
||||
---
|
||||
|
||||
## Geyser Extensions
|
||||
Geyser Extensions are the equivalent of "plugins", but specifically for the Geyser platform. This brings the advantage of them being platform-agnostic, meaning that you won't have to worry about supporting all platforms individually. Additionally, they will be, by design, only applied for Bedrock players joining via Geyser.
|
||||
|
||||
### What can Geyser Extensions do?
|
||||
Extensions can fully utilize the Geyser API to add additional functionality to Geyser. See [Geyser API docs](/geyser/api/) for info on what is currently possible. To name a few examples:
|
||||
- Register custom items
|
||||
- Hide commands from being suggested
|
||||
- Change the MOTD
|
||||
- Register your own commands
|
||||
- Listen to events, e.g. the emote event.
|
||||
|
||||
The underlying Geyser API is steadily expanding, creating more and more opportunities.
|
||||
|
||||
### Which Geyser Extensions exist?
|
||||
At the moment, extensions are still a new system, so there is only a small list of known extensions for Geyser. However, new extensions are always being created!
|
||||
There is an [official list](https://github.com/GeyserMC/GeyserExtensionList) of available extensions you can check out. If you have an extension you'd like to see on this list, feel free to open a PR!
|
||||
|
||||
### Installing Extensions
|
||||
To install an extension, simply put the extension .jar file into Geyser's 'extensions' folder. Then, restart Geyser (or the server Geyser runs on).
|
||||
|
||||
### Creating Geyser Extensions
|
||||
The easiest way to create an extension would be utilizing [this official template](https://github.com/GeyserMC/GeyserExampleExtension/). Simply create a new repository from the template, customize the 'extension.yml' & 'settings.gradle' files, and get started making the extension.
|
||||
|
||||
Geyser recognizes extensions when they have a file called 'extension.yml' in the jars 'resources' folder.
|
||||
|
||||
extension.yml:
|
||||
```yml
|
||||
id: exampleid
|
||||
name: ExampleExtension
|
||||
main: org.geyser.extension.exampleid.ExampleExtension
|
||||
api: 1.0.0
|
||||
version: 1.0.0
|
||||
authors: [ExampleAuthor]
|
||||
```
|
||||
|
||||
Explanations for the individual fields:
|
||||
- id: The id of the extension. Every extension needs to have their unique id - all lowercase letters. If you e.g. register a command for your extension, it will have the id as a prefix: e.g. '/exampleid command'.
|
||||
- name: The name of the extension.
|
||||
- main: The main class of your extension.
|
||||
- api: The Base API version your extension targets.
|
||||
- authors: The author(s) of the extension. To add more than one entry, separate entries with a comma.
|
||||
|
||||
### Creating the main class
|
||||
|
||||
The main class, the entrypoint for the extension, needs to [implement the 'Extension' interface provided by Geyser](https://github.com/GeyserMC/GeyserExampleExtension/blob/47614575a69bddecb241676215f3c9f9113db304/src/main/java/org/geyser/extension/exampleid/ExampleExtension.java#L10).
|
||||
That way, Geyser recognizes the extension, and gives you access to important methods - such as 'logger()', to get your extensions logger. <br>
|
||||
To see all the methods provided by that interface, see [here](https://github.com/GeyserMC/Geyser/blob/master/api/src/main/java/org/geysermc/geyser/api/extension/Extension.java).
|
||||
|
||||
Unlike plugins, extensions do not have a 'onEnable' or 'onDisable' method. Instead, most actions are done in events at different stages during Geyser's lifecycle using events.
|
||||
Some important ones are:
|
||||
- `GeyserPreInitializeEvent`: This event is fired when Geyser starts to initialize. If you e.g. need to register extension commands that are configured in your config,
|
||||
you would need to load the config here to ensure that your config is ready before the GeyserDefineCommandsEvent is fired.
|
||||
- `GeyserPostInitializeEvent`: It is called when Geyser has completed initializing. The bulk of your code should go here, as the GeyserAPI is fully available at this stage.
|
||||
- `GeyserShutdownEvent`: Called when Geyser is shutting down. You can use this to e.g. save data, or clean up resources.
|
||||
|
||||
See below for an example:
|
||||
```java
|
||||
@Subscribe
|
||||
public void onPostInitialize(GeyserPostInitializeEvent event) {
|
||||
// example: show that your extension is loading.
|
||||
this.logger().info("Loading example extension...");
|
||||
}
|
||||
```
|
||||
If you wish to register custom items, global resource packs (or soon, custom blocks and entities), you will need to subscribe to the event using the @Subscribe annotation,
|
||||
and register them in the event. You can find an example for custom items [here](/geyser/custom-items/#geyser-extensions). For other events, see [here](/geyser/events) for documentation.
|
||||
|
||||
To build your extension, run the Gradle build task, and install the extension.
|
||||
|
||||
### Creating commands with Geyser Extensions
|
||||
To create a command, you would need to use the "Commands" package in the Geyser API. Brief rundown:
|
||||
- [Command.java](https://github.com/GeyserMC/Geyser/blob/master/api/src/main/java/org/geysermc/geyser/api/command/Command.java)
|
||||
This interface represents a command in Geyser - to make one, you can use the CommandBuilder. You can register it with the
|
||||
[GeyserDefineCommandsEvent](https://github.com/GeyserMC/Geyser/blob/master/api/src/main/java/org/geysermc/geyser/api/event/lifecycle/GeyserDefineCommandsEvent.java)
|
||||
- [CommandExecutor.java](https://github.com/GeyserMC/Geyser/blob/master/api/src/main/java/org/geysermc/geyser/api/command/CommandExecutor.java)
|
||||
This interface represents a command execute handler in Geyser, and extends the CommandSource interface.
|
||||
- [CommandSource.java](https://github.com/GeyserMC/Geyser/blob/master/api/src/main/java/org/geysermc/geyser/api/command/CommandSource.java)
|
||||
This interface represents a command source in Geyser. It can be used to e.g. send messages to the source, check if the source has permission to execute a command, or get the locale.
|
||||
|
||||
```java
|
||||
Command command = Command.builder(this) // "this" is the extension's main class
|
||||
.name("ExampleCommand")
|
||||
.bedrockOnly(true)
|
||||
.source(CommandSource.class)
|
||||
.aliases(List.of("example", "ex"))
|
||||
.description("An example command")
|
||||
.executableOnConsole(false)
|
||||
.suggestedOpOnly(false)
|
||||
.permission("example.command")
|
||||
.executor((source, cmd, args) -> {
|
||||
// this is the command executor - this is where you would put your code to execute the command.
|
||||
// source is the source that executed the command
|
||||
// cmd is the command that was executed
|
||||
// args are the arguments passed to the command
|
||||
source.sendMessage("Hello World");
|
||||
})
|
||||
.build();
|
||||
```
|
||||
|
||||
To register the command, you would need to subscribe to the GeyserDefineCommandsEvent, and register the command there:
|
||||
```java
|
||||
@Subscribe
|
||||
public void onDefineCommands(GeyserDefineCommandsEvent event) {
|
||||
event.register(command);
|
||||
}
|
||||
```
|
||||
If everything went right, you should be able to execute the command in-game by running "/extesionid [command]" - in our case, "/exampleid examplecommand".
|
||||
Here, it would send "Hello World" to the source that ran the command.
|
||||
Since we also set aliases, you could also run "/exampleid example" or "/exampleid ex" for the same command.
|
||||
To provide args, simple run "/exampleid examplecommand [args]" - replacing [args] with the arguments you want to pass to the command.
|
||||
|
||||
### Listening to Events
|
||||
See [here](/geyser/events) for documentation. You do not need to register the event listener, Geyser will do that for you.
|
||||
|
||||
---
|
||||
|
||||
Facing troubles with extensions?
|
||||
- Make sure you are using the latest version of Geyser - older versions might not have the latest API changes.
|
||||
- Add debug prints.
|
||||
- Ask in the #development channel in the [Geyser Discord server](https://discord.gg/geysermc).
|
||||
@@ -6,7 +6,7 @@ title: Forms and Cumulus
|
||||
|
||||
Bedrock Edition has a cool exclusive feature called Forms.<br>
|
||||
Cumulus is the Forms API that we use in Geyser and Floodgate.<br>
|
||||
The source code is available [here](https://github.com/GeyserMC/Cumulus). You can access the Cumulus API through the [Floodgate API](/floodgate/api/).
|
||||
The source code is available [here](https://github.com/GeyserMC/Cumulus). You can access the Cumulus API through the [Floodgate API](/floodgate/api/), or the [Geyser API](/geyser/api).
|
||||
|
||||
Bedrock knows three types of Forms:
|
||||
* ModalForm
|
||||
+35
-5
@@ -1,29 +1,48 @@
|
||||
---
|
||||
title: Using Geyser or Floodgate as a dependency
|
||||
title: Getting Started with the API
|
||||
---
|
||||
|
||||
To start, add the Open Collaboration repository to your project:
|
||||
|
||||
**Maven**
|
||||
```xml
|
||||
<repository>
|
||||
<id>opencollab-snapshot-repo</id>
|
||||
<id>opencollab-snapshot</id>
|
||||
<url>https://repo.opencollab.dev/main/</url>
|
||||
</repository>
|
||||
```
|
||||
The "main" repository contains both release and snapshot versions.
|
||||
|
||||
**Gradle**
|
||||
```groovy
|
||||
repositories {
|
||||
maven {
|
||||
url = uri("https://repo.opencollab.dev/main/")
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Using Geyser
|
||||
|
||||
Add Geyser's API codebase as a dependency:
|
||||
|
||||
**Maven**
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>org.geysermc.geyser</groupId>
|
||||
<artifactId>api</artifactId>
|
||||
<version>2.1.0-SNAPSHOT</version>
|
||||
<version>2.1.2-SNAPSHOT</version>
|
||||
<scope>provided</scope>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
**Gradle**
|
||||
```groovy
|
||||
dependencies {
|
||||
compileOnly('org.geysermc.geyser:api:2.1.2-SNAPSHOT')
|
||||
}
|
||||
```
|
||||
|
||||
To get a Geyser player, or check if a player is from Bedrock:
|
||||
|
||||
```java
|
||||
@@ -34,23 +53,34 @@ GeyserConnection connection = GeyserApi.api().connectionByUuid(uuid);
|
||||
|
||||
`GeyserApi.api()` may be null until after the Geyser plugin enables.
|
||||
|
||||
For more information on the Geyser API, see [here](/geyser/api/).
|
||||
|
||||
## Using Floodgate
|
||||
|
||||
This page has a very simple primer for the Floodgate API. For a full breakdown, see [here](/floodgate/api/).
|
||||
|
||||
Add Floodgate's API as a dependency:
|
||||
|
||||
**Maven**
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>org.geysermc.floodgate</groupId>
|
||||
<artifactId>api</artifactId>
|
||||
<version>2.0-SNAPSHOT</version>
|
||||
<version>2.2.2-SNAPSHOT</version>
|
||||
<scope>provided</scope>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
**Gradle**
|
||||
```groovy
|
||||
dependencies {
|
||||
compileOnly('org.geysermc.floodgate:api:2.2.2-SNAPSHOT')
|
||||
}
|
||||
```
|
||||
|
||||
Get the Floodgate API using:
|
||||
```java
|
||||
FloodgateApi api = FloodgateApi.getInstance();
|
||||
api.isFloodgatePlayer(uuid);
|
||||
```
|
||||
|
||||
For more information on the Floodgate API, see [here](/floodgate/api/).
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
title: Geyser Command Line Arguments and System Properties
|
||||
---
|
||||
|
||||
# Geyser Command Line Arguments and System Properties
|
||||
Geyser offers a few command line arguments/system properties to allow you to configure Geyser without editing the config files.
|
||||
Additionally, you can suppress some warnings that may be printed to the console.
|
||||
|
||||
### Configuration system properties
|
||||
You can set Geyser to automatically bind to a specific address and port by using the following command line arguments. <br>
|
||||
This is primarily aimed at server hosting providers to automatically configure servers for users.
|
||||
|
||||
<div class="alert alert-info" role="alert">
|
||||
Note: the Geyser specific properties are prioritized over the plugin properties!
|
||||
</div>
|
||||
|
||||
- ```-DgeyserUdpPort=server``` or ```-DpluginUdpPort=server```
|
||||
- ```-1``` means UDP is not supported and will forcibly stop Geyser.
|
||||
- ```server``` means to match the port of the TCP server.
|
||||
- any other number means to use that specific port
|
||||
|
||||
- ```-DgeyserUdpAddress=server``` or ```-DpluginUdpAddress=server```
|
||||
- ```server``` means to match the bind address of the TCP server
|
||||
- any other string will be used as-is for the bind address.
|
||||
|
||||
### Disabling warnings and advanced configuration
|
||||
You may disable some warnings that may be printed to the console by using the following command line arguments:
|
||||
|
||||
<div class="alert alert-danger" role="alert">
|
||||
Warning: Disabling Geyser warnings from being logged will not fix the real issue! Only disable them if you know what you are doing.
|
||||
</div>
|
||||
|
||||
- ```-DGeyser.PrintSecureChatInformation=true```
|
||||
- Allows you to disable the warning about secure chat being disabled.
|
||||
Since the warning is sent when the server sends the warning, this option does not do much anymore.
|
||||
- ```-DGeyser.ShowScoreboardLogs=true```
|
||||
- Allows you to disable warnings related to scoreboards, such as "Tried to update score without the existence of its requested objective".
|
||||
- ```-DGeyser.ShowResourcePackLengthWarning=true```
|
||||
- Allows you to disable the warning about a resource pack having too long paths. Disabling this warning will not fix the underlying issue!
|
||||
Console players might not be able to join your server at all if you have a resource pack with paths exceeding the 80 character limit.
|
||||
- ```-DGeyser.PrintPingsInDebugMode=true```
|
||||
- Controls if pings are being logged in debug mode.
|
||||
- ```-DGeyser.UseDirectAdapters=true```
|
||||
- Allows you to disable the usage of NMS adapters. Disabling will result in a performance penalty and should only be used for debugging.
|
||||
This is Spigot-only and will not work on other platforms.
|
||||
- ```-DGeyser.BedrockNetworkThreads=8```
|
||||
- Allows you to set the number of threads used for the Bedrock networking. This is not set to a specific number by default, but is instead calculated based on the available resources.
|
||||
|
||||
## Geyser-Standalone specific options:
|
||||
|
||||
#### `--config [file]`
|
||||
- **Alias: `-c`**
|
||||
- Points to an alternative config file to use.
|
||||
|
||||
#### `--gui` / `--nogui`
|
||||
- **Alias: `gui` / `nogui`**:
|
||||
- Forces GUI or non-GUI usage, depending on context.
|
||||
|
||||
### Overriding specific config values
|
||||
Overriding a standard config option (e.g. `command-suggestions`):
|
||||
|
||||
`--command-suggestions=false`
|
||||
|
||||
Overriding a nested config option(e.g. the `remote` section with `address`):
|
||||
|
||||
`--remote.address=test.geysermc.org`
|
||||
@@ -0,0 +1,23 @@
|
||||
---
|
||||
title: Global API
|
||||
---
|
||||
|
||||
### Geyser Global API
|
||||
The Global API is available for every server. It currently includes: [Global Linking](#what-is-global-linking), [skin uploading](#what-is-skin-uploading), getting a xuid by gamertag, and getting a gamertag by xuid.
|
||||
We don't store anything else than you can access by the Global API, except for some non-identifiable metrics. The source code of the Global API is available [here](https://github.com/GeyserMC/global_api) and the source code of the Global Linking server is available [here](https://github.com/GeyserMC/GlobalLinkServer).
|
||||
|
||||
As a user of the API, you can get various info about Geyser (or specifically, Floodgate players) that joined any Geyser + Floodgate server before. This includes:
|
||||
- Conversion methods from a Bedrock gamertag to Bedrock xuid, and vice-versa. Only provides info for players who are in Geyser's cache. <br>
|
||||
If you need them for all players, you can use a third-party API, e.g. https://mcprofile.io/endpoints, which also provides info from the Geyser Global API.
|
||||
- Skin info: Whenever a Bedrock player joins via Floodgate, their skin gets converted & uploaded to mineskin. If you want to grab that converted skin, use the xuid of the Bedrock player in this endpoint to get a texture id, or a base64 encoded "value", which you could use directly in e.g. player heads.
|
||||
|
||||
See the [Global API docs](https://api.geysermc.org/docs) for more info, and detailed usage.
|
||||
|
||||
### Examples
|
||||
Here are a few examples of how you could use the Global API. <br>
|
||||
|
||||
[GeyserDiscordBot](https://github.com/GeyserMC/GeyserDiscordBot/blob/master/src/main/java/org/geysermc/discordbot/commands/FloodgateUuidCommand.java)
|
||||
- GeyserMC's discord bot has a /uuid command to get a floodgate uuid from a bedrock username. <br>
|
||||
|
||||
[FabricGeyserPlayerHeads](https://github.com/onebeastchris/fabricgeyserplayerheads/blob/master/src/main/java/net/onebeastofchris/geyserplayerheads/utils/PlayerUtils.java#L57-L75)
|
||||
- A fabric mod that uses the Global API to get a Bedrock player's skin, and then uses that to create a player head.
|
||||
@@ -1,24 +0,0 @@
|
||||
---
|
||||
title: Standalone Command Line Arguments
|
||||
---
|
||||
|
||||
# General command-line arguments
|
||||
|
||||
### `--config [file]`
|
||||
**Alias: `-c`**
|
||||
|
||||
Points to an alternative config file to use.
|
||||
|
||||
### `--gui` / `--nogui`
|
||||
**Alias: `gui` / `nogui`**
|
||||
|
||||
Forces GUI or non-GUI usage, depending on context.
|
||||
|
||||
# Overriding specific config values
|
||||
Overriding a standard config option (e.g. `command-suggestions`):
|
||||
|
||||
`--command-suggestions=false`
|
||||
|
||||
Overriding a nested config option(e.g. the `remote` section with `address`):
|
||||
|
||||
`--remote.address=test.geysermc.org`
|
||||
Reference in new issue
Block a user