Networking 1.21.11

Ein allgemeiner Leitfaden über Networking unter Verwendung der Fabric API.

WARNING

Diese Seite ist für die Version 1.21.11 geschrieben. Dokumentationen für ältere Versionen sind möglicherweise unvollständig.

In Minecraft wird Networking verwendet, damit Client und Server miteinander kommunizieren können. Networking ist ein weites Feld, daher ist diese Seite in mehrere Kategorien unterteilt.

Warum ist Networking wichtig?

Pakete sind das Kernkonzept von Minecraft Networking. Pakete bestehen aus beliebigen Daten, die entweder vom Server zum Client oder vom Client zum Server gesendet werden können. Das folgende Diagramm zeigt eine visuelle Darstellung der Networkingarchitektur in Fabric:

Beachte, dass die Pakete die Brücke zwischen dem Server und dem Client bilden. Das liegt daran, dass fast alles, was du im Spiel tust, in irgendeiner Weise mit Networking zu tun hat, ob du es weißt oder nicht. Wenn du zum Beispiel eine Chat-Nachricht sendest, wird ein Paket mit dem Inhalt an den Server geschickt. Der Server sendet dann ein weiteres Paket mit deiner Nachricht an alle anderen Clients.

Wichtig ist, dass immer ein Server läuft, auch im Einzelspielermodus und im LAN. Pakete werden immer noch zur Kommunikation zwischen dem Client und dem Server verwendet, auch wenn niemand anderes mit dir spielt. Wenn von Seiten bei Networking die Rede ist, werden die Begriffe "logischer Client" und "logischer Server" verwendet. Der integrierte Singleplayer/LAN-Server und der dedizierte Server sind beide logische Server, aber nur der dedizierte Server kann als physischer Server betrachtet werden.

Wenn der Status zwischen dem Client und dem Server nicht synchronisiert wird, kann es zu Problemen kommen, wenn der Server oder andere Clients nicht mit dem übereinstimmen, was ein anderer macht. Dies wird oft als "Desync" bezeichnet. Wenn du deinen eigenen Mod schreibst, musst du eventuell ein Datenpaket senden, um den Status des Servers und aller Clients synchron zu halten.

Eine Einführung in Networking

Einen Payload definieren

INFO

Eine Payload sind die Daten, die innerhalb eines Pakets gesendet werden.

Dies kann durch das Erstellen eines Java Record mit einem BlockPos-Parameter, der CustomPacketPayload implementiert, gelöst werden.

public record SummonLightningS2CPayload(BlockPos pos) implements CustomPacketPayload {
	public static final Identifier SUMMON_LIGHTNING_PAYLOAD_ID = Identifier.fromNamespaceAndPath(ExampleMod.MOD_ID, "summon_lightning");
	public static final CustomPacketPayload.Type<SummonLightningS2CPayload> ID = new CustomPacketPayload.Type<>(SUMMON_LIGHTNING_PAYLOAD_ID);
	public static final StreamCodec<RegistryFriendlyByteBuf, SummonLightningS2CPayload> CODEC = StreamCodec.composite(BlockPos.STREAM_CODEC, SummonLightningS2CPayload::pos, SummonLightningS2CPayload::new);

	@Override
	public Type<? extends CustomPacketPayload> type() {
		return ID;
	}
}

Zugleich haben wir folgendes definiert:

• Einen Identifier, der zur Identifizierung des Payload unseres Pakets verwendet wird. In diesem Beispiel lautet der Bezeichner example-mod:summon_lightning.

public static final Identifier SUMMON_LIGHTNING_PAYLOAD_ID = Identifier.fromNamespaceAndPath(ExampleMod.MOD_ID, "summon_lightning");

• Eine öffentliche, statische Instanz von CustomPayload.Id zur eindeutigen Identifizierung dieses benutzdefinierten Payloads. Wir werden auf diese ID sowohl in unserem allgemeinen als auch in unserem Client-Code verweisen.

public static final CustomPacketPayload.Type<SummonLightningS2CPayload> ID = new CustomPacketPayload.Type<>(SUMMON_LIGHTNING_PAYLOAD_ID);

• Eine öffentliche, statische Instanz eines StreamCodec, damit das Spiel weiß, wie es den Inhalt des Pakets serialisieren/deserialisieren kann.

public static final StreamCodec<RegistryFriendlyByteBuf, SummonLightningS2CPayload> CODEC = StreamCodec.composite(BlockPos.STREAM_CODEC, SummonLightningS2CPayload::pos, SummonLightningS2CPayload::new);

Wir haben auch type überschrieben, um unsere Payload-ID zurückzugeben.

@Override
public Type<? extends CustomPacketPayload> type() {
	return ID;
}

Einen Payload registrieren

Bevor wir ein Paket mit unserer benutzerdefinierten Nutzlast senden, müssen wir es auf beiden physischen Seiten registrieren.

INFO

S2C und C2S sind zwei gängige Suffixe, die Server-to-Client und Client-to-Server bedeuten.

Dies kann in unserem gemeinsamen Initialisierers mit Hilfe von PayloadTypeRegistry.playS2C().register erfolgen, das eine CustomPayload.Id und einen type entgegennimmt.

PayloadTypeRegistry.playS2C().register(SummonLightningS2CPayload.ID, SummonLightningS2CPayload.CODEC);

Eine ähnliche Methode existiert, um Client-to-Server Payloads zu registrieren: PayloadTypeRegistry.playC2S().register.

Senden eines Pakets an den Client

Um ein Paket mit unserem benutzerdefinierten Payload zu senden, können wir ServerPlayNetworking.send verwenden, das einen ServerPlayer und einen CustomPayload entgegennimmt.

Beginnen wir mit der Erstellung unseres Blitz-Kartoffel-Item. Du kannst use überschreiben, um eine Aktion auszulösen, wenn das Item verwendet wird. In diesem Fall, lasst uns Pakete an die Spieler in den Serverlevel senden.

public class LightningTaterItem extends Item {
	public LightningTaterItem(Properties properties) {
		super(properties);
	}

	@Override
	public InteractionResult use(Level level, Player user, InteractionHand hand) {
		if (level.isClientSide()) {
			return InteractionResult.PASS;
		}

		SummonLightningS2CPayload payload = new SummonLightningS2CPayload(user.blockPosition());

		for (ServerPlayer player : PlayerLookup.world((ServerLevel) level)) {
			ServerPlayNetworking.send(player, payload);
		}

		return InteractionResult.SUCCESS;
	}
}

Schauen wir uns den obigen Code an.

Wir senden nur Pakete, wenn die Aktion auf dem Server initiiert wird, indem wir frühzeitig mit einer isClient-Prüfung zurückkehren:

if (level.isClientSide()) {
	return InteractionResult.PASS;
}

Wir erstellen eine Instanz des Payloads mit der Position des Users:

SummonLightningS2CPayload payload = new SummonLightningS2CPayload(user.blockPosition());

Schließlich rufen wir die Spieler in dem Serverlevel durch PlayerLookup ab und senden ein Paket an jeden Spieler.

for (ServerPlayer player : PlayerLookup.world((ServerLevel) level)) {
	ServerPlayNetworking.send(player, payload);
}

INFO

Fabric API bietet PlayerLookup, eine Sammlung von Hilfsfunktionen, die Spieler auf einem Server suchen.

Ein häufig verwendeter Begriff zur Beschreibung der Funktionalität dieser Methoden ist "Tracking". Es bedeutet, dass eine Entität oder ein Chunk auf dem Server dem Client eines Spielers bekannt ist (innerhalb seiner Sichtweite) und die Entität oder die Block Entität sollte die Clients über Änderungen informieren.

Tracking ist ein wichtiges Konzept für effizientes Networking, damit nur die notwendigen Spieler durch das Senden von Paketen über Änderungen informiert werden.

Empfangen eines Pakets auf dem Client

Um ein von einem Server gesendetes Paket auf dem Client zu empfangen, musst du angeben, wie du das eingehende Paket behandeln willst.

Dies kann im Client-Initialisierer erfolgen, indem ClientPlayNetworking.registerGlobalReceiver aufgerufen und eine CustomPayload.Id und ein PlayPayloadHandler übergeben wird, der eine funktionale Schnittstelle ist.

In diesem Fall definieren wir die auszulösende Aktion innerhalb der Implementierung der PlayPayloadHandler-Implementierung (als Lambda-Ausdruck).

ClientPlayNetworking.registerGlobalReceiver(SummonLightningS2CPayload.ID, (payload, context) -> {
	ClientLevel level = context.client().level;

	if (level == null) {
		return;
	}

	BlockPos lightningPos = payload.pos();
	LightningBolt entity = EntityType.LIGHTNING_BOLT.create(level, EntitySpawnReason.TRIGGERED);

	if (entity != null) {
		entity.setPos(lightningPos.getX(), lightningPos.getY(), lightningPos.getZ());
		level.addEntity(entity);
	}
});

Schauen wir uns den obigen Code an.

Wir können auf die Daten aus unserem Payload zugreifen, indem wir die Getter-Methoden des Records aufrufen. In diesem Fall payload.pos(). Welche genutzt werden können, um die x,- y- und z-Positionen abzurufen.

BlockPos lightningPos = payload.pos();

Schließlich erstellen wir eine LightningBolt und fügen diesen dem Level hinzu.

LightningBolt entity = EntityType.LIGHTNING_BOLT.create(level, EntitySpawnReason.TRIGGERED);

if (entity != null) {
	entity.setPos(lightningPos.getX(), lightningPos.getY(), lightningPos.getZ());
	level.addEntity(entity);
}

Wenn du nun diesen Mod auf einem Server installierst und ein Spieler dein Item "Lightning Tater" benutzt, sehen alle Spieler Blitze, die an der Position des Users einschlagen.

Senden eines Pakets an den Server

Genau wie beim Senden eines Pakets an den Client erstellen wir zunächst einen benutzerdefinierten Payload. Dieses Mal, wenn ein Spieler eine giftige Kartoffel auf einer lebenden Entität verwendet, fordern wir den Server auf, den Leuchten-Effekt auf diese anzuwenden.

public record GiveGlowingEffectC2SPayload(int entityId) implements CustomPacketPayload {
	public static final Identifier GIVE_GLOWING_EFFECT_PAYLOAD_ID = Identifier.fromNamespaceAndPath(ExampleMod.MOD_ID, "give_glowing_effect");
	public static final CustomPacketPayload.Type<GiveGlowingEffectC2SPayload> ID = new CustomPacketPayload.Type<>(GIVE_GLOWING_EFFECT_PAYLOAD_ID);
	public static final StreamCodec<RegistryFriendlyByteBuf, GiveGlowingEffectC2SPayload> CODEC = StreamCodec.composite(ByteBufCodecs.INT, GiveGlowingEffectC2SPayload::entityId, GiveGlowingEffectC2SPayload::new);

	@Override
	public Type<? extends CustomPacketPayload> type() {
		return ID;
	}
}

Wir übergeben den entsprechenden Codec zusammen mit einem Methodenverweis, um den Wert aus dem Record zu erhalten und diesen Codec zu bauen.

Dann registrieren wir unseren Payload in unserem gemeinsamen Initialisierer. Diesmal jedoch als Client-to-Server Payload unter Verwendung von PayloadTypeRegistry.playC2S().register.

PayloadTypeRegistry.playC2S().register(GiveGlowingEffectC2SPayload.ID, GiveGlowingEffectC2SPayload.CODEC);

Um ein Paket zu senden, fügen wir eine Aktion hinzu, wenn der Spieler eine giftige Kartoffel benutzt. Wir werden das Event UseEntityCallback verwenden, um die Dinge übersichtlich zu halten.

Wir registrieren das Event in unserem Client-Initialisierer, und wir verwenden isClientSide(), um sicherzustellen, dass die Aktion nur auf dem logischen Client ausgelöst wird.

UseEntityCallback.EVENT.register((player, level, hand, entity, hitResult) -> {
	if (!level.isClientSide()) {
		return InteractionResult.PASS;
	}

	ItemStack usedItemStack = player.getItemInHand(hand);

	if (entity instanceof LivingEntity && usedItemStack.is(Items.POISONOUS_POTATO) && hand == InteractionHand.MAIN_HAND) {
		GiveGlowingEffectC2SPayload payload = new GiveGlowingEffectC2SPayload(hitResult.getEntity().getId());
		ClientPlayNetworking.send(payload);

		return InteractionResult.SUCCESS;
	}

	return InteractionResult.PASS;
});

Wir erstellen eine Instanz unseres GiveGlowingEffectC2SPayload mit den notwendigen Argumenten. In diesem Fall, der Netzwerk ID der Zielentität.

GiveGlowingEffectC2SPayload payload = new GiveGlowingEffectC2SPayload(hitResult.getEntity().getId());

Schließlich senden wir ein Paket an den Server, indem wir ClientPlayNetworking.send mit der Instanz unseres GiveGlowingEffectC2SPayload aufrufen.

ClientPlayNetworking.send(payload);

Empfangen eines Pakets auf dem Server

Dies kann im gemeinsamen Initialisierer geschehen, indem man ServerPlayNetworking.registerGlobalReceiver aufruft und eine CustomPayload.Id und einen PlayPayloadHandler übergibt.

ServerPlayNetworking.registerGlobalReceiver(GiveGlowingEffectC2SPayload.ID, (payload, context) -> {
	Entity entity = context.player().level().getEntity(payload.entityId());

	if (entity instanceof LivingEntity livingEntity && livingEntity.closerThan(context.player(), 5)) {
		livingEntity.addEffect(new MobEffectInstance(MobEffects.GLOWING, 100));
	}
});

INFO

Es ist wichtig, dass du den Inhalt des Pakets auf der Serverseite validierst.

In diesem Fall überprüfen wir anhand der Netzwerk-ID, ob die Entität existiert.

Entity entity = context.player().level().getEntity(payload.entityId());

Außerdem muss es sich bei der Zielentität um eine lebende Entität handeln, und wir beschränken die Reichweite der Zielentität vom Spieler auf 5.

if (entity instanceof LivingEntity livingEntity && livingEntity.closerThan(context.player(), 5)) {

Wenn ein Spieler nun versucht, eine giftige Kartoffel auf einer lebenden Entität zu verwenden, wird der Leuchten-Effekt auf diese angewendet.