How to use a physics tick attachment

While attachments can simply be standalone classes holding data, there is another special use for attachments.

Using the ShipPhysicsListener interface, you can have your attachment run logic on every Physics Tick.

A ShipPhysicsListener attachment is one of the few ways to get a PhysShip or PhysLevel.

Usage

Modify your existing attachment class to implement the ShipPhysicsListener interface

package my.packagename

class MyAttachment(): ShipPhysicsListener

package my.packagename;

public final class MyAttachment implements ShipPhysicsListener {
    public MyAttachment() {}
}

Then implement the physics tick method:

package my.packagename

class MyAttachment(): ShipPhysicsListener {
    override fun physTick(
        physShip: PhysShip, physLevel: PhysLevel
    ) {
        // do stuff
    }
}

package my.packagename;

public final class MyAttachment implements ShipPhysicsListener {
    public MyAttachment() {}

    @Override
    public void physTick(@NotNull PhysShip physShip, @NotNull PhysLevel physLevel) {
        // do stuff
    }
}

Being wary of threads

The physics tick method is called on a different thread to the normal minecraft game thread. This means that any values you access from both the physics tick and the game tick must be thread safe!

For example, if my mod updates a direction variable in the attachment every game tick (e.g. in a Block Entity tick method), and it reads that variable in the physTick method, that variable must be thread safe.

Usually that means making it volatile or a Concurrent class.

If you ignore this advice, the game could crash randomly with a ConcurrentModificationException. If your users are experiencing this crash, check your attachments, you might've missed making a variable thread safe.

Last modified: 03 June 2026