Caelus API Wiki

Caelus API is a small library / API mod. It adds no blocks, items, or creatures of its own. Its entire job is to take the elytra's fall-flying (gliding) behaviour and turn it into a single, controllable entity attribute that other mods can read and write.

In vanilla, gliding is hard-wired: you can only fly when an elytra is worn in the chest armour slot and it has the glider data component. Caelus API replaces that fixed rule with the caelus:fall_flying attribute - if an entity's value for this attribute is high enough, the entity is allowed to glide; if it is not, the entity cannot. This makes "can this entity glide right now?" a flexible, stackable value instead of a single yes/no check on one slot.

Because it is a dependency, it is present in your game only because another mod relies on it.

Yes - if another mod relies on it. Caelus API is a required dependency for mods that move elytra flight off the chest slot or grant gliding from new sources - extra equipment slots, trinket/back slots, capes, wings, or status effects. Those mods will fail to load or lose their flight ability without it.

No - on its own. Caelus API by itself does nothing visible in-game: it adds no mobs, blocks, items, recipes, or world content, and it does not give you the ability to fly just by being installed. There is nothing to "use" directly as a player.

Rule of thumb: if your modpack or a mod lists Caelus API as a requirement, it needs to be present. Otherwise it serves no purpose alone.

Caelus API registers a new entity attribute, caelus:fall_flying, on living entities. The attribute has a small base value that is not enough to glide on its own. When something that should enable flight is present - for example a worn elytra - a modifier is added that raises the attribute above the gliding threshold.

The bundled elytra modifier is caelus:elytra (value 1.0, added on top of the base). Each game tick, while the gliding condition holds, the entity's total fall_flying value is high enough that the engine permits fall flying; when the source is removed, the modifier drops away and the entity can no longer glide.

This is what lets other mods enable gliding from any source: instead of only checking the chest slot, they simply contribute to the caelus:fall_flying attribute. The result is normal, smooth elytra gliding driven by an attribute rather than a single hard-coded item slot.

• caelus:fall_flying - the core attribute. A small base value (gliding off) plus modifiers from flight-granting sources. Once the total is high enough, the entity may glide.
• caelus:elytra modifier - the built-in modifier (value 1.0) that represents a normal worn elytra; it is what pushes the attribute over the threshold so a standard elytra still works exactly as players expect.

Because flight is decided by an attribute, dependent mods can grant gliding without using the vanilla chest slot at all. Typical sources other mods enable through Caelus API:

• a dedicated back / elytra equipment slot (so you can wear a chestplate and keep gliding),
• capes and wings that double as gliders,
• trinket / accessory items,
• status effects or buffs that temporarily allow flight,
• custom items that should let the holder glide.

In every case the player experience is the same as a vanilla elytra: jump, start gliding, and descend slowly with full directional control.

• Caelus API does not give you flight by itself - you still need a flight source (an elytra, or an item/slot from a mod that uses Caelus) to actually glide.
• It is fully compatible with normal elytra play: a standard elytra still grants gliding through the built-in modifier.
• Keep the build matched to your game version so the mods relying on it load correctly.
• There is normally no configuration you need to touch; it works silently in the background.

Modders use Caelus API to grant elytra-style gliding from custom sources without re-implementing fall-flying logic. Add it as a dependency, then interact with the fall-flying attribute.

Declaring the dependency

Declare Caelus API as a required dependency in your mod descriptor so the game enforces correct load order, and reference it from your build configuration.

Reading the attribute and capability

import com.illusivesoulworks.caelus.api.CaelusApi;
import net.minecraft.world.entity.ai.attributes.AttributeInstance;

// the fall-flying attribute holder
var attr = CaelusApi.getInstance().getFallFlyingAttribute();

// query whether an entity is currently allowed to glide
CaelusApi.TriState state = CaelusApi.getInstance().canFallFly(entity);
boolean allowed = CaelusApi.getInstance().canFallFly(entity, false);

// read the live value on an entity
AttributeInstance inst = entity.getAttribute(attr);
double value = inst == null ? 0 : inst.getValue();

Granting flight from your own item

// add the bundled elytra-style modifier while your gear is equipped
var modifier = CaelusApi.getInstance().getElytraModifier();
AttributeInstance inst = entity.getAttribute(CaelusApi.getInstance().getFallFlyingAttribute());
if (inst != null && !inst.hasModifier(modifier.id())) {
    inst.addTransientModifier(modifier);
}

Always compile and test against the exact Caelus API version your release targets - the attribute and API surface can change between game versions.

My game crashes or a mod fails to load mentioning Caelus. Make sure the correct Caelus API build is present and matches the version the dependent mod requires.

I installed Caelus API but I still cannot fly. That is expected - it adds no flight on its own. You need a flight source: a normal elytra, or an item/slot from a mod that uses Caelus API.

Can I wear a chestplate and still glide? Only if a mod that depends on Caelus API adds a separate slot for the elytra/glider; Caelus API provides the attribute that makes such a setup possible.

Can I remove it? Only if you also remove every mod that depends on it; otherwise those mods break or lose their flight ability.

Is it a cheat / creative-flight mod? No. It governs normal elytra-style gliding only; it does not add free creative flight.

There are several files with similar names - which do I pick? Pick the build whose version matches your game version and the requirement listed by the mod you are installing it for.