Skip to content

Player Gauges (UI)

Jump to bottom
Pheonix KageDesu edited this page Aug 15, 2025 · 1 revision

⚠️ Information actual for version 0.10.3 and above

header

What we’ll do

  • Where to add gauges in Plugin Parameters
  • How to add a new gauge (HP/MP/EXP or custom)
  • What each UGauge field means
  • How the NUI style JSON works and binds to gauge values
  • Quick examples and tips

Where to configure

Plugin Manager path:

  • Player and Party settings → UI Elements Settings → Gauges → Gauges List (uiGauges of type struct<UGauge>[])

Each entry in Gauges List is a UGauge (one on‑screen gauge).

pp

Add a gauge (quick steps)

  1. Open Gauges List → Add.
  2. Set “Style” to the NUI gauge style filename (from data/AABSZ/gauges/ without “.json”), e.g. player_hp.
  3. Set scripts:
    • maxValueScript: JavaScript returning max value (e.g. $gameParty.leader().mhp)
    • currentValueScript: JavaScript returning current value (e.g. $gameParty.leader().hp)
  4. Position:
    • positionX: e.g. center - 54hdp
    • positionY: e.g. bottom - 44hdp
  5. Refresh:
    • autoRefreshSeconds: e.g. 0.2 (0 = disabled)
    • autoRefreshOnVariable: a Game Variable ID to trigger refresh on change (0 = none)
  6. Optional:
    • visibilitySwitch: switch ID that hides/shows the gauge (0 = none)
    • opacityWhileMessage: 0–255 opacity while a message window is shown

Save and test.

UGauge fields (reference)

  • visibilitySwitch:int
    • Switch ID to toggle visibility (0 = ignore)
  • opacityWhileMessage:int
    • Opacity (0–255) during message display
  • style:string
    • The base filename of a NUI style JSON in data/AABSZ/gauges (e.g. player_hp)
  • maxValueScript:string
    • JS expression for the max (e.g. $gameParty.leader().mmp)
  • currentValueScript:string
    • JS expression for the current (e.g. $gameParty.leader().mp)
  • autoRefreshSeconds:number
    • Recompute scripts every N seconds (supports decimals, 0 = off)
  • autoRefreshOnVariable:int
    • Game Variable ID; recompute on change (0 = off)
  • positionX:string
    • X position expression (e.g. center, 120hdp, center + 40hdp)
  • positionY:string
    • Y position expression (e.g. bottom - 44hdp, 2hdp)

Notes:

  • Use $gameParty.leader().hp, .mhp, .mp, .mmp, .nexp (next level), .cexp (current level progress), etc.
  • You can also use $gameVariables.value(3) to bind to a variable.

About styles (NUI JSON)

  • Location: data/AABSZ/gauges/*.json
  • Example style: player_hp.json (already included)
  • Important bindings used by gauges:
    • x: $positionX (provided by UGauge.positionX)
    • y: $positionY (provided by UGauge.positionY)
    • rate: $rate01 (fill rate; assumed 0..1 based on current/max)
    • Text often uses $currentValue, $maxValue, $rate (assumed percent)

Example (from player_hp.json):

"bindings": {
  "x": "$positionX",
  "y": "$positionY",
  "rate": "$rate01"
}

And text:

"text": ["%1", "$currentValue", "$maxValue", "$rate"]

Assumptions:

  • $rate01 is computed as current/max (0..1), $rate is a percent. The plugin exposes $currentValue, $maxValue to styles.

Examples

Example 1: Player HP gauge

UGauge entry fields:

  • style: player_hp
  • maxValueScript: $gameParty.leader().mhp
  • currentValueScript: $gameParty.leader().hp
  • autoRefreshSeconds: 0.2
  • positionX: center - 54hdp
  • positionY: bottom - 44hdp

Example 2: Player MP gauge

  • style: player_mp
  • maxValueScript: $gameParty.leader().mmp
  • currentValueScript: $gameParty.leader().mp
  • autoRefreshSeconds: 0.2
  • positionX: center + 108hdp
  • positionY: bottom - 44hdp

Example 3: EXP gauge (level progress)

  • style: player_exp
  • maxValueScript: $gameParty.leader().nexp
  • currentValueScript: $gameParty.leader().cexp
  • autoRefreshSeconds: 0.2
  • positionX: center
  • positionY: bottom - 60hdp

Example 4: TP gauge

  • style: player_tp
  • maxValueScript: $gameParty.leader().mtp
  • currentValueScript: $gameParty.leader().tp
  • autoRefreshSeconds: 0.2
  • positionX: center
  • positionY: bottom - 60hdp

Example 5: Custom variable gauge

Track a Game Variable (ID 3) up to 100:

  • style: player_hp (or your own custom style)
  • maxValueScript: 100
  • currentValueScript: $gameVariables.value(3)
  • autoRefreshOnVariable: 3
  • autoRefreshSeconds: 0 (optional)
  • positionX: 20hdp
  • positionY: 20hdp

Position expressions quick tips

  • Absolute: 100 or 100hdp
  • Anchors: left, center, right, top, bottom
  • Combine: center + 40hdp, bottom - 60hdp

Troubleshooting

  • Gauge not moving: check currentValueScript and maxValueScript both return numbers, and that refresh is enabled (timer or variable).
  • Not visible: ensure visibilitySwitch is 0 or ON; confirm style filename matches a file in data/AABSZ/gauges.
  • Text shows raw placeholders: your style must bind text to $currentValue, $maxValue, $rate (as in player_hp.json).

Clone this wiki locally