Block groups

Back to Zarith

A block group is an entity holding any number of blocks that move together as one rigid body. One physics block, a rope link, a felled tree, an assembled house and a car are all block groups. The base class is com.raiiiden.zarith.group.BlockGroupEntity.

Out of the box a group:

• collides with terrain and with other bodies,
• lets entities stand on it, carries them, and pushes them out of its way (if it is solid to entities),
• floats, drags and drifts in water and lava (if its buoyancy hook says so),
• catches fire per block, spreads it, and burns blocks away,
• can be mined block by block, stripped with an axe and lit with flint and steel,
• is shoved and broken by explosions,
• thuds, kicks up dust and crushes entities it falls on,
• holds arrows that hit it,
• splits into separate groups when a block holding it together goes,
• saves and loads, and syncs to clients.

World interaction and Destruction cover those behaviours in detail. This page covers the data structures and how to make and customise groups.

PhysicsBlockEntity

com.raiiiden.zarith.entity.PhysicsBlockEntity is Zarith’s own concrete group, registered as zarith:physics_block. Every group the /zarith commands make is one of these. Use it when you want a group with standard behaviour and do not need your own entity type.

It adds a flags byte, synced to clients and saved as Flags:

It also turns load bearing on, so physics blocks take part in structural collapse.

// One block centred on a point
PhysicsBlockEntity.create(level, state, centre, flags);

// One block centred on a point, turned about its centre
PhysicsBlockEntity.create(level, state, centre, rotation, flags);

// Any grid; origin is where the grid's (0, 0, 0) corner goes
PhysicsBlockEntity.create(level, grid, origin, rotation, flags);

Each create only builds the entity. Call level.addFreshEntity(entity) to spawn it, and call setVehicle or link before that if you need them.

BlockGrid

com.raiiiden.zarith.group.BlockGrid stores a group’s blocks on an integer grid.

Layout

Blocks are kept in 8 by 8 by 8 bricks. Only bricks that hold a block exist. Each brick has four 512 bit masks (a block is here, it is live, it collides, it weighs) and a palette of block states with a byte or short index per spot, or no index array at all while the brick holds a single state. A brick of one material costs a few hundred bytes whatever its size.

Block ids

A block is addressed by an int id: its brick’s slot times 512 plus its spot inside the brick. Ids never change. A removed block keeps its id, its position and its state, and restore(id) brings it back. That is why packets, saved references and client predictions can all use ids safely. It also means an id can name a block that is no longer there, so check isLive(id) before using one you kept.

for (int id = grid.firstLive(); id >= 0; id = grid.nextLive(id)) {
    BlockState state = grid.state(id);
    CellKind kind = grid.kind(id);
    int x = grid.x(id), y = grid.y(id), z = grid.z(id);
}

Methods

Connectivity

components() returns the group’s connected parts as lists of ids. The rules:

• Solid blocks join any of their 26 neighbours that are also solid, diagonals included.
• A diagonal bond holds only while it is as built. If a solid block that sat between the two diagonal blocks was ever removed (its position is in the grid’s cut set), the diagonal bond is broken. This stops two blocks touching at an edge from holding a structure together after the block that really joined them is gone.
• Non solid blocks (SOFT, LOOSE) hang on the nearest solid part through faces, spreading outward from the solids. Non solid blocks that reach no solid form parts of their own.
• components(cracks) also treats the listed solid pairs (BlockGrid.crackKey(a, b)) as broken.

The cut set is saved with the grid and carried into pieces by subset, so a diagonal that was cut stays cut after the group splits or reloads.

CellKind

Every block in a group has a kind, decided when it is added.

SOFT blocks still count for mass and inertia but not for collision, so a tree’s crown makes it top heavy without snagging on everything. A group whose softBlocksEntities() returns true lets entities stand on its SOFT blocks too, though they still pass through terrain and bodies.

/zarith assemble makes blocks with a collision shape SOLID and everything else LOOSE.

The ordinals are saved, so new kinds must be added at the end of the enum.

How the body’s shape is built

Each time the body is built or reshaped, the group turns its grid into a BodyShape:

1. Live full cube blocks that weigh are merged into boxes with mergedBoxes, joining only blocks of the same kind and the same density. Mass only SOFT boxes and colliding SOLID boxes stay separate.
2. Every other weighing block adds its own collision boxes from BlockBodies.shapeOf, at its own density.
3. A vehicle’s ballast, if any, is added as one mass only box.

Each block’s density comes from the cellDensity(cell) hook, which by default is BlockBodies.density for weighing blocks and 0 for LOOSE ones. Blocks with zero density are left out.

After blocks are removed, or a block’s state changes, the body is reshaped in place. Its joints and vehicle are rebuilt about the new centre of mass by the core.

Making your own group type

Extend BlockGroupEntity when you want behaviour of your own: a tree that leaves saplings, a ship hull with its own drag, a wrecking ball.

public class CrateEntity extends BlockGroupEntity {

    public CrateEntity(EntityType<? extends CrateEntity> type, Level level) {
        super(type, level);
    }

    public static CrateEntity create(ServerLevel level, BlockGrid grid, Vector3d origin) {
        CrateEntity crate = new CrateEntity(MyEntities.CRATE.get(), level);
        crate.setup(grid, origin, new Quaternionf(), new Vector3f(), new Vector3f());
        return crate;
    }

    // Pieces that break off are crates too.
    @Override
    protected BlockGroupEntity newPiece(ServerLevel level) {
        return new CrateEntity(MyEntities.CRATE.get(), level);
    }

    @Override
    protected float buoyancy(int cell) {
        return cellDensity(cell) / 0.5f;   // floats half under
    }

    @Override
    protected boolean fireSpreadsToWorld() {
        return false;
    }
}

What you have to do yourself:

1. Register the entity type the way your loader wants. Copy Zarith’s builder settings: MobCategory.MISC, fireImmune(), a client tracking range of 10 chunks, and an update interval of 1. The server sends poses itself every tick, but vanilla’s own tracking packets should not lag behind. The size you give the builder does not matter, because the group overrides its bounding box.
2. Register the renderer. BlockGroupRenderer is generic over any BlockGroupEntity, so pass its constructor: BlockGroupRenderer::new.
3. Call setup before spawning. setup(grid, origin, rotation, linearVelocity, angularVelocity) fills a new group. Spawn with level.addFreshEntity.
4. Implement newPiece. It returns an empty group of your type for pieces that break off. Return null to drop pieces instead of spawning them; the blocks then stay in the parent.

On 1.20.1 and 1.21.1, extra saved data goes in readAdditionalSaveData(CompoundTag) and addAdditionalSaveData(CompoundTag); call super first. On 26.x those methods take ValueInput and ValueOutput, and you override readGroup(CompoundTag) and writeGroup(CompoundTag) instead, which hold the whole group under one key (saveKey(), default "zarith").

Hooks

Override these to tune a group. All are protected unless marked. “Server” hooks run on the logical server only.

Body and material

Fluids

Entities

Fire

Explosions and tools

Load and destruction

Impacts and sound

Lifecycle

Several hooks can remove the group (by burning, breaking or splitting it). Code after a hook in your own override should check isRemoved().

Public methods

State

Frames

Actions (server)

Global tuning (public static fields, apply to every group)

Removing blocks and splitting

Every way a block leaves a group (mining, burning, blasts, impacts, carving, collapse) ends in the same steps:

1. The blocks are removed from the grid.
2. grid.components() finds the parts that are left.
3. If there is more than one part, they are sorted by solid block count. The biggest stays in this group. Each other part with a solid block becomes a new group through newPiece and setup, starting with this group’s pose, velocity and spin and carrying its fire. A part with no solid block goes to looseComponent, which by default spawns it too.
4. Fire spots that no longer touch a block go out. onCellsRemoved runs. Load bearing groups ask for a structural check. Clients get the removed ids.
5. The body is reshaped, or, with no blocks left at all, the group is discarded. With only non solid blocks left, the next tick calls noSolidsLeft.

Pieces that break off through blasts, collapse or impacts are also flagged as debris when they are small enough, and are made slippery for their first 40 ticks (friction 0.05) so they slide away from what they broke off instead of wedging against it.

The client copy

On the client a group has the same grid, kept in step by packets, but no body. Its pose comes from buffered server snapshots drawn two ticks behind. When the local player breaks a block, the block disappears at once and comes back 30 ticks later if the server never confirmed it. See Networking and client.

The field renderCache (public, client) holds the renderer’s mesh for the group. Leave it alone.