Flame Templates

Flame Game Templates

三種主要遊戲類型的完整起始模板和架構。

Reference Index

AI Usage Guide

需要 RPG 遊戲？      → Read references/rpg.md
需要平台遊戲？       → Read references/platformer.md
需要 Roguelike？    → Read references/roguelike.md

Template Comparison

Quick Start

每個模板包含：

• 完整 main.dart
• Player 類別
• 核心遊戲循環
• 基礎 UI

Related Skills

• flame-core - 引擎核心基礎
• flame-systems - 14 個遊戲系統

Platformer Game Template

Project Structure

lib/
├── main.dart
├── game/
│   └── platformer_game.dart
├── player/
│   ├── player.dart
│   └── player_state.dart
├── world/
│   ├── platform.dart
│   ├── hazard.dart
│   └── level_loader.dart
├── collectibles/
│   ├── coin.dart
│   └── powerup.dart
├── enemies/
│   └── enemy.dart
└── ui/
    └── hud.dart

Main Entry Point

import 'package:flame/game.dart';
import 'package:flutter/material.dart';

void main() {
  runApp(
    GameWidget<PlatformerGame>(
      game: PlatformerGame(),
      overlayBuilderMap: {
        'hud': (_, game) => GameHUD(game: game),
        'pause': (_, game) => PauseMenu(game: game),
        'gameOver': (_, game) => GameOverScreen(game: game),
        'levelComplete': (_, game) => LevelCompleteScreen(game: game),
      },
      initialActiveOverlays: const ['hud'],
    ),
  );
}

Core Game Class

class PlatformerGame extends FlameGame with HasCollisionDetection, HasKeyboardHandlerComponents {
  late Player player;
  late CameraComponent cam;

  int currentLevel = 1;
  int score = 0;
  int lives = 3;

  static const double gravity = 800;

  @override
  Future<void> onLoad() async {
    // Setup camera with fixed resolution
    camera.viewport = FixedResolutionViewport(resolution: Vector2(400, 240));
    camera.viewfinder.anchor = Anchor.center;

    await loadLevel(currentLevel);
  }

  Future<void> loadLevel(int levelNum) async {
    // Clear world
    world.removeAll(world.children);

    // Load level from Tiled
    final level = await TiledComponent.load(
      'level_$levelNum.tmx',
      Vector2.all(16),
    );
    world.add(level);

    // Parse objects from Tiled
    _parseLevel(level);

    // Add boundaries
    world.add(ScreenHitbox());

    // Follow player
    camera.follow(player, horizontalOnly: false, verticalOnly: false);
  }

  void _parseLevel(TiledComponent level) {
    final spawnLayer = level.tileMap.getLayer<ObjectGroup>('Spawns');

    for (final obj in spawnLayer?.objects ?? []) {
      switch (obj.class_) {
        case 'Player':
          player = Player(position: Vector2(obj.x, obj.y));
          world.add(player);
          break;
        case 'Coin':
          world.add(Coin(position: Vector2(obj.x, obj.y)));
          break;
        case 'Enemy':
          world.add(Enemy(position: Vector2(obj.x, obj.y)));
          break;
        case 'Goal':
          world.add(Goal(position: Vector2(obj.x, obj.y)));
          break;
      }
    }
  }

  void collectCoin() {
    score += 100;
  }

  void playerDied() {
    lives--;
    if (lives <= 0) {
      overlays.add('gameOver');
    } else {
      // Respawn at checkpoint
      player.respawn();
    }
  }

  void levelComplete() {
    overlays.add('levelComplete');
  }

  void nextLevel() {
    overlays.remove('levelComplete');
    currentLevel++;
    loadLevel(currentLevel);
  }
}

Player Class

class Player extends SpriteAnimationGroupComponent<PlayerState>
    with HasGameRef<PlatformerGame>, CollisionCallbacks, KeyboardHandler {

  static const double moveSpeed = 150;
  static const double jumpForce = 300;
  static const double maxFallSpeed = 400;

  Vector2 velocity = Vector2.zero();
  bool isOnGround = false;
  bool isFacingRight = true;
  int _horizontalInput = 0;

  Vector2 _spawnPoint = Vector2.zero();

  Player({required Vector2 position})
      : super(
          position: position,
          size: Vector2(32, 32),
          anchor: Anchor.bottomCenter,
        ) {
    _spawnPoint = position.clone();
  }

  @override
  Future<void> onLoad() async {
    animations = {
      PlayerState.idle: await _loadAnim('idle', 4, 0.15),
      PlayerState.run: await _loadAnim('run', 6, 0.1),
      PlayerState.jump: await _loadAnim('jump', 1, 0.1),
      PlayerState.fall: await _loadAnim('fall', 1, 0.1),
    };
    current = PlayerState.idle;

    add(RectangleHitbox(
      size: Vector2(20, 30),
      position: Vector2(6, 2),
    ));
  }

  @override
  bool onKeyEvent(KeyEvent event, Set<LogicalKeyboardKey> keys) {
    _horizontalInput = 0;

    if (keys.contains(LogicalKeyboardKey.keyA) ||
        keys.contains(LogicalKeyboardKey.arrowLeft)) {
      _horizontalInput = -1;
    }
    if (keys.contains(LogicalKeyboardKey.keyD) ||
        keys.contains(LogicalKeyboardKey.arrowRight)) {
      _horizontalInput = 1;
    }

    // Jump
    if ((keys.contains(LogicalKeyboardKey.space) ||
         keys.contains(LogicalKeyboardKey.keyW) ||
         keys.contains(LogicalKeyboardKey.arrowUp)) &&
        isOnGround) {
      _jump();
    }

    return true;
  }

  void _jump() {
    velocity.y = -jumpForce;
    isOnGround = false;
    current = PlayerState.jump;
  }

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

    // Horizontal movement
    velocity.x = _horizontalInput * moveSpeed;

    // Flip sprite
    if (_horizontalInput != 0) {
      isFacingRight = _horizontalInput > 0;
      scale.x = isFacingRight ? 1 : -1;
    }

    // Apply gravity
    velocity.y += PlatformerGame.gravity * dt;
    velocity.y = velocity.y.clamp(-jumpForce, maxFallSpeed);

    // Apply velocity
    position += velocity * dt;

    // Update animation
    _updateAnimation();

    // Death check (fell off map)
    if (position.y > game.size.y + 100) {
      game.playerDied();
    }
  }

  void _updateAnimation() {
    if (!isOnGround) {
      current = velocity.y < 0 ? PlayerState.jump : PlayerState.fall;
    } else if (velocity.x.abs() > 1) {
      current = PlayerState.run;
    } else {
      current = PlayerState.idle;
    }
  }

  @override
  void onCollision(Set<Vector2> intersectionPoints, PositionComponent other) {
    if (other is Platform) {
      _resolvePlatformCollision(intersectionPoints, other);
    }
    super.onCollision(intersectionPoints, other);
  }

  void _resolvePlatformCollision(Set<Vector2> points, Platform platform) {
    if (points.length < 2) return;

    final mid = (points.first + points.last) / 2;
    final collisionNormal = position - mid;
    collisionNormal.normalize();

    // Landing on top
    if (collisionNormal.y < -0.5 && velocity.y > 0) {
      isOnGround = true;
      velocity.y = 0;
      position.y = platform.position.y;
    }
    // Hitting from below
    else if (collisionNormal.y > 0.5 && velocity.y < 0) {
      velocity.y = 0;
    }
    // Hitting from side
    else {
      final pushBack = collisionNormal.x > 0 ? 1 : -1;
      position.x += pushBack * 2;
    }
  }

  @override
  void onCollisionStart(Set<Vector2> points, PositionComponent other) {
    if (other is Coin) {
      other.collect();
      game.collectCoin();
    }
    if (other is Enemy) {
      // Check if stomping
      if (velocity.y > 0 && position.y < other.position.y) {
        other.stomp();
        velocity.y = -jumpForce * 0.5; // Bounce
      } else {
        // Take damage
        game.playerDied();
      }
    }
    if (other is Hazard) {
      game.playerDied();
    }
    if (other is Goal) {
      game.levelComplete();
    }
    super.onCollisionStart(points, other);
  }

  void respawn() {
    position = _spawnPoint.clone();
    velocity = Vector2.zero();
  }
}

enum PlayerState { idle, run, jump, fall }

Platform Class

class Platform extends PositionComponent with CollisionCallbacks {
  Platform({
    required Vector2 position,
    required Vector2 size,
  }) : super(position: position, size: size);

  @override
  Future<void> onLoad() async {
    add(RectangleHitbox()..collisionType = CollisionType.passive);
  }
}

class MovingPlatform extends Platform {
  final Vector2 moveDistance;
  final double moveSpeed;

  Vector2 _startPos = Vector2.zero();
  double _progress = 0;
  int _direction = 1;

  MovingPlatform({
    required super.position,
    required super.size,
    required this.moveDistance,
    this.moveSpeed = 50,
  });

  @override
  Future<void> onLoad() async {
    await super.onLoad();
    _startPos = position.clone();
  }

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

    _progress += moveSpeed * dt * _direction;

    if (_progress >= moveDistance.length) {
      _progress = moveDistance.length;
      _direction = -1;
    } else if (_progress <= 0) {
      _progress = 0;
      _direction = 1;
    }

    final normalized = moveDistance.normalized();
    position = _startPos + normalized * _progress;
  }
}

Collectible Classes

class Coin extends SpriteAnimationComponent with CollisionCallbacks, HasGameRef {
  bool isCollected = false;

  Coin({required Vector2 position})
      : super(
          position: position,
          size: Vector2.all(16),
          anchor: Anchor.center,
        );

  @override
  Future<void> onLoad() async {
    animation = await game.loadSpriteAnimation(
      'coin.png',
      SpriteAnimationData.sequenced(
        amount: 4,
        stepTime: 0.1,
        textureSize: Vector2.all(16),
      ),
    );
    add(CircleHitbox()..collisionType = CollisionType.passive);
  }

  void collect() {
    if (isCollected) return;
    isCollected = true;

    // Play collect animation
    add(SequenceEffect([
      ScaleEffect.to(Vector2.all(1.5), EffectController(duration: 0.1)),
      OpacityEffect.fadeOut(EffectController(duration: 0.1)),
      RemoveEffect(),
    ]));
  }
}

class PowerUp extends SpriteComponent with CollisionCallbacks, HasGameRef {
  final PowerUpType type;

  PowerUp({required Vector2 position, required this.type})
      : super(position: position, size: Vector2.all(24), anchor: Anchor.center);

  @override
  Future<void> onLoad() async {
    sprite = await game.loadSprite('powerup_${type.name}.png');
    add(RectangleHitbox()..collisionType = CollisionType.passive);
  }
}

enum PowerUpType { speedBoost, doubleJump, invincible }

Enemy Class

class Enemy extends SpriteAnimationComponent with CollisionCallbacks, HasGameRef {
  final double patrolDistance;
  final double speed;

  Vector2 _startPos = Vector2.zero();
  int _direction = 1;
  bool _isStomped = false;

  Enemy({
    required Vector2 position,
    this.patrolDistance = 100,
    this.speed = 50,
  }) : super(position: position, size: Vector2(32, 32), anchor: Anchor.bottomCenter);

  @override
  Future<void> onLoad() async {
    animation = await game.loadSpriteAnimation(
      'enemy_walk.png',
      SpriteAnimationData.sequenced(amount: 4, stepTime: 0.15, textureSize: Vector2.all(32)),
    );
    _startPos = position.clone();

    add(RectangleHitbox(size: Vector2(28, 28), position: Vector2(2, 4)));
  }

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

    position.x += speed * _direction * dt;

    if ((position.x - _startPos.x).abs() >= patrolDistance) {
      _direction *= -1;
      scale.x = _direction.toDouble();
    }
  }

  void stomp() {
    _isStomped = true;
    animation = null; // Or play death animation

    add(SequenceEffect([
      ScaleEffect.to(Vector2(1.5, 0.3), EffectController(duration: 0.1)),
      RemoveEffect(),
    ]));
  }
}

HUD

class GameHUD extends StatelessWidget {
  final PlatformerGame game;

  const GameHUD({required this.game});

  @override
  Widget build(BuildContext context) {
    return SafeArea(
      child: Padding(
        padding: const EdgeInsets.all(16),
        child: Row(
          mainAxisAlignment: MainAxisAlignment.spaceBetween,
          children: [
            // Score
            Row(
              children: [
                const Icon(Icons.star, color: Colors.yellow),
                const SizedBox(width: 8),
                Text(
                  '${game.score}',
                  style: const TextStyle(
                    color: Colors.white,
                    fontSize: 24,
                    fontWeight: FontWeight.bold,
                  ),
                ),
              ],
            ),
            // Lives
            Row(
              children: List.generate(
                game.lives,
                (_) => const Icon(Icons.favorite, color: Colors.red),
              ),
            ),
          ],
        ),
      ),
    );
  }
}

Roguelike Game Template

Project Structure

lib/
├── main.dart
├── game/
│   ├── roguelike_game.dart
│   └── game_state.dart
├── player/
│   └── player.dart
├── dungeon/
│   ├── dungeon_generator.dart
│   ├── floor_manager.dart
│   └── room.dart
├── enemies/
│   ├── enemy.dart
│   └── spawn_table.dart
├── items/
│   ├── item.dart
│   └── loot_table.dart
├── combat/
│   └── combat_system.dart
└── ui/
    ├── hud.dart
    └── minimap.dart

Main Entry Point

import 'package:flame/game.dart';
import 'package:flutter/material.dart';

void main() {
  runApp(
    GameWidget<RoguelikeGame>(
      game: RoguelikeGame(),
      overlayBuilderMap: {
        'hud': (_, game) => GameHUD(game: game),
        'inventory': (_, game) => InventoryScreen(game: game),
        'gameOver': (_, game) => GameOverScreen(game: game),
        'floorTransition': (_, game) => FloorTransition(game: game),
      },
      initialActiveOverlays: const ['hud'],
    ),
  );
}

Core Game Class

class RoguelikeGame extends FlameGame with HasCollisionDetection, HasKeyboardHandlerComponents {
  late Player player;
  late FloorManager floorManager;
  late DungeonGenerator dungeonGenerator;
  late SpawnTable enemySpawnTable;
  late LootTable lootTable;

  int currentFloor = 1;
  int gold = 0;
  int runSeed = 0;

  // Meta progression (persists between runs)
  MetaProgress meta = MetaProgress();

  @override
  Future<void> onLoad() async {
    camera.viewfinder.anchor = Anchor.center;
    camera.viewfinder.zoom = 2.0;

    // Initialize systems
    floorManager = FloorManager();
    dungeonGenerator = DungeonGenerator();
    enemySpawnTable = SpawnTable.load('enemies.json');
    lootTable = LootTable.load('loot.json');

    // Start new run
    startNewRun();
  }

  void startNewRun() {
    currentFloor = 1;
    gold = 0;
    runSeed = DateTime.now().millisecondsSinceEpoch;

    player = Player(stats: _getStartingStats());
    world.add(player);

    generateFloor();
    camera.follow(player);
  }

  void generateFloor() {
    // Clear previous floor
    world.children.whereType<DungeonTile>().forEach((t) => t.removeFromParent());
    world.children.whereType<Enemy>().forEach((e) => e.removeFromParent());
    world.children.whereType<ItemDrop>().forEach((i) => i.removeFromParent());

    // Generate dungeon
    final seed = runSeed + currentFloor;
    final dungeon = dungeonGenerator.generate(
      width: 50 + currentFloor * 5,
      height: 50 + currentFloor * 5,
      seed: seed,
    );

    // Create tiles
    _buildFloor(dungeon);

    // Place player at spawn
    player.position = dungeon.spawnPoint * 16;

    // Spawn enemies
    _spawnEnemies(dungeon, seed);

    // Place items
    _placeItems(dungeon, seed);

    // Place exit
    world.add(FloorExit(position: dungeon.exitPoint * 16));
  }

  void _buildFloor(DungeonData dungeon) {
    for (int y = 0; y < dungeon.height; y++) {
      for (int x = 0; x < dungeon.width; x++) {
        final tileType = dungeon.grid[y][x];
        if (tileType > 0) {
          world.add(DungeonTile(
            position: Vector2(x * 16.0, y * 16.0),
            tileType: tileType,
          ));
        }
      }
    }
  }

  void _spawnEnemies(DungeonData dungeon, int seed) {
    final random = SeededRandom(seed);
    final enemyCount = 3 + currentFloor * 2;

    for (int i = 0; i < enemyCount; i++) {
      final room = random.pick(dungeon.rooms);
      final position = room.randomPoint(random) * 16;

      final enemyType = enemySpawnTable.roll(random, currentFloor);
      world.add(Enemy.spawn(enemyType, position, currentFloor));
    }
  }

  void _placeItems(DungeonData dungeon, int seed) {
    final random = SeededRandom(seed + 1000);
    final itemCount = 2 + random.nextInt(3);

    for (int i = 0; i < itemCount; i++) {
      final room = random.pick(dungeon.rooms);
      final position = room.randomPoint(random) * 16;

      final itemId = lootTable.roll(random, currentFloor);
      world.add(ItemDrop(itemId: itemId, position: position));
    }
  }

  void descendFloor() {
    overlays.add('floorTransition');

    Future.delayed(const Duration(seconds: 1), () {
      currentFloor++;
      generateFloor();
      overlays.remove('floorTransition');
    });
  }

  void playerDied() {
    // Save meta progress
    meta.totalGold += gold;
    meta.highestFloor = max(meta.highestFloor, currentFloor);
    meta.totalRuns++;
    meta.save();

    overlays.add('gameOver');
  }

  PlayerStats _getStartingStats() {
    return PlayerStats(
      maxHp: 100 + meta.hpUpgrade * 10,
      attack: 10 + meta.attackUpgrade * 2,
      defense: 5 + meta.defenseUpgrade,
    );
  }
}

Dungeon Generator

class DungeonGenerator {
  DungeonData generate({
    required int width,
    required int height,
    required int seed,
  }) {
    final random = SeededRandom(seed);
    final grid = List.generate(height, (_) => List.filled(width, 0));
    final rooms = <DungeonRoom>[];

    // BSP dungeon generation
    _splitSpace(
      grid, rooms, random,
      Rect.fromLTWH(1, 1, width - 2.0, height - 2.0),
    );

    // Connect rooms
    _connectRooms(grid, rooms, random);

    // Determine spawn and exit
    final spawnRoom = rooms.first;
    final exitRoom = rooms.last;

    return DungeonData(
      width: width,
      height: height,
      grid: grid,
      rooms: rooms,
      spawnPoint: spawnRoom.center,
      exitPoint: exitRoom.center,
    );
  }

  void _splitSpace(
    List<List<int>> grid,
    List<DungeonRoom> rooms,
    SeededRandom random,
    Rect space,
  ) {
    const minSize = 8;

    if (space.width < minSize * 2 && space.height < minSize * 2) {
      _createRoom(grid, rooms, random, space);
      return;
    }

    final splitHorizontal = space.width > space.height
        ? false
        : space.height > space.width
            ? true
            : random.nextBool();

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

  void _createRoom(
    List<List<int>> grid,
    List<DungeonRoom> rooms,
    SeededRandom random,
    Rect space,
  ) {
    final roomWidth = 4 + random.nextInt((space.width - 4).toInt().clamp(1, 8));
    final roomHeight = 4 + random.nextInt((space.height - 4).toInt().clamp(1, 8));
    final roomX = space.left.toInt() + random.nextInt((space.width - roomWidth).toInt().clamp(1, 5));
    final roomY = space.top.toInt() + random.nextInt((space.height - roomHeight).toInt().clamp(1, 5));

    final room = DungeonRoom(
      Rect.fromLTWH(roomX.toDouble(), roomY.toDouble(), roomWidth.toDouble(), roomHeight.toDouble()),
    );
    rooms.add(room);

    // Fill room with floor tiles
    for (int y = roomY; y < roomY + roomHeight; y++) {
      for (int x = roomX; x < roomX + roomWidth; x++) {
        if (y >= 0 && y < grid.length && x >= 0 && x < grid[0].length) {
          grid[y][x] = 1; // Floor
        }
      }
    }
  }

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

  void _createCorridor(List<List<int>> grid, Vector2 from, Vector2 to) {
    int x = from.x.toInt();
    int y = from.y.toInt();

    while (x != to.x.toInt()) {
      if (y >= 0 && y < grid.length && x >= 0 && x < grid[0].length) {
        grid[y][x] = 1;
      }
      x += x < to.x ? 1 : -1;
    }
    while (y != to.y.toInt()) {
      if (y >= 0 && y < grid.length && x >= 0 && x < grid[0].length) {
        grid[y][x] = 1;
      }
      y += y < to.y ? 1 : -1;
    }
  }
}

class DungeonRoom {
  final Rect bounds;

  DungeonRoom(this.bounds);

  Vector2 get center => Vector2(bounds.center.dx, bounds.center.dy);

  Vector2 randomPoint(SeededRandom random) {
    return Vector2(
      bounds.left + random.nextInt(bounds.width.toInt()),
      bounds.top + random.nextInt(bounds.height.toInt()),
    );
  }
}

Player Class

class Player extends SpriteAnimationGroupComponent<PlayerState>
    with HasGameRef<RoguelikeGame>, CollisionCallbacks, KeyboardHandler {

  PlayerStats stats;
  Vector2 velocity = Vector2.zero();
  Vector2 _inputDir = Vector2.zero();

  static const double speed = 100;
  static const double attackCooldown = 0.3;
  double _attackTimer = 0;

  Player({required this.stats})
      : super(size: Vector2.all(16), anchor: Anchor.center);

  @override
  Future<void> onLoad() async {
    animations = {
      PlayerState.idle: await _loadAnim('idle', 4),
      PlayerState.walk: await _loadAnim('walk', 4),
      PlayerState.attack: await _loadAnim('attack', 4),
    };
    current = PlayerState.idle;

    add(CircleHitbox(radius: 6));
  }

  @override
  bool onKeyEvent(KeyEvent event, Set<LogicalKeyboardKey> keys) {
    _inputDir = Vector2.zero();

    if (keys.contains(LogicalKeyboardKey.keyW)) _inputDir.y = -1;
    if (keys.contains(LogicalKeyboardKey.keyS)) _inputDir.y = 1;
    if (keys.contains(LogicalKeyboardKey.keyA)) _inputDir.x = -1;
    if (keys.contains(LogicalKeyboardKey.keyD)) _inputDir.x = 1;

    if (_inputDir.length > 0) _inputDir.normalize();

    // Attack
    if (keys.contains(LogicalKeyboardKey.space) && _attackTimer <= 0) {
      _attack();
    }

    return true;
  }

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

    if (_attackTimer > 0) {
      _attackTimer -= dt;
    } else {
      velocity = _inputDir * speed;
      position += velocity * dt;

      current = velocity.length > 1 ? PlayerState.walk : PlayerState.idle;
    }
  }

  void _attack() {
    _attackTimer = attackCooldown;
    current = PlayerState.attack;

    // Find enemies in range
    final enemies = game.world.children.whereType<Enemy>();
    for (final enemy in enemies) {
      if (position.distanceTo(enemy.position) < 30) {
        final damage = stats.attack;
        enemy.takeDamage(damage);
      }
    }
  }

  void takeDamage(int damage) {
    final actualDamage = max(1, damage - stats.defense);
    stats.hp -= actualDamage;

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

    if (stats.hp <= 0) {
      game.playerDied();
    }
  }

  void heal(int amount) {
    stats.hp = min(stats.hp + amount, stats.maxHp);
  }

  @override
  void onCollisionStart(Set<Vector2> points, PositionComponent other) {
    if (other is ItemDrop) {
      other.pickup(this);
    }
    if (other is FloorExit) {
      game.descendFloor();
    }
    super.onCollisionStart(points, other);
  }
}

enum PlayerState { idle, walk, attack }

Enemy Class

class Enemy extends SpriteAnimationComponent with CollisionCallbacks, HasGameRef<RoguelikeGame> {
  final String enemyType;
  final int level;
  int hp;
  final int maxHp;
  final int attack;
  final int exp;

  Enemy({
    required this.enemyType,
    required this.level,
    required this.maxHp,
    required this.attack,
    required this.exp,
    required Vector2 position,
  })  : hp = maxHp,
        super(position: position, size: Vector2.all(16), anchor: Anchor.center);

  factory Enemy.spawn(String type, Vector2 position, int floor) {
    final baseHp = 20 + floor * 5;
    final baseAttack = 5 + floor * 2;
    return Enemy(
      enemyType: type,
      level: floor,
      maxHp: baseHp,
      attack: baseAttack,
      exp: 10 + floor * 5,
      position: position,
    );
  }

  @override
  Future<void> onLoad() async {
    animation = await game.loadSpriteAnimation(
      'enemies/$enemyType.png',
      SpriteAnimationData.sequenced(amount: 4, stepTime: 0.15, textureSize: Vector2.all(16)),
    );
    add(CircleHitbox(radius: 6));
  }

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

    // Simple AI: move towards player
    final player = game.player;
    final dist = position.distanceTo(player.position);

    if (dist < 100 && dist > 20) {
      final dir = (player.position - position).normalized();
      position += dir * 30 * dt;
    } else if (dist <= 20) {
      // Attack player
      _tryAttack();
    }
  }

  double _attackCooldown = 0;
  void _tryAttack() {
    if (_attackCooldown > 0) return;
    _attackCooldown = 1.0;
    game.player.takeDamage(attack);
  }

  void takeDamage(int damage) {
    hp -= damage;

    // Damage number
    add(FloatingText('-$damage', Colors.red));

    if (hp <= 0) {
      _die();
    }
  }

  void _die() {
    // Grant exp
    game.player.stats.exp += exp;

    // Maybe drop loot
    if (Random().nextDouble() < 0.3) {
      final itemId = game.lootTable.roll(SeededRandom(), level);
      game.world.add(ItemDrop(itemId: itemId, position: position));
    }

    removeFromParent();
  }
}

Meta Progression

class MetaProgress {
  int totalGold = 0;
  int totalRuns = 0;
  int highestFloor = 0;

  // Upgrades
  int hpUpgrade = 0;
  int attackUpgrade = 0;
  int defenseUpgrade = 0;

  int getUpgradeCost(String type) {
    final level = switch (type) {
      'hp' => hpUpgrade,
      'attack' => attackUpgrade,
      'defense' => defenseUpgrade,
      _ => 0,
    };
    return 100 * (level + 1);
  }

  bool buyUpgrade(String type) {
    final cost = getUpgradeCost(type);
    if (totalGold < cost) return false;

    totalGold -= cost;
    switch (type) {
      case 'hp':
        hpUpgrade++;
      case 'attack':
        attackUpgrade++;
      case 'defense':
        defenseUpgrade++;
    }
    save();
    return true;
  }

  Future<void> save() async {
    final prefs = await SharedPreferences.getInstance();
    await prefs.setInt('meta_gold', totalGold);
    await prefs.setInt('meta_runs', totalRuns);
    await prefs.setInt('meta_floor', highestFloor);
    await prefs.setInt('upgrade_hp', hpUpgrade);
    await prefs.setInt('upgrade_attack', attackUpgrade);
    await prefs.setInt('upgrade_defense', defenseUpgrade);
  }

  Future<void> load() async {
    final prefs = await SharedPreferences.getInstance();
    totalGold = prefs.getInt('meta_gold') ?? 0;
    totalRuns = prefs.getInt('meta_runs') ?? 0;
    highestFloor = prefs.getInt('meta_floor') ?? 0;
    hpUpgrade = prefs.getInt('upgrade_hp') ?? 0;
    attackUpgrade = prefs.getInt('upgrade_attack') ?? 0;
    defenseUpgrade = prefs.getInt('upgrade_defense') ?? 0;
  }
}

Mini-Map

class MiniMap extends PositionComponent with HasGameRef<RoguelikeGame> {
  static const double scale = 0.1;

  @override
  void render(Canvas canvas) {
    final dungeon = game.floorManager.currentDungeon;
    if (dungeon == null) return;

    // Background
    canvas.drawRect(
      Rect.fromLTWH(0, 0, dungeon.width * scale, dungeon.height * scale),
      Paint()..color = Colors.black.withOpacity(0.7),
    );

    // Rooms
    for (int y = 0; y < dungeon.height; y++) {
      for (int x = 0; x < dungeon.width; x++) {
        if (dungeon.grid[y][x] > 0) {
          canvas.drawRect(
            Rect.fromLTWH(x * scale, y * scale, scale, scale),
            Paint()..color = Colors.grey,
          );
        }
      }
    }

    // Player
    final playerPos = game.player.position / 16 * scale;
    canvas.drawCircle(
      Offset(playerPos.x, playerPos.y),
      2,
      Paint()..color = Colors.green,
    );

    // Exit
    final exitPos = dungeon.exitPoint * scale;
    canvas.drawRect(
      Rect.fromLTWH(exitPos.x - 1, exitPos.y - 1, 3, 3),
      Paint()..color = Colors.yellow,
    );
  }
}

RPG Game Template

Project Structure

lib/
├── main.dart
├── game/
│   ├── rpg_game.dart
│   └── game_state.dart
├── player/
│   ├── player.dart
│   └── player_stats.dart
├── enemies/
│   ├── enemy.dart
│   └── enemy_ai.dart
├── combat/
│   ├── combat_system.dart
│   └── turn_manager.dart
├── world/
│   ├── world_map.dart
│   └── npc.dart
└── ui/
    ├── hud.dart
    ├── dialog_box.dart
    └── menu.dart

Main Entry Point

import 'package:flame/game.dart';
import 'package:flutter/material.dart';

void main() {
  runApp(
    GameWidget<RpgGame>(
      game: RpgGame(),
      overlayBuilderMap: {
        'hud': (_, game) => GameHUD(game: game),
        'dialog': (_, game) => DialogOverlay(game: game),
        'menu': (_, game) => GameMenu(game: game),
        'combat': (_, game) => CombatUI(game: game),
      },
      initialActiveOverlays: const ['hud'],
    ),
  );
}

Core Game Class

class RpgGame extends FlameGame with HasCollisionDetection {
  late Player player;
  late WorldMap currentMap;
  late DialogueManager dialogueManager;
  late QuestManager questManager;
  late InventoryManager inventory;
  late CombatSystem combat;

  GameMode mode = GameMode.exploration;

  @override
  Future<void> onLoad() async {
    camera.viewfinder.anchor = Anchor.center;

    // Initialize systems
    dialogueManager = DialogueManager();
    questManager = QuestManager();
    inventory = InventoryManager();
    combat = CombatSystem();

    addAll([dialogueManager, questManager, inventory, combat]);

    // Load initial map
    await loadMap('town_start');

    // Create player
    player = Player(position: Vector2(200, 200));
    world.add(player);

    camera.follow(player);
  }

  Future<void> loadMap(String mapId) async {
    // Clear current map
    world.children.whereType<MapComponent>().forEach((c) => c.removeFromParent());

    currentMap = await WorldMap.load(mapId);
    world.add(currentMap);

    // Spawn NPCs
    for (final npcData in currentMap.npcs) {
      world.add(Npc.fromData(npcData));
    }
  }

  void startCombat(List<Enemy> enemies) {
    mode = GameMode.combat;
    combat.start(player, enemies);
    overlays.add('combat');
  }

  void endCombat() {
    mode = GameMode.exploration;
    overlays.remove('combat');
  }

  void showDialog(String dialogueId) {
    dialogueManager.startDialogue(dialogueId);
    overlays.add('dialog');
  }

  void hideDialog() {
    overlays.remove('dialog');
  }
}

enum GameMode { exploration, combat, dialogue, menu }

Player Class

class Player extends SpriteAnimationGroupComponent<PlayerState>
    with HasGameRef<RpgGame>, CollisionCallbacks, KeyboardHandler {

  static const double speed = 150;

  final PlayerStats stats = PlayerStats();
  Vector2 velocity = Vector2.zero();
  Vector2 _inputDirection = Vector2.zero();

  Player({required Vector2 position})
      : super(
          position: position,
          size: Vector2.all(48),
          anchor: Anchor.center,
        );

  @override
  Future<void> onLoad() async {
    animations = {
      PlayerState.idleDown: await _loadAnim('idle_down', 4),
      PlayerState.idleUp: await _loadAnim('idle_up', 4),
      PlayerState.idleLeft: await _loadAnim('idle_left', 4),
      PlayerState.idleRight: await _loadAnim('idle_right', 4),
      PlayerState.walkDown: await _loadAnim('walk_down', 6),
      PlayerState.walkUp: await _loadAnim('walk_up', 6),
      PlayerState.walkLeft: await _loadAnim('walk_left', 6),
      PlayerState.walkRight: await _loadAnim('walk_right', 6),
    };
    current = PlayerState.idleDown;

    add(RectangleHitbox(size: size * 0.6, position: size * 0.2));
  }

  @override
  bool onKeyEvent(KeyEvent event, Set<LogicalKeyboardKey> keys) {
    if (game.mode != GameMode.exploration) return false;

    _inputDirection = Vector2.zero();
    if (keys.contains(LogicalKeyboardKey.keyW) ||
        keys.contains(LogicalKeyboardKey.arrowUp)) {
      _inputDirection.y = -1;
    }
    if (keys.contains(LogicalKeyboardKey.keyS) ||
        keys.contains(LogicalKeyboardKey.arrowDown)) {
      _inputDirection.y = 1;
    }
    if (keys.contains(LogicalKeyboardKey.keyA) ||
        keys.contains(LogicalKeyboardKey.arrowLeft)) {
      _inputDirection.x = -1;
    }
    if (keys.contains(LogicalKeyboardKey.keyD) ||
        keys.contains(LogicalKeyboardKey.arrowRight)) {
      _inputDirection.x = 1;
    }

    if (_inputDirection.length > 0) {
      _inputDirection.normalize();
    }

    // Interaction key
    if (keys.contains(LogicalKeyboardKey.keyE) ||
        keys.contains(LogicalKeyboardKey.space)) {
      _tryInteract();
    }

    return true;
  }

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

    if (game.mode == GameMode.exploration) {
      velocity = _inputDirection * speed;
      position += velocity * dt;
      _updateAnimation();
    }
  }

  void _updateAnimation() {
    if (velocity.length < 1) {
      // Idle
      current = switch (current) {
        PlayerState.walkDown => PlayerState.idleDown,
        PlayerState.walkUp => PlayerState.idleUp,
        PlayerState.walkLeft => PlayerState.idleLeft,
        PlayerState.walkRight => PlayerState.idleRight,
        _ => current,
      };
    } else {
      // Walking
      if (velocity.y > 0) {
        current = PlayerState.walkDown;
      } else if (velocity.y < 0) {
        current = PlayerState.walkUp;
      } else if (velocity.x < 0) {
        current = PlayerState.walkLeft;
      } else {
        current = PlayerState.walkRight;
      }
    }
  }

  void _tryInteract() {
    // Check for nearby NPCs
    final npcs = game.world.children.whereType<Npc>();
    for (final npc in npcs) {
      if (position.distanceTo(npc.position) < 50) {
        npc.interact();
        break;
      }
    }
  }

  @override
  void onCollisionStart(Set<Vector2> points, PositionComponent other) {
    if (other is Enemy && game.mode == GameMode.exploration) {
      game.startCombat([other]);
    }
    super.onCollisionStart(points, other);
  }
}

enum PlayerState {
  idleDown, idleUp, idleLeft, idleRight,
  walkDown, walkUp, walkLeft, walkRight,
}

NPC Class

class Npc extends SpriteComponent with TapCallbacks, HasGameRef<RpgGame> {
  final String npcId;
  final String dialogueId;
  final String? questId;

  Npc({
    required this.npcId,
    required this.dialogueId,
    this.questId,
    required Vector2 position,
  }) : super(position: position, size: Vector2.all(48), anchor: Anchor.center);

  @override
  void onTapDown(TapDownEvent event) {
    interact();
  }

  void interact() {
    // Check if has quest to give
    if (questId != null) {
      final quest = game.questManager.getQuest(questId!);
      if (quest?.status == QuestStatus.available) {
        game.questManager.startQuest(questId!);
      }
    }

    // Start dialogue
    game.showDialog(dialogueId);
  }
}

Combat System (Turn-based)

class CombatSystem extends Component with HasGameRef<RpgGame> {
  final List<CombatParticipant> turnOrder = [];
  int currentTurnIndex = 0;
  bool isPlayerTurn = false;

  CombatParticipant get currentTurn => turnOrder[currentTurnIndex];

  void start(Player player, List<Enemy> enemies) {
    turnOrder.clear();
    turnOrder.add(CombatParticipant.player(player));
    for (final enemy in enemies) {
      turnOrder.add(CombatParticipant.enemy(enemy));
    }

    // Sort by speed
    turnOrder.sort((a, b) => b.speed.compareTo(a.speed));
    currentTurnIndex = 0;
    _startTurn();
  }

  void _startTurn() {
    isPlayerTurn = currentTurn.isPlayer;

    if (!isPlayerTurn) {
      // AI takes action
      Future.delayed(const Duration(milliseconds: 500), () {
        _executeAITurn();
      });
    }
  }

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

  void _executeAITurn() {
    // Simple AI: attack player
    final player = turnOrder.firstWhere((p) => p.isPlayer);
    _executeAction(CombatAction.attack(currentTurn, player));
    _nextTurn();
  }

  void _executeAction(CombatAction action) {
    switch (action.type) {
      case ActionType.attack:
        final damage = DamageCalculator.calculate(
          attacker: action.actor.stats,
          defender: action.target!.stats,
          baseDamage: 10,
        );
        action.target!.takeDamage(damage.damage);
        break;
      // Handle other actions...
    }
  }

  void _nextTurn() {
    // Check for combat end
    if (_checkCombatEnd()) return;

    do {
      currentTurnIndex = (currentTurnIndex + 1) % turnOrder.length;
    } while (currentTurn.isDefeated);

    _startTurn();
  }

  bool _checkCombatEnd() {
    final playerDefeated = turnOrder.where((p) => p.isPlayer).every((p) => p.isDefeated);
    final enemiesDefeated = turnOrder.where((p) => !p.isPlayer).every((p) => p.isDefeated);

    if (playerDefeated) {
      game.endCombat();
      // Game over
      return true;
    }
    if (enemiesDefeated) {
      // Victory - grant rewards
      _grantRewards();
      game.endCombat();
      return true;
    }
    return false;
  }
}

HUD Overlay

class GameHUD extends StatelessWidget {
  final RpgGame game;

  const GameHUD({required this.game});

  @override
  Widget build(BuildContext context) {
    return SafeArea(
      child: Padding(
        padding: const EdgeInsets.all(16),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            // Health bar
            _buildHealthBar(),
            const SizedBox(height: 8),
            // Mana bar
            _buildManaBar(),
            const Spacer(),
            // Quest tracker
            _buildQuestTracker(),
          ],
        ),
      ),
    );
  }

  Widget _buildHealthBar() {
    final stats = game.player.stats;
    return Row(
      children: [
        const Icon(Icons.favorite, color: Colors.red, size: 20),
        const SizedBox(width: 8),
        Expanded(
          child: LinearProgressIndicator(
            value: stats.hp / stats.maxHp,
            backgroundColor: Colors.grey[800],
            valueColor: const AlwaysStoppedAnimation(Colors.red),
          ),
        ),
        const SizedBox(width: 8),
        Text('${stats.hp}/${stats.maxHp}', style: const TextStyle(color: Colors.white)),
      ],
    );
  }
}