UseCodec

Delegates field decoding/encoding to an existing Codec object.

Use this only for custom, hand-written codecs (for example, variable-byte-integer encoders or image-bitmap parsers). If the field's type is itself annotated with @ProtocolMessage, declare the field with that type directly instead — the processor generates the codec by convention and wires it up automatically, including sealed dispatch and forward references to codecs generated in the same compilation round. @UseCodec cannot forward-reference a KSP-generated codec class.

The referenced codec must be a Kotlin object implementing Codec<T>.

Without a length annotation — the codec reads directly from the buffer:

@ProtocolMessage
data class Message(
    @UseCodec(VariableIntCodec::class) val length: Int,
)
// Generated: val length = VariableIntCodec.decode(buffer)

With a length annotation — the codec receives a size-limited slice:

@ProtocolMessage
data class ImageFrame(
    val bitmapLength: Int,
    @UseCodec(PngBitmapCodec::class) @LengthFrom("bitmapLength") val bitmap: ImageBitmap,
)
// Generated: val _slice = buffer.readBytes(bitmapLength); val bitmap = PngBitmapCodec.decode(_slice)

For nested @ProtocolMessage types, skip @UseCodec entirely. Length annotations attach directly to the nested field:

@ProtocolMessage
data class Frame(
    val length: UShort,
    @LengthFrom("length") val body: BodyMessage,  // BodyMessage has @ProtocolMessage — no @UseCodec
)

Composes with @LengthPrefixed, @RemainingBytes, and @LengthFrom.

Parameters