States API

State machine implementation for managing entity and player states with transitions, guards, enter/exit hooks, and timed state changes.

For complete API documentation, see README.md.

---

State Context Registration

Define States

enum HealthState {
  HealthState_Healthy = 0,
  HealthState_Injured,
  HealthState_Critical,
  HealthState_Dead
};

Register Context

#define STATE_CONTEXT_HEALTH "myplugin.health"

public plugin_precache() {
  // Register context with initial state
  State_Context_Register(STATE_CONTEXT_HEALTH, HealthState_Healthy);
}

---

Register Hooks

Enter/Exit Hooks

public plugin_precache() {
  State_Context_Register(STATE_CONTEXT_HEALTH, HealthState_Healthy);

  // Enter hooks - called when entering state
  State_Context_RegisterEnterHook(STATE_CONTEXT_HEALTH, HealthState_Healthy, "@Health_Healthy_Enter");
  State_Context_RegisterEnterHook(STATE_CONTEXT_HEALTH, HealthState_Injured, "@Health_Injured_Enter");
  State_Context_RegisterEnterHook(STATE_CONTEXT_HEALTH, HealthState_Critical, "@Health_Critical_Enter");

  // Exit hooks - called when leaving state
  State_Context_RegisterExitHook(STATE_CONTEXT_HEALTH, HealthState_Critical, "@Health_Critical_Exit");
}

Transition Hook

Called on specific state-to-state transition:

public plugin_precache() {
  // ...

  // Called when transitioning from Injured to Critical
  State_Context_RegisterTransitionHook(
    STATE_CONTEXT_HEALTH,
    HealthState_Injured,
    HealthState_Critical,
    "@Health_Injured_To_Critical"
  );
}

@Health_Injured_To_Critical(const StateManager:this) {
  static pPlayer; pPlayer = State_Manager_GetUserToken(this);
  client_print(pPlayer, print_center, "Warning: Condition worsening!");
}

Change Hook

Called on any state change:

public plugin_precache() {
  State_Context_RegisterChangeHook(STATE_CONTEXT_HEALTH, "@Health_Changed");
}

@Health_Changed(const StateManager:this) {
  static pPlayer; pPlayer = State_Manager_GetUserToken(this);
  static HealthState:iNewState; iNewState = State_Manager_GetState(this);

  // Update HUD, play sound, etc.
  UpdateHealthHUD(pPlayer, iNewState);
}

Change Guard

Validate state changes before they happen:

public plugin_precache() {
  State_Context_RegisterChangeGuard(STATE_CONTEXT_HEALTH, "@Health_CanChange");
}

bool:@Health_CanChange(const StateManager:this, any:iOldState, any:iNewState) {
  static pPlayer; pPlayer = State_Manager_GetUserToken(this);

  // Can't become healthy if poisoned
  if (iNewState == HealthState_Healthy && IsPlayerPoisoned(pPlayer)) {
    return false;
  }

  return true;
}

---

State Manager Lifecycle

Create Manager

new StateManager:g_rgpPlayerStateManagers[MAX_PLAYERS + 1] = { StateManager_Invalid, ... };

public client_connect(pPlayer) {
  // Create manager with player as user token
  g_rgpPlayerStateManagers[pPlayer] = State_Manager_Create(STATE_CONTEXT_HEALTH, pPlayer);
}

Destroy Manager

public client_disconnected(pPlayer) {
  if (g_rgpPlayerStateManagers[pPlayer] != StateManager_Invalid) {
    State_Manager_Destroy(g_rgpPlayerStateManagers[pPlayer]);
    g_rgpPlayerStateManagers[pPlayer] = StateManager_Invalid;
  }
}

---

State Transitions

Immediate Transition

// Set state immediately
State_Manager_SetState(g_rgpPlayerStateManagers[pPlayer], HealthState_Injured);

Timed Transition

// Transition to state after delay
State_Manager_SetState(g_rgpPlayerStateManagers[pPlayer], HealthState_Critical, 5.0);

Force Transition

// Force transition even during another transition
State_Manager_SetState(g_rgpPlayerStateManagers[pPlayer], HealthState_Dead, _, true);

Reset to Initial State

// Reset to initial state (HealthState_Healthy)
State_Manager_ResetState(g_rgpPlayerStateManagers[pPlayer]);

Query Current State

new HealthState:iState = State_Manager_GetState(g_rgpPlayerStateManagers[pPlayer]);

switch (iState) {
  case HealthState_Healthy: { /* ... */ }
  case HealthState_Injured: { /* ... */ }
  case HealthState_Critical: { /* ... */ }
  case HealthState_Dead: { /* ... */ }
}

---

Hook Implementations

Enter Hook

@Health_Healthy_Enter(const StateManager:this) {
  static pPlayer; pPlayer = State_Manager_GetUserToken(this);
  client_print(pPlayer, print_center, "You are healthy!");

  // Clear any negative effects
  ClearHealthEffects(pPlayer);
}

@Health_Injured_Enter(const StateManager:this) {
  static pPlayer; pPlayer = State_Manager_GetUserToken(this);
  client_print(pPlayer, print_center, "You are injured. Be careful!");

  // Apply visual effect
  ApplyInjuredEffect(pPlayer);
}

@Health_Critical_Enter(const StateManager:this) {
  static pPlayer; pPlayer = State_Manager_GetUserToken(this);
  client_print(pPlayer, print_center, "CRITICAL! Find a medkit!");

  // Apply urgent effects
  ApplyCriticalEffect(pPlayer);
  StartHeartbeatSound(pPlayer);
}

Exit Hook

@Health_Critical_Exit(const StateManager:this) {
  static pPlayer; pPlayer = State_Manager_GetUserToken(this);

  // Remove critical effects
  StopHeartbeatSound(pPlayer);
  ClearCriticalEffect(pPlayer);

  client_print(pPlayer, print_center, "Condition stabilizing...");
}

---

Common Patterns

Health-Based State Updates

@Player_TakeDamage_Post(const pPlayer) {
  UpdateHealthState(pPlayer);
}

@Player_Healed(const pPlayer) {
  UpdateHealthState(pPlayer);
}

UpdateHealthState(const pPlayer) {
  static StateManager:pManager; pManager = g_rgpPlayerStateManagers[pPlayer];
  if (pManager == StateManager_Invalid) return;

  static Float:flHealth; pev(pPlayer, pev_health, flHealth);

  if (flHealth <= 0.0) {
    State_Manager_SetState(pManager, HealthState_Dead);
  } else if (flHealth < 20.0) {
    State_Manager_SetState(pManager, HealthState_Critical);
  } else if (flHealth < 50.0) {
    State_Manager_SetState(pManager, HealthState_Injured);
  } else {
    State_Manager_SetState(pManager, HealthState_Healthy);
  }
}

Infection State Machine

enum InfectionState {
  InfectionState_None = 0,
  InfectionState_Infected,
  InfectionState_Transforming,
  InfectionState_Zombie
};

#define STATE_CONTEXT_INFECTION "myplugin.infection"

public plugin_precache() {
  State_Context_Register(STATE_CONTEXT_INFECTION, InfectionState_None);

  State_Context_RegisterEnterHook(STATE_CONTEXT_INFECTION, InfectionState_Infected, "@Infection_Infected_Enter");
  State_Context_RegisterEnterHook(STATE_CONTEXT_INFECTION, InfectionState_Transforming, "@Infection_Transforming_Enter");
  State_Context_RegisterEnterHook(STATE_CONTEXT_INFECTION, InfectionState_Zombie, "@Infection_Zombie_Enter");

  State_Context_RegisterChangeGuard(STATE_CONTEXT_INFECTION, "@Infection_CanChange");
}

// When player is bitten
InfectPlayer(const pPlayer) {
  new StateManager:pManager = g_rgpPlayerInfectionState[pPlayer];

  // Start infection, transform after 10 seconds
  State_Manager_SetState(pManager, InfectionState_Infected);
  State_Manager_SetState(pManager, InfectionState_Transforming, 10.0);
}

@Infection_Transforming_Enter(const StateManager:this) {
  static pPlayer; pPlayer = State_Manager_GetUserToken(this);

  // Schedule final transformation
  State_Manager_SetState(this, InfectionState_Zombie, 5.0);

  client_print(pPlayer, print_center, "Transformation beginning...");
}

@Infection_Zombie_Enter(const StateManager:this) {
  static pPlayer; pPlayer = State_Manager_GetUserToken(this);

  // Complete transformation
  PlayerRole_Player_AssignRole(pPlayer, ROLE_ZOMBIE);
}

Reset on Spawn

public HamHook_Player_Spawn_Post(const pPlayer) {
  if (!is_user_alive(pPlayer)) return HAM_IGNORED;

  // Reset health state
  State_Manager_ResetState(g_rgpPlayerStateManagers[pPlayer]);

  // Reset infection state
  State_Manager_ResetState(g_rgpPlayerInfectionState[pPlayer]);

  return HAM_HANDLED;
}

---

Checklist

• Define state enum
• Register context in plugin_precache
• Create managers in client_connect
• Destroy managers in client_disconnected
• Register enter/exit hooks for state effects
• Use guard hooks to validate transitions
• Get user token with State_Manager_GetUserToken
• Reset states on spawn if appropriate