Solids API

Back to Zarith

com.raiiiden.zarith.api.ZarithSolid is for anything that moves and should behave like blocks: entities stand on it, arrows stick in it, explosions are blocked by it, rain stops on it. Block groups implement it, and so do Felled’s fallen trees. Implement it yourself when you have a moving object that is not a block group, such as an entity with its own model and a few collision boxes.

The point of the interface is that you write no mixins. Zarith has one set of mixins for all of this, and every registered solid gets their effects. Two mods redirecting the same vanilla call crash the game, so if your mod and Zarith both mixed into entity collision, players would get a crash on launch.

What you get

Registering

Register the solid when it joins a level and remove it when it leaves, on both sides:

ZarithSolids.add(this);     // when it joins a level
ZarithSolids.remove(this);  // when it leaves

For an entity, the reliable place is the level’s own entity callback, which fires for every way an entity can arrive or go, chunk loading and unloading included. BlockGroupEntity wraps setLevelCallback for this; copy that approach.

The set of solids is stored on the Level object itself (a mixin adds a SolidIndex field), so it goes away with the level and nothing can leak across worlds. Solids that report isSolidRemoved() are dropped from the set the next time it is searched.

Lookups

With 12 or fewer solids in a level, near just checks them all. With more, it uses a grid of 8 by 8 block columns rebuilt at most once a tick, with each solid’s bounds padded by 2 blocks so one that moved since the rebuild is still found. A search covering more than 64 columns falls back to checking every solid.

The interface

Methods are named solidLevel, isSolidRemoved and solidBounds rather than reusing Entity’s level(), isRemoved() and getBoundingBox(). On obfuscated Minecraft versions those entity methods are renamed in the shipped jar, and an interface method an entity only inherits would then have no implementation at run time.

Identity and shape

Collision

Cover and shade

Entities

The server side of carrying and pushing other entities is not done for you. BlockGroupEntity does it in its own tick: it finds riders before reading the new pose, carries them by the distance under their feet, then calls pushOut for every nearby non player entity. A custom solid that moves should do the same.

Helper classes

SolidFrame

SolidFrame does the geometry for boxes that all share one rotation, which is the common case: every box of a group turns with the group. It is a separating axis test between an axis aligned entity box and a turned box, in double precision.

SolidFrame frame = new SolidFrame();
frame.set(rotation);          // once per pose change

Then for each of your boxes, given its world centre (bx, by, bz) and half extents (hx, hy, hz) along your own axes:

SolidFrame.EPS is 1e-7. SolidFrame.SHALLOW is 0.05: a box deeper than this inside a solid is treated as stuck and left alone, as vanilla does with blocks.

SolidCollision

Static helpers around the collision mixin.

SolidCover

What weather, projectiles and explosions call. You can call it too.

A hit on a solid is reported as a BlockHitResult whose block position is the air block just inside the hit point. Projectile code that checks getBlockState(hit.getBlockPos()) sees air there, which is why Zarith also patches the arrow and projectile hit code.

SolidMotion

Called from Zarith’s client mixins: advanceAll(level, player) at the start of the client tick and beforeLocalPlayerTick(player) at the start of the local player’s tick. You do not call these.

A minimal solid

A sketch of a moving platform entity with one box, to show the shape of an implementation. It skips pose syncing and server side carrying, which you would add as BlockGroupEntity does.

public class PlatformEntity extends Entity implements ZarithSolid {

    private static final double HX = 2, HY = 0.25, HZ = 2;
    private final Quaternionf rotation = new Quaternionf();
    private final SolidFrame frame = new SolidFrame();
    private double nx, ny = 1, nz;

    // ... constructor, ticking, syncing ...

    @Override
    public void setLevelCallback(EntityInLevelCallback callback) {
        super.setLevelCallback(callback == EntityInLevelCallback.NULL ? callback : new EntityInLevelCallback() {
            @Override public void onMove() { callback.onMove(); }
            @Override public void onRemove(RemovalReason reason) {
                callback.onRemove(reason);
                ZarithSolids.remove(PlatformEntity.this);
            }
        });
        if (callback != EntityInLevelCallback.NULL) ZarithSolids.add(this);
    }

    @Override public Level solidLevel() { return level(); }
    @Override public boolean isSolidRemoved() { return isRemoved(); }
    @Override public AABB solidBounds() { return getBoundingBox(); }
    @Override public boolean isSolid() { return true; }

    @Override
    public double sweep(AABB box, Direction.Axis axis, double move) {
        nx = 0; ny = 1; nz = 0;
        double dx = axis == Direction.Axis.X ? Math.signum(move) : 0;
        double dy = axis == Direction.Axis.Y ? Math.signum(move) : 0;
        double dz = axis == Direction.Axis.Z ? Math.signum(move) : 0;
        double t = frame.contact(getX(), getY(), getZ(), HX, HY, HZ, box, dx, dy, dz);
        if (t == SolidFrame.NONE || t > Math.abs(move)) return move;
        nx = frame.nx; ny = frame.ny; nz = frame.nz;
        return Math.copySign(t, move);
    }

    @Override public double sweepNormalX() { return nx; }
    @Override public double sweepNormalY() { return ny; }
    @Override public double sweepNormalZ() { return nz; }

    // deepens, touches, overlaps, clip, resistanceAt, coverTop, cover, topAt,
    // landed, pushOut and clientAdvance follow the same pattern with the
    // matching SolidFrame method.
}

Call frame.set(rotation) whenever the rotation changes, and keep solidBounds() covering the turned box.