`data/block_components/`

A block component: typed data stored on one block cell, such as a sign’s text or a chest’s contents. It exists only while the cell holds a block its applies_to mask matches, and is removed with the block. Records are saved with their chunk and sent to the clients its audience admits. A component may name handler sections that run in the same transaction when a record is removed or added, may be sealed to one namespace’s transaction sections, and may be left out of undo, clipboard and blueprint records.


Registry	`manifold:block_component`
Files	`data/block_components/.ron`, `.update.ron`, `*.final.ron`
Sides	both: the server and every client load it, and the handshake’s data hash covers it
Reads	nothing
Contract	Block components (`docs/architecture/block-components.md`), data stage

Entry

A record, written BlockComponent(..); the name before the parentheses is optional.

Field	Type	Required	Default	Description
`id`	`string`	yes		The component’s key, `<mod-id>:<name>`.
`codec`	`BlockComponentCodec`	yes		How the bytes are encoded: a serde type described by `schema`, or bytes the schema describes field by field.
`schema`	list of `BlockComponentField`	no	none	The fields of the bytes, in order; for `shape: Elements`, one element’s.
`persist`	`u16`	yes		The persist version records are written at, from 1. A record saved at another version stays offline until a version that reads it.
`audience`	`BlockAudience`	no	`Public`	Who receives records: `Public` (every client holding the chunk), `Owner` (the record owner’s connections) or `Viewers` (the cell’s viewer set). `Party` is refused until block delivery reads party relations.
`replicate`	`BlockDelivery`	no	`None`	When records reach clients.
`applies_to`	`block-mask`	yes		The blocks the component may exist on.
`max_bytes`	`u32`	yes		The largest encoded record, 1 to 65,536 bytes.
`orientation_sensitive`	`bool`	no	`false`	Whether rotating or mirroring the cell needs the declaring mod’s transform hook.
`undo`	`BlockUndo`	no	`Include`	Whether undo records, clipboards and blueprints capture records.
`on_remove`	`BlockHandler`	no	`None`	The transaction section kind appended when a record is removed (`Handler("item.spill")`); an unregistered kind refuses the transaction.
`on_add`	`BlockHandler`	no	`None`	The transaction section kind appended when a record is created.
`writer`	`BlockWriter`	no	`Any`	Who may write records: `Any`, or only transaction sections of one namespace (`Section("item")`).
`shape`	`BlockShape`	no	`Whole`	`Whole` records, or `Elements` (a list of optional elements, sent as element deltas).

Variant	Written	Description
`Postcard`	`Postcard`	A serde type encoded with postcard, described by `schema`.
`Dynamic`	`Dynamic`	Bytes the schema describes field by field.

`BlockComponentField`

One field of a block component’s schema.

A record: BlockComponentField(..) or (..).

Field	Type	Required	Default	Description
`name`	`string`	yes		The field’s name.
`kind`	`field-kind`	yes		The field’s kind.

`BlockAudience`

Who receives a block component’s records.

Variant	Written	Description
`Owner`	`Owner`	The connections of the record’s owner.
`Party`	`Party`	The owner’s party: refused for block components for now.
`Public`	`Public`	Every client holding the chunk.
`Viewers`	`Viewers`	The cell’s viewer set.

`BlockDelivery`

When block component records reach clients.

Variant	Written	Description
`None`	`None`	Never: server only.
`ToAll`	`ToAll`	With the chunk and on every change, to the clients the audience admits.
`OnRequest`	`OnRequest`	Only to the cell’s viewer set.

`BlockUndo`

Whether records travel through undo, clipboards and blueprints.

Variant	Written	Description
`Include`	`Include`	They do.
`Exclude`	`Exclude`	They never do: a restored or pasted block comes back without it.

`BlockHandler`

A handler section kind, or none.

Variant	Written	Description
`None`	`None`	No handler.
`Handler`	`Handler(string)`	The section kind to append.

`BlockWriter`

Who may write a block component.

Variant	Written	Description
`Any`	`Any`	Any transaction section.
`Section`	`Section(string)`	Only sections whose kind is this namespace or starts with it and a `.`.

`BlockShape`

How a block component’s bytes are structured.

Variant	Written	Description
`Whole`	`Whole`	One value.
`Elements`	`Elements`	A list of optional elements.

Value forms used here: block-mask, field-kind.

`data/block_components/`

Entry

Example

Types

`BlockComponentCodec`