gen1recomp/docs/rfcs/0008-device-power-info.md

RFC 0008 — Read-only device power information for sandboxed mods

Status

Proposed. Engine: Loader.lua, Sandbox.lua. Test: tests/modkit/cases/device_power_info.lua.

Motivation

A handheld UI mod can show the player's battery state and warn before power loss. The sandbox correctly removes love.system because that module also launches URLs and exposes other host operations, but it leaves no scoped way to read the harmless power values that LÖVE already provides.

The decision it extends

Extends the mod sandbox in src/mods/Sandbox.lua: blocked host modules stay blocked while legitimate operations receive narrow engine-owned facades.

The exact API delta

Add mod.device:powerInfo() -> state, percent.

The engine calls love.system.getPowerInfo() outside the mod sandbox and returns only its first two values. state is one of LÖVE's standard power states. percent is 0 through 100 or nil. When the platform has no power-information backend, the result is "unknown", nil.

No permission grants access to love.system; URL launching, clipboard access, OS identification, and the module table itself remain unavailable.

Migration note for existing mods

Mods that used love.system.getPowerInfo() replace that call with mod.device:powerInfo(). No other mod changes.

Parity tests

• No mod: loading no mods does not call the platform power backend.
• Mod API: a fixture mod loaded through the public loader receives state and percentage through mod.device, while the existing sandbox suite keeps proving that direct love.system access is refused.
• Unavailable backend: the public facade returns "unknown", nil rather than inventing battery data or failing mod load.

Deprecation etiquette

Nothing deprecated. The facade is additive; the sandbox's love.system block remains in force.