Stamina in your game (combat.stamina) #

What it is for #

combat.stamina gives the player one stamina gauge. Actions pay for themselves by name (attack, special, dash, guard, sprint, or any custom name), the gauge refills after a short pause, and at zero the player is exhausted: every action is refused until the gauge is back at a chosen share of its maximum. It charges the strikes of combat.melee and the dashes of movement.dash by itself, drains while the character sprints, and publishes the gauge to the HUD. It draws nothing: the HUD shows the variables.

Turn it on #

Install the kit in a project and set its settings with the tools below; gripforge kit api combat.stamina lists every setting, and gripforge docs combat-stamina prints this guide offline.

gripforge_gamekit_install   { project_id: "gkp_…", id: "combat.stamina" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "combat.stamina",
                              config: { "max": 120, "regen": 20, "costs": { "attack": 15 } } }

First example #

<!-- test: kits/combat_stamina/tests/combat_stamina.rs::a_named_action_is_paid_and_reported --> A named action is paid at its cost, reported by stamina.spent, and a number is a custom action.

combat.stamina.spend("attack")   // true: 100 -> 82, event stamina.spent { action: "attack", cost: 18, value: 82 }
combat.stamina.value()           // 82
combat.stamina.spend(30)         // true: a custom action, event stamina.spent { action: "custom" }
combat.stamina.value()           // 52

Settings and defaults #

Services #

• combat.stamina (service, also served as movement.stamina for the kits that climb, swim or glide): value(), max(), exhausted(), spend(action | amount, partial?) answers true when paid, costOf(action), drain(action, seconds), restore(amount), refill(), setMax(max, refill?).
• Variables for the HUD: player.stamina, player.stamina.max, player.exhausted.

Events #

• stamina.spent: an action was paid: its action, cost and what is left (value); a sprint drain emits nothing per tick.
• stamina.refused: an action was refused, with a reason of exhausted, short, cancelled or dead.
• stamina.exhausted: the gauge hit zero and the exhaustion state began; recover is the value it must reach again.
• stamina.recovered: the exhaustion state ended.
• stamina.restored: restore or refill gave points back (a rest, a potion).

Hooks and modding #

• stamina.spend: the player is about to pay cost for action; cost is mutable (0 makes the action free) and a tap can cancel, which refuses the action like an exhausted gauge (stamina.refused, reason cancelled).
• stamina.exhaust: a continuous decision asked once when the gauge hits zero and held until it is back at recover x max; recover is mutable, and cancelling it means no exhaustion state at all (an "endless stamina" mod).

Every setting above is moddable. A hook document of a game or a mod taps a decision:

{ "id": "free_dash", "hook": "stamina.spend", "match": { "action": "dash" }, "set": { "cost": 0 } }
{ "id": "endless_stamina", "hook": "stamina.exhaust", "cancel": true }

Using it from content #

Script verbs: actions stamina_spend (a named action, or a custom name with amount) and stamina_restore; conditions stamina_at_least and stamina_exhausted.

{ "stamina_spend": "guard" }
{ "stamina_restore": 50 }
{ "stamina_at_least": 20 }

When it does not do what you expect #

Limits #

• It manages the gauge of the player only, not one gauge per NPC.
• It runs on the web player and the native Rust host; there is no Godot, Unity or Unreal adapter yet.
• It draws no gauge: bind the three variables to a HUD.

Versions #

Kit combat.stamina 1.0.0 (since 2026-10-22); it needs game.engine ^1, and uses combat.melee, movement.dash and combat.core when they are installed. The shared movement.stamina pool is served by this kit.