Skip to content

Commit

Permalink
fix(docs): More suggestions from Xfact
Browse files Browse the repository at this point in the history
  • Loading branch information
ChampionAsh5357 committed May 22, 2024
1 parent a8cf187 commit 1122d46
Showing 1 changed file with 21 additions and 7 deletions.
28 changes: 21 additions & 7 deletions docs/networking/streamcodecs.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,11 +60,15 @@ Additionally, there are some static instances that encode and decode primivites

#### Variable-Sized Number

`VAR_INT` and `VAR_LONG` are alternatives of `INT` and `LONG` respectively where the value is encoded to be as small as possible. This is done by encoding seven bits at a time, using the upper bit as a marker of whether there is more data for this number. Numbers between 0 and 2^28-1 for integers or 0 and 2^56-1 for longs will be sent shorter or equal to the number of bytes in a integer or long, respectively. If the values of your numbers are normally in this range and generally at the lower end of it, then these variable stream codecs should be used.
`VAR_INT` and `VAR_LONG` are stream codecs where the value is encoded to be as small as possible. This is done by encoding seven bits at a time, using the upper bit as a marker of whether there is more data for this number. Numbers between 0 and 2^28-1 for integers or 0 and 2^56-1 for longs will be sent shorter or equal to the number of bytes in a integer or long, respectively. If the values of your numbers are normally in this range and generally at the lower end of it, then these variable stream codecs should be used.

:::note
`VAR_INT` is an alternative for `INT`.
:::

#### Trusted Tags

`TRUSTED_TAG` and `TRUSTED_COMPOUND_TAG` are variants of `TAG` and `COMPOUND_TAG`, respectively, that have an unlimited heap to decode the tag to, compared to the 2MiB limit of `TAG` and `COMPOUND_TAG`. Only the [block entity data packet][blockentity] and [entity data serializers][entityserializer] use these trusted variants.
`TRUSTED_TAG` and `TRUSTED_COMPOUND_TAG` are variants of `TAG` and `COMPOUND_TAG`, respectively, that have an unlimited heap to decode the tag to, compared to the 2MiB limit of `TAG` and `COMPOUND_TAG`. Trusted tag stream condecs should ideally only be used in clientbound packets, such as what Vanilla does for [block entity data packet][blockentity] and [entity data serializers][entityserializer].

If a different limit should be used, then a `NbtAccounter` can be supplied with the given size using `ByteBufCodecs#tagCodec` or `#compoundTagCodec`.

Expand Down Expand Up @@ -172,11 +176,13 @@ public static final StreamCodec<RegistryFriendlyByteBuf, Integer> STREAM_CODEC =

A stream codec which supplies an in-code value and encodes to nothing can be represented using `StreamCodec#unit`. This is useful if no information should be synced across the network.

:::warning
Unit stream codecs expects that any encoded object must match the unit specified; otherwise an error will be thrown. Therefore, all objects must have some `equals` implementation that returns true for the unit object.
:::

```java
public static final StreamCodec<ByteBuf, IEventBus> UNIT_STREAM_CODEC =
StreamCodec.unit(
() -> NeoForge.EVENT_BUS // Can also be a raw value
);
public static final StreamCodec<ByteBuf, Item> UNIT_STREAM_CODEC =
StreamCodec.unit(Items.AIR);
```
### Lazy Initialized

Expand All @@ -185,7 +191,7 @@ Sometimes, a stream codec may rely on data that is not present when it is constr
```java
public static final StreamCodec<ByteBuf, IEventBus> LAZY_STREAM_CODEC =
NeoForgeStreamCodecs.lazy(
() -> StreamCodec.unit(NeoForge.EVENT_BUS)
() -> StreamCodec.unit(Items.AIR)
);
```

Expand Down Expand Up @@ -291,6 +297,10 @@ public static final StreamCodec<RegistryFriendlyByteBuf, Optional<DataComponentT

Registry objects can be sent across the network using one of three methods: `registry`, `holderRegistry`, or `holder`. Each takes in a `ResourceKey` representing the registry the registry object is in.

:::warning
Custom registries must be syncable by calling `RegistryBuilder#sync` and setting the value to `true`. Otherwise, the encoder will throw an exception.
:::

`registry` and `holderRegistry` returns the registry object or a holder wrapped registry object, respectively. These methods send over an id representing the registry object.

```java
Expand All @@ -312,6 +322,10 @@ public static final StreamCodec<RegistryFriendlyByteBuf, Holder<SoundEvent>> STR
);
```

:::note
`holder` will only throw an exception for a non-synced custom registry if the holder is not direct.
:::

### Holder Sets

Tags or sets of holder wrapped registry objects can be sent using `holderSet`. This takes in a `ResourceKey` representing the registry the registry objects are in.
Expand Down

1 comment on commit 1122d46

@neoforged-pages-deployments
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Deploying with Cloudflare Pages

Name Result
Last commit: 1122d46d381809867dc9d3827be822db0f46abaf
Status: ✅ Deploy successful!
Preview URL: https://83abb849.neoforged-docs-previews.pages.dev
PR Preview URL: https://pr-80.neoforged-docs-previews.pages.dev

Please sign in to comment.