Why a mount was refused

From Sunrise's modding bookead8a1e

EntityRef::start_riding(host, vehicle, force) seats a player or a mob on a mob, boat, minecart or generic seat entity and answers Ok(()). Where it refuses, it names the cause as a StartRidingRefusal:

RefusalCause
NoEntityA handle is stale or held out, or names an entity that was removed, is dying, or is in another level. Also the answer with no game backend.
PlayerVehicleThe vehicle is a player, forced or not.
UnsupportedRiderThe rider is neither a player nor a mob.
UnsupportedVehicleThe vehicle takes no passenger (a marker, or an entity that is not a seat).
SameEntityThe rider is the vehicle.
AlreadyRidingThe rider already rides this vehicle.
CycleThe vehicle rides the rider, directly or through other vehicles.
CannotRideUnforced, the rider may not ride now: a sneaking player, a mob in its boarding cooldown, a warden or a wither.
FullThe vehicle has no room. force passes a mob's or a seat's count, not a boat's or a minecart's storage limit.
CanceledA mod's entity_mount hook canceled the mount or the dismount from the old vehicle.
rust
match rider.start_riding(host, vehicle, false) {
    Ok(()) => {}
    Err(StartRidingRefusal::Full) => { /* try another seat */ }
    Err(other) => { /* `other` displays its cause */ }
}

The enum is #[non_exhaustive]: keep a wildcard arm. It crosses the wasm boundary whole, so a wasm mod reads the same refusal a native mod does.

Why nothing rides a player

Vanilla's Entity.startRiding refuses a vehicle whose entity type is not saved with the level before it reads force, and the player type is one: a player's save keeps no passengers, so a passenger on a player would have nowhere to be written. start_riding keeps that refusal, forced or not, and names it PlayerVehicle.

When entity_mount fires

entity_mount fires only after every other check passed: a refusal at those checks reaches no hook. (This is this engine's order; moving the hook earlier is tracked in #1557.) The checks run again after the hook, since a hook can fill, remove or remount the vehicle, and then name what the hook changed. Such a refusal means the requested mount did not complete; what the hook moved or removed stays as it left it.

Edit this page on GitHub · Spotted something wrong? Open an issue or ask on Discord.