EnergyStorage class

Namespace: DoriosCore · Package: DoriosCore/index.js

EnergyStorage manages Dorios Energy (DE) on a helper entity. It uses scoreboard-safe mantissa and exponent values so large capacities remain usable through ordinary numeric methods.

import { EnergyStorage } from "DoriosCore/index.js";

Definition

class EnergyStorage

Constructor

new EnergyStorage(entity)

new EnergyStorage(entity: Entity)

Creates an energy manager and ensures the entity has a scoreboard identity.

Parameter	Type	Description
entity	Entity	Helper or storage entity whose energy values are managed.

const energy = new EnergyStorage(entity);

Properties

Property	Type	Description
entity	Entity	Entity that owns the stored energy.
scoreId	`ScoreboardIdentity	undefined`
cap	number	Cached capacity last loaded or assigned by the manager.

Static methods

EnergyStorage.initializeObjectives()

EnergyStorage.initializeObjectives(): void

Creates or loads the energy, energyExp, energyCap, and energyCapExp scoreboard objectives. DoriosCore calls this during initialization; normal addons do not need to call it.

EnergyStorage.normalizeValue(amount)

EnergyStorage.normalizeValue(amount: number): NormalizedValue

Converts a number into a scoreboard-safe pair.

Parameter	Type	Description
amount	number	Raw energy amount to normalize. Nonfinite values are normalized safely by the storage implementation.

Returns:

interface NormalizedValue {
  value: number; // mantissa
  exp: number;   // base-10 exponent
}

EnergyStorage.combineValue(value, exp)

EnergyStorage.combineValue(value: number, exp: number): number

Reconstructs value × 10^exp.

Parameter	Type	Description
value	number	Stored mantissa.
exp	number	Stored base-10 exponent.

EnergyStorage.formatEnergyToText(value)

EnergyStorage.formatEnergyToText(value: number): string

Formats energy using DE, kDE, MDE, GDE, TDE, or PDE.

EnergyStorage.formatEnergyToText(1_500_000); // "1.50 MDE"

EnergyStorage.getEnergyFromText(input, index)

EnergyStorage.getEnergyFromText(input: string, index?: number): number | undefined

Parses a formatted energy amount from display or preserved-lore text.

Parameter	Type	Default	Description
input	string	—	Text containing one or more formatted DE values.
index	number	0	Zero-based formatted value to return. For preserved stored / capacity text, 0 selects stored energy and 1 selects capacity.

Returns undefined when the requested value cannot be parsed.

EnergyStorage.setCap(entity, amount)

EnergyStorage.setCap(entity: Entity, amount: number): void

Sets capacity without retaining a manager instance.

Parameter	Type	Description
entity	Entity	Entity receiving the new capacity.
amount	number	Maximum DE amount.

Instance methods

setCap(amount)

setCap(amount: number): void

Stores a new maximum capacity and updates the cached cap value.

getCap()

getCap(): number

Reads, combines, caches, and returns maximum capacity.

getCapNormalized()

getCapNormalized(): NormalizedValue

Returns the capacity mantissa and exponent without combining them.

set(amount)

set(amount: number): void

Normalizes and stores the raw current energy amount. Use add() or consume() when capacity and availability must be enforced.

Parameter	Type	Description
amount	number	Raw stored amount.

get()

get(): number

Returns current stored energy as a regular number.

getNormalized()

getNormalized(): NormalizedValue

Returns current stored energy as a mantissa/exponent pair.

getFreeSpace()

getFreeSpace(): number

Returns max(0, capacity - stored).

add(amount)

add(amount: number): number

Adds energy without exceeding free capacity for positive requests. Negative values subtract directly, so callers should use consume() when insufficient storage must fail safely.

Parameter	Type	Description
amount	number	Requested signed energy change.

Returns the signed amount actually applied.

consume(amount)

consume(amount: number): number

Consumes the full requested amount only when it is available. Entities tagged dorios:infinite_storage or with the legacy creative tag report success without reducing their value.

Parameter	Type	Description
amount	number	Positive amount required by the operation.

Returns amount on success and 0 for nonpositive or insufficient requests.

has(amount)

has(amount: number): boolean

Returns whether stored energy is at least amount.

isFull()

isFull(): boolean

Returns whether no free capacity remains.

rebalance()

rebalance(): void

Reads and rewrites the current amount to restore the preferred mantissa/exponent scale.

getPercent()

getPercent(): number

Returns fill percentage from 0 through 100.

display(slot)

display(slot?: number): void

Writes the correct 48-frame utilitycraft:energy_00 through utilitycraft:energy_48 item into the entity inventory. The item label includes stored energy, capacity, and percentage.

Parameter	Type	Default	Description
slot	number	0	Destination inventory slot.

transferTo(other, amount)

transferTo(other: EnergyStorage, amount: number): number

Moves up to amount, limited by source contents and target free space.

Parameter	Type	Description
other	EnergyStorage	Receiving storage.
amount	number	Maximum DE to move.

Returns the transferred amount.

transferToEntity(entity, amount)

transferToEntity(entity: Entity, amount: number): number

Creates an EnergyStorage wrapper for entity and transfers up to amount into it.

receiveFrom(other, amount)

receiveFrom(other: EnergyStorage, amount: number): number

Moves energy from other into this storage. The amount is limited by the source and this storage's free space.

receiveFromEntity(entity, amount)

receiveFromEntity(entity: Entity, amount: number): number

Creates a source wrapper for entity and receives up to amount.

transferToNetwork(speed, mode)

transferToNetwork(speed: number, mode?: TransferMode): number

Sends energy to node positions supplied by UtilityCore's network system. DoriosCore performs the storage transfers; UtilityCore owns network discovery and connectivity.

Parameter	Type	Default	Description
speed	number	—	Total maximum DE sent by this call.
mode	"nearest" | "farthest" | "round"	Entity transferMode, then nearest	Target ordering or distribution behavior.

Stale cached node positions and tags are removed when they no longer resolve to energy containers. Returns total transferred energy.

Example

import { EnergyStorage } from "DoriosCore/index.js";

const energy = new EnergyStorage(entity);
energy.setCap(256_000);

const accepted = energy.add(5_000);

if (energy.has(800)) {
  energy.consume(800);
}

energy.transferToNetwork(4_000, "nearest");
energy.display(0);

Remarks

• Machine and Generator automatically create an energy manager as runtime.energy.
• Normal addon code does not manipulate scoreboard objectives directly.
• Call display() only for a slot backed by the required UtilityCraft resource-pack frames.