KubeJS Integration | Nourished Wiki

Nourished includes an optional KubeJS integration for registering nutrients, nutrient curves, and tracker milestones from scripts, and for responding to gameplay events.

KubeJS is optional. Install it alongside Nourished to use this integration. Nourished’s KubeJS API is currently experimental and may change between releases.

Script locations

Use startup_scripts for registrations that define nutrients, curves, or tracker milestones. Use server_scripts for gameplay event listeners.

kubejs/
├── startup_scripts/
└── server_scripts/

Reload scripts or restart the game after changing startup registrations.

Registering a nutrient

Call NourishedAPI.registerNutrient() from a startup script:

NourishedAPI.registerNutrient({
  id: "omega3",
  displayName: "Omega-3",
  color: 0x4AA3FF,
  decayRate: 0.0012,
  critical: 0.12,
  low: 0.30,
  excess: 0.90,
  icon: "minecraft:cod",
  tags: ["nourished:nutrients/omega3"],
  tooltipColor: 0xFFAA00,
  tooltipText: "Omega-3 from foods rich in healthy fats."
});

Required fields are id and displayName. Optional fields are:

Field	Purpose
`color`	Default nutrient bar color
`decayRate`	Default decay rate
`critical`	Critical threshold
`low`	Low threshold
`excess`	Excess threshold
`beneficial`	Whether the nutrient is beneficial; defaults to `true`
`icon`	Item ID used as the nutrient icon
`tags`	Nutrient tags associated with the definition
`tooltipColor`	Default tooltip text color, separate from the bar color
`tooltipText`	Runtime tooltip text for this nutrient

Nutrient IDs should be unique. Registering an ID that is already in use can fail. Registering a nutrient does not assign foods to it; add item mappings or a nutrient item tag separately. See Custom Nutrients for the config, datapack, and tooltip options.

Registering a nutrient response curve

Use NourishedAPI.registerNutrientCurve() in a startup script to select a built-in response curve for a nutrient:

NourishedAPI.registerNutrientCurve({
  nutrient: "protein",
  preset: "DIMINISHING"
});

Built-in presets are FLAT, DIMINISHING, CONFIDENCE_GATED, and SYNERGY. Preset names are case-insensitive.

For a custom curve, use the "custom" preset and provide a grid:

NourishedAPI.registerNutrientCurve({
  nutrient: "omega3",
  preset: "custom",
  grid: {
    xCells: 2,
    yCells: 2,
    multipliers: [
      1.0, 1.0, 1.0,
      1.0, 0.8, 0.6,
      1.0, 0.6, 0.3
    ]
  }
});

The multipliers array must contain (xCells + 1) * (yCells + 1) numbers in row-major order. A curve can only be registered once per nutrient through this API.

Registering tracker milestones

Use NourishedAPI.registerTrackerMilestone() from a startup script:

NourishedAPI.registerTrackerMilestone({
  id: "mymod:activity/mining/tunnel_rat",
  trackerId: "nourished:activity/mining_blocks",
  goal: 500.0,
  scope: "current_period",
  rewardEffectId: "minecraft:night_vision",
  rewardAmplifier: 0,
  rewardDuration: 600
});

Required fields are id, trackerId, goal, and scope. scope must be "lifetime" or "current_period". Optional reward fields are rewardEffectId, rewardAmplifier, rewardDuration, and advancementId.

Querying player data

The NourishedAPI script binding provides:

NourishedAPI.getNutrientKeys()
NourishedAPI.getNutrientLevel(player, "fruits")
NourishedAPI.isNutrientCritical(player, "fruits")
NourishedAPI.getGutHealth(player)

getNutrientKeys() returns the registered nutrient keys. The player query functions expect a player object supplied by KubeJS, such as event.player in an event callback.

Gameplay events

Nourished events are available under the NourishedEvents event group. Register listeners in a server script:

NourishedEvents.nutrientChanged(event => {
  console.log(`${event.nutrientKey}: ${event.oldValue} -> ${event.newValue}`);
});

All of these are server events:

Event	Fields	When it fires
`nutrientChanged`	`player`, `playerId`, `nutrientKey`, `oldValue`, `newValue`	A nutrient value changes
`nutrientCritical`	`player`, `playerId`, `nutrientKey`	A nutrient reaches its critical threshold
`nutrientExcess`	`player`, `playerId`, `nutrientKey`	A nutrient reaches its excess threshold
`sourceConsumed`	`playerId`, `itemId`, `nutrientKey`, `amount`	A food source applies a nutrient value
`foodEaten`	`player`, `itemId`, `nutrientDeltas`	Nourished processes a food item; `nutrientDeltas` maps nutrient keys to applied amounts
`gutHealthChanged`	`player`, `playerId`, `oldValue`, `newValue`, `cause`	Gut health changes
`rawFoodPenalty`	`player`, `playerId`, `itemId`, `tier`	Nourished is about to apply a raw-food penalty
`nutrientModifier`	`player`, `playerId`, `itemId`, `nutrientKey`, `amount`	A nutrient amount is about to be applied

IDs such as itemId and playerId are strings. player is available on events that expose it; prefer playerId when you only need the UUID.

Modifying or cancelling an effect

nutrientModifier lets a script change the amount Nourished is about to apply:

NourishedEvents.nutrientModifier(event => {
  if (event.nutrientKey === "fruits") {
    event.amount *= 0.5;
  }
});

Calling event.cancel() on this event sets its amount to zero:

NourishedEvents.nutrientModifier(event => {
  if (event.itemId === "mymod:food_to_block") {
    event.cancel();
  }
});

rawFoodPenalty can be cancelled to prevent the pending penalty:

NourishedEvents.rawFoodPenalty(event => {
  if (event.itemId === "mymod:sushi") {
    event.cancel();
  }
});

These events are experimental. Test scripts on a server before relying on them in a modpack.