FFUtilities

Modrinth ↗Source ↗

This guide describes the public API in the current source version 0.2.12. Use the dependency guidance below and check that the mod is loaded when integrating conditionally.

FFUtilities — Modding API

FFUtilities is a shared library for Fabric, NeoForge and Forge. Package root: com.fyxe.ffutilities.api. The same API is built for every target below; gameplay mods bundle the jar for their target with Jar-in-Jar, so players do not need a separate download. Keep the required ffutilities dependency in your loader metadata (neoforge.mods.toml, mods.toml or fabric.mod.json); the embedded mod satisfies it.

Each target is published to the Fyxe Gitea Maven registry (or a sibling local publication) as com.fyxe.ffutilities:ffutilities-<minecraft>-<loader>:<version>:

Gradle Kotlin DSL, one target per build script (ffutilities holds the pinned version, for example 0.2.8):

// NeoForge (ModDevGradle)
val ffutilitiesJar = "com.fyxe.ffutilities:ffutilities-1.21.1-neoforge:$ffutilities"
implementation(ffutilitiesJar)
jarJar(ffutilitiesJar) {
    version {
        strictly("[$ffutilities,0.3.0)")
        prefer(ffutilities)
    }
}

// Forge 1.20.1 (ModDevGradle Legacy: modImplementation remaps the SRG jar for development)
val ffutilitiesJar = "com.fyxe.ffutilities:ffutilities-1.20.1-forge:$ffutilities"
modImplementation(ffutilitiesJar)
jarJar(ffutilitiesJar) {
    version {
        strictly("[$ffutilities,0.3.0)")
        prefer(ffutilities)
    }
}

// Fabric (Loom). Forge Config API Port comes along as a dependency, from
// maven("https://raw.githubusercontent.com/Fuzss/modresources/main/maven/")
val ffutilitiesJar = "com.fyxe.ffutilities:ffutilities-1.21.1-fabric:$ffutilities"
modImplementation(ffutilitiesJar)
include(ffutilitiesJar)

In a Groovy build script the NeoForge form jarJar(implementation("...")) { version { ... } } also works.

Differences between targets

• Minecraft 1.21.11 renamed ResourceLocation to Identifier; methods that take or return IDs use the name of their version.
• Configs: NeoForge's ModConfigSpec on 1.20.6+ (Fabric included, through Forge Config API Port) and Forge's ForgeConfigSpec on 1.20.1. ConfigValidators and ConfigLists work with both.
• ConfigScreens.register(modId) works on every loader: it adds the generated config screen on NeoForge 1.21.1+ (Mods list) and Fabric 1.21.1+ (Mod Menu), and does nothing where no generated screen exists (1.20.x, Forge). ConfigScreens.register(ModContainer) is also available on NeoForge.
• SimpleCodecReloadListener registers like any server data reload listener: AddReloadListenerEvent on NeoForge and Forge, Fabric API's resource loader on Fabric.

Core utilities

ResourceLocation id = Ids.of("mymod", "widget");
if (Mods.isLoaded("someothermod")) {
    // Access optional integration code only after the load check.
}
// 0.2.10: Better Combat's weapon category, with no dependency on Better Combat.
String category = BetterCombat.weaponCategory(player.getMainHandItem()).orElse("none");
if (BetterCombat.isHoldingWeapon(player)) {
    int swing = BetterCombat.comboCount(player); // 0 for the first swing of a combo
}
// 0.2.14: optional temperature categories (not degrees).
ToughAsNails.playerTemperature(player).ifPresent(level -> {
    // Apply your mod's own rules for ICY, COLD, NEUTRAL, WARM or HOT.
});
// import com.fyxe.ffutilities.api.compat.ToughAsNails;

// 0.2.12: an Epic Fight hit, read in a damage event: the item that swung and where its blade was.
ItemStack weapon = EpicFight.usedItem(source).orElse(attacker.getMainHandItem());
Optional<Vec3> blade = EpicFight.weaponPosition(source, victim);
// 0.2.6: rain or snow reaching an entity from open sky (top of hitbox, then feet).
if (WeatherUtil.isSnowingOn(entity)) {
    // Pile snow on it.
} else if (WeatherUtil.precipitationAt(level, pos) == Biome.Precipitation.RAIN) {
    // Rain falls on this block.
}

Version-proof wrappers (0.2.11)

These wrap vanilla code that changed between Minecraft 1.20.1 and 1.21.11, so a mod calls one method instead of writing its own Stonecutter conditional. Each behaves the same on every target.

ResourceLocation tired = Ids.of("mymod", "tired");
AttributeInstance stamina = AttributeUtil.instance(player, Ids.of("somemod", "max_stamina"));
AttributeUtil.setTransient(stamina, tired, -0.2, AttributeUtil.operation(2)); // null-safe, replaces an older one
EffectUtil.add(player, Ids.vanilla("slowness"), 100, 0);
int level = NbtUtil.getInt(tag, "level", 1);
int nutrition = FoodUtil.food(stack).map(FoodUtil.FoodValues::nutrition).orElse(0);
dispatcher.register(Commands.literal("mymod").requires(CommandUtil.requires(CommandUtil.GAME_MASTER)));

On 1.21.11 the type is called Identifier instead of ResourceLocation.

Config and data

ConfigValidators validates resource locations, tags, registry IDs, weighted entries, keyed numbers, booleans, nonblank strings, and hex colors (hexColor, 0.2.10). KeyedEntries.split separates a config entry at the last occurrence of a chosen character. Blank lines and comments (# followed by whitespace, or ##) are skipped, while tag keys such as #minecraft:skeletons=#6E5134 are kept. ConfigLists parses lists into maps of string or resource ID keys to doubles, integers, or booleans; freezeStringDoubles, freezeStringInts, and freezeStringBooleans return immutable snapshots.

ConfigValidators.keyed(separator, keyCheck, valueCheck) (0.2.11) builds a validator for your own key=value lines, with ConfigValidators.isDouble and isInt for values: keyed('=', RegistryMatcher::isValid, ConfigValidators::isDouble) accepts #minecraft:logs=2.5. ConfigValidators.expression("speed", "weight") accepts equations that parse and use only those variables.

RegistryUtil.item, .block, and .fluid return Optional lookups by ID. SimpleCodecReloadListener<T> is a base for datapack reload listeners backed by a codec; loaded() returns the current keyed entries. Keep domain-specific rules in the gameplay mod.

RegistryFilter, RegistryValues and RegistryMatcher (0.2.5, api.registry) read config entries written as an ID (minecraft:cow), a tag (#minecraft:logs) or a whole namespace (somemod:*). A filter's blacklist always wins and an empty whitelist allows everything; keyed values return the most specific match (ID, then tag, then namespace). Tag membership is read live, so datapack reloads apply. ConfigValidators.registryMatcher validates the entry format.

IdKeywords<V> (0.2.10, api.registry) maps words in IDs to values from config lines such as dagger=stab, for guessing what an unlisted modded item is. Names are split into words at anything other than a letter or digit; a keyword matches a word that equals it or ends with it (sword matches iron_longsword), a keyword with underscores matches those words in a row, and the longest keyword wins (pickaxe beats axe). IdKeywords.isKeyword validates keys.

IdKeywords<String> kinds = IdKeywords.parse(List.of("dagger=stab", "axe=chop", "pickaxe=dig"), '=', v -> v);
kinds.match(Ids.of("somemod", "iron_greataxe")); // Optional[chop]
kinds.match("diamond_pickaxe");                   // Optional[dig]

RegistryFilter<Block> blocks = RegistryFilter.of(Registries.BLOCK, WHITELIST.get(), BLACKLIST.get());
RegistryValues<Block, Double> mess = RegistryValues.parse(Registries.BLOCK, MULTIPLIERS.get(), '=', Double::valueOf);
if (blocks.allows(state.getBlockHolder())) {
    double multiplier = mess.getOrDefault(state.getBlockHolder(), 1.0); // "minecraft:mud=3.0", "#minecraft:dirt=1.25"
}

Math, time, and selection

MathUtil provides numeric clamp, lerp, inverseLerp, and stageIndex, plus (0.2.11) remap, remapClamped, approach (move toward a target by at most a step) and smoothstep. WeightedRandom.pick(items, weightFn, random) selects by integer weights. TickGate.every and everyStaggered support periodic work without a timer per entity.

ExpressionEvaluator.evaluate(expression, vars) evaluates configurable arithmetic with named variables (keys in lower case) and returns NaN when the text is malformed or a variable is missing. It supports + - * / %, ^ (power, right to left, so -2^2 is -4), parentheses and the functions abs, min, max (any number of arguments), clamp(x, low, high), pow, sqrt, floor, ceil and round. From 0.2.11, compile parses once into a reusable Expression with evaluate(vars) and variables(), tryCompile returns an Optional, and isValid(expression, allowedVariables) checks config input. Text after a complete expression (1 2) is now an error.

// Parse when the config loads, evaluate every tick.
Expression drain = ExpressionEvaluator.compile(DRAIN_EQUATION.get()); // "base * (1 + weight / 100) ^ 2"
double value = drain.evaluate(Map.of("base", 0.5, "weight", 40.0)); // 0.98

TimeFormat formats seconds or ticks as minutes and seconds, and (0.2.11) duration / ticksAsDuration give the two largest units: 45s, 2m 5s, 1h 2m, 3d 4h. TextUtil (0.2.11) has roman (4 is IV, 1 to 3999), decimal(value, maxDecimals) and percent (no trailing zeros, always a dot: decimal(2.50, 2) is 2.5), and copyable(text) / copyOnClick(style, text) for chat text that copies itself when clicked.

ColorUtil.parseHex reads #RRGGBB (opaque) or #AARRGGBB with a fallback color; ColorUtil.tryParseHex (0.2.10) returns an empty OptionalInt for malformed input instead, and ColorUtil.isHex checks a value. 0.2.11 adds toHex(argb, withAlpha), channel getters alpha, red, green, blue, builders argb, rgb, withAlpha, and mixing with fadeAlpha, lerp, scaleRgb and multiply (straight-alpha 0xAARRGGBB, channels clamped).

HUD and client helpers

HudPlacement.anchorX, anchorY, and relativeText calculate positions from anchor enums, offsets, and layout; clusterOffset(index, spacing, orientation, direction) (0.2.11) gives the {dx, dy} of the n-th icon in a row or column. ClientInput and GuiUtil (above) cover modifier keys, texture blits, scaled drawing and tooltips. HudTextStyle and related enums describe bold, outline, shadow, alignment, and expansion. HudTextRenderer.draw and ConfigScreens.register (see above) live under api.client; access those only from client code. TooltipMode.shouldShow(shiftDown) controls tooltip visibility.

FFUtilities does not define injury, spoilage, rarity, or encumbrance rules. Use each gameplay mod's own API for those features.

Sable cargo mass

A consumer calls the bridge from its optional Sable server physics hook, immediately before ServerSubLevel.updateMergedMassData. This example supplies total stack weight with FFItemWeight's public API. FFItemWeight already installs this integration automatically; do not register another weight provider for the same body.

// import com.fyxe.ffutilities.api.compat.Sable;
// import com.fyxe.ffutilities.api.player.InventoryUtil;
// import com.fyxe.ffitemweight.api.ItemWeightAPI;
Sable.refreshInventoryMass(subLevel, blockEntity ->
    InventoryUtil.blockItems(blockEntity).stream()
        .mapToDouble(ItemWeightAPI::getWeight).sum());