🎮 GameVariable

High-Performance Game State Management for C#

The "Standard Library" for Game Mechanics. 🛠️ Stop writing if (health < 0) health = 0; for the 1,000th time.

Quick Start • Packages • Guide • Examples • Contributing

---

✨ Why GameVariable?

Every game needs Health, Mana, Cooldowns, and XP. Most developers write ad-hoc, buggy classes for each one. GameVariable gives you battle-tested, zero-allocation primitives that handle the math for you.

❌ The Old Way // Manual clamping... everywhere health -= damage; if (health < 0) health = 0; if (health > maxHealth) health = maxHealth; // Manual timer spaghetti cooldown -= deltaTime; if (cooldown < 0) cooldown = 0; bool canUse = cooldown <= 0; // Forgot to handle overflow? xp += 5000; // Now level 1 has 5000/100 XP 😱

✅ The GameVariable Way // Auto-clamped. Always safe. health -= damage; if (health.IsEmpty()) Die(); // Built-in timer semantics cooldown.Tick(deltaTime); if (cooldown.IsFull()) UseAbility(); // Handles massive level-ups automatically experience.Add(5000); // Result: Level 50! 🚀

---

📦 Packages

Choose your weapon! ⚔️

graph LR
    subgraph Core["🔷 Variable.Core"]
        IBoundedInfo["IBoundedInfo"]
    end
    
    Bounded["📊 Variable.Bounded"] --> Core
    Timer["⏱️ Variable.Timer"] --> Core
    Regen["♻️ Variable.Regen"] --> Bounded
    Reservoir["🔋 Variable.Reservoir"] --> Bounded
    Experience["⭐ Variable.Experience"] --> Core
    RPG["📈 Variable.RPG"] --> Core
    Inventory["🎒 Variable.Inventory"] --> Core
    Input["🎮 Variable.Input"] --> Core
    Intent["🧠 GameVariable.Intent"]
    Grid["🕸️ Variable.Grid"]
    
    style Core fill:#4a9eff,stroke:#2980b9,stroke-width:2px,color:#fff
    style Bounded fill:#2ecc71,stroke:#27ae60,color:#fff
    style Timer fill:#e74c3c,stroke:#c0392b,color:#fff
    style Regen fill:#f39c12,stroke:#d68910,color:#fff
    style Reservoir fill:#3498db,stroke:#2980b9,color:#fff
    style Experience fill:#e67e22,stroke:#d35400,color:#fff
    style RPG fill:#1abc9c,stroke:#16a085,color:#fff
    style Inventory fill:#95a5a6,stroke:#7f8c8d,color:#fff
    style Input fill:#9b59b6,stroke:#8e44ad,color:#fff
    style Intent fill:#34495e,stroke:#2c3e50,color:#fff
    style Grid fill:#6c5ce7,stroke:#a29bfe,color:#fff

Loading

🧐 Which package do I need?

If you need to build...	Use this package
Health, Mana, Stamina	Variable.Bounded
Cooldowns, Casting Bars	Variable.Timer
Regenerating Shields	Variable.Regen
Ammo, Batteries, Fuel	Variable.Reservoir
Leveling, Skills, XP	Variable.Experience
Combos, Input Buffers	Variable.Input
Complex Stats (Armor/Resist)	Variable.RPG
Inventory Limits	Variable.Inventory
AI State Machines	GameVariable.Intent
Spatial Data, Maps, Boards	Variable.Grid

---

🚀 Quick Start

Installation

# Install the basics
dotnet add package Variable.Bounded
dotnet add package Variable.Timer

1. The "Ultimate Character" Example

Let's build a character using multiple packages!

using Variable.Bounded;
using Variable.Timer;
using Variable.Regen;
using Variable.Experience;

public struct Hero
{
    // 1. Health (0-100)
    public BoundedFloat Health;
    
    // 2. Mana that regens (+5/sec)
    public RegenFloat Mana;

    // 3. Ability Cooldown (3 sec)
    public Cooldown FireballCd;
    
    // 4. Leveling System
    public ExperienceInt XP;

    public Hero(float maxHp)
    {
        Health = new BoundedFloat(maxHp);
        Mana = new RegenFloat(100f, 100f, 5f); // Starts full
        FireballCd = new Cooldown(3f);         // Starts ready
        XP = new ExperienceInt(1000);          // Need 1000 for lvl 2
    }

    public void Update(float dt)
    {
        // Auto-regen mana
        Mana.Tick(dt);
        
        // Tick cooldown
        FireballCd.Tick(dt);
    }
    
    public void CastFireball()
    {
        if (FireballCd.IsReady() && Mana.Value >= 20f)
        {
            Mana.Value -= 20f;
            FireballCd.Reset();
            Console.WriteLine("KA-BOOM! 🔥");
        }
    }
}

---

💡 Cool Tricks

Temperature System (Negative Ranges) ❄️🔥

BoundedFloat isn't just for 0-100. It handles negative ranges perfectly.

// Range: -50°C to +50°C. Starts at 20°C.
var temp = new BoundedFloat(50f, -50f, 20f);

temp -= 100f; // Clamped to -50f (Absolute Zero-ish)

if (temp.IsEmpty()) ApplyFrostbite();

Progress Bars in UI 📊

All bounded types implement IBoundedInfo. You can write one UI script for everything!

public void UpdateBar(IBoundedInfo info)
{
    // Works for Health, Mana, Timer, XP... anything!
    barImage.fillAmount = (float)info.GetRatio();
}

---

🏗️ Architecture & Philosophy

1. Zero Allocation: Everything is a struct. No new keywords in your update loop. No Garbage Collection spikes.
2. Burst Compatible: Optimized for Unity's DOTS/ECS and Burst Compiler.
3. Fail-Safe: Math is clamped. State is consistent. No NaN or Infinity surprises.

---

🤝 Contributing

We love PRs! Please read CONTRIBUTING.md first.

• Found a bug? Open an issue.
• Have an idea? Start a discussion.

---

Made with ❤️ for game developers

Author: Md Ishtiaq Ahamed Fahim
GitHub: iafahim/GameVariable
Email: iafahim.dev@gmail.com