Wiki 9Minecraft Caelus API Wiki
Caelus API Wiki › Guide

Caelus API — Guide

Do I Need This?

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.

How It Works

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.

The Fall-Flying Attribute

  • 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.

Gliding From Any Source

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.

Tips

  • 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.

Developer API

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.