Skip to content

Commit

Permalink
Networking API javadoc fixes and small refactors (#3285)
Browse files Browse the repository at this point in the history 
* 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 <[email protected]>
  • Loading branch information
@apple502j @modmuss50
apple502j and modmuss50 authored Aug 30, 2023
1 parent f091af9 commit 017b9d9
Show file tree
Hide file tree
Showing 9 changed files with 78 additions and 27 deletions.
7 changes: 5 additions & 2 deletions ...ava/net/fabricmc/fabric/api/client/networking/v1/ClientConfigurationConnectionEvents.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,9 +29,9 @@
* 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)
*/
Expand Down Expand Up @@ -63,6 +63,9 @@ public class ClientConfigurationConnectionEvents {
}
});

private ClientConfigurationConnectionEvents() {
}

@FunctionalInterface
public interface Init {
void onConfigurationInit(ClientConfigurationNetworkHandler handler, MinecraftClient client);
Expand Down
2 changes: 1 addition & 1 deletion ...ient/java/net/fabricmc/fabric/api/client/networking/v1/ClientConfigurationNetworking.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@
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.
Expand Down
32 changes: 25 additions & 7 deletions ...ing-api-v1/src/client/java/net/fabricmc/fabric/api/client/networking/v1/package-info.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
9 changes: 6 additions & 3 deletions ...n/java/net/fabricmc/fabric/api/networking/v1/FabricServerConfigurationNetworkHandler.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,13 +26,14 @@
*/
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
*/
Expand All @@ -41,8 +42,10 @@ default void addTask(ServerPlayerConfigurationTask task) {
}

/**
* 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");
Expand Down
2 changes: 2 additions & 0 deletions ...c-networking-api-v1/src/main/java/net/fabricmc/fabric/api/networking/v1/PacketSender.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@
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;
Expand All @@ -35,6 +36,7 @@
* Represents something that supports sending packets to channels.
* @see PacketByteBufs
*/
@ApiStatus.NonExtendable
public interface PacketSender {
/**
* Makes a packet for a channel.
Expand Down
6 changes: 3 additions & 3 deletions ...c-networking-api-v1/src/main/java/net/fabricmc/fabric/api/networking/v1/PlayerLookup.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@
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.
*
Expand Down Expand Up @@ -117,8 +117,8 @@ public static Collection<ServerPlayerEntity> tracking(Entity entity) {

// 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();
Expand Down
9 changes: 6 additions & 3 deletions .../main/java/net/fabricmc/fabric/api/networking/v1/ServerConfigurationConnectionEvents.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,11 +28,11 @@
* 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.
*/
Expand All @@ -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
Expand Down Expand Up @@ -76,6 +76,9 @@ public class ServerConfigurationConnectionEvents {
}
});

private ServerConfigurationConnectionEvents() {
}

@FunctionalInterface
public interface Configure {
void onSendConfiguration(ServerConfigurationNetworkHandler handler, MinecraftServer server);
Expand Down
4 changes: 2 additions & 2 deletions ...ing-api-v1/src/main/java/net/fabricmc/fabric/api/networking/v1/ServerLoginNetworking.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@
import java.util.Set;
import java.util.concurrent.Future;

import org.jetbrains.annotations.ApiStatus;
import org.jetbrains.annotations.Nullable;

import net.minecraft.network.PacketByteBuf;
Expand Down Expand Up @@ -151,10 +152,9 @@ public interface LoginQueryResponseHandler {

/**
* 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}.
Expand Down
34 changes: 28 additions & 6 deletions ...c-networking-api-v1/src/main/java/net/fabricmc/fabric/api/networking/v1/package-info.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;

0 comments on commit 017b9d9

Please sign in to comment.