# Action System Design

## Overview

The combat system now uses a flexible **action point** system that automatically manages turn flow and supports complex action economies.

## How It Works

### Core State
```javascript
G.actionsRemaining // Current actions left this turn
G.actionsPerTurn   // Base actions per turn (modifiable by effects)
```

### Turn Flow
1. **Player turn begins** → `actionsRemaining` reset to `actionsPerTurn`
2. **Player uses move** → `consumeAction()` decrements counter
3. **Actions reach 0** → Auto-transition to robot turn
4. **Robot turn** → Robots attack → Back to player turn

### Key Benefit
**No explicit turn-end calls in moves!** Just call `consumeAction(G, events)` and it handles the rest.

---

## Supporting Complex Action Rules

### Example 1: Two Actions Per Turn
```javascript
// In setup:
actionsPerTurn: 2

// Now player can attack twice, or recharge + attack, etc.
```

### Example 2: Primary Weapon + One Other Action
```javascript
// Track whether primary has been used
G.primaryWeaponUsed = false;

// In useWeapon:
if (weapon.subtype === 'primary') {
  if (G.primaryWeaponUsed) {
    effects.showMessage('Primary weapon already used this turn!');
    return;
  }
  G.primaryWeaponUsed = true;
}

// In combatPlayerTurn.onBegin:
G.primaryWeaponUsed = false; // Reset for new turn
```

### Example 3: Free Actions (Doesn't Consume Action)
```javascript
// For example, a passive ability trigger:
useFreeAbility: ({ G, effects }) => {
  // Do stuff
  effects.showMessage('Free action!');
  // DON'T call consumeAction!
}
```

### Example 4: Speed Booster Consumable
```javascript
// In cards.js:
speed_booster: {
  id: 'speed_booster',
  name: 'Speed Booster',
  type: 'consumable',
  description: 'Take an extra action this turn',
  effect: (G) => {
    G.actionsRemaining += 1; // Add an action!
    G.actionsPerTurn += 1;   // Increase max for UI display
  }
}

// In move:
useConsumable: ({ G, effects }, consumableId) => {
  const consumable = getEquipmentDefinition(consumableId);
  consumable.effect(G);
  // Remove from inventory
  delete G.player.inventory[consumableId];
  effects.showMessage(`Used ${consumable.name}!`);
  // This is a free action - no consumeAction call!
}
```

### Example 5: Conditional Free Actions
```javascript
// Weapon that doesn't consume action if it kills
useWeapon: ({ G, ctx, effects, events }, weaponId, targetIndex) => {
  const robot = G.robots[targetIndex];
  const weapon = G.player.equipment[weaponId];
  
  // ... attack logic ...
  
  const robotKilled = robot.hp <= 0;
  
  if (robotKilled && weapon.id === 'executioner_blade') {
    effects.showMessage('Execute! Free action!');
    // Don't consume action on kill
  } else {
    consumeAction(G, events);
  }
}
```

### Example 6: Variable Action Costs
```javascript
// Heavy weapon costs 2 actions
useWeapon: ({ G, events, effects }, weaponId, targetIndex) => {
  const weapon = G.player.equipment[weaponId];
  
  // ... attack logic ...
  
  if (weapon.subtype === 'heavy') {
    consumeAction(G, events, 2); // Costs 2 actions!
  } else {
    consumeAction(G, events, 1); // Normal cost
  }
}
```

---

## Balance Tweaking

Want to experiment with different action economies? Just change one number:

```javascript
// In setup():
actionsPerTurn: 1  // Standard: one action per turn
actionsPerTurn: 2  // Aggressive: two actions per turn
actionsPerTurn: 3  // Frenetic: three actions per turn
```

Everything else automatically adjusts!

---

## UI Integration

The UI automatically:
- Shows "Actions: X/Y" during player turn
- Disables all actions during robot turn
- Shows "Pass Turn" button to skip remaining actions
- Updates action count in real-time

---

## Future Possibilities

- **Action banking**: Unused actions carry over (max 3)
- **Combo system**: Using certain actions in sequence grants bonus action
- **Stun effects**: Set `actionsPerTurn = 0` for a turn
- **Time pressure**: Lose 1 HP per action over 2 (encourages fast play)
- **Multi-target attacks**: Cost more actions but hit multiple robots

