Flame Systems

Flame Game Systems

14 個常見遊戲系統的實作模式與參考代碼。

Reference Index

AI Usage Guide

需要任務系統？     → Read references/quest.md
需要對話系統？     → Read references/dialogue.md
需要多語言？       → Read references/localization.md
需要背包系統？     → Read references/inventory.md
需要裝備外觀？     → Read references/paperdoll.md
需要戰鬥系統？     → Read references/combat.md
需要技能系統？     → Read references/skills.md
需要存檔功能？     → Read references/saveload.md
需要成就系統？     → Read references/achievement.md
需要商店系統？     → Read references/shop.md
需要製作系統？     → Read references/crafting.md
需要隨機生成？     → Read references/procedural.md
需要多人連線？     → Read references/multiplayer.md
需要關卡編輯？     → Read references/leveleditor.md

System Dependencies

Combat ──→ Skills (技能影響戰鬥)
       ──→ Inventory (裝備影響屬性)
       ──→ Paper Doll (裝備外觀)

Quest ──→ Dialogue (NPC 給予任務)
      ──→ Achievement (完成任務獲得成就)
      ──→ Inventory (任務獎勵物品)

Shop ──→ Inventory (購買物品存入背包)
     ──→ Crafting (購買材料用於製作)

Procedural ──→ Combat (生成敵人)
           ──→ Inventory (隨機掉落)

Related Skills

• flame-core - 引擎核心基礎
• flame-templates - 遊戲類型模板

Achievement System Reference

Data Structure

enum AchievementCategory { combat, exploration, collection, story, social }
enum AchievementRarity { bronze, silver, gold, platinum }

class AchievementData {
  final String id;
  final String title;
  final String description;
  final String iconPath;
  final AchievementCategory category;
  final AchievementRarity rarity;
  final int points;
  final bool isHidden;
  final AchievementCondition condition;
  final AchievementReward? reward;
}

class AchievementCondition {
  final String type;          // 'count', 'flag', 'multi'
  final String targetId;      // What to track
  final int requiredValue;    // Target count
  final List<AchievementCondition>? subConditions; // For 'multi' type
}

class AchievementReward {
  final int gold;
  final int exp;
  final List<String> itemIds;
  final String? titleId;      // Unlocked title/badge
}

class AchievementProgress {
  final AchievementData data;
  int currentValue = 0;
  bool isUnlocked = false;
  DateTime? unlockedAt;

  double get progress => currentValue / data.condition.requiredValue;
  bool get isComplete => currentValue >= data.condition.requiredValue;
}

Achievement Manager

class AchievementManager extends Component {
  final Map<String, AchievementProgress> _achievements = {};
  int totalPoints = 0;

  List<AchievementProgress> get unlocked =>
      _achievements.values.where((a) => a.isUnlocked).toList();

  List<AchievementProgress> get inProgress =>
      _achievements.values.where((a) => !a.isUnlocked && !a.data.isHidden).toList();

  void loadAchievements(List<AchievementData> achievements) {
    for (final achievement in achievements) {
      _achievements[achievement.id] = AchievementProgress(data: achievement);
    }
  }

  void updateProgress(String type, String targetId, int amount) {
    for (final progress in _achievements.values) {
      if (progress.isUnlocked) continue;

      final condition = progress.data.condition;
      if (condition.type == type && condition.targetId == targetId) {
        progress.currentValue += amount;

        if (progress.isComplete) {
          _unlock(progress);
        } else {
          onProgressUpdated?.call(progress);
        }
      }
    }
  }

  void setFlag(String flagId) {
    for (final progress in _achievements.values) {
      if (progress.isUnlocked) continue;

      final condition = progress.data.condition;
      if (condition.type == 'flag' && condition.targetId == flagId) {
        progress.currentValue = 1;
        _unlock(progress);
      }
    }
  }

  void _unlock(AchievementProgress progress) {
    progress.isUnlocked = true;
    progress.unlockedAt = DateTime.now();
    totalPoints += progress.data.points;

    _grantReward(progress.data.reward);
    onAchievementUnlocked?.call(progress);
  }

  void _grantReward(AchievementReward? reward) {
    if (reward == null) return;
    // Grant gold, exp, items via game reference
  }

  // Callbacks
  void Function(AchievementProgress)? onAchievementUnlocked;
  void Function(AchievementProgress)? onProgressUpdated;
}

JSON Data Format

{
  "achievements": [
    {
      "id": "first_kill",
      "title": "First Blood",
      "description": "Defeat your first enemy",
      "iconPath": "achievements/first_kill.png",
      "category": "combat",
      "rarity": "bronze",
      "points": 10,
      "isHidden": false,
      "condition": { "type": "count", "targetId": "enemy_killed", "requiredValue": 1 },
      "reward": { "gold": 100, "exp": 50 }
    },
    {
      "id": "monster_slayer",
      "title": "Monster Slayer",
      "description": "Defeat 100 enemies",
      "iconPath": "achievements/monster_slayer.png",
      "category": "combat",
      "rarity": "silver",
      "points": 50,
      "isHidden": false,
      "condition": { "type": "count", "targetId": "enemy_killed", "requiredValue": 100 },
      "reward": { "gold": 500, "exp": 200, "items": ["trophy_sword"] }
    },
    {
      "id": "secret_area",
      "title": "???",
      "description": "???",
      "iconPath": "achievements/secret.png",
      "category": "exploration",
      "rarity": "gold",
      "points": 100,
      "isHidden": true,
      "condition": { "type": "flag", "targetId": "found_secret_area", "requiredValue": 1 }
    }
  ]
}

Achievement Popup

class AchievementPopup extends PositionComponent {
  final AchievementProgress achievement;
  double displayTime = 0;
  static const displayDuration = 3.0;

  @override
  Future<void> onLoad() async {
    // Slide in from right
    position = Vector2(game.size.x, 20);
    add(MoveEffect.to(
      Vector2(game.size.x - 320, 20),
      EffectController(duration: 0.3, curve: Curves.easeOut),
    ));
  }

  @override
  void update(double dt) {
    super.update(dt);
    displayTime += dt;
    if (displayTime >= displayDuration) {
      // Slide out
      add(MoveEffect.to(
        Vector2(game.size.x, 20),
        EffectController(duration: 0.3, curve: Curves.easeIn),
        onComplete: removeFromParent,
      ));
    }
  }

  @override
  void render(Canvas canvas) {
    // Background
    canvas.drawRRect(
      RRect.fromRectAndRadius(
        Rect.fromLTWH(0, 0, 300, 80),
        Radius.circular(10),
      ),
      Paint()..color = _getRarityColor(achievement.data.rarity),
    );

    // Icon
    // ...

    // Text
    _drawText(canvas, 'Achievement Unlocked!', Vector2(80, 10), size: 12);
    _drawText(canvas, achievement.data.title, Vector2(80, 30), size: 16);
    _drawText(canvas, '+${achievement.data.points} points', Vector2(80, 55), size: 12);
  }

  Color _getRarityColor(AchievementRarity rarity) {
    return switch (rarity) {
      AchievementRarity.bronze => Color(0xFFCD7F32),
      AchievementRarity.silver => Color(0xFFC0C0C0),
      AchievementRarity.gold => Color(0xFFFFD700),
      AchievementRarity.platinum => Color(0xFFE5E4E2),
    };
  }
}

Achievement List UI

class AchievementListUI extends PositionComponent {
  final AchievementManager manager;
  AchievementCategory? selectedCategory;

  @override
  void render(Canvas canvas) {
    // Category tabs
    double x = 0;
    for (final category in AchievementCategory.values) {
      final isSelected = category == selectedCategory;
      _drawTab(canvas, category.name, Vector2(x, 0), isSelected);
      x += 100;
    }

    // Achievement list
    final achievements = _getFilteredAchievements();
    double y = 50;
    for (final achievement in achievements) {
      _drawAchievementRow(canvas, achievement, Vector2(0, y));
      y += 70;
    }

    // Total points
    _drawText(canvas, 'Total: ${manager.totalPoints} points', Vector2(0, size.y - 30));
  }

  void _drawAchievementRow(Canvas canvas, AchievementProgress progress, Vector2 pos) {
    final data = progress.data;

    // Background
    final color = progress.isUnlocked ? Colors.green.withOpacity(0.3) : Colors.grey.withOpacity(0.3);
    canvas.drawRect(Rect.fromLTWH(pos.x, pos.y, size.x, 60), Paint()..color = color);

    // Icon (greyed out if locked)
    // ...

    // Title & description
    final title = data.isHidden && !progress.isUnlocked ? '???' : data.title;
    final desc = data.isHidden && !progress.isUnlocked ? 'Hidden achievement' : data.description;
    _drawText(canvas, title, pos + Vector2(70, 10));
    _drawText(canvas, desc, pos + Vector2(70, 30), size: 12, color: Colors.grey);

    // Progress bar (if not unlocked)
    if (!progress.isUnlocked && !data.isHidden) {
      _drawProgressBar(canvas, progress.progress, pos + Vector2(70, 45), 200);
    }
  }

  List<AchievementProgress> _getFilteredAchievements() {
    if (selectedCategory == null) {
      return manager._achievements.values.toList();
    }
    return manager._achievements.values
        .where((a) => a.data.category == selectedCategory)
        .toList();
  }
}

Integration

// When enemy is killed
void onEnemyKilled(Enemy enemy) {
  achievementManager.updateProgress('count', 'enemy_killed', 1);
  achievementManager.updateProgress('count', 'enemy_${enemy.type}_killed', 1);
}

// When area is discovered
void onAreaDiscovered(String areaId) {
  achievementManager.setFlag('discovered_$areaId');
}

// When item is collected
void onItemCollected(Item item) {
  achievementManager.updateProgress('count', 'item_collected', 1);
  achievementManager.updateProgress('count', 'item_${item.type}_collected', 1);
}

Combat System Reference

Data Structure

class CombatStats {
  int hp;
  int maxHp;
  int mp;
  int maxMp;
  int attack;
  int defense;
  int speed;
  int critRate;     // Percentage
  int critDamage;   // Percentage bonus

  CombatStats({
    required this.maxHp,
    required this.maxMp,
    required this.attack,
    required this.defense,
    this.speed = 100,
    this.critRate = 5,
    this.critDamage = 150,
  }) : hp = maxHp, mp = maxMp;
}

class DamageResult {
  final int damage;
  final bool isCrit;
  final bool isMiss;
  final DamageType type;
}

enum DamageType { physical, magical, pure }
enum CombatState { idle, attacking, defending, stunned, dead }

Damage Calculation

class DamageCalculator {
  static DamageResult calculate({
    required CombatStats attacker,
    required CombatStats defender,
    required int baseDamage,
    DamageType type = DamageType.physical,
  }) {
    // Miss check (based on speed difference)
    final hitChance = 95 + (attacker.speed - defender.speed) ~/ 10;
    if (Random().nextInt(100) >= hitChance) {
      return DamageResult(damage: 0, isCrit: false, isMiss: true, type: type);
    }

    // Base damage
    int damage = baseDamage + attacker.attack;

    // Defense reduction (physical only)
    if (type == DamageType.physical) {
      damage = (damage * (100 / (100 + defender.defense))).round();
    }

    // Critical hit
    final isCrit = Random().nextInt(100) < attacker.critRate;
    if (isCrit) {
      damage = (damage * attacker.critDamage / 100).round();
    }

    // Minimum damage
    damage = damage.clamp(1, 9999);

    return DamageResult(damage: damage, isCrit: isCrit, isMiss: false, type: type);
  }
}

Combat Entity (Enemy/Player)

abstract class CombatEntity extends SpriteAnimationGroupComponent<CombatState>
    with HasGameRef {
  late CombatStats stats;
  CombatState state = CombatState.idle;

  bool get isAlive => stats.hp > 0;
  bool get isDead => !isAlive;

  void takeDamage(DamageResult result) {
    if (result.isMiss) {
      showFloatingText('MISS', Colors.grey);
      return;
    }

    stats.hp -= result.damage;
    stats.hp = stats.hp.clamp(0, stats.maxHp);

    // Visual feedback
    showFloatingText(
      result.isCrit ? '${result.damage}!' : '${result.damage}',
      result.isCrit ? Colors.orange : Colors.white,
    );

    // Flash red
    add(ColorEffect(
      Colors.red,
      EffectController(duration: 0.1),
      opacityTo: 0.5,
    ));

    if (isDead) {
      onDeath();
    }
  }

  void heal(int amount) {
    stats.hp += amount;
    stats.hp = stats.hp.clamp(0, stats.maxHp);
    showFloatingText('+$amount', Colors.green);
  }

  void showFloatingText(String text, Color color) {
    add(FloatingDamageText(text, color));
  }

  void onDeath() {
    state = CombatState.dead;
    current = CombatState.dead;
  }
}

Turn-Based Combat

class TurnBasedCombat extends Component {
  final List<CombatEntity> participants = [];
  int currentTurnIndex = 0;
  bool isPlayerTurn = false;

  CombatEntity get currentTurn => participants[currentTurnIndex];

  void startCombat(List<CombatEntity> entities) {
    participants.clear();
    participants.addAll(entities);

    // Sort by speed
    participants.sort((a, b) => b.stats.speed.compareTo(a.stats.speed));

    currentTurnIndex = 0;
    _startTurn();
  }

  void _startTurn() {
    final entity = currentTurn;

    if (entity.isDead) {
      nextTurn();
      return;
    }

    isPlayerTurn = entity is Player;
    onTurnStarted?.call(entity);

    if (!isPlayerTurn) {
      // AI takes action
      _executeAI(entity as Enemy);
    }
  }

  void playerAction(CombatAction action) {
    if (!isPlayerTurn) return;
    _executeAction(currentTurn, action);
  }

  void _executeAction(CombatEntity actor, CombatAction action) {
    switch (action.type) {
      case ActionType.attack:
        final result = DamageCalculator.calculate(
          attacker: actor.stats,
          defender: action.target!.stats,
          baseDamage: action.baseDamage,
        );
        action.target!.takeDamage(result);
        break;

      case ActionType.skill:
        // Execute skill effect
        action.skill!.execute(actor, action.target);
        break;

      case ActionType.item:
        // Use item
        action.item!.use(action.target ?? actor);
        break;

      case ActionType.defend:
        actor.state = CombatState.defending;
        // Defense buff until next turn
        break;

      case ActionType.flee:
        if (Random().nextInt(100) < 50) {
          endCombat(CombatResult.fled);
        }
        break;
    }

    // Check combat end
    if (_checkCombatEnd()) return;

    nextTurn();
  }

  void nextTurn() {
    do {
      currentTurnIndex = (currentTurnIndex + 1) % participants.length;
    } while (currentTurn.isDead);

    _startTurn();
  }

  bool _checkCombatEnd() {
    final enemies = participants.whereType<Enemy>();
    final players = participants.whereType<Player>();

    if (enemies.every((e) => e.isDead)) {
      endCombat(CombatResult.victory);
      return true;
    }
    if (players.every((p) => p.isDead)) {
      endCombat(CombatResult.defeat);
      return true;
    }
    return false;
  }

  void Function(CombatEntity)? onTurnStarted;
  void Function(CombatResult)? onCombatEnded;
}

Action-Based Combat (Real-time)

class ActionCombat extends Component {
  final Player player;
  final List<Enemy> enemies = [];

  double attackCooldown = 0;
  static const attackCooldownTime = 0.5;

  @override
  void update(double dt) {
    super.update(dt);

    if (attackCooldown > 0) {
      attackCooldown -= dt;
    }

    // Check player attack input
    if (player.isAttacking && attackCooldown <= 0) {
      _performAttack();
      attackCooldown = attackCooldownTime;
    }
  }

  void _performAttack() {
    // Find enemies in attack range
    final attackRange = 50.0;
    for (final enemy in enemies) {
      if (player.position.distanceTo(enemy.position) < attackRange) {
        final result = DamageCalculator.calculate(
          attacker: player.stats,
          defender: enemy.stats,
          baseDamage: player.weapon?.damage ?? 10,
        );
        enemy.takeDamage(result);

        if (enemy.isDead) {
          _onEnemyKilled(enemy);
        }
      }
    }
  }

  void _onEnemyKilled(Enemy enemy) {
    // Drop loot
    enemy.dropLoot();
    // Grant exp
    player.gainExp(enemy.expReward);
    enemies.remove(enemy);
  }
}

Floating Damage Text

class FloatingDamageText extends TextComponent {
  FloatingDamageText(String text, Color color)
      : super(
          text: text,
          textRenderer: TextPaint(
            style: TextStyle(fontSize: 20, color: color, fontWeight: FontWeight.bold),
          ),
          anchor: Anchor.center,
        );

  @override
  Future<void> onLoad() async {
    add(MoveEffect.by(
      Vector2(0, -50),
      EffectController(duration: 1.0, curve: Curves.easeOut),
    ));
    add(OpacityEffect.fadeOut(
      EffectController(duration: 1.0),
      onComplete: removeFromParent,
    ));
  }
}

Combat UI

class CombatUI extends PositionComponent {
  final TurnBasedCombat combat;

  @override
  void render(Canvas canvas) {
    // Draw action menu when player turn
    if (combat.isPlayerTurn) {
      _drawActionMenu(canvas);
    }

    // Draw turn order
    _drawTurnOrder(canvas);
  }

  void _drawActionMenu(Canvas canvas) {
    final actions = ['Attack', 'Skill', 'Item', 'Defend', 'Flee'];
    double y = 0;
    for (final action in actions) {
      _drawButton(canvas, action, Vector2(0, y));
      y += 40;
    }
  }
}

Crafting System Reference

Data Structure

class Recipe {
  final String id;
  final String resultItemId;
  final int resultQuantity;
  final List<RecipeIngredient> ingredients;
  final int? requiredLevel;
  final String? requiredStation;  // Crafting station ID
  final double craftTime;         // Seconds
  final int exp;                  // Crafting exp gained
}

class RecipeIngredient {
  final String itemId;
  final int quantity;
}

class CraftingStation {
  final String id;
  final String name;
  final List<String> availableRecipes;
}

Crafting Manager

class CraftingManager extends Component {
  final Map<String, Recipe> _recipes = {};
  final Map<String, CraftingStation> _stations = {};
  final InventoryManager inventory;

  List<String> _unlockedRecipes = [];
  Recipe? _currentCraft;
  double _craftProgress = 0;

  bool get isCrafting => _currentCraft != null;

  void loadRecipes(List<Recipe> recipes) {
    for (final recipe in recipes) {
      _recipes[recipe.id] = recipe;
    }
  }

  void loadStations(List<CraftingStation> stations) {
    for (final station in stations) {
      _stations[station.id] = station;
    }
  }

  void unlockRecipe(String recipeId) {
    if (!_unlockedRecipes.contains(recipeId)) {
      _unlockedRecipes.add(recipeId);
      onRecipeUnlocked?.call(_recipes[recipeId]!);
    }
  }

  List<Recipe> getAvailableRecipes([String? stationId]) {
    if (stationId != null) {
      final station = _stations[stationId];
      return station?.availableRecipes
          .map((id) => _recipes[id])
          .whereType<Recipe>()
          .where((r) => _unlockedRecipes.contains(r.id))
          .toList() ?? [];
    }
    return _recipes.values
        .where((r) => _unlockedRecipes.contains(r.id))
        .toList();
  }

  CraftResult canCraft(String recipeId) {
    final recipe = _recipes[recipeId];
    if (recipe == null) return CraftResult.recipeNotFound;

    if (!_unlockedRecipes.contains(recipeId)) {
      return CraftResult.recipeLocked;
    }

    // Check ingredients
    for (final ingredient in recipe.ingredients) {
      if (!inventory.hasItem(ingredient.itemId, ingredient.quantity)) {
        return CraftResult.missingIngredients;
      }
    }

    return CraftResult.canCraft;
  }

  void startCraft(String recipeId) {
    if (isCrafting) return;

    final result = canCraft(recipeId);
    if (result != CraftResult.canCraft) {
      onCraftFailed?.call(result);
      return;
    }

    final recipe = _recipes[recipeId]!;

    // Consume ingredients
    for (final ingredient in recipe.ingredients) {
      inventory.removeItem(ingredient.itemId, ingredient.quantity);
    }

    _currentCraft = recipe;
    _craftProgress = 0;
    onCraftStarted?.call(recipe);
  }

  void cancelCraft() {
    if (!isCrafting) return;

    // Return ingredients
    for (final ingredient in _currentCraft!.ingredients) {
      final item = ItemDatabase.get(ingredient.itemId);
      if (item != null) {
        inventory.addItem(item, ingredient.quantity);
      }
    }

    _currentCraft = null;
    _craftProgress = 0;
  }

  @override
  void update(double dt) {
    if (!isCrafting) return;

    _craftProgress += dt;

    if (_craftProgress >= _currentCraft!.craftTime) {
      _completeCraft();
    }
  }

  void _completeCraft() {
    final recipe = _currentCraft!;
    final resultItem = ItemDatabase.get(recipe.resultItemId);

    if (resultItem != null) {
      inventory.addItem(resultItem, recipe.resultQuantity);
    }

    onCraftCompleted?.call(recipe);
    _currentCraft = null;
    _craftProgress = 0;
  }

  double get craftProgress => isCrafting
      ? (_craftProgress / _currentCraft!.craftTime).clamp(0, 1)
      : 0;

  // Callbacks
  void Function(Recipe)? onRecipeUnlocked;
  void Function(Recipe)? onCraftStarted;
  void Function(Recipe)? onCraftCompleted;
  void Function(CraftResult)? onCraftFailed;
}

enum CraftResult { canCraft, recipeNotFound, recipeLocked, missingIngredients, alreadyCrafting }

JSON Data Format

{
  "recipes": [
    {
      "id": "recipe_health_potion",
      "resultItemId": "potion_health",
      "resultQuantity": 1,
      "ingredients": [
        { "itemId": "herb_red", "quantity": 2 },
        { "itemId": "bottle_empty", "quantity": 1 }
      ],
      "craftTime": 3.0,
      "exp": 10
    },
    {
      "id": "recipe_iron_sword",
      "resultItemId": "sword_iron",
      "resultQuantity": 1,
      "ingredients": [
        { "itemId": "iron_ingot", "quantity": 3 },
        { "itemId": "wood_handle", "quantity": 1 }
      ],
      "requiredStation": "station_forge",
      "craftTime": 10.0,
      "exp": 25
    }
  ],
  "stations": [
    {
      "id": "station_alchemy",
      "name": "Alchemy Table",
      "availableRecipes": ["recipe_health_potion", "recipe_mana_potion"]
    },
    {
      "id": "station_forge",
      "name": "Forge",
      "availableRecipes": ["recipe_iron_sword", "recipe_iron_armor"]
    }
  ]
}

Crafting UI

class CraftingUI extends PositionComponent with TapCallbacks {
  final CraftingManager craftingManager;
  final String? stationId;

  String selectedRecipeId = '';

  @override
  void render(Canvas canvas) {
    // Recipe list
    final recipes = craftingManager.getAvailableRecipes(stationId);
    double y = 10;
    for (final recipe in recipes) {
      _drawRecipeRow(canvas, recipe, Vector2(10, y));
      y += 70;
    }

    // Selected recipe details
    if (selectedRecipeId.isNotEmpty) {
      _drawRecipeDetails(canvas, Vector2(size.x - 280, 10));
    }

    // Crafting progress
    if (craftingManager.isCrafting) {
      _drawCraftingProgress(canvas, Vector2(size.x / 2 - 100, size.y - 50));
    }
  }

  void _drawRecipeRow(Canvas canvas, Recipe recipe, Vector2 pos) {
    final canCraft = craftingManager.canCraft(recipe.id) == CraftResult.canCraft;
    final bg = canCraft ? Colors.green.withOpacity(0.2) : Colors.grey.withOpacity(0.2);

    canvas.drawRect(Rect.fromLTWH(pos.x, pos.y, 300, 60), Paint()..color = bg);

    final resultItem = ItemDatabase.get(recipe.resultItemId)!;
    _drawText(canvas, resultItem.name, pos + Vector2(70, 10));
    _drawText(canvas, 'x${recipe.resultQuantity}', pos + Vector2(70, 30), size: 12);

    // Ingredient icons (small)
    double x = 200;
    for (final ing in recipe.ingredients) {
      _drawIngredientIcon(canvas, ing, pos + Vector2(x, 20));
      x += 30;
    }
  }

  void _drawRecipeDetails(Canvas canvas, Vector2 pos) {
    final recipe = craftingManager._recipes[selectedRecipeId]!;
    final resultItem = ItemDatabase.get(recipe.resultItemId)!;

    // Panel background
    canvas.drawRRect(
      RRect.fromRectAndRadius(Rect.fromLTWH(pos.x, pos.y, 260, 350), Radius.circular(8)),
      Paint()..color = Colors.black.withOpacity(0.8),
    );

    // Result item
    _drawText(canvas, resultItem.name, pos + Vector2(10, 10), size: 18);
    _drawText(canvas, resultItem.description, pos + Vector2(10, 35), size: 11);

    // Ingredients
    _drawText(canvas, 'Materials:', pos + Vector2(10, 100), size: 14);
    double y = 120;
    for (final ing in recipe.ingredients) {
      final item = ItemDatabase.get(ing.itemId)!;
      final hasEnough = inventory.hasItem(ing.itemId, ing.quantity);
      final owned = inventory.getItemCount(ing.itemId);
      final color = hasEnough ? Colors.green : Colors.red;

      _drawText(
        canvas,
        '${item.name}: $owned/${ing.quantity}',
        pos + Vector2(10, y),
        size: 12,
        color: color,
      );
      y += 20;
    }

    // Craft time
    _drawText(canvas, 'Time: ${recipe.craftTime}s', pos + Vector2(10, 250), size: 12);

    // Craft button
    final canCraft = craftingManager.canCraft(selectedRecipeId) == CraftResult.canCraft;
    _drawButton(canvas, 'Craft', pos + Vector2(80, 290), enabled: canCraft);
  }

  void _drawCraftingProgress(Canvas canvas, Vector2 pos) {
    // Progress bar
    canvas.drawRect(
      Rect.fromLTWH(pos.x, pos.y, 200, 20),
      Paint()..color = Colors.grey,
    );
    canvas.drawRect(
      Rect.fromLTWH(pos.x, pos.y, 200 * craftingManager.craftProgress, 20),
      Paint()..color = Colors.green,
    );

    // Cancel button
    _drawButton(canvas, 'Cancel', pos + Vector2(210, 0));
  }
}

Recipe Discovery

class RecipeDiscovery {
  final CraftingManager craftingManager;

  // Discover recipe by trying combinations
  Recipe? tryDiscover(List<String> itemIds) {
    for (final recipe in craftingManager._recipes.values) {
      if (_matchesIngredients(recipe, itemIds)) {
        if (!craftingManager._unlockedRecipes.contains(recipe.id)) {
          craftingManager.unlockRecipe(recipe.id);
          return recipe;
        }
      }
    }
    return null;
  }

  bool _matchesIngredients(Recipe recipe, List<String> itemIds) {
    final recipeItems = recipe.ingredients.map((i) => i.itemId).toSet();
    return recipeItems.containsAll(itemIds) && itemIds.toSet().containsAll(recipeItems);
  }
}

Batch Crafting

extension BatchCrafting on CraftingManager {
  int getMaxCraftable(String recipeId) {
    final recipe = _recipes[recipeId];
    if (recipe == null) return 0;

    int maxAmount = 999;
    for (final ingredient in recipe.ingredients) {
      final available = inventory.getItemCount(ingredient.itemId);
      final possible = available ~/ ingredient.quantity;
      maxAmount = min(maxAmount, possible);
    }
    return maxAmount;
  }

  void craftMultiple(String recipeId, int count) {
    final max = getMaxCraftable(recipeId);
    final toCraft = min(count, max);

    for (int i = 0; i < toCraft; i++) {
      startCraft(recipeId);
      // In practice, queue these or process instantly
    }
  }
}

Dialogue System Reference

Data Structure

class DialogueNode {
  final String id;
  final String speakerId;
  final String text;
  final List<DialogueChoice> choices;
  final String? nextNodeId;  // For linear dialogue
  final DialogueAction? action;

  bool get hasChoices => choices.isNotEmpty;
}

class DialogueChoice {
  final String text;
  final String nextNodeId;
  final String? condition;  // Optional requirement
}

class DialogueAction {
  final String type;  // 'give_quest', 'give_item', 'set_flag'
  final Map<String, dynamic> params;
}

class Dialogue {
  final String id;
  final Map<String, DialogueNode> nodes;
  final String startNodeId;
}

Dialogue Manager

class DialogueManager extends Component {
  final Map<String, Dialogue> _dialogues = {};
  Dialogue? _currentDialogue;
  DialogueNode? _currentNode;

  bool get isActive => _currentDialogue != null;

  void loadDialogues(Map<String, Dialogue> dialogues) {
    _dialogues.addAll(dialogues);
  }

  void startDialogue(String dialogueId) {
    _currentDialogue = _dialogues[dialogueId];
    if (_currentDialogue != null) {
      _showNode(_currentDialogue!.startNodeId);
      onDialogueStarted?.call(_currentDialogue!);
    }
  }

  void _showNode(String nodeId) {
    _currentNode = _currentDialogue?.nodes[nodeId];
    if (_currentNode != null) {
      _executeAction(_currentNode!.action);
      onNodeChanged?.call(_currentNode!);
    }
  }

  void selectChoice(int index) {
    if (_currentNode == null || index >= _currentNode!.choices.length) return;

    final choice = _currentNode!.choices[index];
    if (choice.nextNodeId == 'end') {
      endDialogue();
    } else {
      _showNode(choice.nextNodeId);
    }
  }

  void advance() {
    if (_currentNode?.hasChoices == true) return;  // Wait for choice

    if (_currentNode?.nextNodeId == null || _currentNode?.nextNodeId == 'end') {
      endDialogue();
    } else {
      _showNode(_currentNode!.nextNodeId!);
    }
  }

  void endDialogue() {
    final dialogue = _currentDialogue;
    _currentDialogue = null;
    _currentNode = null;
    onDialogueEnded?.call(dialogue!);
  }

  void _executeAction(DialogueAction? action) {
    if (action == null) return;
    onActionTriggered?.call(action);
  }

  // Callbacks
  void Function(Dialogue)? onDialogueStarted;
  void Function(Dialogue)? onDialogueEnded;
  void Function(DialogueNode)? onNodeChanged;
  void Function(DialogueAction)? onActionTriggered;
}

JSON Data Format

{
  "dialogues": {
    "npc_elder_intro": {
      "startNodeId": "node_1",
      "nodes": {
        "node_1": {
          "speakerId": "elder",
          "text": "Welcome, young adventurer! Our village needs your help.",
          "nextNodeId": "node_2"
        },
        "node_2": {
          "speakerId": "elder",
          "text": "Will you help us?",
          "choices": [
            { "text": "Of course!", "nextNodeId": "node_accept" },
            { "text": "What's in it for me?", "nextNodeId": "node_reward" },
            { "text": "Not interested.", "nextNodeId": "end" }
          ]
        },
        "node_accept": {
          "speakerId": "elder",
          "text": "Wonderful! Please clear the rats from the cellar.",
          "action": { "type": "give_quest", "params": { "questId": "main_002" } },
          "nextNodeId": "end"
        },
        "node_reward": {
          "speakerId": "elder",
          "text": "I can offer 200 gold and a fine sword.",
          "nextNodeId": "node_2"
        }
      }
    }
  }
}

Dialogue UI

class DialogueBox extends PositionComponent with TapCallbacks {
  final DialogueManager manager;
  DialogueNode? _node;

  @override
  Future<void> onLoad() async {
    manager.onNodeChanged = (node) {
      _node = node;
    };
  }

  @override
  void render(Canvas canvas) {
    if (_node == null) return;

    // Draw box background
    canvas.drawRRect(
      RRect.fromRectAndRadius(
        Rect.fromLTWH(0, 0, size.x, size.y),
        const Radius.circular(10),
      ),
      Paint()..color = Colors.black.withOpacity(0.8),
    );

    // Draw speaker name
    _drawText(canvas, _node!.speakerId, Vector2(20, 10));

    // Draw text
    _drawText(canvas, _node!.text, Vector2(20, 40));

    // Draw choices
    if (_node!.hasChoices) {
      double y = 100;
      for (int i = 0; i < _node!.choices.length; i++) {
        _drawText(canvas, '${i + 1}. ${_node!.choices[i].text}', Vector2(20, y));
        y += 25;
      }
    } else {
      _drawText(canvas, '[Click to continue]', Vector2(20, size.y - 30));
    }
  }

  @override
  void onTapDown(TapDownEvent event) {
    if (!_node!.hasChoices) {
      manager.advance();
    }
  }
}

Typewriter Effect

class TypewriterText extends PositionComponent {
  final String fullText;
  final double charDelay;
  String _displayedText = '';
  double _timer = 0;
  int _charIndex = 0;

  TypewriterText({
    required this.fullText,
    this.charDelay = 0.03,
  });

  bool get isComplete => _charIndex >= fullText.length;

  void skipToEnd() {
    _displayedText = fullText;
    _charIndex = fullText.length;
  }

  @override
  void update(double dt) {
    if (isComplete) return;

    _timer += dt;
    while (_timer >= charDelay && _charIndex < fullText.length) {
      _displayedText += fullText[_charIndex];
      _charIndex++;
      _timer -= charDelay;
    }
  }
}

NPC Integration

class Npc extends SpriteComponent with TapCallbacks {
  final String dialogueId;
  final DialogueManager dialogueManager;

  @override
  void onTapDown(TapDownEvent event) {
    dialogueManager.startDialogue(dialogueId);
  }
}

Inventory System Reference

Data Structure

enum ItemType { weapon, armor, consumable, material, quest, misc }
enum ItemRarity { common, uncommon, rare, epic, legendary }

class ItemData {
  final String id;
  final String name;
  final String description;
  final ItemType type;
  final ItemRarity rarity;
  final String iconPath;
  final int maxStack;
  final int buyPrice;
  final int sellPrice;
  final Map<String, dynamic> stats;  // For equipment
  final Map<String, dynamic> effects; // For consumables

  bool get isStackable => maxStack > 1;
}

class InventorySlot {
  ItemData? item;
  int quantity = 0;

  bool get isEmpty => item == null;
  bool get isFull => quantity >= (item?.maxStack ?? 0);

  bool canAdd(ItemData newItem, int amount) {
    if (isEmpty) return true;
    if (item!.id != newItem.id) return false;
    return quantity + amount <= item!.maxStack;
  }
}

Inventory Manager

class InventoryManager extends Component {
  final int slotCount;
  late List<InventorySlot> slots;
  int gold = 0;

  InventoryManager({this.slotCount = 20}) {
    slots = List.generate(slotCount, (_) => InventorySlot());
  }

  bool addItem(ItemData item, [int amount = 1]) {
    // Try to stack with existing
    if (item.isStackable) {
      for (final slot in slots) {
        if (slot.item?.id == item.id && !slot.isFull) {
          final canFit = item.maxStack - slot.quantity;
          final toAdd = amount.clamp(0, canFit);
          slot.quantity += toAdd;
          amount -= toAdd;
          if (amount <= 0) {
            onItemAdded?.call(item, toAdd);
            return true;
          }
        }
      }
    }

    // Find empty slot
    for (final slot in slots) {
      if (slot.isEmpty) {
        slot.item = item;
        slot.quantity = amount.clamp(1, item.maxStack);
        onItemAdded?.call(item, slot.quantity);
        return true;
      }
    }

    onInventoryFull?.call(item);
    return false;
  }

  bool removeItem(String itemId, [int amount = 1]) {
    for (final slot in slots) {
      if (slot.item?.id == itemId) {
        if (slot.quantity >= amount) {
          slot.quantity -= amount;
          if (slot.quantity <= 0) {
            slot.item = null;
          }
          onItemRemoved?.call(itemId, amount);
          return true;
        }
      }
    }
    return false;
  }

  int getItemCount(String itemId) {
    return slots
        .where((s) => s.item?.id == itemId)
        .fold(0, (sum, s) => sum + s.quantity);
  }

  bool hasItem(String itemId, [int amount = 1]) {
    return getItemCount(itemId) >= amount;
  }

  void swapSlots(int fromIndex, int toIndex) {
    final temp = slots[fromIndex];
    slots[fromIndex] = slots[toIndex];
    slots[toIndex] = temp;
    onSlotsSwapped?.call(fromIndex, toIndex);
  }

  // Callbacks
  void Function(ItemData, int)? onItemAdded;
  void Function(String, int)? onItemRemoved;
  void Function(ItemData)? onInventoryFull;
  void Function(int, int)? onSlotsSwapped;
}

Item Database

class ItemDatabase {
  static final Map<String, ItemData> _items = {};

  static void loadFromJson(String json) {
    final data = jsonDecode(json) as Map<String, dynamic>;
    for (final entry in data['items']) {
      final item = ItemData.fromJson(entry);
      _items[item.id] = item;
    }
  }

  static ItemData? get(String id) => _items[id];
  static List<ItemData> getByType(ItemType type) =>
      _items.values.where((i) => i.type == type).toList();
}

JSON Data Format

{
  "items": [
    {
      "id": "potion_health",
      "name": "Health Potion",
      "description": "Restores 50 HP",
      "type": "consumable",
      "rarity": "common",
      "iconPath": "items/potion_red.png",
      "maxStack": 99,
      "buyPrice": 50,
      "sellPrice": 25,
      "effects": { "heal": 50 }
    },
    {
      "id": "sword_iron",
      "name": "Iron Sword",
      "description": "A basic iron sword",
      "type": "weapon",
      "rarity": "common",
      "iconPath": "items/sword_iron.png",
      "maxStack": 1,
      "buyPrice": 100,
      "sellPrice": 50,
      "stats": { "attack": 10 }
    }
  ]
}

Inventory UI

class InventoryUI extends PositionComponent with DragCallbacks {
  final InventoryManager inventory;
  final int columns = 5;
  final double slotSize = 64;
  final double padding = 4;

  int? _dragFromIndex;

  @override
  void render(Canvas canvas) {
    for (int i = 0; i < inventory.slots.length; i++) {
      final slot = inventory.slots[i];
      final pos = _getSlotPosition(i);

      // Slot background
      final color = slot.isEmpty ? Colors.grey : _getRarityColor(slot.item!.rarity);
      canvas.drawRect(
        Rect.fromLTWH(pos.x, pos.y, slotSize, slotSize),
        Paint()..color = color.withOpacity(0.5),
      );

      // Item icon & quantity
      if (!slot.isEmpty) {
        // Draw icon (sprite)
        // Draw quantity
        if (slot.quantity > 1) {
          _drawText(canvas, '${slot.quantity}', pos + Vector2(slotSize - 16, slotSize - 16));
        }
      }
    }
  }

  Vector2 _getSlotPosition(int index) {
    final x = (index % columns) * (slotSize + padding);
    final y = (index ~/ columns) * (slotSize + padding);
    return Vector2(x, y);
  }

  int? _getSlotAtPosition(Vector2 pos) {
    final col = (pos.x / (slotSize + padding)).floor();
    final row = (pos.y / (slotSize + padding)).floor();
    final index = row * columns + col;
    return (index >= 0 && index < inventory.slots.length) ? index : null;
  }

  @override
  void onDragStart(DragStartEvent event) {
    _dragFromIndex = _getSlotAtPosition(event.localPosition);
  }

  @override
  void onDragEnd(DragEndEvent event) {
    if (_dragFromIndex != null) {
      final toIndex = _getSlotAtPosition(event.localEndPosition);
      if (toIndex != null && toIndex != _dragFromIndex) {
        inventory.swapSlots(_dragFromIndex!, toIndex);
      }
    }
    _dragFromIndex = null;
  }

  Color _getRarityColor(ItemRarity rarity) {
    return switch (rarity) {
      ItemRarity.common => Colors.grey,
      ItemRarity.uncommon => Colors.green,
      ItemRarity.rare => Colors.blue,
      ItemRarity.epic => Colors.purple,
      ItemRarity.legendary => Colors.orange,
    };
  }
}

Level Editor System Reference

Data Structure

class LevelData {
  final String id;
  final String name;
  final int width;
  final int height;
  final List<List<int>> tileGrid;
  final List<PlacedEntity> entities;
  final Map<String, dynamic> properties;
  DateTime lastModified;

  Map<String, dynamic> toJson() => {
    'id': id,
    'name': name,
    'width': width,
    'height': height,
    'tileGrid': tileGrid,
    'entities': entities.map((e) => e.toJson()).toList(),
    'properties': properties,
    'lastModified': lastModified.toIso8601String(),
  };
}

class PlacedEntity {
  final String id;
  final String typeId;
  final Vector2 position;
  final Map<String, dynamic> properties;

  PlacedEntity({
    required this.id,
    required this.typeId,
    required this.position,
    this.properties = const {},
  });
}

class TileDef {
  final int id;
  final String name;
  final String spritePath;
  final bool isSolid;
  final Map<String, dynamic> properties;
}

class EntityDef {
  final String typeId;
  final String name;
  final String category;
  final String iconPath;
  final Vector2 defaultSize;
  final List<PropertyDef> editableProperties;
}

class PropertyDef {
  final String name;
  final String type;  // 'int', 'double', 'string', 'bool', 'vector2'
  final dynamic defaultValue;
}

Level Editor

class LevelEditor extends Component with HasGameRef, DragCallbacks, TapCallbacks {
  LevelData? currentLevel;

  // Editor state
  EditorTool currentTool = EditorTool.paint;
  int selectedTileId = 0;
  String? selectedEntityType;
  PlacedEntity? selectedEntity;

  // View state
  Vector2 cameraOffset = Vector2.zero();
  double zoom = 1.0;

  // Undo/Redo
  final List<EditorAction> undoStack = [];
  final List<EditorAction> redoStack = [];

  void newLevel(int width, int height) {
    currentLevel = LevelData(
      id: 'level_${DateTime.now().millisecondsSinceEpoch}',
      name: 'New Level',
      width: width,
      height: height,
      tileGrid: List.generate(height, (_) => List.filled(width, 0)),
      entities: [],
      properties: {},
      lastModified: DateTime.now(),
    );
  }

  void loadLevel(LevelData level) {
    currentLevel = level;
    undoStack.clear();
    redoStack.clear();
  }

  Future<void> saveLevel() async {
    if (currentLevel == null) return;

    currentLevel!.lastModified = DateTime.now();
    final json = jsonEncode(currentLevel!.toJson());
    final file = File('levels/${currentLevel!.id}.json');
    await file.writeAsString(json);
  }

  // Tile operations
  void setTile(int x, int y, int tileId) {
    if (currentLevel == null) return;
    if (x < 0 || x >= currentLevel!.width) return;
    if (y < 0 || y >= currentLevel!.height) return;

    final oldTile = currentLevel!.tileGrid[y][x];
    if (oldTile == tileId) return;

    _recordAction(TileChangeAction(x, y, oldTile, tileId));
    currentLevel!.tileGrid[y][x] = tileId;
  }

  // Entity operations
  void placeEntity(String typeId, Vector2 position) {
    if (currentLevel == null) return;

    final entity = PlacedEntity(
      id: 'entity_${DateTime.now().millisecondsSinceEpoch}',
      typeId: typeId,
      position: position,
    );

    _recordAction(EntityAddAction(entity));
    currentLevel!.entities.add(entity);
  }

  void removeEntity(PlacedEntity entity) {
    _recordAction(EntityRemoveAction(entity));
    currentLevel!.entities.remove(entity);
  }

  void moveEntity(PlacedEntity entity, Vector2 newPosition) {
    final oldPosition = entity.position.clone();
    _recordAction(EntityMoveAction(entity, oldPosition, newPosition));
    entity.position.setFrom(newPosition);
  }

  // Undo/Redo
  void _recordAction(EditorAction action) {
    undoStack.add(action);
    redoStack.clear();
  }

  void undo() {
    if (undoStack.isEmpty) return;
    final action = undoStack.removeLast();
    action.undo(this);
    redoStack.add(action);
  }

  void redo() {
    if (redoStack.isEmpty) return;
    final action = redoStack.removeLast();
    action.execute(this);
    undoStack.add(action);
  }
}

enum EditorTool { paint, erase, fill, select, entity, pan }

Editor Actions (Undo/Redo)

abstract class EditorAction {
  void execute(LevelEditor editor);
  void undo(LevelEditor editor);
}

class TileChangeAction extends EditorAction {
  final int x, y;
  final int oldTile, newTile;

  TileChangeAction(this.x, this.y, this.oldTile, this.newTile);

  @override
  void execute(LevelEditor editor) {
    editor.currentLevel!.tileGrid[y][x] = newTile;
  }

  @override
  void undo(LevelEditor editor) {
    editor.currentLevel!.tileGrid[y][x] = oldTile;
  }
}

class EntityAddAction extends EditorAction {
  final PlacedEntity entity;

  EntityAddAction(this.entity);

  @override
  void execute(LevelEditor editor) {
    editor.currentLevel!.entities.add(entity);
  }

  @override
  void undo(LevelEditor editor) {
    editor.currentLevel!.entities.remove(entity);
  }
}

class EntityMoveAction extends EditorAction {
  final PlacedEntity entity;
  final Vector2 oldPosition, newPosition;

  EntityMoveAction(this.entity, this.oldPosition, this.newPosition);

  @override
  void execute(LevelEditor editor) {
    entity.position.setFrom(newPosition);
  }

  @override
  void undo(LevelEditor editor) {
    entity.position.setFrom(oldPosition);
  }
}

Editor UI

class EditorUI extends PositionComponent {
  final LevelEditor editor;

  @override
  void render(Canvas canvas) {
    // Tool palette
    _drawToolPalette(canvas, Vector2(10, 10));

    // Tile palette
    _drawTilePalette(canvas, Vector2(10, 100));

    // Entity palette
    _drawEntityPalette(canvas, Vector2(10, 300));

    // Properties panel (when entity selected)
    if (editor.selectedEntity != null) {
      _drawPropertiesPanel(canvas, Vector2(size.x - 250, 10));
    }

    // Menu bar
    _drawMenuBar(canvas);
  }

  void _drawToolPalette(Canvas canvas, Vector2 pos) {
    final tools = [
      ('Paint', EditorTool.paint),
      ('Erase', EditorTool.erase),
      ('Fill', EditorTool.fill),
      ('Select', EditorTool.select),
      ('Entity', EditorTool.entity),
      ('Pan', EditorTool.pan),
    ];

    double x = pos.x;
    for (final (name, tool) in tools) {
      final selected = editor.currentTool == tool;
      _drawToolButton(canvas, name, Vector2(x, pos.y), selected);
      x += 50;
    }
  }

  void _drawTilePalette(Canvas canvas, Vector2 pos) {
    _drawText(canvas, 'Tiles', pos, size: 14);

    double x = pos.x;
    double y = pos.y + 25;
    for (final tile in tileDefinitions) {
      final selected = editor.selectedTileId == tile.id;
      _drawTileThumbnail(canvas, tile, Vector2(x, y), selected);
      x += 36;
      if (x > 150) {
        x = pos.x;
        y += 36;
      }
    }
  }

  void _drawPropertiesPanel(Canvas canvas, Vector2 pos) {
    final entity = editor.selectedEntity!;
    final def = getEntityDef(entity.typeId);

    canvas.drawRRect(
      RRect.fromRectAndRadius(Rect.fromLTWH(pos.x, pos.y, 240, 300), Radius.circular(8)),
      Paint()..color = Colors.black.withOpacity(0.8),
    );

    _drawText(canvas, def.name, pos + Vector2(10, 10), size: 16);

    double y = 40;
    for (final prop in def.editableProperties) {
      _drawText(canvas, prop.name, pos + Vector2(10, y), size: 12);
      _drawPropertyInput(canvas, entity, prop, pos + Vector2(100, y));
      y += 30;
    }

    _drawButton(canvas, 'Delete', pos + Vector2(10, 250));
  }

  void _drawMenuBar(Canvas canvas) {
    final items = ['File', 'Edit', 'View', 'Test'];
    double x = 0;
    for (final item in items) {
      _drawMenuItem(canvas, item, Vector2(x, 0));
      x += 80;
    }
  }
}

Grid Renderer

class EditorGridRenderer extends Component {
  final LevelEditor editor;
  final double tileSize;

  @override
  void render(Canvas canvas) {
    if (editor.currentLevel == null) return;

    final level = editor.currentLevel!;

    // Draw tiles
    for (int y = 0; y < level.height; y++) {
      for (int x = 0; x < level.width; x++) {
        final tileId = level.tileGrid[y][x];
        _drawTile(canvas, x, y, tileId);
      }
    }

    // Draw grid lines
    _drawGrid(canvas, level.width, level.height);

    // Draw entities
    for (final entity in level.entities) {
      _drawEntity(canvas, entity);
    }

    // Draw selection highlight
    if (editor.selectedEntity != null) {
      _drawSelectionBox(canvas, editor.selectedEntity!);
    }
  }

  void _drawGrid(Canvas canvas, int width, int height) {
    final paint = Paint()
      ..color = Colors.white.withOpacity(0.2)
      ..strokeWidth = 1;

    for (int x = 0; x <= width; x++) {
      canvas.drawLine(
        Offset(x * tileSize, 0),
        Offset(x * tileSize, height * tileSize),
        paint,
      );
    }
    for (int y = 0; y <= height; y++) {
      canvas.drawLine(
        Offset(0, y * tileSize),
        Offset(width * tileSize, y * tileSize),
        paint,
      );
    }
  }
}

Level Loader (Runtime)

class LevelLoader {
  final Map<int, TileDef> tileDefinitions;
  final Map<String, EntityFactory> entityFactories;

  Future<void> loadLevelIntoGame(String levelId, FlameGame game) async {
    final file = File('levels/$levelId.json');
    final json = jsonDecode(await file.readAsString());
    final levelData = LevelData.fromJson(json);

    // Create tile components
    for (int y = 0; y < levelData.height; y++) {
      for (int x = 0; x < levelData.width; x++) {
        final tileId = levelData.tileGrid[y][x];
        final tileDef = tileDefinitions[tileId];
        if (tileDef != null) {
          game.world.add(TileComponent(
            tileDef: tileDef,
            position: Vector2(x * 32.0, y * 32.0),
          ));
        }
      }
    }

    // Create entity components
    for (final entity in levelData.entities) {
      final factory = entityFactories[entity.typeId];
      if (factory != null) {
        game.world.add(factory.create(entity));
      }
    }
  }
}

abstract class EntityFactory {
  Component create(PlacedEntity data);
}

class EnemyFactory extends EntityFactory {
  @override
  Component create(PlacedEntity data) {
    return Enemy(
      position: data.position,
      enemyType: data.properties['enemyType'] ?? 'default',
    );
  }
}

JSON Level Format

{
  "id": "level_001",
  "name": "Tutorial Level",
  "width": 20,
  "height": 15,
  "tileGrid": [
    [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1],
    [1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1],
    [1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1]
  ],
  "entities": [
    {
      "id": "entity_001",
      "typeId": "player_spawn",
      "position": {"x": 64, "y": 64},
      "properties": {}
    },
    {
      "id": "entity_002",
      "typeId": "enemy",
      "position": {"x": 320, "y": 128},
      "properties": {"enemyType": "slime", "patrol": true}
    }
  ],
  "properties": {
    "backgroundMusic": "level1_bgm",
    "timeLimit": 300
  }
}

Localization System Reference

Data Structure

class LocalizationManager {
  String _currentLocale = 'en';
  final Map<String, Map<String, String>> _translations = {};

  String get currentLocale => _currentLocale;
  List<String> get availableLocales => _translations.keys.toList();

  void loadTranslations(String locale, Map<String, String> strings) {
    _translations[locale] = strings;
  }

  void setLocale(String locale) {
    if (_translations.containsKey(locale)) {
      _currentLocale = locale;
      onLocaleChanged?.call(locale);
    }
  }

  String tr(String key, [Map<String, dynamic>? params]) {
    final text = _translations[_currentLocale]?[key] ?? key;

    if (params == null) return text;

    // Replace placeholders: {name}, {count}
    return text.replaceAllMapped(
      RegExp(r'\{(\w+)\}'),
      (match) => params[match.group(1)]?.toString() ?? match.group(0)!,
    );
  }

  void Function(String)? onLocaleChanged;
}

// Global accessor
late LocalizationManager l10n;

JSON Translation Files

// assets/i18n/en.json
{
  "game_title": "Epic Adventure",
  "menu_start": "Start Game",
  "menu_settings": "Settings",
  "menu_quit": "Quit",
  "dialog_hello": "Hello, {name}!",
  "quest_kill": "Kill {count} {enemy}",
  "item_gold": "{amount} Gold",
  "achievement_unlocked": "Achievement Unlocked: {title}"
}

// assets/i18n/zh_TW.json
{
  "game_title": "史詩冒險",
  "menu_start": "開始遊戲",
  "menu_settings": "設定",
  "menu_quit": "離開",
  "dialog_hello": "你好，{name}！",
  "quest_kill": "擊敗 {count} 隻 {enemy}",
  "item_gold": "{amount} 金幣",
  "achievement_unlocked": "成就解鎖：{title}"
}

Loading Translations

class MyGame extends FlameGame {
  @override
  Future<void> onLoad() async {
    l10n = LocalizationManager();

    // Load from JSON
    final enJson = await rootBundle.loadString('assets/i18n/en.json');
    final zhJson = await rootBundle.loadString('assets/i18n/zh_TW.json');

    l10n.loadTranslations('en', Map<String, String>.from(jsonDecode(enJson)));
    l10n.loadTranslations('zh_TW', Map<String, String>.from(jsonDecode(zhJson)));

    // Set default or saved preference
    final savedLocale = prefs.getString('locale') ?? 'en';
    l10n.setLocale(savedLocale);
  }
}

Usage in Game

// Simple text
final title = l10n.tr('game_title');  // "Epic Adventure" or "史詩冒險"

// With parameters
final greeting = l10n.tr('dialog_hello', {'name': 'Hero'});
// "Hello, Hero!" or "你好，Hero！"

final questText = l10n.tr('quest_kill', {'count': 5, 'enemy': 'Rats'});
// "Kill 5 Rats" or "擊敗 5 隻 Rats"

// In components
class MenuButton extends TextComponent {
  final String textKey;

  @override
  Future<void> onLoad() async {
    text = l10n.tr(textKey);

    l10n.onLocaleChanged = (_) {
      text = l10n.tr(textKey);
    };
  }
}

Pluralization

extension LocalizationExtension on LocalizationManager {
  String plural(String key, int count, {Map<String, dynamic>? params}) {
    final pluralKey = count == 1 ? '${key}_one' : '${key}_other';
    final finalParams = {...?params, 'count': count};
    return tr(pluralKey, finalParams);
  }
}

// JSON
{
  "enemy_killed_one": "Killed 1 enemy",
  "enemy_killed_other": "Killed {count} enemies"
}

// Usage
l10n.plural('enemy_killed', 1);  // "Killed 1 enemy"
l10n.plural('enemy_killed', 5);  // "Killed 5 enemies"

Language Selector UI

class LanguageSelector extends PositionComponent with TapCallbacks {
  final List<Map<String, String>> languages = [
    {'code': 'en', 'name': 'English'},
    {'code': 'zh_TW', 'name': '繁體中文'},
    {'code': 'ja', 'name': '日本語'},
  ];

  @override
  void render(Canvas canvas) {
    double y = 0;
    for (final lang in languages) {
      final isSelected = lang['code'] == l10n.currentLocale;
      _drawText(
        canvas,
        '${isSelected ? "► " : "  "}${lang['name']}',
        Vector2(0, y),
      );
      y += 30;
    }
  }

  @override
  void onTapDown(TapDownEvent event) {
    final index = (event.localPosition.y / 30).floor();
    if (index < languages.length) {
      l10n.setLocale(languages[index]['code']!);
    }
  }
}

Font Support

// For CJK characters, use appropriate fonts
final chineseRenderer = TextPaint(
  style: const TextStyle(
    fontFamily: 'NotoSansTC',  // Supports Chinese
    fontSize: 16,
  ),
);

// Load in pubspec.yaml
// fonts:
//   - family: NotoSansTC
//     fonts:
//       - asset: assets/fonts/NotoSansTC-Regular.otf

Multiplayer System Reference

Architecture Overview

// Client-Server model
// Server: Authoritative game state
// Client: Input sending + state interpolation

enum NetworkRole { server, client }
enum ConnectionState { disconnected, connecting, connected, error }

Network Message

abstract class NetworkMessage {
  final String type;
  final int timestamp;

  NetworkMessage(this.type) : timestamp = DateTime.now().millisecondsSinceEpoch;

  Map<String, dynamic> toJson();
  factory NetworkMessage.fromJson(Map<String, dynamic> json);
}

class PlayerInputMessage extends NetworkMessage {
  final String playerId;
  final Vector2 moveDirection;
  final bool isShooting;

  PlayerInputMessage({
    required this.playerId,
    required this.moveDirection,
    this.isShooting = false,
  }) : super('player_input');

  @override
  Map<String, dynamic> toJson() => {
    'type': type,
    'timestamp': timestamp,
    'playerId': playerId,
    'moveDirection': {'x': moveDirection.x, 'y': moveDirection.y},
    'isShooting': isShooting,
  };
}

class GameStateMessage extends NetworkMessage {
  final List<PlayerState> players;
  final List<EntityState> entities;

  GameStateMessage({
    required this.players,
    required this.entities,
  }) : super('game_state');
}

class PlayerState {
  final String id;
  final Vector2 position;
  final int health;
  final String animation;
}

WebSocket Client

class NetworkClient {
  WebSocketChannel? _channel;
  ConnectionState state = ConnectionState.disconnected;
  String? playerId;

  final _messageController = StreamController<NetworkMessage>.broadcast();
  Stream<NetworkMessage> get messages => _messageController.stream;

  Future<void> connect(String serverUrl) async {
    state = ConnectionState.connecting;

    try {
      _channel = WebSocketChannel.connect(Uri.parse(serverUrl));

      _channel!.stream.listen(
        (data) {
          final json = jsonDecode(data);
          final message = NetworkMessage.fromJson(json);
          _messageController.add(message);
        },
        onDone: () {
          state = ConnectionState.disconnected;
          onDisconnected?.call();
        },
        onError: (error) {
          state = ConnectionState.error;
          onError?.call(error.toString());
        },
      );

      state = ConnectionState.connected;
      onConnected?.call();
    } catch (e) {
      state = ConnectionState.error;
      onError?.call(e.toString());
    }
  }

  void send(NetworkMessage message) {
    if (state != ConnectionState.connected) return;
    _channel?.sink.add(jsonEncode(message.toJson()));
  }

  void disconnect() {
    _channel?.sink.close();
    state = ConnectionState.disconnected;
  }

  void Function()? onConnected;
  void Function()? onDisconnected;
  void Function(String)? onError;
}

State Synchronization

class NetworkSync extends Component with HasGameRef {
  final NetworkClient client;
  final Map<String, NetworkPlayer> remotePlayers = {};

  // Interpolation buffer
  final Map<String, List<PlayerState>> stateBuffer = {};
  static const interpolationDelay = 100; // ms

  @override
  void onMount() {
    client.messages.listen(_handleMessage);
    super.onMount();
  }

  void _handleMessage(NetworkMessage message) {
    switch (message.type) {
      case 'game_state':
        _handleGameState(message as GameStateMessage);
        break;
      case 'player_joined':
        _handlePlayerJoined(message);
        break;
      case 'player_left':
        _handlePlayerLeft(message);
        break;
    }
  }

  void _handleGameState(GameStateMessage state) {
    for (final playerState in state.players) {
      if (playerState.id == client.playerId) {
        // Local player - reconcile
        _reconcileLocalPlayer(playerState);
      } else {
        // Remote player - buffer for interpolation
        stateBuffer.putIfAbsent(playerState.id, () => []);
        stateBuffer[playerState.id]!.add(playerState);

        // Keep buffer size limited
        if (stateBuffer[playerState.id]!.length > 10) {
          stateBuffer[playerState.id]!.removeAt(0);
        }
      }
    }
  }

  @override
  void update(double dt) {
    // Interpolate remote players
    final renderTime = DateTime.now().millisecondsSinceEpoch - interpolationDelay;

    for (final entry in stateBuffer.entries) {
      final playerId = entry.key;
      final buffer = entry.value;

      if (buffer.length < 2) continue;

      // Find states to interpolate between
      PlayerState? from, to;
      for (int i = 0; i < buffer.length - 1; i++) {
        if (buffer[i].timestamp <= renderTime && buffer[i + 1].timestamp >= renderTime) {
          from = buffer[i];
          to = buffer[i + 1];
          break;
        }
      }

      if (from != null && to != null) {
        final t = (renderTime - from.timestamp) / (to.timestamp - from.timestamp);
        final interpolatedPos = Vector2(
          from.position.x + (to.position.x - from.position.x) * t,
          from.position.y + (to.position.y - from.position.y) * t,
        );

        remotePlayers[playerId]?.position = interpolatedPos;
      }
    }
  }
}

Input Prediction (Client-side)

class InputPredictor {
  final List<PendingInput> pendingInputs = [];
  int inputSequence = 0;

  void sendInput(Vector2 moveDirection, NetworkClient client) {
    final input = PendingInput(
      sequence: inputSequence++,
      moveDirection: moveDirection,
      timestamp: DateTime.now().millisecondsSinceEpoch,
    );

    pendingInputs.add(input);

    // Send to server
    client.send(PlayerInputMessage(
      playerId: client.playerId!,
      moveDirection: moveDirection,
    ));

    // Apply locally (prediction)
    localPlayer.applyInput(moveDirection);
  }

  void reconcile(PlayerState serverState, int lastProcessedInput) {
    // Remove acknowledged inputs
    pendingInputs.removeWhere((i) => i.sequence <= lastProcessedInput);

    // Reset to server state
    localPlayer.position = serverState.position;

    // Reapply pending inputs
    for (final input in pendingInputs) {
      localPlayer.applyInput(input.moveDirection);
    }
  }
}

class PendingInput {
  final int sequence;
  final Vector2 moveDirection;
  final int timestamp;

  PendingInput({
    required this.sequence,
    required this.moveDirection,
    required this.timestamp,
  });
}

Lobby System

class LobbyManager {
  final NetworkClient client;
  final List<LobbyRoom> rooms = [];
  LobbyRoom? currentRoom;

  Future<void> refreshRooms() async {
    client.send(RequestRoomsMessage());
  }

  Future<void> createRoom(String name, int maxPlayers) async {
    client.send(CreateRoomMessage(name: name, maxPlayers: maxPlayers));
  }

  Future<void> joinRoom(String roomId) async {
    client.send(JoinRoomMessage(roomId: roomId));
  }

  Future<void> leaveRoom() async {
    client.send(LeaveRoomMessage());
    currentRoom = null;
  }

  void setReady(bool ready) {
    client.send(SetReadyMessage(ready: ready));
  }
}

class LobbyRoom {
  final String id;
  final String name;
  final String hostId;
  final int maxPlayers;
  final List<LobbyPlayer> players;
  final bool isStarted;

  bool get isFull => players.length >= maxPlayers;
  bool get canStart => players.every((p) => p.isReady) && players.length >= 2;
}

class LobbyPlayer {
  final String id;
  final String name;
  final bool isReady;
  final bool isHost;
}

Lobby UI

class LobbyUI extends PositionComponent {
  final LobbyManager lobbyManager;

  @override
  void render(Canvas canvas) {
    if (lobbyManager.currentRoom == null) {
      _drawRoomList(canvas);
    } else {
      _drawRoomLobby(canvas);
    }
  }

  void _drawRoomList(Canvas canvas) {
    _drawText(canvas, 'Available Rooms', Vector2(10, 10), size: 24);

    double y = 50;
    for (final room in lobbyManager.rooms) {
      final status = room.isFull ? '(Full)' : '${room.players.length}/${room.maxPlayers}';
      _drawText(canvas, '${room.name} $status', Vector2(10, y));
      _drawButton(canvas, 'Join', Vector2(300, y - 5), enabled: !room.isFull);
      y += 40;
    }

    _drawButton(canvas, 'Create Room', Vector2(10, size.y - 50));
    _drawButton(canvas, 'Refresh', Vector2(150, size.y - 50));
  }

  void _drawRoomLobby(Canvas canvas) {
    final room = lobbyManager.currentRoom!;
    _drawText(canvas, room.name, Vector2(10, 10), size: 24);

    double y = 50;
    for (final player in room.players) {
      final status = player.isReady ? '[Ready]' : '[Not Ready]';
      final host = player.isHost ? '(Host)' : '';
      _drawText(canvas, '${player.name} $host $status', Vector2(10, y));
      y += 30;
    }

    _drawButton(canvas, 'Ready', Vector2(10, size.y - 50));
    _drawButton(canvas, 'Leave', Vector2(150, size.y - 50));

    if (room.canStart && _isHost()) {
      _drawButton(canvas, 'Start Game', Vector2(size.x - 150, size.y - 50));
    }
  }
}

Simple Firebase Realtime Database

class FirebaseMultiplayer {
  final DatabaseReference _db = FirebaseDatabase.instance.ref();
  String? roomId;
  String? playerId;

  Future<void> createRoom() async {
    final roomRef = _db.child('rooms').push();
    roomId = roomRef.key;

    await roomRef.set({
      'hostId': playerId,
      'state': 'waiting',
      'players': {playerId: {'x': 0, 'y': 0, 'ready': false}},
    });
  }

  void listenToRoom() {
    _db.child('rooms/$roomId').onValue.listen((event) {
      final data = event.snapshot.value as Map?;
      if (data != null) {
        _updateFromServerState(data);
      }
    });
  }

  void updatePosition(Vector2 position) {
    _db.child('rooms/$roomId/players/$playerId').update({
      'x': position.x,
      'y': position.y,
    });
  }
}

Paper Doll System Reference

Data Structure

enum EquipSlot { head, body, legs, feet, mainHand, offHand, accessory }

class EquipmentData {
  final String id;
  final EquipSlot slot;
  final String spritePath;      // Visual sprite
  final Vector2 spriteOffset;   // Position offset on character
  final Map<String, int> stats;
}

class PaperDollState {
  final Map<EquipSlot, EquipmentData?> equipped = {};

  EquipmentData? getEquipped(EquipSlot slot) => equipped[slot];

  void equip(EquipmentData equipment) {
    equipped[equipment.slot] = equipment;
  }

  void unequip(EquipSlot slot) {
    equipped[slot] = null;
  }
}

Paper Doll Component

class PaperDollComponent extends PositionComponent with HasGameRef {
  final PaperDollState state;

  // Base character sprite
  late SpriteComponent baseBody;

  // Equipment layers (rendered in order)
  final Map<EquipSlot, SpriteComponent> equipmentSprites = {};

  // Layer order (bottom to top)
  static const renderOrder = [
    EquipSlot.body,
    EquipSlot.legs,
    EquipSlot.feet,
    EquipSlot.mainHand,
    EquipSlot.offHand,
    EquipSlot.head,
    EquipSlot.accessory,
  ];

  @override
  Future<void> onLoad() async {
    // Base body sprite
    baseBody = SpriteComponent(
      sprite: await game.loadSprite('character/base.png'),
      size: Vector2(64, 64),
    );
    add(baseBody);

    // Initial equipment
    await _refreshEquipment();
  }

  Future<void> _refreshEquipment() async {
    // Remove old sprites
    for (final sprite in equipmentSprites.values) {
      sprite.removeFromParent();
    }
    equipmentSprites.clear();

    // Add equipped items in order
    int priority = 1;
    for (final slot in renderOrder) {
      final equipment = state.getEquipped(slot);
      if (equipment != null) {
        final sprite = SpriteComponent(
          sprite: await game.loadSprite(equipment.spritePath),
          position: equipment.spriteOffset,
          size: Vector2(64, 64),
          priority: priority++,
        );
        equipmentSprites[slot] = sprite;
        add(sprite);
      }
    }
  }

  Future<void> onEquipmentChanged() async {
    await _refreshEquipment();
  }
}

Animated Paper Doll

class AnimatedPaperDoll extends PositionComponent with HasGameRef {
  final PaperDollState state;
  String currentAnimation = 'idle';

  // Animation data per equipment
  late Map<EquipSlot, SpriteAnimationComponent> animatedParts;

  @override
  Future<void> onLoad() async {
    await _loadAnimations();
  }

  Future<void> _loadAnimations() async {
    // Base body animation
    final baseAnim = await _loadPartAnimation('base', currentAnimation);
    add(baseAnim..priority = 0);

    // Equipment animations
    int priority = 1;
    for (final slot in PaperDollComponent.renderOrder) {
      final equipment = state.getEquipped(slot);
      if (equipment != null) {
        final anim = await _loadPartAnimation(
          equipment.id,
          currentAnimation,
        );
        anim.priority = priority++;
        animatedParts[slot] = anim;
        add(anim);
      }
    }
  }

  Future<SpriteAnimationComponent> _loadPartAnimation(
    String partId,
    String animName,
  ) async {
    // Load sprite sheet: character/{partId}_{animName}.png
    return SpriteAnimationComponent(
      animation: await game.loadSpriteAnimation(
        'character/${partId}_$animName.png',
        SpriteAnimationData.sequenced(
          amount: 4,
          stepTime: 0.15,
          textureSize: Vector2(64, 64),
        ),
      ),
      size: Vector2(64, 64),
    );
  }

  void playAnimation(String name) {
    if (currentAnimation == name) return;
    currentAnimation = name;
    // Reload all animations
    removeAll(children);
    _loadAnimations();
  }
}

Equipment Stats Integration

class CharacterStats {
  final PaperDollState paperDoll;

  int get totalAttack => _baseAttack + _equipmentBonus('attack');
  int get totalDefense => _baseDefense + _equipmentBonus('defense');
  int get totalSpeed => _baseSpeed + _equipmentBonus('speed');

  int _equipmentBonus(String stat) {
    int bonus = 0;
    for (final equipment in paperDoll.equipped.values) {
      if (equipment != null) {
        bonus += equipment.stats[stat] ?? 0;
      }
    }
    return bonus;
  }
}

Equipment Preview UI

class EquipmentPreview extends PositionComponent {
  final PaperDollState currentState;
  final EquipmentData? previewItem;

  @override
  void render(Canvas canvas) {
    // Show current vs preview stats
    final currentStats = _calculateStats(currentState);
    final previewStats = _calculateStatsWithItem(currentState, previewItem);

    double y = 0;
    for (final stat in ['attack', 'defense', 'speed']) {
      final current = currentStats[stat] ?? 0;
      final preview = previewStats[stat] ?? 0;
      final diff = preview - current;

      final color = diff > 0 ? Colors.green : (diff < 0 ? Colors.red : Colors.white);
      final diffText = diff > 0 ? '+$diff' : (diff < 0 ? '$diff' : '');

      _drawText(canvas, '$stat: $current → $preview $diffText', Vector2(0, y), color);
      y += 20;
    }
  }
}

JSON Data Format

{
  "equipment": [
    {
      "id": "helmet_iron",
      "name": "Iron Helmet",
      "slot": "head",
      "spritePath": "equipment/helmet_iron.png",
      "spriteOffset": [0, -8],
      "stats": { "defense": 5 }
    },
    {
      "id": "armor_leather",
      "name": "Leather Armor",
      "slot": "body",
      "spritePath": "equipment/armor_leather.png",
      "spriteOffset": [0, 0],
      "stats": { "defense": 10, "speed": -1 }
    },
    {
      "id": "sword_steel",
      "name": "Steel Sword",
      "slot": "mainHand",
      "spritePath": "equipment/sword_steel.png",
      "spriteOffset": [16, 0],
      "stats": { "attack": 15 }
    }
  ]
}

Equipment Slot UI

class EquipmentSlotUI extends PositionComponent with TapCallbacks {
  final EquipSlot slot;
  final PaperDollState state;
  final InventoryManager inventory;

  @override
  void render(Canvas canvas) {
    // Draw slot background with icon
    final equipped = state.getEquipped(slot);

    canvas.drawRect(
      Rect.fromLTWH(0, 0, 64, 64),
      Paint()..color = Colors.grey.withOpacity(0.5),
    );

    if (equipped != null) {
      // Draw equipment icon
    } else {
      // Draw slot placeholder icon
      _drawSlotIcon(canvas, slot);
    }
  }

  @override
  void onTapDown(TapDownEvent event) {
    final equipped = state.getEquipped(slot);
    if (equipped != null) {
      // Unequip and add to inventory
      state.unequip(slot);
      inventory.addItem(ItemDatabase.get(equipped.id)!);
    } else {
      // Open inventory to select equipment
      openEquipmentSelector?.call(slot);
    }
  }

  void Function(EquipSlot)? openEquipmentSelector;
}

Procedural Generation Reference

Random with Seed

class SeededRandom {
  late Random _random;
  final int seed;

  SeededRandom([int? seed]) : seed = seed ?? DateTime.now().millisecondsSinceEpoch {
    _random = Random(this.seed);
  }

  int nextInt(int max) => _random.nextInt(max);
  double nextDouble() => _random.nextDouble();
  bool nextBool() => _random.nextBool();

  T pick<T>(List<T> list) => list[nextInt(list.length)];

  T pickWeighted<T>(Map<T, int> weights) {
    final total = weights.values.fold(0, (a, b) => a + b);
    var roll = nextInt(total);
    for (final entry in weights.entries) {
      roll -= entry.value;
      if (roll < 0) return entry.key;
    }
    return weights.keys.first;
  }
}

Dungeon Generation (BSP)

class DungeonGenerator {
  final int width;
  final int height;
  final int minRoomSize;
  final SeededRandom random;

  late List<List<int>> grid;  // 0 = wall, 1 = floor
  final List<Rect> rooms = [];

  DungeonGenerator({
    required this.width,
    required this.height,
    this.minRoomSize = 6,
    int? seed,
  }) : random = SeededRandom(seed);

  List<List<int>> generate() {
    grid = List.generate(height, (_) => List.filled(width, 0));
    rooms.clear();

    _splitSpace(Rect.fromLTWH(0, 0, width.toDouble(), height.toDouble()));
    _connectRooms();

    return grid;
  }

  void _splitSpace(Rect space) {
    if (space.width < minRoomSize * 2 || space.height < minRoomSize * 2) {
      _createRoom(space);
      return;
    }

    final splitHorizontal = random.nextBool();

    if (splitHorizontal && space.height > minRoomSize * 2) {
      final splitY = space.top + minRoomSize + random.nextInt((space.height - minRoomSize * 2).toInt());
      _splitSpace(Rect.fromLTRB(space.left, space.top, space.right, splitY));
      _splitSpace(Rect.fromLTRB(space.left, splitY, space.right, space.bottom));
    } else if (space.width > minRoomSize * 2) {
      final splitX = space.left + minRoomSize + random.nextInt((space.width - minRoomSize * 2).toInt());
      _splitSpace(Rect.fromLTRB(space.left, space.top, splitX, space.bottom));
      _splitSpace(Rect.fromLTRB(splitX, space.top, space.right, space.bottom));
    } else {
      _createRoom(space);
    }
  }

  void _createRoom(Rect space) {
    final roomW = minRoomSize + random.nextInt((space.width - minRoomSize).toInt().clamp(1, 10));
    final roomH = minRoomSize + random.nextInt((space.height - minRoomSize).toInt().clamp(1, 10));
    final roomX = space.left + random.nextInt((space.width - roomW).toInt().clamp(1, 10));
    final roomY = space.top + random.nextInt((space.height - roomH).toInt().clamp(1, 10));

    final room = Rect.fromLTWH(roomX, roomY, roomW.toDouble(), roomH.toDouble());
    rooms.add(room);

    for (int y = roomY.toInt(); y < roomY + roomH && y < height; y++) {
      for (int x = roomX.toInt(); x < roomX + roomW && x < width; x++) {
        grid[y][x] = 1;
      }
    }
  }

  void _connectRooms() {
    for (int i = 0; i < rooms.length - 1; i++) {
      _createCorridor(rooms[i].center, rooms[i + 1].center);
    }
  }

  void _createCorridor(Offset from, Offset to) {
    int x = from.dx.toInt();
    int y = from.dy.toInt();

    // Horizontal first, then vertical
    while (x != to.dx.toInt()) {
      if (y >= 0 && y < height && x >= 0 && x < width) {
        grid[y][x] = 1;
      }
      x += x < to.dx ? 1 : -1;
    }
    while (y != to.dy.toInt()) {
      if (y >= 0 && y < height && x >= 0 && x < width) {
        grid[y][x] = 1;
      }
      y += y < to.dy ? 1 : -1;
    }
  }
}

Room Templates

class RoomTemplate {
  final String id;
  final int width;
  final int height;
  final List<List<int>> layout;
  final List<SpawnPoint> spawns;
}

class SpawnPoint {
  final Vector2 position;
  final String type;  // 'enemy', 'item', 'chest', 'entrance', 'exit'
}

class TemplateRoomGenerator {
  final List<RoomTemplate> templates;
  final SeededRandom random;

  List<List<int>> generateWithTemplates(int gridWidth, int gridHeight) {
    final grid = List.generate(gridHeight, (_) => List.filled(gridWidth, 0));
    final placedRooms = <Rect>[];

    // Place rooms using templates
    for (int attempts = 0; attempts < 20; attempts++) {
      final template = random.pick(templates);
      final x = random.nextInt(gridWidth - template.width);
      final y = random.nextInt(gridHeight - template.height);

      if (_canPlace(placedRooms, x, y, template)) {
        _placeTemplate(grid, x, y, template);
        placedRooms.add(Rect.fromLTWH(
          x.toDouble(), y.toDouble(),
          template.width.toDouble(), template.height.toDouble(),
        ));
      }
    }

    return grid;
  }
}

Enemy Spawning

class SpawnTable {
  final List<SpawnEntry> entries;

  SpawnTable(this.entries);

  String roll(SeededRandom random, int floorLevel) {
    final validEntries = entries.where((e) =>
        floorLevel >= e.minFloor && floorLevel <= e.maxFloor
    ).toList();

    final weights = <String, int>{};
    for (final entry in validEntries) {
      weights[entry.enemyId] = entry.weight;
    }

    return random.pickWeighted(weights);
  }
}

class SpawnEntry {
  final String enemyId;
  final int weight;
  final int minFloor;
  final int maxFloor;
}

// Usage
class DungeonFloor extends Component {
  void spawnEnemies(int count) {
    for (int i = 0; i < count; i++) {
      final enemyId = spawnTable.roll(random, currentFloor);
      final position = _findValidSpawnPosition();
      _spawnEnemy(enemyId, position);
    }
  }
}

Loot Generation

class LootTable {
  final List<LootEntry> entries;
  final SeededRandom random;

  List<LootDrop> generateLoot(int lootLevel) {
    final drops = <LootDrop>[];

    for (final entry in entries) {
      if (random.nextDouble() * 100 < entry.dropChance) {
        final quantity = entry.minQuantity +
            random.nextInt(entry.maxQuantity - entry.minQuantity + 1);
        drops.add(LootDrop(entry.itemId, quantity));
      }
    }

    return drops;
  }
}

class LootEntry {
  final String itemId;
  final double dropChance;  // Percentage
  final int minQuantity;
  final int maxQuantity;
}

class LootDrop {
  final String itemId;
  final int quantity;

  LootDrop(this.itemId, this.quantity);
}

Roguelike Floor Manager

class FloorManager extends Component with HasGameRef {
  int currentFloor = 1;
  late DungeonGenerator generator;
  late SpawnTable enemySpawnTable;
  late LootTable lootTable;

  final Map<int, int> floorSeeds = {};  // Floor -> seed mapping

  void generateFloor(int floor) {
    currentFloor = floor;

    // Use consistent seed for this floor
    final seed = floorSeeds[floor] ?? DateTime.now().millisecondsSinceEpoch;
    floorSeeds[floor] = seed;

    generator = DungeonGenerator(
      width: 50 + floor * 5,
      height: 50 + floor * 5,
      seed: seed,
    );

    final dungeon = generator.generate();
    _buildFloorFromGrid(dungeon);

    // Spawn enemies (more on deeper floors)
    final enemyCount = 3 + floor * 2;
    spawnEnemies(enemyCount);

    // Place items
    _placeItems();
  }

  void descendToNextFloor() {
    // Clear current floor
    world.children.whereType<Enemy>().forEach((e) => e.removeFromParent());
    world.children.whereType<Item>().forEach((i) => i.removeFromParent());

    generateFloor(currentFloor + 1);
    player.position = _findStartPosition();
  }
}

Noise-based Terrain

class NoiseGenerator {
  // Simple Perlin-like noise
  double noise2D(double x, double y, int seed) {
    final random = Random(seed + (x * 1000 + y).toInt());
    return random.nextDouble();
  }

  double smoothNoise2D(double x, double y, int seed) {
    final corners = (noise2D(x - 1, y - 1, seed) +
            noise2D(x + 1, y - 1, seed) +
            noise2D(x - 1, y + 1, seed) +
            noise2D(x + 1, y + 1, seed)) / 16;
    final sides = (noise2D(x - 1, y, seed) +
            noise2D(x + 1, y, seed) +
            noise2D(x, y - 1, seed) +
            noise2D(x, y + 1, seed)) / 8;
    final center = noise2D(x, y, seed) / 4;
    return corners + sides + center;
  }

  List<List<int>> generateTerrain(int width, int height, int seed) {
    final terrain = List.generate(height, (_) => List.filled(width, 0));

    for (int y = 0; y < height; y++) {
      for (int x = 0; x < width; x++) {
        final value = smoothNoise2D(x / 10, y / 10, seed);
        terrain[y][x] = (value * 4).toInt(); // 0-3 terrain types
      }
    }

    return terrain;
  }
}

JSON Data Format

{
  "spawnTables": {
    "dungeon_common": [
      { "enemyId": "slime", "weight": 50, "minFloor": 1, "maxFloor": 99 },
      { "enemyId": "skeleton", "weight": 30, "minFloor": 1, "maxFloor": 99 },
      { "enemyId": "orc", "weight": 15, "minFloor": 3, "maxFloor": 99 },
      { "enemyId": "dragon", "weight": 5, "minFloor": 10, "maxFloor": 99 }
    ]
  },
  "lootTables": {
    "common_chest": [
      { "itemId": "gold", "dropChance": 100, "minQuantity": 10, "maxQuantity": 50 },
      { "itemId": "potion_health", "dropChance": 50, "minQuantity": 1, "maxQuantity": 2 },
      { "itemId": "weapon_random", "dropChance": 10, "minQuantity": 1, "maxQuantity": 1 }
    ]
  }
}

Quest System Reference

Data Structure

enum QuestStatus { locked, available, active, completed }
enum ObjectiveType { kill, collect, talk, reach, custom }

class QuestObjective {
  final String id;
  final ObjectiveType type;
  final String description;
  final int requiredAmount;
  int currentAmount = 0;

  bool get isComplete => currentAmount >= requiredAmount;
}

class Quest {
  final String id;
  final String title;
  final String description;
  final List<QuestObjective> objectives;
  final List<String> prerequisites; // Quest IDs
  final QuestReward reward;
  QuestStatus status = QuestStatus.locked;

  bool get canStart => status == QuestStatus.available;
  bool get isComplete => objectives.every((o) => o.isComplete);
}

class QuestReward {
  final int gold;
  final int exp;
  final List<String> itemIds;
}

Quest Manager

class QuestManager extends Component {
  final Map<String, Quest> _quests = {};
  final List<Quest> _activeQuests = [];

  void loadQuests(List<Quest> quests) {
    for (final quest in quests) {
      _quests[quest.id] = quest;
    }
    _updateAvailability();
  }

  void startQuest(String questId) {
    final quest = _quests[questId];
    if (quest != null && quest.canStart) {
      quest.status = QuestStatus.active;
      _activeQuests.add(quest);
      onQuestStarted?.call(quest);
    }
  }

  void updateProgress(ObjectiveType type, String targetId, int amount) {
    for (final quest in _activeQuests) {
      for (final obj in quest.objectives) {
        if (obj.type == type && _matchesTarget(obj, targetId)) {
          obj.currentAmount += amount;
          onObjectiveProgress?.call(quest, obj);

          if (quest.isComplete) {
            _completeQuest(quest);
          }
        }
      }
    }
  }

  void _completeQuest(Quest quest) {
    quest.status = QuestStatus.completed;
    _activeQuests.remove(quest);
    _grantReward(quest.reward);
    onQuestCompleted?.call(quest);
    _updateAvailability();
  }

  void _updateAvailability() {
    for (final quest in _quests.values) {
      if (quest.status == QuestStatus.locked) {
        final prereqsMet = quest.prerequisites.every(
          (id) => _quests[id]?.status == QuestStatus.completed,
        );
        if (prereqsMet) {
          quest.status = QuestStatus.available;
        }
      }
    }
  }

  // Callbacks
  void Function(Quest)? onQuestStarted;
  void Function(Quest)? onQuestCompleted;
  void Function(Quest, QuestObjective)? onObjectiveProgress;
}

JSON Data Format

{
  "quests": [
    {
      "id": "main_001",
      "title": "The Beginning",
      "description": "Talk to the village elder",
      "prerequisites": [],
      "objectives": [
        {
          "type": "talk",
          "targetId": "npc_elder",
          "description": "Talk to Elder",
          "required": 1
        }
      ],
      "reward": { "gold": 100, "exp": 50, "items": ["sword_001"] }
    },
    {
      "id": "main_002",
      "title": "Pest Control",
      "description": "Clear the rats from the cellar",
      "prerequisites": ["main_001"],
      "objectives": [
        {
          "type": "kill",
          "targetId": "enemy_rat",
          "description": "Kill Rats",
          "required": 5
        }
      ],
      "reward": { "gold": 200, "exp": 100, "items": [] }
    }
  ]
}

Integration with Game

// When enemy dies
void onEnemyKilled(Enemy enemy) {
  questManager.updateProgress(
    ObjectiveType.kill,
    enemy.typeId,
    1,
  );
}

// When item collected
void onItemCollected(Item item) {
  questManager.updateProgress(
    ObjectiveType.collect,
    item.id,
    item.quantity,
  );
}

// When talking to NPC
void onNpcTalk(Npc npc) {
  questManager.updateProgress(
    ObjectiveType.talk,
    npc.id,
    1,
  );
}

Quest UI Component

class QuestTracker extends PositionComponent with HasGameRef {
  final QuestManager questManager;

  @override
  void render(Canvas canvas) {
    double y = 0;
    for (final quest in questManager.activeQuests) {
      _drawText(canvas, quest.title, Vector2(0, y), bold: true);
      y += 20;
      for (final obj in quest.objectives) {
        final status = '${obj.currentAmount}/${obj.requiredAmount}';
        _drawText(canvas, '  ${obj.description} $status', Vector2(0, y));
        y += 16;
      }
      y += 10;
    }
  }
}

Save/Load System Reference

Data Structure

class SaveData {
  final String version;
  final DateTime timestamp;
  final PlayerSaveData player;
  final WorldSaveData world;
  final Map<String, dynamic> custom;

  Map<String, dynamic> toJson() => {
    'version': version,
    'timestamp': timestamp.toIso8601String(),
    'player': player.toJson(),
    'world': world.toJson(),
    'custom': custom,
  };

  factory SaveData.fromJson(Map<String, dynamic> json) => SaveData(
    version: json['version'],
    timestamp: DateTime.parse(json['timestamp']),
    player: PlayerSaveData.fromJson(json['player']),
    world: WorldSaveData.fromJson(json['world']),
    custom: json['custom'] ?? {},
  );
}

class PlayerSaveData {
  final Vector2 position;
  final CombatStats stats;
  final List<String> inventoryItems;
  final Map<String, int> itemQuantities;
  final List<String> equippedItems;
  final List<String> learnedSkills;
  final int gold;
  final int exp;
  final int level;
}

class WorldSaveData {
  final String currentScene;
  final List<String> completedQuests;
  final List<String> activeQuests;
  final Map<String, int> questProgress;
  final List<String> unlockedAchievements;
  final Map<String, bool> flags;
  final double playTime;
}

Save Manager

class SaveManager {
  static const maxSlots = 3;
  final String saveDirectory;

  SaveManager({required this.saveDirectory});

  Future<void> save(int slot, SaveData data) async {
    final file = File('$saveDirectory/save_$slot.json');
    final json = jsonEncode(data.toJson());
    await file.writeAsString(json);
  }

  Future<SaveData?> load(int slot) async {
    final file = File('$saveDirectory/save_$slot.json');
    if (!await file.exists()) return null;

    final json = await file.readAsString();
    return SaveData.fromJson(jsonDecode(json));
  }

  Future<bool> exists(int slot) async {
    final file = File('$saveDirectory/save_$slot.json');
    return file.exists();
  }

  Future<void> delete(int slot) async {
    final file = File('$saveDirectory/save_$slot.json');
    if (await file.exists()) {
      await file.delete();
    }
  }

  Future<List<SaveSlotInfo>> getAllSlots() async {
    final slots = <SaveSlotInfo>[];
    for (int i = 0; i < maxSlots; i++) {
      final data = await load(i);
      slots.add(SaveSlotInfo(
        slot: i,
        isEmpty: data == null,
        timestamp: data?.timestamp,
        playTime: data?.world.playTime ?? 0,
        level: data?.player.level ?? 0,
      ));
    }
    return slots;
  }
}

class SaveSlotInfo {
  final int slot;
  final bool isEmpty;
  final DateTime? timestamp;
  final double playTime;
  final int level;
}

Auto-Save

class AutoSaveManager extends Component with HasGameRef<MyGame> {
  final SaveManager saveManager;
  final Duration interval;
  double _timer = 0;

  AutoSaveManager({
    required this.saveManager,
    this.interval = const Duration(minutes: 5),
  });

  @override
  void update(double dt) {
    _timer += dt;
    if (_timer >= interval.inSeconds) {
      _timer = 0;
      _performAutoSave();
    }
  }

  Future<void> _performAutoSave() async {
    final data = game.collectSaveData();
    await saveManager.save(0, data);  // Slot 0 for auto-save
    game.showNotification('Auto-saved');
  }
}

Cloud Save (Firebase)

class CloudSaveManager {
  final FirebaseFirestore _firestore = FirebaseFirestore.instance;

  Future<void> uploadSave(String oderId, SaveData data) async {
    await _firestore
        .collection('saves')
        .doc(userId)
        .set(data.toJson());
  }

  Future<SaveData?> downloadSave(String userId) async {
    final doc = await _firestore
        .collection('saves')
        .doc(userId)
        .get();

    if (!doc.exists) return null;
    return SaveData.fromJson(doc.data()!);
  }

  Future<void> syncSave(String userId, SaveData localData) async {
    final cloudData = await downloadSave(userId);

    if (cloudData == null) {
      // No cloud save, upload local
      await uploadSave(userId, localData);
    } else if (localData.timestamp.isAfter(cloudData.timestamp)) {
      // Local is newer, upload
      await uploadSave(userId, localData);
    } else if (cloudData.timestamp.isAfter(localData.timestamp)) {
      // Cloud is newer, prompt user
      onConflict?.call(localData, cloudData);
    }
  }

  void Function(SaveData local, SaveData cloud)? onConflict;
}

Save/Load UI

class SaveLoadUI extends PositionComponent with TapCallbacks {
  final SaveManager saveManager;
  final bool isSaveMode;
  List<SaveSlotInfo> slots = [];

  @override
  Future<void> onLoad() async {
    slots = await saveManager.getAllSlots();
  }

  @override
  void render(Canvas canvas) {
    _drawTitle(canvas, isSaveMode ? 'Save Game' : 'Load Game');

    double y = 60;
    for (final slot in slots) {
      _drawSlot(canvas, slot, Vector2(0, y));
      y += 100;
    }
  }

  void _drawSlot(Canvas canvas, SaveSlotInfo slot, Vector2 pos) {
    // Background
    canvas.drawRRect(
      RRect.fromRectAndRadius(
        Rect.fromLTWH(pos.x, pos.y, 300, 80),
        Radius.circular(8),
      ),
      Paint()..color = Colors.black.withOpacity(0.7),
    );

    if (slot.isEmpty) {
      _drawText(canvas, 'Empty Slot', pos + Vector2(20, 30));
    } else {
      _drawText(canvas, 'Level ${slot.level}', pos + Vector2(20, 15));
      _drawText(canvas, _formatPlayTime(slot.playTime), pos + Vector2(20, 35));
      _drawText(canvas, _formatTimestamp(slot.timestamp!), pos + Vector2(20, 55));
    }
  }

  String _formatPlayTime(double seconds) {
    final hours = (seconds / 3600).floor();
    final mins = ((seconds % 3600) / 60).floor();
    return '${hours}h ${mins}m';
  }

  @override
  void onTapDown(TapDownEvent event) {
    final slotIndex = ((event.localPosition.y - 60) / 100).floor();
    if (slotIndex >= 0 && slotIndex < slots.length) {
      if (isSaveMode) {
        onSaveSelected?.call(slotIndex);
      } else if (!slots[slotIndex].isEmpty) {
        onLoadSelected?.call(slotIndex);
      }
    }
  }

  void Function(int)? onSaveSelected;
  void Function(int)? onLoadSelected;
}

Serialization Helpers

extension Vector2Serialization on Vector2 {
  Map<String, double> toJson() => {'x': x, 'y': y};
  static Vector2 fromJson(Map<String, dynamic> json) =>
      Vector2(json['x'], json['y']);
}

extension CombatStatsSerializion on CombatStats {
  Map<String, dynamic> toJson() => {
    'hp': hp,
    'maxHp': maxHp,
    'mp': mp,
    'maxMp': maxMp,
    'attack': attack,
    'defense': defense,
    'speed': speed,
  };

  static CombatStats fromJson(Map<String, dynamic> json) => CombatStats(
    maxHp: json['maxHp'],
    maxMp: json['maxMp'],
    attack: json['attack'],
    defense: json['defense'],
    speed: json['speed'],
  )
    ..hp = json['hp']
    ..mp = json['mp'];
}

Game Integration

class MyGame extends FlameGame {
  late SaveManager saveManager;

  SaveData collectSaveData() {
    return SaveData(
      version: '1.0.0',
      timestamp: DateTime.now(),
      player: PlayerSaveData(
        position: player.position,
        stats: player.stats,
        inventoryItems: inventory.items.map((i) => i.id).toList(),
        // ...
      ),
      world: WorldSaveData(
        currentScene: router.currentRoute,
        completedQuests: questManager.completedQuests,
        // ...
      ),
    );
  }

  void applySaveData(SaveData data) {
    // Restore player
    player.position = data.player.position;
    player.stats = data.player.stats;

    // Restore inventory
    inventory.clear();
    for (final itemId in data.player.inventoryItems) {
      inventory.addItem(ItemDatabase.get(itemId)!);
    }

    // Restore world state
    router.pushReplacementNamed(data.world.currentScene);
    questManager.restoreState(data.world);

    onGameLoaded?.call();
  }
}

Shop System Reference

Data Structure

enum CurrencyType { gold, gems, tokens }

class ShopItem {
  final String itemId;
  final int price;
  final CurrencyType currency;
  final int stock;        // -1 for unlimited
  final int? requiredLevel;
  final String? requiredQuestId;

  int currentStock;

  bool get isAvailable => currentStock != 0;
}

class Shop {
  final String id;
  final String name;
  final String? npcId;
  final List<ShopItem> items;
  final double buybackRate;  // Sell price multiplier (e.g., 0.5)
}

class Wallet {
  final Map<CurrencyType, int> _currencies = {
    CurrencyType.gold: 0,
    CurrencyType.gems: 0,
    CurrencyType.tokens: 0,
  };

  int get(CurrencyType type) => _currencies[type] ?? 0;

  bool canAfford(CurrencyType type, int amount) => get(type) >= amount;

  void add(CurrencyType type, int amount) {
    _currencies[type] = (_currencies[type] ?? 0) + amount;
  }

  bool spend(CurrencyType type, int amount) {
    if (!canAfford(type, amount)) return false;
    _currencies[type] = _currencies[type]! - amount;
    return true;
  }
}

Shop Manager

class ShopManager extends Component {
  final Map<String, Shop> _shops = {};
  final InventoryManager inventory;
  final Wallet wallet;

  void loadShops(List<Shop> shops) {
    for (final shop in shops) {
      _shops[shop.id] = shop;
    }
  }

  Shop? getShop(String shopId) => _shops[shopId];

  BuyResult buyItem(String shopId, String itemId, int quantity) {
    final shop = _shops[shopId];
    if (shop == null) return BuyResult.shopNotFound;

    final shopItem = shop.items.firstWhere(
      (i) => i.itemId == itemId,
      orElse: () => null,
    );
    if (shopItem == null) return BuyResult.itemNotFound;

    // Check stock
    if (shopItem.stock != -1 && shopItem.currentStock < quantity) {
      return BuyResult.outOfStock;
    }

    // Check requirements
    if (shopItem.requiredLevel != null && player.level < shopItem.requiredLevel!) {
      return BuyResult.levelRequired;
    }

    // Check price
    final totalPrice = shopItem.price * quantity;
    if (!wallet.canAfford(shopItem.currency, totalPrice)) {
      return BuyResult.insufficientFunds;
    }

    // Check inventory space
    final item = ItemDatabase.get(itemId);
    if (item == null) return BuyResult.itemNotFound;

    // Execute purchase
    wallet.spend(shopItem.currency, totalPrice);
    inventory.addItem(item, quantity);

    if (shopItem.stock != -1) {
      shopItem.currentStock -= quantity;
    }

    onItemPurchased?.call(shop, item, quantity, totalPrice);
    return BuyResult.success;
  }

  SellResult sellItem(String shopId, String itemId, int quantity) {
    final shop = _shops[shopId];
    if (shop == null) return SellResult.shopNotFound;

    // Check inventory
    if (!inventory.hasItem(itemId, quantity)) {
      return SellResult.notEnoughItems;
    }

    final item = ItemDatabase.get(itemId)!;

    // Calculate sell price
    final sellPrice = (item.sellPrice * quantity * shop.buybackRate).round();

    // Execute sale
    inventory.removeItem(itemId, quantity);
    wallet.add(CurrencyType.gold, sellPrice);

    onItemSold?.call(shop, item, quantity, sellPrice);
    return SellResult.success;
  }

  void Function(Shop, ItemData, int, int)? onItemPurchased;
  void Function(Shop, ItemData, int, int)? onItemSold;
}

enum BuyResult { success, shopNotFound, itemNotFound, outOfStock, insufficientFunds, levelRequired }
enum SellResult { success, shopNotFound, notEnoughItems }

JSON Data Format

{
  "shops": [
    {
      "id": "shop_blacksmith",
      "name": "Blacksmith",
      "npcId": "npc_blacksmith",
      "buybackRate": 0.5,
      "items": [
        { "itemId": "sword_iron", "price": 100, "currency": "gold", "stock": -1 },
        { "itemId": "sword_steel", "price": 300, "currency": "gold", "stock": 5 },
        { "itemId": "armor_iron", "price": 200, "currency": "gold", "stock": -1 },
        { "itemId": "sword_legendary", "price": 1000, "currency": "gold", "stock": 1, "requiredLevel": 20 }
      ]
    },
    {
      "id": "shop_potion",
      "name": "Potion Shop",
      "npcId": "npc_alchemist",
      "buybackRate": 0.3,
      "items": [
        { "itemId": "potion_health", "price": 50, "currency": "gold", "stock": -1 },
        { "itemId": "potion_mana", "price": 50, "currency": "gold", "stock": -1 },
        { "itemId": "potion_rare", "price": 10, "currency": "gems", "stock": 3 }
      ]
    }
  ]
}

Shop UI

class ShopUI extends PositionComponent with TapCallbacks {
  final ShopManager shopManager;
  final String shopId;
  late Shop shop;

  String selectedItemId = '';
  int quantity = 1;
  bool isBuyMode = true;

  @override
  Future<void> onLoad() async {
    shop = shopManager.getShop(shopId)!;
  }

  @override
  void render(Canvas canvas) {
    // Header
    _drawText(canvas, shop.name, Vector2(10, 10), size: 24);

    // Mode tabs
    _drawTab(canvas, 'Buy', Vector2(10, 50), isBuyMode);
    _drawTab(canvas, 'Sell', Vector2(100, 50), !isBuyMode);

    // Item list
    final items = isBuyMode ? _getShopItems() : _getInventoryItems();
    double y = 100;
    for (final item in items) {
      _drawItemRow(canvas, item, Vector2(10, y), item.id == selectedItemId);
      y += 60;
    }

    // Selected item details
    if (selectedItemId.isNotEmpty) {
      _drawItemDetails(canvas, Vector2(size.x - 250, 100));
    }

    // Player gold
    _drawText(
      canvas,
      'Gold: ${shopManager.wallet.get(CurrencyType.gold)}',
      Vector2(size.x - 150, 10),
    );
  }

  void _drawItemRow(Canvas canvas, ItemData item, Vector2 pos, bool selected) {
    final bg = selected ? Colors.blue.withOpacity(0.3) : Colors.grey.withOpacity(0.2);
    canvas.drawRect(Rect.fromLTWH(pos.x, pos.y, 300, 50), Paint()..color = bg);

    // Icon, name, price
    _drawText(canvas, item.name, pos + Vector2(60, 10));

    if (isBuyMode) {
      final shopItem = shop.items.firstWhere((i) => i.itemId == item.id);
      _drawText(canvas, '${shopItem.price} G', pos + Vector2(60, 30), size: 12);
      if (shopItem.stock != -1) {
        _drawText(canvas, 'Stock: ${shopItem.currentStock}', pos + Vector2(200, 30), size: 12);
      }
    } else {
      _drawText(canvas, 'Sell: ${(item.sellPrice * shop.buybackRate).round()} G', pos + Vector2(60, 30), size: 12);
    }
  }

  void _drawItemDetails(Canvas canvas, Vector2 pos) {
    final item = ItemDatabase.get(selectedItemId)!;

    // Item info panel
    canvas.drawRRect(
      RRect.fromRectAndRadius(Rect.fromLTWH(pos.x, pos.y, 230, 300), Radius.circular(8)),
      Paint()..color = Colors.black.withOpacity(0.8),
    );

    _drawText(canvas, item.name, pos + Vector2(10, 10), size: 18);
    _drawText(canvas, item.description, pos + Vector2(10, 40), size: 12);

    // Quantity selector
    _drawText(canvas, 'Qty: $quantity', pos + Vector2(10, 200));

    // Buy/Sell button
    final buttonText = isBuyMode ? 'Buy' : 'Sell';
    _drawButton(canvas, buttonText, pos + Vector2(10, 250));
  }

  @override
  void onTapDown(TapDownEvent event) {
    // Handle item selection, quantity change, buy/sell button
  }
}

Daily/Rotating Shop

class DailyShop {
  final String id;
  final List<String> possibleItems;
  final int displayCount;
  DateTime lastRefresh = DateTime(2000);

  List<ShopItem> currentItems = [];

  void refresh() {
    if (_shouldRefresh()) {
      currentItems = _generateDailyItems();
      lastRefresh = DateTime.now();
    }
  }

  bool _shouldRefresh() {
    final now = DateTime.now();
    final lastMidnight = DateTime(now.year, now.month, now.day);
    return lastRefresh.isBefore(lastMidnight);
  }

  List<ShopItem> _generateDailyItems() {
    final shuffled = List<String>.from(possibleItems)..shuffle();
    return shuffled.take(displayCount).map((id) => ShopItem(
      itemId: id,
      price: ItemDatabase.get(id)!.buyPrice,
      currency: CurrencyType.gold,
      stock: 1,
    )).toList();
  }
}

Discount System

class DiscountManager {
  final Map<String, double> _itemDiscounts = {};
  final Map<String, double> _categoryDiscounts = {};
  double globalDiscount = 0;

  double getDiscount(ItemData item) {
    // Check specific item discount
    if (_itemDiscounts.containsKey(item.id)) {
      return _itemDiscounts[item.id]!;
    }

    // Check category discount
    if (_categoryDiscounts.containsKey(item.type.name)) {
      return _categoryDiscounts[item.type.name]!;
    }

    return globalDiscount;
  }

  int applyDiscount(int originalPrice, ItemData item) {
    final discount = getDiscount(item);
    return (originalPrice * (1 - discount)).round();
  }

  void setItemDiscount(String itemId, double discount) {
    _itemDiscounts[itemId] = discount.clamp(0, 1);
  }

  void setSaleEvent(double discount, Duration duration) {
    globalDiscount = discount;
    Future.delayed(duration, () => globalDiscount = 0);
  }
}

Skills System Reference

Data Structure

enum SkillType { active, passive }
enum TargetType { self, singleEnemy, allEnemies, singleAlly, allAllies, area }
enum EffectType { damage, heal, buff, debuff, summon, special }

class SkillData {
  final String id;
  final String name;
  final String description;
  final String iconPath;
  final SkillType type;
  final TargetType targetType;
  final int mpCost;
  final double cooldown;
  final int requiredLevel;
  final List<String> prerequisites;  // Required skill IDs
  final List<SkillEffect> effects;
}

class SkillEffect {
  final EffectType type;
  final int value;
  final double duration;  // For buffs/debuffs
  final String? statusId; // Status effect to apply
}

class LearnedSkill {
  final SkillData data;
  int level = 1;
  double currentCooldown = 0;

  bool get isReady => currentCooldown <= 0;
  int get effectiveValue => (data.effects.first.value * (1 + level * 0.1)).round();
}

Skills Manager

class SkillsManager extends Component {
  final Map<String, LearnedSkill> _learnedSkills = {};
  int skillPoints = 0;

  List<LearnedSkill> get activeSkills =>
      _learnedSkills.values.where((s) => s.data.type == SkillType.active).toList();

  List<LearnedSkill> get passiveSkills =>
      _learnedSkills.values.where((s) => s.data.type == SkillType.passive).toList();

  bool canLearn(SkillData skill) {
    if (_learnedSkills.containsKey(skill.id)) return false;
    if (skillPoints <= 0) return false;

    // Check prerequisites
    for (final prereqId in skill.prerequisites) {
      if (!_learnedSkills.containsKey(prereqId)) return false;
    }

    return true;
  }

  void learnSkill(SkillData skill) {
    if (!canLearn(skill)) return;

    _learnedSkills[skill.id] = LearnedSkill(data: skill);
    skillPoints--;
    onSkillLearned?.call(skill);
  }

  void upgradeSkill(String skillId) {
    final skill = _learnedSkills[skillId];
    if (skill == null || skillPoints <= 0) return;

    skill.level++;
    skillPoints--;
    onSkillUpgraded?.call(skill);
  }

  bool useSkill(String skillId, CombatEntity caster, List<CombatEntity> targets) {
    final skill = _learnedSkills[skillId];
    if (skill == null || !skill.isReady) return false;

    final casterStats = caster.stats;
    if (casterStats.mp < skill.data.mpCost) return false;

    // Consume MP
    casterStats.mp -= skill.data.mpCost;

    // Apply effects
    for (final effect in skill.data.effects) {
      _applyEffect(effect, skill.effectiveValue, caster, targets);
    }

    // Start cooldown
    skill.currentCooldown = skill.data.cooldown;

    onSkillUsed?.call(skill, targets);
    return true;
  }

  void _applyEffect(
    SkillEffect effect,
    int value,
    CombatEntity caster,
    List<CombatEntity> targets,
  ) {
    switch (effect.type) {
      case EffectType.damage:
        for (final target in targets) {
          final result = DamageResult(
            damage: value,
            isCrit: false,
            isMiss: false,
            type: DamageType.magical,
          );
          target.takeDamage(result);
        }
        break;

      case EffectType.heal:
        for (final target in targets) {
          target.heal(value);
        }
        break;

      case EffectType.buff:
        for (final target in targets) {
          target.addStatusEffect(StatusEffect(
            id: effect.statusId!,
            duration: effect.duration,
            value: value,
          ));
        }
        break;

      case EffectType.debuff:
        for (final target in targets) {
          target.addStatusEffect(StatusEffect(
            id: effect.statusId!,
            duration: effect.duration,
            value: -value,
            isDebuff: true,
          ));
        }
        break;
    }
  }

  @override
  void update(double dt) {
    // Update cooldowns
    for (final skill in _learnedSkills.values) {
      if (skill.currentCooldown > 0) {
        skill.currentCooldown -= dt;
      }
    }
  }

  void Function(SkillData)? onSkillLearned;
  void Function(LearnedSkill)? onSkillUpgraded;
  void Function(LearnedSkill, List<CombatEntity>)? onSkillUsed;
}

Skill Tree

class SkillTree {
  final String id;
  final String name;
  final List<SkillTreeNode> nodes;
}

class SkillTreeNode {
  final SkillData skill;
  final Vector2 position;    // UI position
  final List<String> connections;  // Connected skill IDs
}

class SkillTreeUI extends PositionComponent with TapCallbacks {
  final SkillTree tree;
  final SkillsManager manager;

  @override
  void render(Canvas canvas) {
    // Draw connections first
    for (final node in tree.nodes) {
      for (final connId in node.connections) {
        final connNode = tree.nodes.firstWhere((n) => n.skill.id == connId);
        _drawConnection(canvas, node.position, connNode.position);
      }
    }

    // Draw skill nodes
    for (final node in tree.nodes) {
      final isLearned = manager._learnedSkills.containsKey(node.skill.id);
      final canLearn = manager.canLearn(node.skill);

      Color color;
      if (isLearned) {
        color = Colors.green;
      } else if (canLearn) {
        color = Colors.yellow;
      } else {
        color = Colors.grey;
      }

      _drawSkillNode(canvas, node, color);
    }
  }

  void _drawConnection(Canvas canvas, Vector2 from, Vector2 to) {
    canvas.drawLine(
      Offset(from.x, from.y),
      Offset(to.x, to.y),
      Paint()
        ..color = Colors.white.withOpacity(0.5)
        ..strokeWidth = 2,
    );
  }

  void _drawSkillNode(Canvas canvas, SkillTreeNode node, Color color) {
    canvas.drawCircle(
      Offset(node.position.x, node.position.y),
      30,
      Paint()..color = color,
    );
    // Draw skill icon inside
  }

  @override
  void onTapDown(TapDownEvent event) {
    for (final node in tree.nodes) {
      if ((event.localPosition - node.position).length < 30) {
        if (manager.canLearn(node.skill)) {
          manager.learnSkill(node.skill);
        }
        break;
      }
    }
  }
}

JSON Data Format

{
  "skills": [
    {
      "id": "fireball",
      "name": "Fireball",
      "description": "Launch a ball of fire at the enemy",
      "iconPath": "skills/fireball.png",
      "type": "active",
      "targetType": "singleEnemy",
      "mpCost": 10,
      "cooldown": 3.0,
      "requiredLevel": 1,
      "prerequisites": [],
      "effects": [
        { "type": "damage", "value": 50 }
      ]
    },
    {
      "id": "heal",
      "name": "Heal",
      "description": "Restore HP to an ally",
      "iconPath": "skills/heal.png",
      "type": "active",
      "targetType": "singleAlly",
      "mpCost": 15,
      "cooldown": 5.0,
      "requiredLevel": 3,
      "prerequisites": [],
      "effects": [
        { "type": "heal", "value": 100 }
      ]
    },
    {
      "id": "attack_up",
      "name": "Power Boost",
      "description": "Increase attack power for 30 seconds",
      "iconPath": "skills/attack_up.png",
      "type": "active",
      "targetType": "self",
      "mpCost": 20,
      "cooldown": 60.0,
      "requiredLevel": 5,
      "prerequisites": ["fireball"],
      "effects": [
        { "type": "buff", "value": 20, "duration": 30.0, "statusId": "attack_buff" }
      ]
    }
  ],
  "skillTrees": [
    {
      "id": "mage",
      "name": "Mage",
      "nodes": [
        { "skillId": "fireball", "position": [100, 100], "connections": ["attack_up"] },
        { "skillId": "attack_up", "position": [100, 200], "connections": [] },
        { "skillId": "heal", "position": [200, 100], "connections": [] }
      ]
    }
  ]
}

Skill Hotbar UI

class SkillHotbar extends PositionComponent with HasGameRef {
  final SkillsManager manager;
  final int slotCount = 4;

  @override
  void render(Canvas canvas) {
    final skills = manager.activeSkills.take(slotCount).toList();

    for (int i = 0; i < slotCount; i++) {
      final x = i * 70.0;

      // Slot background
      canvas.drawRRect(
        RRect.fromRectAndRadius(Rect.fromLTWH(x, 0, 64, 64), Radius.circular(8)),
        Paint()..color = Colors.black.withOpacity(0.7),
      );

      if (i < skills.length) {
        final skill = skills[i];

        // Skill icon
        // ...

        // Cooldown overlay
        if (!skill.isReady) {
          final progress = skill.currentCooldown / skill.data.cooldown;
          canvas.drawRect(
            Rect.fromLTWH(x, 0, 64, 64 * progress),
            Paint()..color = Colors.black.withOpacity(0.6),
          );

          // Cooldown text
          _drawText(canvas, '${skill.currentCooldown.ceil()}', Vector2(x + 32, 32));
        }

        // Hotkey number
        _drawText(canvas, '${i + 1}', Vector2(x + 4, 4), size: 12);
      }
    }
  }
}