Skip to main content

Class BatterySystem

Namespace: mobisim.Battery

Tracks an actor's remaining power, broadcasts level updates to UI and analysis consumers each frame, and fires a one-time depletion event when the battery reaches its minimum value.

[DisallowMultipleComponent]
public class BatterySystem : MonoBehaviour, IDataLoggable

Inheritance​

object→Object→Component→Behaviour→MonoBehaviour→BatterySystem

Implements​

IDataLoggable

Examples​

// Monitor the battery level via the event aggregator:
public class BatteryUI : MonoBehaviour, IHandle
{
    private void OnEnable()
    {
        UnityServiceLocator.Current.TryGet(out var aggregator);
        aggregator?.Subscribe(this, channelKey);
    }
    private void OnDisable()
    {
        UnityServiceLocator.Current.TryGet(out var aggregator);
        aggregator?.Unsubscribe(this, channelKey);
    }
    public void Handle(BatteryMessage msg) => slider.value = msg.BatteryLevel;
}

// Drain the battery from another system:
batterySystem.DrainBattery(0.5f * Time.deltaTime);

Remarks​

BatterySystem holds the authoritative charge level, exposes methods to drain or replenish it, fires a one-time depletion event when the minimum is reached, and exposes the level for per-frame logging via IDataLoggable. It is the single source of truth for an actor's power state; all other components read from or write to it rather than maintaining their own copies.

Level changes are published every frame via IEventAggregator rather than only on change, because UI consumers (sliders, fill bars) need continuous synchronisation with the render loop and should not need to hold state between frames. The channel-scoped publication (m_ChannelKey) ensures that multi-vehicle scenes do not cross-contaminate: each vehicle's battery UI subscribes only to its own vehicle's channel.

Optional sub-systems (shareableSystem, drainSystem) are attached by other components at runtime rather than being required fields. This keeps BatterySystem functional as a standalone charge-tracker when sharing or automatic drain are not needed.

Fields​

drainSystem​

Optional sub-system that automatically drains the battery at a configured rate over time.

[NonSerialized]
public BatteryDrainSystem drainSystem

Field Value​

BatteryDrainSystem

Remarks​

Like shareableSystem, this is set programmatically rather than in the Inspector. A null value means battery drain is entirely manual (driven by Single) calls from external systems such as a motor controller).

shareableSystem​

Optional sub-system that synchronises this battery level with a shared pool across multiple actors.

[NonSerialized]
public ShareableBatterySystem shareableSystem

Field Value​

ShareableBatterySystem

Remarks​

Marked [NonSerialized] because the reference is established programmatically at runtime by whichever component opts into battery sharing — it is not wired up in the Inspector. A null value means this actor's battery is independent.

Properties​

BatteryLevelMax​

The maximum battery level the system can hold.

public float BatteryLevelMax { get; }

Property Value​

float

BatteryLevelMin​

The minimum battery level to be considered depleted.

public float BatteryLevelMin { get; }

Property Value​

float

RuntimeBatteryLevel​

The current battery level, always clamped to [BatteryLevelMin, BatteryLevelMax].

public float RuntimeBatteryLevel { get; set; }

Property Value​

float

Remarks​

The setter fires m_OnBatteryUpdated immediately on every assignment so that local UI bound directly to this event (e.g., a slider wired in the Inspector) updates in sync with the value change. The event-aggregator broadcast happens separately each frame in Update rather than here, keeping the setter lightweight.

Methods​

Collect()​

Snapshots the current battery state into a BatteryDataLog for the analysis pipeline.

public DataLog Collect()

Returns​

DataLog — A BatteryDataLog cast to DataLog containing the current level, shareable level, and remaining battery life.

Remarks​

When shareableSystem or drainSystem are null (i.e., those optional sub-systems are not attached), the corresponding log fields are written as 0f. Downstream analysis code must treat a zero value as "not applicable" rather than "depleted" when these sub-systems are absent.

DrainBattery(float)​

Reduces the battery level by drainAmount.

public void DrainBattery(float drainAmount)

Parameters​

NameTypeDescription
drainAmountfloatAmount to subtract from the current battery level. Use a positive value to drain; pass a negative value to recharge.

Remarks​

Pass a positive value to consume charge (the common case). Passing a negative value will increase the level — this is intentional to support recharging scenarios but callers should be explicit about the direction.The setter clamps the result, so the level never goes below BatteryLevelMin or above BatteryLevelMax.