gameplay-mechanics

Q: How do I install gameplay-mechanics?

Run npx skills add https://github.com/pluginagentmarketplace/custom-plugin-game-developer --skill gameplay-mechanics in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/gameplay-mechanics/ (personal) or .claude/skills/gameplay-mechanics/ (project).

by pluginagentmarketplaceMedia & Creative

Core gameplay mechanics implementation, system interactions, feedback loops, and iterative balance refinement for engaging player experiences.

Installs: 300
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/pluginagentmarketplace/custom-plugin-game-developer --skill gameplay-mechanics

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads gameplay-mechanics automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Gameplay Mechanics Implementation

Core Mechanics Framework

┌─────────────────────────────────────────────────────────────┐
│                    ACTION → EFFECT LOOP                      │
├─────────────────────────────────────────────────────────────┤
│  INPUT          PROCESS          OUTPUT          FEEDBACK   │
│  ┌─────┐       ┌─────────┐      ┌─────────┐    ┌─────────┐ │
│  │Press│──────→│Validate │─────→│Update   │───→│Visual   │ │
│  │Button│      │& Execute│      │State    │    │Audio    │ │
│  └─────┘       └─────────┘      └─────────┘    │Haptic   │ │
│                                                 └─────────┘ │
│                                                              │
│  TIMING REQUIREMENTS:                                        │
│  • Input → Response: < 100ms (feels responsive)             │
│  • Animation start: < 50ms (feels instant)                  │
│  • Audio feedback: < 20ms (in sync with action)             │
└─────────────────────────────────────────────────────────────┘

Feedback Loop Design

FEEDBACK TIMING LAYERS:
┌─────────────────────────────────────────────────────────────┐
│  IMMEDIATE (0-100ms):                                        │
│  ├─ Button press sound                                      │
│  ├─ Animation start                                         │
│  ├─ Screen shake                                            │
│  └─ Controller vibration                                    │
│                                                              │
│  SHORT-TERM (100ms-1s):                                      │
│  ├─ Damage numbers appear                                   │
│  ├─ Health bar updates                                      │
│  ├─ Enemy reaction animation                                │
│  └─ Particle effects                                        │
│                                                              │
│  LONG-TERM (1s+):                                            │
│  ├─ XP/Score increase                                       │
│  ├─ Level up notification                                   │
│  ├─ Achievement unlock                                      │
│  └─ Story progression                                       │
└─────────────────────────────────────────────────────────────┘

Combat Mechanics

// ✅ Production-Ready: Combat State Machine
public class CombatStateMachine : MonoBehaviour
{
    public enum CombatState { Idle, Attacking, Blocking, Recovering, Staggered }

    [Header("Combat Parameters")]
    [SerializeField] private float attackDamage = 10f;
    [SerializeField] private float attackRange = 2f;
    [SerializeField] private float attackCooldown = 0.5f;
    [SerializeField] private float blockDamageReduction = 0.7f;
    [SerializeField] private float staggerDuration = 0.3f;

    private CombatState _currentState = CombatState.Idle;
    private float _stateTimer;

    public event Action<CombatState> OnStateChanged;
    public event Action<float> OnDamageDealt;
    public event Action<float> OnDamageTaken;

    public bool TryAttack()
    {
        if (_currentState != CombatState.Idle) return false;

        TransitionTo(CombatState.Attacking);
        StartCoroutine(AttackSequence());
        return true;
    }

    private IEnumerator AttackSequence()
    {
        // Wind-up phase
        yield return new WaitForSeconds(0.1f);

        // Active hit frame
        var hits = Physics.OverlapSphere(transform.position + transform.forward, attackRange);
        foreach (var hit in hits)
        {
            if (hit.TryGetComponent<IDamageable>(out var target))
            {
                target.TakeDamage(attackDamage);
                OnDamageDealt?.Invoke(attackDamage);
            }
        }

        // Recovery phase
        yield return new WaitForSeconds(attackCooldown);
        TransitionTo(CombatState.Idle);
    }

    public float TakeDamage(float damage)
    {
        float finalDamage = _currentState == CombatState.Blocking
            ? damage * (1f - blockDamageReduction)
            : damage;

        OnDamageTaken?.Invoke(finalDamage);

        if (finalDamage > 5f) // Stagger threshold
        {
            TransitionTo(CombatState.Staggered);
            StartCoroutine(RecoverFromStagger());
        }

        return finalDamage;
    }

    private void TransitionTo(CombatState newState)
    {
        _currentState = newState;
        _stateTimer = 0f;
        OnStateChanged?.Invoke(newState);
    }
}

Resource Economy System

ECONOMY BALANCE FORMULA:
┌─────────────────────────────────────────────────────────────┐
│  INCOME vs EXPENDITURE:                                      │
│                                                              │
│  Hourly Income = (Enemies/hr × Gold/Enemy) + PassiveIncome  │
│  Hourly Spend  = (Upgrades + Consumables + Deaths)          │
│                                                              │
│  BALANCE RATIO:                                              │
│  • < 0.8: Too scarce (frustrating)                          │
│  • 0.8-1.2: Balanced (meaningful choices)                   │
│  • > 1.2: Too abundant (no tension)                         │
│                                                              │
│  EXAMPLE STAMINA SYSTEM:                                     │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  Max: 100  │  Regen: 20/sec  │  On Hit: +10           │  │
│  ├───────────────────────────────────────────────────────┤  │
│  │  Light Attack: -10  │  Heavy Attack: -25              │  │
│  │  Dodge: -15         │  Block: -5/hit                  │  │
│  │  Sprint: -5/sec     │  Jump: -8                       │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Progression Systems

PROGRESSION CURVE:
┌─────────────────────────────────────────────────────────────┐
│  Power                                                       │
│    ↑                                                         │
│    │                                    ╱───── Late Game     │
│    │                              ╱────╱       (slow, goals) │
│    │                        ╱────╱                           │
│    │                  ╱────╱                                 │
│    │            ╱────╱       Mid Game                        │
│    │      ╱────╱             (steady progress)               │
│    │ ╱───╱                                                   │
│    │╱ Early Game (fast, hook player)                        │
│    └────────────────────────────────────────────────→ Time   │
│                                                              │
│  XP CURVE FORMULA:                                           │
│  XP_needed(level) = base_xp × (level ^ growth_rate)         │
│  • growth_rate 1.5: Gentle curve (casual)                   │
│  • growth_rate 2.0: Standard curve (balanced)               │
│  • growth_rate 2.5: Steep curve (hardcore)                  │
└─────────────────────────────────────────────────────────────┘

// ✅ Production-Ready: Progression Manager
public class ProgressionManager : MonoBehaviour
{
    [Header("Progression Config")]
    [SerializeField] private int baseXP = 100;
    [SerializeField] private float growthRate = 2.0f;
    [SerializeField] private int maxLevel = 50;

    private int _currentLevel = 1;
    private int _currentXP = 0;

    public event Action<int> OnLevelUp;
    public event Action<int, int> OnXPGained; // current, required

    public int XPForLevel(int level)
    {
        return Mathf.RoundToInt(baseXP * Mathf.Pow(level, growthRate));
    }

    public void AddXP(int amount)
    {
        _currentXP += amount;
        int required = XPForLevel(_currentLevel);

        OnXPGained?.Invoke(_currentXP, required);

        while (_currentXP >= required && _currentLevel < maxLevel)
        {
            _currentXP -= required;
            _currentLevel++;
            OnLevelUp?.Invoke(_currentLevel);
            required = XPForLevel(_currentLevel);
        }
    }

    public float GetProgressToNextLevel()
    {
        return (float)_currentXP / XPForLevel(_currentLevel);
    }
}

Movement Mechanics

PLATFORMER FEEL PARAMETERS:
┌─────────────────────────────────────────────────────────────┐
│  MOVEMENT:                                                   │
│  • Walk Speed: 5-8 units/sec                                │
│  • Run Speed: 10-15 units/sec                               │
│  • Acceleration: 20-50 units/sec²                           │
│  • Deceleration: 30-60 units/sec² (snappier = higher)       │
│                                                              │
│  JUMP:                                                       │
│  • Jump Height: 2-4 units                                   │
│  • Jump Duration: 0.3-0.5 sec                               │
│  • Gravity: 20-40 units/sec²                                │
│  • Fall Multiplier: 1.5-2.5x (faster fall = tighter)       │
│                                                              │
│  FEEL ENHANCERS:                                             │
│  • Coyote Time: 0.1-0.15 sec (jump after leaving edge)      │
│  • Jump Buffer: 0.1-0.15 sec (early jump input)             │
│  • Variable Jump: Release = shorter jump                    │
│  • Air Control: 50-80% of ground control                    │
└─────────────────────────────────────────────────────────────┘

Event-Driven Architecture

EVENT SYSTEM PATTERN:
┌─────────────────────────────────────────────────────────────┐
│  ACTION EXECUTED                                             │
│       │                                                      │
│       ▼                                                      │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              EVENT DISPATCHER                        │    │
│  │  DamageDealt(amount, position, type)                │    │
│  └─────────────────────────────────────────────────────┘    │
│       │                                                      │
│       ├──→ VFX System: Spawn damage numbers                 │
│       ├──→ Audio System: Play hit sound                     │
│       ├──→ UI System: Update health bar                     │
│       ├──→ Camera System: Screen shake                      │
│       ├──→ AI System: Alert nearby enemies                  │
│       └──→ Analytics: Log combat event                      │
│                                                              │
│  BENEFITS:                                                   │
│  • Systems don't need direct references                     │
│  • Easy to add/remove observers                             │
│  • Same event triggers multiple effects                     │
│  • Easy networking (replicate events)                       │
└─────────────────────────────────────────────────────────────┘

Balance Iteration

RAPID BALANCE WORKFLOW:
┌─────────────────────────────────────────────────────────────┐
│  1. PLAYTEST (15-30 min)                                     │
│     → Watch players, note friction points                   │
│                                                              │
│  2. ANALYZE (5-15 min)                                       │
│     → What felt wrong? Too easy/hard?                       │
│     → Check telemetry data                                  │
│                                                              │
│  3. ADJUST (5-10 min)                                        │
│     → Change ONE variable at a time                         │
│     → Document the change                                   │
│                                                              │
│  4. TEST (5 min)                                             │
│     → Verify change has intended effect                     │
│                                                              │
│  5. REPEAT                                                   │
│     → Target: 4-6 iterations per hour                       │
└─────────────────────────────────────────────────────────────┘

BALANCE SPREADSHEET FORMAT:
┌──────────┬────────┬─────────┬─────────┬──────────┐
│ Weapon   │ Damage │ Speed   │ Range   │ DPS      │
├──────────┼────────┼─────────┼─────────┼──────────┤
│ Sword    │ 10     │ 1.0/sec │ 2m      │ 10.0     │
│ Axe      │ 20     │ 0.5/sec │ 1.5m    │ 10.0     │
│ Dagger   │ 5      │ 2.0/sec │ 1m      │ 10.0     │
│ Spear    │ 12     │ 0.8/sec │ 3m      │ 9.6      │
└──────────┴────────┴─────────┴─────────┴──────────┘

🔧 Troubleshooting

┌─────────────────────────────────────────────────────────────┐
│ PROBLEM: Controls feel unresponsive                         │
├─────────────────────────────────────────────────────────────┤
│ SOLUTIONS:                                                   │
│ → Add immediate audio/visual feedback on input              │
│ → Reduce input-to-action delay (< 100ms)                    │
│ → Add input buffering for combo actions                     │
│ → Check for frame rate issues                               │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ PROBLEM: One strategy dominates all others                  │
├─────────────────────────────────────────────────────────────┤
│ SOLUTIONS:                                                   │
│ → Nerf dominant option OR buff alternatives                 │
│ → Add situational counters                                  │
│ → Create rock-paper-scissors relationships                  │
│ → Add resource costs to powerful options                    │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ PROBLEM: Players don't understand mechanic                  │
├─────────────────────────────────────────────────────────────┤
│ SOLUTIONS:                                                   │
│ → Add clearer visual/audio feedback                         │
│ → Create safe tutorial space                                │
│ → Use consistent visual language                            │
│ → Add UI hints or tooltips                                  │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ PROBLEM: Progression feels grindy                           │
├─────────────────────────────────────────────────────────────┤
│ SOLUTIONS:                                                   │
│ → Reduce XP requirements                                    │
│ → Add more XP sources                                       │
│ → Give meaningful rewards more frequently                   │
│ → Add catch-up mechanics for late content                   │
└─────────────────────────────────────────────────────────────┘

Mechanic Comparison

Mechanic	Skill Floor	Skill Ceiling	Feedback Speed
Button Mash	Low	Low	Instant
Timing-Based	Medium	High	Instant
Resource Management	Medium	High	Delayed
Combo System	High	Very High	Instant
Strategic	Medium	Very High	Delayed

Use this skill: When implementing core mechanics, balancing systems, or designing player feedback.

FAQ

What does the gameplay-mechanics skill do?

Core gameplay mechanics implementation, system interactions, feedback loops, and iterative balance refinement for engaging player experiences.

How do I install gameplay-mechanics?

Run npx skills add https://github.com/pluginagentmarketplace/custom-plugin-game-developer --skill gameplay-mechanics in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/gameplay-mechanics/ (personal) or .claude/skills/gameplay-mechanics/ (project).

Which AI agents can use gameplay-mechanics?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is gameplay-mechanics safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains gameplay-mechanics?

It is published by pluginagentmarketplace in pluginagentmarketplace/custom-plugin-game-developer. It has 300 recorded installs.