BlockEntityStateContainer¶
class BlockEntityStateContainer(val blockEntity: BlockEntity)
Wraps a block entity and tracks which properties have changed since the last sync.
This class provides dirty tracking for efficient server-to-client synchronization. Only modified properties are included in generated state packets.
Parameters¶
- blockEntity: The block entity to monitor for changes.
Constructors¶
BlockEntityStateContainer¶
constructor(blockEntity: BlockEntity)
Parameters
- blockEntity: The block entity to monitor for changes.
Properties¶
blockEntity¶
val blockEntity: BlockEntity
Parameters
- blockEntity: The block entity to monitor for changes.
isDirty¶
Whether any properties have changed.
lastSyncTick¶
var lastSyncTick: Long
Server tick when this container was last synced.
pos¶
val pos: BlockPos
The block position of the wrapped block entity.
Functions¶
captureCurrentValues¶
fun captureCurrentValues()
Re-reads every @Sync property straight off the block entity into propertyValues.
A container only ever learned a value when something changed it, so anything that was already true before the container existed - a tank filled last session, a machine loaded from disk - was invisible to it. That is fine while the only consumer is a delta stream, and wrong the moment someone opens a screen expecting to see current state.
Reads through the property getter rather than any backing map, so a delegated property (an itemField/fluidField storage) reports the live object exactly as the block entity's own code would. A getter that throws is skipped rather than propagated: seeding is best-effort, and one awkward property must not stop a screen opening.
clearDirty¶
fun clearDirty(serverTick: Long)
Clears the dirty flag, marking all properties as synced.
Should be called after successfully sending a state packet to clients.
Parameters
- serverTick: The server tick when the sync completed.
generatePacket¶
fun generatePacket(serverTick: Long): BlockEntityStatePacket?
Generates a state packet containing all dirty properties.
Return
A packet with all dirty property updates, or null if no changes.
Parameters
- serverTick: The current server tick.
getAllProperties¶
fun getAllProperties(): Map<String, Any?>
Gets a snapshot of all tracked properties.
Return
An immutable map of all property names and values.
getDirtyProperties¶
fun getDirtyProperties(): Set<String>
Gets all dirty property names.
Useful for debugging or logging.
Return
An immutable set of property names that have changed.
getProperty¶
fun getProperty(propertyName: String): Any?
Gets the current value of a property.
Return
The property value, or null if not tracked.
Parameters
- propertyName: The name of the property.
Gets the current value of a property with a type cast.
Return
The property value cast to type T, or null if not found/wrong type.
Parameters
-
propertyName: The name of the property.
-
T: The expected type of the property.
markAllDirty¶
fun markAllDirty()
Marks every known property dirty, so the next packet carries a full snapshot rather than a delta.
For a viewer who has just started tracking: they have missed every change so far, and a delta stream tells them nothing until the next one happens.
reset¶
fun reset()
Resets all tracking, clearing dirty flags and property values.
Useful when the block entity is unloaded or the container is no longer needed.
setPropertySerializer¶
fun <T> setPropertySerializer(propertyName: String, serializer: KSerializer<T>)
Registers a serializer for propertyName if one isn't already known.
Only needed for properties whose type can't be resolved automatically via kotlinx.serialization.serializerOrNull (see the init block).
Parameters
-
propertyName: The name of the property.
-
serializer: The serializer to use when encoding this property.
updateProperty¶
fun <T> updateProperty(propertyName: String, value: T?): Boolean
Records a property value and marks it dirty if it changed.
Return
True if the value changed, false if it's the same as before.
Parameters
-
propertyName: The name of the property.
-
value: The new value.