mirror of
https://github.com/FabricMC/fabric.git
synced 2025-04-21 03:10:54 -04:00
Networking API javadoc fixes and small refactors (#3285)
* Mark events class constructor as private * Enhance FabricServerConfigurationNetworkHandler javadoc * Expand package-info * Mark some interfaces as non-extendable * Refactor PlayerLookup and fix javadoc The example about block entities was removed. This is not the proper way to do it anymore; you should use `BlockEntity#markDirty` and the built-in syncing. * Fix missing period * Fix typos * Fix checkstyle. --------- Co-authored-by: modmuss50 <modmuss50@gmail.com>
This commit is contained in:
apple502j
GitHub
parent
f091af96c5
commit
017b9d93e2
9 changed files with 78 additions and 27 deletions
fabric-networking-api-v1/src
client/java/net/fabricmc/fabric/api/client/networking/v1
main/java/net/fabricmc/fabric/api/networking/v1
|
|
@ -29,9 +29,9 @@ import net.fabricmc.fabric.api.event.EventFactory;
|
|||
* Offers access to events related to the configuration connection to a server on a logical client.
|
||||
*/
|
||||
@ApiStatus.Experimental
|
||||
public class ClientConfigurationConnectionEvents {
|
||||
public final class ClientConfigurationConnectionEvents {
|
||||
/**
|
||||
* Event indicating a connection entered the CONFIGURATION state, ready for registering channel handlers.
|
||||
* Event indicating a connection entering the CONFIGURATION state, ready for registering channel handlers.
|
||||
*
|
||||
* @see ClientConfigurationNetworking#registerReceiver(Identifier, ClientConfigurationNetworking.ConfigurationChannelHandler)
|
||||
*/
|
||||
|
|
@ -63,6 +63,9 @@ public class ClientConfigurationConnectionEvents {
|
|||
}
|
||||
});
|
||||
|
||||
private ClientConfigurationConnectionEvents() {
|
||||
}
|
||||
|
||||
@FunctionalInterface
|
||||
public interface Init {
|
||||
void onConfigurationInit(ClientConfigurationNetworkHandler handler, MinecraftClient client);
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@ import net.fabricmc.fabric.impl.networking.client.ClientNetworkingImpl;
|
|||
import net.fabricmc.fabric.mixin.networking.client.accessor.ClientCommonNetworkHandlerAccessor;
|
||||
|
||||
/**
|
||||
* Offers access to configurtion stage client-side networking functionalities.
|
||||
* Offers access to configuration stage client-side networking functionalities.
|
||||
*
|
||||
* <p>Client-side networking functionalities include receiving clientbound packets,
|
||||
* sending serverbound packets, and events related to client-side network handlers.
|
||||
|
|
|
|||
|
|
@ -17,13 +17,31 @@
|
|||
/**
|
||||
* The Networking API (client side), version 1.
|
||||
*
|
||||
* <p>For login stage networking see {@link net.fabricmc.fabric.api.client.networking.v1.ClientLoginNetworking}.
|
||||
* For play stage networking see {@link net.fabricmc.fabric.api.client.networking.v1.ClientPlayNetworking}.
|
||||
*
|
||||
* <p>For events related to connection to a server see {@link net.fabricmc.fabric.api.client.networking.v1.ClientLoginConnectionEvents} for login stage
|
||||
* or {@link net.fabricmc.fabric.api.client.networking.v1.ClientPlayConnectionEvents} for play stage.
|
||||
*
|
||||
* <p>For events related to the ability of a server to receive packets on a channel of a specific name see {@link net.fabricmc.fabric.api.client.networking.v1.C2SPlayChannelEvents}.
|
||||
* <p>There are three stages of Minecraft networking, all of which are supported in this API:
|
||||
* <dl>
|
||||
* <dt>LOGIN</dt>
|
||||
* <dd>This is the initial stage, before the player logs into the world. If using a proxy server,
|
||||
* the packets in this stage may be intercepted and discarded by the proxy. <strong>Most of the pre-1.20.2
|
||||
* uses of this event should be replaced with the CONFIGURATION stage.</strong>
|
||||
* Related events are found at {@link net.fabricmc.fabric.api.client.networking.v1.ClientLoginConnectionEvents},
|
||||
* and related methods are found at {@link net.fabricmc.fabric.api.client.networking.v1.ClientLoginNetworking}.
|
||||
* </dd>
|
||||
* <dt>CONFIGURATION</dt>
|
||||
* <dd>This is the stage after LOGIN. The player is authenticated, but still hasn't joined the
|
||||
* world at this point. Clients can use this phase to send configurations or verify their mod
|
||||
* versions. Note that some server mods allow players in the PLAY stage to re-enter this stage,
|
||||
* for example when a player chooses a minigame server in a lobby.
|
||||
* Related events are found at {@link net.fabricmc.fabric.api.client.networking.v1.C2SConfigurationChannelEvents}
|
||||
* and {@link net.fabricmc.fabric.api.client.networking.v1.ClientConfigurationConnectionEvents}, and related methods are found at
|
||||
* {@link net.fabricmc.fabric.api.client.networking.v1.ClientConfigurationNetworking}.
|
||||
* </dd>
|
||||
* <dt>PLAY</dt>
|
||||
* <dd>This is the stage after CONFIGURATION, where gameplay-related packets are sent and received.
|
||||
* The player has joined the world and is playing the game. Related events are found at
|
||||
* {@link net.fabricmc.fabric.api.client.networking.v1.C2SPlayChannelEvents}
|
||||
* and {@link net.fabricmc.fabric.api.client.networking.v1.ClientPlayConnectionEvents}, and related methods are found at
|
||||
* {@link net.fabricmc.fabric.api.client.networking.v1.ClientPlayNetworking}.</dd>
|
||||
* </dl>
|
||||
*/
|
||||
|
||||
package net.fabricmc.fabric.api.client.networking.v1;
|
||||
|
|
|
|||
|
|
@ -26,13 +26,14 @@ import net.minecraft.util.Identifier;
|
|||
*/
|
||||
public interface FabricServerConfigurationNetworkHandler {
|
||||
/**
|
||||
* Enqueue a {@link ServerPlayerConfigurationTask} task to be processed.
|
||||
* Enqueues a {@link ServerPlayerConfigurationTask} task to be processed.
|
||||
*
|
||||
* <p>Before adding a task use {@link ServerConfigurationNetworking#canSend(ServerConfigurationNetworkHandler, Identifier)}
|
||||
* to ensure that the client can process this task.
|
||||
*
|
||||
* <p>Once the client has handled the task a packet should be sent to the server.
|
||||
* Upon receiving this packet the server should call {@link FabricServerConfigurationNetworkHandler#completeTask(ServerPlayerConfigurationTask.Key)}
|
||||
* Upon receiving this packet the server should call {@link FabricServerConfigurationNetworkHandler#completeTask(ServerPlayerConfigurationTask.Key)},
|
||||
* otherwise the client cannot join the world.
|
||||
*
|
||||
* @param task the task
|
||||
*/
|
||||
|
|
@ -41,8 +42,10 @@ public interface FabricServerConfigurationNetworkHandler {
|
|||
}
|
||||
|
||||
/**
|
||||
* Completes the task identified by {@code key}.
|
||||
*
|
||||
* @param key the key
|
||||
* @param key the task key
|
||||
* @throws IllegalStateException if the current task is not {@code key}
|
||||
*/
|
||||
default void completeTask(ServerPlayerConfigurationTask.Key key) {
|
||||
throw new UnsupportedOperationException("Implemented via mixin");
|
||||
|
|
|
|||
|
|
@ -21,6 +21,7 @@ import java.util.Objects;
|
|||
import io.netty.channel.ChannelFutureListener;
|
||||
import io.netty.util.concurrent.Future;
|
||||
import io.netty.util.concurrent.GenericFutureListener;
|
||||
import org.jetbrains.annotations.ApiStatus;
|
||||
import org.jetbrains.annotations.Nullable;
|
||||
|
||||
import net.minecraft.network.PacketByteBuf;
|
||||
|
|
@ -35,6 +36,7 @@ import net.fabricmc.fabric.impl.networking.GenericFutureListenerHolder;
|
|||
* Represents something that supports sending packets to channels.
|
||||
* @see PacketByteBufs
|
||||
*/
|
||||
@ApiStatus.NonExtendable
|
||||
public interface PacketSender {
|
||||
/**
|
||||
* Makes a packet for a channel.
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@ import net.fabricmc.fabric.mixin.networking.accessor.EntityTrackerAccessor;
|
|||
import net.fabricmc.fabric.mixin.networking.accessor.ThreadedAnvilChunkStorageAccessor;
|
||||
|
||||
/**
|
||||
* For example, a block entity may use the methods in this class to send a packet to all clients which can see the block entity in order notify clients about a change.
|
||||
* Helper methods to lookup players in a server.
|
||||
*
|
||||
* <p>The word "tracking" means that an entity/chunk on the server is known to a player's client (within in view distance) and the (block) entity should notify tracking clients of changes.
|
||||
*
|
||||
|
|
@ -117,8 +117,8 @@ public final class PlayerLookup {
|
|||
|
||||
// return an immutable collection to guard against accidental removals.
|
||||
if (tracker != null) {
|
||||
return Collections.unmodifiableCollection(tracker.getPlayersTracking()
|
||||
.stream().map(PlayerAssociatedNetworkHandler::getPlayer).collect(Collectors.toSet()));
|
||||
return tracker.getPlayersTracking()
|
||||
.stream().map(PlayerAssociatedNetworkHandler::getPlayer).collect(Collectors.toUnmodifiableSet());
|
||||
}
|
||||
|
||||
return Collections.emptySet();
|
||||
|
|
|
|||
|
|
@ -28,11 +28,11 @@ import net.fabricmc.fabric.api.event.EventFactory;
|
|||
* Offers access to events related to the connection to a client on a logical server while a client is configuring.
|
||||
*/
|
||||
@ApiStatus.Experimental
|
||||
public class ServerConfigurationConnectionEvents {
|
||||
public final class ServerConfigurationConnectionEvents {
|
||||
/**
|
||||
* Event fired before any vanilla configuration has taken place.
|
||||
*
|
||||
* <p>This event is executed on {@linkplain io.netty.channel.EventLoop netty's event loops}
|
||||
* <p>This event is executed on {@linkplain io.netty.channel.EventLoop netty's event loops}.
|
||||
*
|
||||
* <p>Task queued during this event will complete before vanilla configuration starts.
|
||||
*/
|
||||
|
|
@ -45,7 +45,7 @@ public class ServerConfigurationConnectionEvents {
|
|||
/**
|
||||
* Event fired during vanilla configuration.
|
||||
*
|
||||
* <p>This event is executed on {@linkplain io.netty.channel.EventLoop netty's event loops}
|
||||
* <p>This event is executed on {@linkplain io.netty.channel.EventLoop netty's event loops}.
|
||||
*
|
||||
* <p>An example usage of this:
|
||||
* <pre>{@code
|
||||
|
|
@ -76,6 +76,9 @@ public class ServerConfigurationConnectionEvents {
|
|||
}
|
||||
});
|
||||
|
||||
private ServerConfigurationConnectionEvents() {
|
||||
}
|
||||
|
||||
@FunctionalInterface
|
||||
public interface Configure {
|
||||
void onSendConfiguration(ServerConfigurationNetworkHandler handler, MinecraftServer server);
|
||||
|
|
|
|||
|
|
@ -20,6 +20,7 @@ import java.util.Objects;
|
|||
import java.util.Set;
|
||||
import java.util.concurrent.Future;
|
||||
|
||||
import org.jetbrains.annotations.ApiStatus;
|
||||
import org.jetbrains.annotations.Nullable;
|
||||
|
||||
import net.minecraft.network.PacketByteBuf;
|
||||
|
|
@ -151,10 +152,9 @@ public final class ServerLoginNetworking {
|
|||
|
||||
/**
|
||||
* Allows blocking client log-in until all futures passed into {@link LoginSynchronizer#waitFor(Future)} are completed.
|
||||
*
|
||||
* @apiNote this interface is not intended to be implemented by users of api.
|
||||
*/
|
||||
@FunctionalInterface
|
||||
@ApiStatus.NonExtendable
|
||||
public interface LoginSynchronizer {
|
||||
/**
|
||||
* Allows blocking client log-in until the {@code future} is {@link Future#isDone() done}.
|
||||
|
|
|
|||
|
|
@ -17,13 +17,35 @@
|
|||
/**
|
||||
* The Networking API, version 1.
|
||||
*
|
||||
* <p>For login stage networking see {@link net.fabricmc.fabric.api.networking.v1.ServerLoginNetworking}.
|
||||
* For play stage networking see {@link net.fabricmc.fabric.api.networking.v1.ServerPlayNetworking}.
|
||||
* <p>There are three stages of Minecraft networking, all of which are supported in this API:
|
||||
* <dl>
|
||||
* <dt>LOGIN</dt>
|
||||
* <dd>This is the initial stage, before the player logs into the world. If using a proxy server,
|
||||
* the packets in this stage may be intercepted and discarded by the proxy. <strong>Most of the pre-1.20.2
|
||||
* uses of this event should be replaced with the CONFIGURATION stage.</strong>
|
||||
* Related events are found at {@link net.fabricmc.fabric.api.networking.v1.ServerLoginConnectionEvents},
|
||||
* and related methods are found at {@link net.fabricmc.fabric.api.networking.v1.ServerLoginNetworking}.
|
||||
* </dd>
|
||||
* <dt>CONFIGURATION</dt>
|
||||
* <dd>This is the stage after LOGIN. The player is authenticated, but still hasn't joined the
|
||||
* world at this point. Servers can use this phase to send configurations or verify client's mod
|
||||
* versions. Note that some server mods allow players in the PLAY stage to re-enter this stage,
|
||||
* for example when a player chooses a minigame server in a lobby.
|
||||
* Related events are found at {@link net.fabricmc.fabric.api.networking.v1.S2CConfigurationChannelEvents}
|
||||
* {@link net.fabricmc.fabric.api.networking.v1.ServerConfigurationConnectionEvents}, and related methods are found at
|
||||
* {@link net.fabricmc.fabric.api.networking.v1.ServerConfigurationNetworking}.
|
||||
* </dd>
|
||||
* <dt>PLAY</dt>
|
||||
* <dd>This is the stage after CONFIGURATION, where gameplay-related packets are sent and received.
|
||||
* The player has joined the world and is playing the game. Related events are found at
|
||||
* {@link net.fabricmc.fabric.api.networking.v1.S2CPlayChannelEvents}
|
||||
* and {@link net.fabricmc.fabric.api.networking.v1.ServerPlayConnectionEvents}, and related methods are found at
|
||||
* {@link net.fabricmc.fabric.api.networking.v1.ServerPlayNetworking}.</dd>
|
||||
* </dl>
|
||||
*
|
||||
* <p>For events related to the connection to a client see {@link net.fabricmc.fabric.api.networking.v1.ServerLoginConnectionEvents} for login stage
|
||||
* or {@link net.fabricmc.fabric.api.networking.v1.ServerPlayConnectionEvents} for play stage.
|
||||
*
|
||||
* <p>For events related to the ability of a client to receive packets on a channel of a specific name see {@link net.fabricmc.fabric.api.networking.v1.S2CPlayChannelEvents}.
|
||||
* <p>In addition, this API includes helpers for {@linkplain
|
||||
* net.fabricmc.fabric.api.networking.v1.PacketByteBufs buffer creations} and {@linkplain
|
||||
* net.fabricmc.fabric.api.networking.v1.PlayerLookup player lookups}.
|
||||
*/
|
||||
|
||||
package net.fabricmc.fabric.api.networking.v1;
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue