playbooks

home / skills / miles990 / flame_demo_game / flame-core

flame-core skill

/skills/flame-core

This skill helps you implement Flame Engine core fundamentals including components, input, collision, camera, animation, and scenes.

npx playbooks add skill miles990/flame_demo_game --skill flame-core

Review the files below or copy the command above to add this skill to your agents.

Files (11)
SKILL.md
2.7 KB
---
name: flame-core
description: Flame Engine core fundamentals - components, input, collision, camera, animation, scenes
domain: game-development
version: 2.0.0
tags: [flame, flutter, dart, 2d-games, game-engine]
---

# Flame Core Fundamentals

Flame Engine 核心基礎，涵蓋組件系統、輸入處理、碰撞檢測、相機、動畫與場景管理。

## Quick Start

```bash
flutter create my_game && cd my_game
flutter pub add flame
flutter pub add flame_audio       # Optional
flutter pub add flame_tiled       # Optional
```

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

void main() => runApp(GameWidget(game: MyGame()));

class MyGame extends FlameGame with HasCollisionDetection {
  @override
  Future<void> onLoad() async {
    camera.viewfinder.anchor = Anchor.topLeft;
  }
}
```

## Reference Index

| Topic | File | Description |
|-------|------|-------------|
| **Components** | `references/components.md` | 組件生命週期、類型、最佳實踐 |
| **Input** | `references/input.md` | 觸控、鍵盤、搖桿輸入處理 |
| **Collision** | `references/collision.md` | 碰撞檢測、Hitbox 類型 |
| **Camera** | `references/camera.md` | 相機設置、跟隨、HUD |
| **Animation** | `references/animation.md` | 精靈動畫、Effects 系統 |
| **Scenes** | `references/scenes.md` | RouterComponent、Overlays、UI |
| **Audio** | `references/audio.md` | 音效、背景音樂、AudioPool |
| **Particles** | `references/particles.md` | 粒子系統、特效、爆炸效果 |
| **Performance** | `references/performance.md` | 效能優化、最佳實踐、常見問題 |
| **Debug** | `references/debug.md` | 除錯模式、日誌、效能監控 |

## AI Usage Guide

```
需要了解組件系統？ → Read references/components.md
需要處理輸入？     → Read references/input.md
需要碰撞檢測？     → Read references/collision.md
需要相機設置？     → Read references/camera.md
需要動畫效果？     → Read references/animation.md
需要場景管理/UI？  → Read references/scenes.md
需要音效/音樂？    → Read references/audio.md
需要粒子特效？     → Read references/particles.md
需要效能優化？     → Read references/performance.md
需要除錯/日誌？    → Read references/debug.md
```

## Component Types Quick Reference

| Type | Use Case |
|------|----------|
| `Component` | Logic only |
| `PositionComponent` | Has position/size |
| `SpriteComponent` | Static image |
| `SpriteAnimationComponent` | Animated sprite |
| `SpriteAnimationGroupComponent` | Multiple states |

## Related Skills

- `flame-systems` - 14 個遊戲系統（任務、對話、背包等）
- `flame-templates` - 遊戲類型模板（RPG、平台、Roguelike）

Overview

This skill documents Flame Engine core fundamentals for building 2D games in Flutter. It covers the component system, input handling, collision detection, camera setup, animation, and scene management. The material helps developers structure game logic, render sprites, and manage interactions and UI overlays.

How this skill works

The skill explains how Flame organizes game objects as Components and PositionComponents, and how lifecycle methods drive load, update, and render. It describes input layers (touch, keyboard, gamepad), Hitbox-based collision detection with HasCollisionDetection, and camera features like viewfinder anchoring and follow behavior. It also details sprite animation types, animation groups, scene routing via RouterComponent, and overlay UI management.

When to use it

  • Starting a new Flame game project and choosing component types
  • Implementing player controls, touch or keyboard input, or gamepad support
  • Adding collision detection and hitboxes for physics or interactions
  • Setting up camera behavior, HUDs, and viewports
  • Creating sprite animations, effects, or animation state groups
  • Organizing scenes, menus, and overlays with RouterComponent

Best practices

  • Prefer small, focused Components to keep lifecycle and updates simple
  • Use PositionComponent subclasses for renderable objects and separate logic-only Components
  • Define clear Hitbox shapes and layers to limit collision checks for performance
  • Keep camera logic separate from gameplay logic; use the viewfinder to control anchoring and follow targets
  • Use SpriteAnimationGroupComponent for state-driven animations to simplify state transitions
  • Profile performance early and batch static graphics where possible

Example use cases

  • Player entity built from PositionComponent with SpriteAnimationComponent and Hitbox for collisions
  • Top-down camera following player with a fixed HUD overlay using Camera.viewfinder and overlays
  • Menu and scene flow managed by RouterComponent with separate Components for each screen
  • Touch and keyboard input handlers added to game for cross-platform controls
  • Particle explosion effect triggered on collision using the Particles system

FAQ

Do I need to use all component types?

No. Choose the simplest type that fits your needs: use Component for logic-only systems and PositionComponent or Sprite-based components for things that render or have position.

How do I reduce collision overhead?

Use collision layers, coarse-grained hitboxes for broad-phase checks, and limit collision checks to relevant components to improve performance.