Flame Engine

https://docs.flame-engine.org/latest
Admin
Flame Engine is a powerful 2D game engine built on Flutter, providing a complete set of tools and...
Tokens:352,865
Snippets:2,891
Trust Score:8.7
Update:1 week ago
Show doc for...
Tokens:
Raw
### Example Yarn file with comments, tags, commands, and nodes

Source: https://docs.flame-engine.org/latest/other_modules/jenny/language/language.html

Shows a complete .yarn file example with a comment, a file-level tag, two <<declare>> commands, and a node. Comments start with // and are ignored by Jenny. File-level tags start with # and are not interpreted. Only <<declare>> and <<character>> commands are allowed at the root level.

```yarn
// This is a comment
// The line below, however, is a tag:
# Chapter 1d

<<declare $visited_graveyard = false>>
<<declare $money = 25>>  // is this too much?

title: Start
---
// Node content
===
```

--------------------------------

### Dartdoc method documentation example

Source: https://docs.flame-engine.org/latest/development/style_guide.html

Method documentation should start with a verb in present simple tense, include a paragraph break after the first sentence, and mention pre- and post-conditions. This example shows the recommended format for a method that adds a child to a container.

```dart
/// Adds a new [child] into the container, and becomes the owner of that
/// child.
///
/// The child will be disposed of when this container is destroyed.
/// It is an error to try to add a child that already belongs to another
/// container.
void addChild(T child) { ... }

```

--------------------------------

### Melos Command: doc-setup

Source: https://docs.flame-engine.org/latest/development/documentation.html

Installs the remaining documentation requirements. Must be run after having Flutter, Melos, and Python 3.8+ installed.

```bash
melos run doc-setup
```

--------------------------------

### Expanded <<give>> command examples

Source: https://docs.flame-engine.org/latest/other_modules/jenny/runtime/command_storage.html

Three examples showing how the <<give>> command is parsed after variable substitution, each with three arguments.

```yarn
<<give 100 gold TraderJoe>>
<<give 5 potion_of_healing TraderJoe>>
<<give 1 "Sword of Darkness" TraderJoe>>

```

--------------------------------

### RouterComponent setup with routes

Source: https://docs.flame-engine.org/latest/flame/router.html

Example of setting up a RouterComponent in a FlameGame, defining routes for different pages and setting the initial route. The routes map includes a regular Route, WorldRoutes with optional maintainState, and a PauseRoute. This is the main setup for using the router in a Flame game.

```dart
import 'package:flame/components.dart';
import 'package:flame/effects.dart';
import 'package:flame/events.dart';
import 'package:flame/game.dart';
import 'package:flame/geometry.dart';
import 'package:flame/rendering.dart';
import 'package:flutter/rendering.dart';

class RouterGame extends FlameGame {
  late final RouterComponent router;

  @override
  Future<void> onLoad() async {
    add(
      router = RouterComponent(
        routes: {
          'home': Route(StartPage.new),
          'level1': WorldRoute(Level1Page.new),
          'level2': WorldRoute(Level2Page.new, maintainState: false),
          'pause': PauseRoute(),
        },
        initialRoute: 'home',
      ),
    );
  }
}
```

--------------------------------

### Full node example with dialogue lines

Source: https://docs.flame-engine.org/latest/other_modules/jenny/language/nodes.html

Complete node example showing a header with a title and custom tag, and a body containing multiple dialogue lines.

```plaintext
title: Gloomy_Morning
camera_zoom: 2
---
You  : Good morning!
Guard: You call this good? 'Tis as crappy as could be
You  : Why, what happened?
Guard: Don't you see the fog? Chills me through to the bones
You  : Sorry to hear that... 
You  : So, can I pass?
Guard: Can I get some exercise cutting you into pieces? Maybe that'll warm me up!
You  : Ok, I think I'll be going. Hope you feel better soon!
===

```

--------------------------------

### ColorQuiz Example Using <<set>>

Source: https://docs.flame-engine.org/latest/other_modules/jenny/language/commands/set.html

A complete example showing how to use <<set>> to update a variable based on user choices in a quiz. It demonstrates both 'to' and '=' assignment forms, and a modifying assignment (+=) for affinity. The example includes a <<jump>> to restart the quiz.

```plaintext
<<declare $favorite_color as String>>

title: ColorQuiz
---
What is your favorite color?
-> White
   <<set $favorite_color to "White">>
-> Red
   <<set $favorite_color to "Red">>
-> Yellow
   <<set $favorite_color = "Yellow">>
-> Blue
   Oh, Nice! Which shade of blue?
   -> Azure
   -> Cerulean
   -> Lapis Lazuli
   Umm, I don't know how to spell that. I'll just put you down as "blue".
   <<set $favorite_color = "Blue">>
-> Black
   <<set $favorite_color = "Black">>
   That's mine too!
   <<set $affinity += 3>>
-> Prefer not to tell
   Aww... Maybe if I ask again really nicely?
   <<jump ColorQuiz>>
===
```

--------------------------------

### Complete AudioPool example in FlameGame

Source: https://docs.flame-engine.org/latest/bridge_packages/flame_audio/audio_pool.html

A complete example showing how to create and use AudioPools in a Flame game, including loading sounds, playing them, and cleaning up.

```dart
import 'package:flame/game.dart';
import 'package:flame_audio/flame_audio.dart';

class MyGame extends FlameGame {
  late AudioPool laserSound;
  late AudioPool explosionSound;

  @override
  Future<void> onLoad() async {
    // Load sound effects into audio pools
    laserSound = await FlameAudio.createPool(
      'laser.mp3',
      minPlayers: 3,
      maxPlayers: 6,
    );

    explosionSound = await FlameAudio.createPool(
      'explosion.mp3',
      minPlayers: 2,
      maxPlayers: 4,
    );
  }

  void fireLaser() async {
    // Play the laser sound effect - can be called rapidly
    final stop = await laserSound.start();

    // If you need to stop the sound early:
    // await stop();
  }

  void enemyDestroyed() async {
    // Play explosion sound effect
    await explosionSound.start(volume: 0.7);
  }

  @override
  Future<void> onRemove() async {
    await super.onRemove();

    // Clean up resources when the game component is removed
    await laserSound.dispose();
    await explosionSound.dispose();
  }
}

```

--------------------------------

### ValueRoute example with RouterComponent and pushAndWait

Source: https://docs.flame-engine.org/latest/flame/router.html

Complete example for the ValueRoute documentation page. It shows a FlameGame with a RouterComponent, a HomePage that pushes a RateRoute via pushAndWait, and a RateRoute that completes with a value. The example includes a DialogBackground and a Star component that toggles active state on tap. The code is from value_route.dart and uses the doc_flame_examples router helper.

```dart
import 'dart:math';
import 'dart:ui';

import 'package:doc_flame_examples/router.dart';
import 'package:flame/components.dart';
import 'package:flame/events.dart';
import 'package:flame/game.dart';
import 'package:flame/geometry.dart';

class ValueRouteExample extends FlameGame {
  late final RouterComponent router;

  @override
  Future<void> onLoad() async {
    router = RouterComponent(
      routes: {'home': Route(HomePage.new)},
      initialRoute: 'home',
    );
    add(router);
  }
}

class HomePage extends Component with HasGameReference<ValueRouteExample> {
  @override
  Future<void> onLoad() async {
    add(
      RoundedButton(
        text: 'Rate me',
        position: game.size / 2,
        action: () async {
          final score = await game.router.pushAndWait(RateRoute());
          firstChild<TextComponent>()!.text = 'Score: $score';
        },
        color: const Color(0xff758f9a),
        borderColor: const Color(0xff60d5ff),
      ),
    );
    add(
      TextComponent(
        text: 'Score: –',
        anchor: Anchor.topCenter,
        position: game.size / 2 + Vector2(0, 30),
        scale: Vector2.all(0.7),
      ),
    );
  }
}

class RateRoute extends ValueRoute<int>
    with HasGameReference<ValueRouteExample> {
  RateRoute() : super(value: -1, transparent: true);

  @override
  Component build() {
    final size = Vector2(250, 130);
    const radius = 18.0;
    final starGap = (size.x - 5 * 2 * radius) / 6;
    return DialogBackground(
      position: game.size / 2,
      size: size,
      children: [
        RoundedButton(
          text: 'Ok',
          position: Vector2(size.x / 2, 100),
          action: () {
            completeWith(
              descendants().where((c) => c is Star && c.active).length,
            );
          },
          color: const Color(0xFFFFFFFF),
          borderColor: const Color(0xFF000000),
        ),
        for (var i = 0; i < 5; i++)
          Star(
            value: i + 1,
            radius: radius,
            position: Vector2(starGap * (i + 1) + radius * (2 * i + 1), 40),
          ),
      ],
    );
  }
}

class DialogBackground extends RectangleComponent with TapCallbacks {
  DialogBackground({super.position, super.size, super.children})
    : super(
        anchor: Anchor.center,
        paint: Paint()..color = const Color(0xee858585),
      );
}

class Star extends PositionComponent with TapCallbacks {
  Star({required this.value, required this.radius, super.position})
    : super(size: Vector2.all(2 * radius), anchor: Anchor.center);

  final int value;
  final double radius;
  final Path path = Path();
  final Paint borderPaint = Paint()
    ..style = PaintingStyle.stroke
    ..color = const Color(0xffffe395)
    ..strokeWidth = 2;
  final Paint fillPaint = Paint()..color = const Color(0xffffe395);
  bool active = false;

  @override
  Future<void> onLoad() async {
    path.moveTo(radius, 0);
    for (var i = 0; i < 5; i++) {
      path.lineTo(
        radius + 0.6 * radius * sin(tau / 5 * (i + 0.5)),
        radius - 0.6 * radius * cos(tau / 5 * (i + 0.5)),
      );
      path.lineTo(
        radius + radius * sin(tau / 5 * (i + 1)),
        radius - radius * cos(tau / 5 * (i + 1)),
      );
    }
    path.close();
  }

  @override
  void render(Canvas canvas) {
    if (active) {
      canvas.drawPath(path, fillPaint);
    }
    canvas.drawPath(path, borderPaint);
  }

  @override
  void onTapDown(TapDownEvent event) {
    var on = true;
    for (final star in parent!.children.whereType<Star>()) {
      star.active = on;
      if (star == this) {
        on = false;
      }
    }
  }
}

```

--------------------------------

### Examples of declare statements

Source: https://docs.flame-engine.org/latest/other_modules/jenny/language/commands/declare.html

Multiple examples of `<<declare>>` statements with different types and expressions.

```yarn
<<declare $prefix = "Mr.">>
<<declare $gold = 100>>
<<declare $been_to_hell = false>>

<<declare $name as String>>
<<declare $distanceTraveled as Number>>

<<declare $birthDay = randomRange(1, 365) as Number>>
<<declare $vulgarity = GetObscenitySetting() as Bool>>

```

--------------------------------

### Install flame package

Source: https://docs.flame-engine.org/latest/README.html

Adds the flame package as a dependency in pubspec.yaml. Run flutter pub get afterwards to install it.

```bash
flutter pub add flame

```

--------------------------------

### SizeEffect.by example (size_by_effect.dart)

Source: https://docs.flame-engine.org/latest/flame/effects/size_effects.html

Full game example showing SizeEffect.by applied to an EmberPlayer on tap, toggling between two size offsets. Requires the component to implement SizeProvider.

```dart
import 'package:doc_flame_examples/ember.dart';
import 'package:flame/components.dart';
import 'package:flame/effects.dart';
import 'package:flame/game.dart';

class SizeByEffectGame extends FlameGame {
  bool reset = false;
  @override
  Future<void> onLoad() async {
    final ember = EmberPlayer(
      position: size / 2,
      size: Vector2(45, 40),
      onTap: (ember) {
        ember.add(
          SizeEffect.by(
            reset ? Vector2(-15, 30) : Vector2(15, -30),
            EffectController(duration: 0.75),
          ),
        );
        reset = !reset;
      },
    )..anchor = Anchor.center;

    add(ember);
  }
}

```

--------------------------------

### Simple FlameGame with custom World and SpriteComponent

Source: https://docs.flame-engine.org/latest/flame/game.html

Shows a minimal FlameGame setup: a SpriteComponent that loads a sprite, a World that adds it, and a main function that runs the game with GameWidget. Use this as a starting point for any Flame game.

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

/// A component that renders the crate sprite, with a 16 x 16 size.
class MyCrate extends SpriteComponent {
  MyCrate() : super(size: Vector2.all(16));

  @override
  Future<void> onLoad() async {
    sprite = await Sprite.load('crate.png');
  }
}

class MyWorld extends World {
  @override
  Future<void> onLoad() async {
    await add(MyCrate());
  }
}

void main() {
  final myGame = FlameGame(world: MyWorld());
  runApp(
    GameWidget(game: myGame),
  );
}

```

--------------------------------

### Custom Palette implementation example

Source: https://docs.flame-engine.org/latest/flame/rendering/palette.html

Shows a custom Palette class that defines static PaletteEntry constants for game colors, following the BasicPalette example. PaletteEntry provides color and paint members.

```dart
import 'dart:ui';

import 'package:flame/palette.dart';

class Palette {
  static PaletteEntry white = BasicPalette.white;

  static PaletteEntry toastBackground = PaletteEntry(Color(0xFFAC3232));
  static PaletteEntry toastText = PaletteEntry(Color(0xFFDA9A00));

  static PaletteEntry grey = PaletteEntry(Color(0xFF404040));
  static PaletteEntry green = PaletteEntry(Color(0xFF54a286));
}

```

--------------------------------

### Load assets with Flame's global loaders

Source: https://docs.flame-engine.org/latest/flame/structure.html

Example of loading audio, images, and a tile map in a FlameGame's onLoad method using FlameAudio, Flame.images, and TiledComponent. The files must be placed in the corresponding assets subdirectories as shown in the file structure example.

```dart
class MyGame extends FlameGame {
  @override
  Future<void> onLoad() async {
    await FlameAudio.play('explosion.mp3');

    // Load some images
    await Flame.images.load('player.png');
    await Flame.images.load('enemy.png');
    
    // Or load all images in your images folder
    await Flame.images.loadAllImages();

    final map1 = await TiledComponent.load('level.tmx', tileSize);
  }
}

```

--------------------------------

### PaintDecorator.tint example game

Source: https://docs.flame-engine.org/latest/flame/rendering/decorators.html

Full FlameGame example that cycles through tint effects on tap: adds tint(0x88FF0000), then replaces with green, blue, white, black, and finally removes the decorator.

```dart
import 'dart:ui';

import 'package:doc_flame_examples/flower.dart';
import 'package:flame/game.dart';
import 'package:flame/rendering.dart';

class DecoratorTintGame extends FlameGame {
  @override
  Future<void> onLoad() async {
    var step = 0;
    add(
      Flower(
        size: 100,
        position: canvasSize / 2,
        onTap: (flower) {
          final decorator = flower.decorator;
          step++;
          if (step == 1) {
            decorator.addLast(PaintDecorator.tint(const Color(0x88FF0000)));
          } else if (step == 2) {
            decorator.replaceLast(PaintDecorator.tint(const Color(0x8800FF00)));
          } else if (step == 3) {
            decorator.replaceLast(PaintDecorator.tint(const Color(0x88000088)));
          } else if (step == 4) {
            decorator.replaceLast(PaintDecorator.tint(const Color(0x66FFFFFF)));
          } else if (step == 5) {
            decorator.replaceLast(PaintDecorator.tint(const Color(0xAA000000)));
          } else {
            decorator.removeLast();
            step = 0;
          }
        },
      )..onTapUp(),
    );
  }
}

```

--------------------------------

### Example character declarations

Source: https://docs.flame-engine.org/latest/other_modules/jenny/language/commands/character.html

Three example declarations of the <<character>> command: one with a single alias, one with a full name and two aliases, and one with a full name and three aliases. Comments show how to document characters. After declaration, any alias can be used in scripts and refers to the same Character object.

```text
// A well-mannered seven-year-old girl, who nevertheless always gets into
// all kinds of zany adventures.
<<character Alice>>

// A magical cat known for his ability to grin majestically, and partially
// vanish. He is mad (by his own admission).
<<character "Cheshire Cat" Cat Cheshire>>

// A foul-tempered Queen, who is also a playing card. Described as
// "a blind fury", her favorite saying is "Off with their heads!".
// Not to be confused with Red Queen.
<<character "Queen of Hearts" Queen QoH QH>>
```

--------------------------------

### OpacityByEffect usage example (opacity_by_effect.dart)

Source: https://docs.flame-engine.org/latest/flame/effects/color_effects.html

Full game example showing how to apply OpacityEffect.by to an EmberPlayer on tap, toggling between increasing and decreasing opacity by 0.9. Requires the HasPaint mixin on the target component.

```dart
import 'package:doc_flame_examples/ember.dart';
import 'package:flame/components.dart';
import 'package:flame/effects.dart';
import 'package:flame/game.dart';

class OpacityByEffectGame extends FlameGame {
  bool reset = false;

  @override
  Future<void> onLoad() async {
    final ember = EmberPlayer(
      position: size / 2,
      size: size / 4,
      onTap: (ember) {
        ember.add(
          OpacityEffect.by(
            reset ? 0.9 : -0.9,
            EffectController(duration: 0.75),
          ),
        );
        reset = !reset;
      },
    )..anchor = Anchor.center;

    add(ember);
  }
}

```

--------------------------------

### SpriteWidget

Source: https://docs.flame-engine.org/latest/flame/other/widgets.html

Documentation for the SpriteWidget widget, including its constructor parameters and usage example.

```APIDOC
## SpriteWidget

### Description
A widget used to display a Sprite inside a widget tree.

### Constructor
```dart
SpriteWidget({
  required Sprite sprite,
  Anchor anchor = Anchor.center,
})
```

### Parameters
- **sprite** (Sprite) - Required - The sprite to display.
- **anchor** (Anchor) - Optional - The anchor point of the sprite. Defaults to `Anchor.center`.

### Example
```dart
SpriteWidget(
  sprite: yourSprite,
  anchor: Anchor.center,
)
```
```

--------------------------------

### PaintDecorator.blur example game

Source: https://docs.flame-engine.org/latest/flame/rendering/decorators.html

Full FlameGame example that cycles through blur effects on tap: adds blur(3.0), replaces with blur(5.0), then blur(0.0, 20.0), and finally removes the decorator.

```dart
import 'package:doc_flame_examples/flower.dart';
import 'package:flame/game.dart';
import 'package:flame/rendering.dart';

class DecoratorBlurGame extends FlameGame {
  @override
  Future<void> onLoad() async {
    var step = 0;
    add(
      Flower(
        size: 100,
        position: canvasSize / 2,
        onTap: (flower) {
          final decorator = flower.decorator;
          step++;
          if (step == 1) {
            decorator.addLast(PaintDecorator.blur(3.0));
          } else if (step == 2) {
            decorator.replaceLast(PaintDecorator.blur(5.0));
          } else if (step == 3) {
            decorator.replaceLast(PaintDecorator.blur(0.0, 20.0));
          } else {
            decorator.replaceLast(null);
            step = 0;
          }
        },
      )..onTapUp(),
    );
  }
}

```

--------------------------------

### ScaleEffect.by example (scale_by_effect.dart)

Source: https://docs.flame-engine.org/latest/flame/effects/scale_effects.html

Full example of using ScaleEffect.by to grow a component by 50% on tap. The effect toggles between scaling up and down, and uses a hold flag to prevent overlapping effects.

```dart
import 'package:doc_flame_examples/flower.dart';
import 'package:flame/effects.dart';
import 'package:flame/game.dart';

class ScaleByEffectGame extends FlameGame {
  bool reverse = false;
  bool hold = false;
  @override
  Future<void> onLoad() async {
    final flower = Flower(
      size: 60,
      position: canvasSize / 2,
      onTap: (flower) {
        if (hold) {
          return;
        }
        hold = true;
        flower.add(
          ScaleEffect.by(
            reverse ? Vector2.all(1 / 1.5) : Vector2.all(1.5),
            EffectController(duration: 0.3),
            onComplete: () => hold = false,
          ),
        );
        reverse = !reverse;
      },
    );
    add(flower);
  }
}

```

```dart
final effect = ScaleEffect.by(
  Vector2.all(1.5),
  EffectController(duration: 0.3),
);

```

--------------------------------

### PaintDecorator.grayscale example game

Source: https://docs.flame-engine.org/latest/flame/rendering/decorators.html

Full FlameGame example that cycles through grayscale effects on tap: adds grayscale(), then replaces with opacity 0.5, 0.2, 0.1, and finally removes the decorator.

```dart
import 'package:doc_flame_examples/flower.dart';
import 'package:flame/game.dart';
import 'package:flame/rendering.dart';

class DecoratorGrayscaleGame extends FlameGame {
  @override
  Future<void> onLoad() async {
    var step = 0;
    add(
      Flower(
        size: 100,
        position: canvasSize / 2,
        onTap: (flower) {
          final decorator = flower.decorator;
          step++;
          if (step == 1) {
            decorator.addLast(PaintDecorator.grayscale());
          } else if (step == 2) {
            decorator.replaceLast(PaintDecorator.grayscale(opacity: 0.5));
          } else if (step == 3) {
            decorator.replaceLast(PaintDecorator.grayscale(opacity: 0.2));
          } else if (step == 4) {
            decorator.replaceLast(PaintDecorator.grayscale(opacity: 0.1));
          } else {
            decorator.removeLast();
            step = 0;
          }
        },
      )..onTapUp(),
    );
  }
}

```

--------------------------------

### SpriteButton

Source: https://docs.flame-engine.org/latest/flame/other/widgets.html

Documentation for the SpriteButton widget, including its constructor parameters and usage example.

```APIDOC
## SpriteButton

### Description
A simple widget that creates a button based on Flame sprites. Useful for creating non-default looking buttons, especially when the desired look is easier to achieve by drawing the button in a graphics editor.

### Constructor
```dart
SpriteButton({
  required VoidCallback? onPressed,
  required Widget label,
  required Sprite sprite,
  required Sprite pressedSprite,
  Sprite? disabledSprite,
  double? height,
  double? width,
})
```

### Parameters
- **onPressed** (VoidCallback?) - Required - Callback when the button is pressed.
- **label** (Widget) - Required - The label widget to display on the button.
- **sprite** (Sprite) - Required - The sprite to display for the button.
- **pressedSprite** (Sprite) - Required - The sprite to display when the button is pressed.
- **disabledSprite** (Sprite) - Optional - The sprite to display when the button is disabled (when `onPressed` is null).
- **height** (double) - Optional - The height of the button.
- **width** (double) - Optional - The width of the button.

### Example
```dart
SpriteButton(
  onPressed: () {
    print('Pressed');
  },
  label: const Text('Sprite Button', style: const TextStyle(color: const Color(0xFF5D275D))),
  sprite: _spriteButton,
  pressedSprite: _pressedSprite,
  // Optional, will be shown when onPressed in null.
  disabledSprite: _disabledSprite,
  height: _height,
  width: _width,
)
```
```

--------------------------------

### Shadow3DDecorator game example (decorator_shadow3d.dart)

Source: https://docs.flame-engine.org/latest/flame/rendering/decorators.html

Full example of a FlameGame using Shadow3DDecorator. The decorator's properties (xShift, opacity, yScale, blur, angle, ascent) are changed on tap to demonstrate different shadow effects. Includes a Grid component that draws a background grid.

```dart
import 'dart:ui';

import 'package:doc_flame_examples/flower.dart';
import 'package:flame/components.dart';
import 'package:flame/game.dart';
import 'package:flame/rendering.dart';

class DecoratorShadowGame extends FlameGame {
  @override
  Color backgroundColor() => const Color(0xFFC7C7C7);

  @override
  Future<void> onLoad() async {
    final decorator = Shadow3DDecorator(base: Vector2(0, 100));
    var step = 0;
    add(Grid());
    add(
      Flower(
        size: 100,
        position: canvasSize / 2,
        decorator: decorator,
        onTap: (flower) {
          step++;
          if (step == 1) {
            decorator.xShift = 200;
            decorator.opacity = 0.5;
          } else if (step == 2) {
            decorator.xShift = 400;
            decorator.yScale = 3;
            decorator.blur = 1;
          } else if (step == 3) {
            decorator.angle = 1.7;
            decorator.blur = 2;
          } else if (step == 4) {
            decorator.ascent = 20;
            decorator.angle = 1.7;
            decorator.blur = 2;
            flower.y -= 20;
          } else {
            decorator.ascent = 0;
            decorator.xShift = 0;
            decorator.yScale = 1;
            decorator.angle = -1.4;
            decorator.opacity = 0.8;
            decorator.blur = 0;
            flower.y += 20;
            step = 0;
          }
        },
      )..onTapUp(),
    );
  }
}

class Grid extends Component {
  final paint = Paint()
    ..color = const Color(0xffa9a9a9)
    ..style = PaintingStyle.stroke
    ..strokeWidth = 1;
  @override
  void render(Canvas canvas) {
    for (var i = 0; i < 50; i++) {
      canvas.drawLine(Offset(0, i * 25), Offset(500, i * 25), paint);
      canvas.drawLine(Offset(i * 25, 0), Offset(i * 25, 500), paint);
    }
  }
}

```

--------------------------------

### GlowEffect usage example (glow_effect.dart)

Source: https://docs.flame-engine.org/latest/flame/effects/color_effects.html

Full game example showing how to apply GlowEffect to a CircleComponent with a glow strength of 10.0 and an infinite duration of 2 seconds. Requires the HasPaint mixin; experimental API.

```dart
import 'package:flame/components.dart';
import 'package:flame/effects.dart';
import 'package:flame/game.dart';

import 'package:flutter/material.dart';

class GlowEffectExample extends FlameGame {
  @override
  Future<void> onLoad() async {
    final paint = Paint()..color = const Color(0xff39FF14);

    add(
      CircleComponent(
        radius: size.y / 4,
        position: size / 2,
        anchor: Anchor.center,
        paint: paint,
      )..add(
        GlowEffect(
          10.0,
          EffectController(
            duration: 2,
            infinite: true,
          ),
        ),
      ),
    );
  }
}

```

--------------------------------

### SequenceEffectController example

Source: https://docs.flame-engine.org/latest/flame/effects/effect_controllers.html

Creates a sequence of effect controllers that execute one after another. The list cannot be empty.

```dart
final controller = SequenceEffectController([
  LinearEffectController(1),
  PauseEffectController(0.2),
  ReverseLinearEffectController(1),
]);
```

--------------------------------

### NineTileBoxWidget

Source: https://docs.flame-engine.org/latest/flame/other/widgets.html

Documentation for the NineTileBoxWidget widget, including its constructor parameters and usage example.

```APIDOC
## NineTileBoxWidget

### Description
A widget that implements a Container using a Nine Tile Box pattern, which draws a rectangle using a 3x3 grid sprite. The corners are drawn at the same size, the sides are stretched, and the middle expands both ways.

### Constructor
```dart
NineTileBoxWidget({
  required Image image,
  required double tileSize,
  required double destTileSize,
  Widget? child,
})
```

### Parameters
- **image** (Image) - Required - A `dart:ui` image instance.
- **tileSize** (double) - Required - The width/height of the tile on your grid image.
- **destTileSize** (double) - Required - The dimensions for the tile on canvas.
- **child** (Widget) - Optional - Any Flutter widget to be placed inside the container.

### Example
```dart
import 'package:flame/widgets';

NineTileBoxWidget(
  image: image, // dart:ui image instance
  tileSize: 16, // The width/height of the tile on your grid image
  destTileSize: 50, // The dimensions for the tile on canvas
  child: SomeWidget(), // Any Flutter widget
)
```
```

--------------------------------

### Create web platform files

Source: https://docs.flame-engine.org/latest/flame/platforms.html

Run this command if the web build complains about 'Missing index.html'. It creates the web platform files.

```bash
flutter create . --platforms=web
```

--------------------------------

### Sync project to GitHub with git commands

Source: https://docs.flame-engine.org/latest/tutorials/bare_flame_game.html

Initializes a git repository, stages all files, creates an initial commit, adds the remote origin, renames the branch to main, and pushes to the remote. Replace the URL with your repository link.

```bash
git init
git add --all
git commit -m 'Initial commit'
git remote add origin https://github.com/your-github-username/syzygy.git
git branch -M main
git push -u origin main

```

--------------------------------

### PositionComponent constructor and anchor usage

Source: https://docs.flame-engine.org/latest/flame/components/position_component.html

Example showing how to create a PositionComponent with an anchor and use positionOfAnchor to get coordinates relative to a specific anchor point.

```APIDOC
## PositionComponent

### Description
Creates a PositionComponent with a given size and anchor. The anchor determines the point within the component used for positioning and rotation.

### Constructor
`PositionComponent({Vector2? size, Anchor anchor = Anchor.topLeft})`

### Parameters
- **size** (Vector2) - Optional - The size of the component.
- **anchor** (Anchor) - Optional - The anchor point of the component. Defaults to `Anchor.topLeft`.

### Example
```dart
final comp = PositionComponent(
  size: Vector2.all(20),
  anchor: Anchor.center,
);

// Returns (0,0)
final p1 = component.position;

// Returns (10, 10)
final p2 = component.positionOfAnchor(Anchor.bottomRight);
```

### Methods
#### positionOfAnchor(Anchor anchor)
Returns the position of a specific anchor point of the component, relative to the component's origin.

- **anchor** (Anchor) - Required - The anchor point to query.
- Returns: Vector2 - The position of the given anchor point.

#### absolutePositionOfAnchor(Anchor anchor)
Returns the absolute position of a specific anchor point of the component.

- **anchor** (Anchor) - Required - The anchor point to query.
- Returns: Vector2 - The absolute position of the given anchor point.

### Properties
- **position** (Vector2) - The position of the component's anchor.
- **absolutePosition** (Vector2) - The absolute position of the component's anchor.
- **nativeAngle** (double) - The angle in radians, measured clockwise, representing the default orientation of the component.
- **anchor** (Anchor) - The anchor point of the component.
```

--------------------------------

### ColumnComponent example usage

Source: https://docs.flame-engine.org/latest/flame/layout/column_component.html

Creates a ColumnComponent with a gap of 10.0, centered main axis alignment, start cross axis alignment, and three TextComponent children.

```dart
ColumnComponent(
  gap: 10.0,
  mainAxisAlignment: MainAxisAlignment.center,
  crossAxisAlignment: CrossAxisAlignment.start,
  children: [
    TextComponent('Child 1'),
    TextComponent('Child 2'),
    TextComponent('Child 3'),
  ],
);
```

--------------------------------

### List project files with ls

Source: https://docs.flame-engine.org/latest/tutorials/bare_flame_game.html

Verify that the project files were created successfully. The output shows the expected directory structure.

```bash
$ ls
README.md               android/   lib/           pubspec.yaml   test/
analysis_options.yaml   ios/       pubspec.lock   syzygy.iml     web/

```

--------------------------------

### DelayedEffectController example

Source: https://docs.flame-engine.org/latest/flame/effects/effect_controllers.html

Creates a DelayedEffectController that executes its child controller after a delay of 5 seconds. During the delay, the effect is considered 'not started' (its .started property returns false).

```dart
final controller = DelayedEffectController(LinearEffectController(1), delay: 5);
```

--------------------------------

### RowComponent example usage

Source: https://docs.flame-engine.org/latest/flame/layout/row_component.html

Creates a RowComponent with a gap of 10.0, centers children along the main axis, and aligns them to the start along the cross axis. The children are three TextComponents.

```dart
RowComponent(
  gap: 10.0,
  mainAxisAlignment: MainAxisAlignment.center,
  crossAxisAlignment: CrossAxisAlignment.start,
  children: [
    TextComponent('Child 1'),
    TextComponent('Child 2'),
    TextComponent('Child 3'),
  ],
);
```

--------------------------------

### Full collision detection game example

Source: https://docs.flame-engine.org/latest/flame/collision_detection.html

A complete FlameGame with HasCollisionDetection that adds an EmberPlayer and a RectangleCollidable. The RectangleCollidable uses CollisionCallbacks to change its hitbox color on collision start and end.

```dart
import 'package:doc_flame_examples/ember.dart';
import 'package:flame/collisions.dart';
import 'package:flame/components.dart';
import 'package:flame/effects.dart';
import 'package:flame/game.dart';
import 'package:flutter/material.dart' hide Image;

class CollisionDetectionGame extends FlameGame with HasCollisionDetection {
  @override
  Future<void> onLoad() async {
    final emberPlayer = EmberPlayer(
      position: Vector2(10, (size.y / 2) - 20),
      size: Vector2.all(40),
      onTap: (emberPlayer) {
        emberPlayer.add(
          MoveEffect.to(
            Vector2(size.x - 40, (size.y / 2) - 20),
            EffectController(
              duration: 5,
              reverseDuration: 5,
              repeatCount: 1,
              curve: Curves.easeOut,
            ),
          ),
        );
      },
    );
    add(emberPlayer);
    add(RectangleCollidable(canvasSize / 2));
  }
}

class RectangleCollidable extends PositionComponent with CollisionCallbacks {
  final _collisionStartColor = Colors.amber;
  final _defaultColor = Colors.cyan;
  late ShapeHitbox hitbox;

  RectangleCollidable(Vector2 position)
    : super(
        position: position,
        size: Vector2.all(50),
        anchor: Anchor.center,
      );

  @override
  Future<void> onLoad() async {
    final defaultPaint = Paint()
      ..color = _defaultColor
      ..style = PaintingStyle.stroke;
    hitbox = RectangleHitbox()
      ..paint = defaultPaint
      ..renderShape = true;
    add(hitbox);
  }

  @override
  void onCollisionStart(
    Set<Vector2> intersectionPoints,
    PositionComponent other,
  ) {
    super.onCollisionStart(intersectionPoints, other);
    hitbox.paint.color = _collisionStartColor;
  }

  @override
  void onCollisionEnd(PositionComponent other) {
    super.onCollisionEnd(other);
    if (!isColliding) {
      hitbox.paint.color = _defaultColor;
    }
  }
}

```

--------------------------------

### Build web for itch.io

Source: https://docs.flame-engine.org/latest/flame/platforms.html

Run this command to create a web build for itch.io. If it complains about 'Missing index.html', run 'flutter create . --platforms=web'.

```bash
flutter build web
```

--------------------------------

### Invalid variable names in YarnSpinner

Source: https://docs.flame-engine.org/latest/other_modules/jenny/language/expressions/variables.html

Examples of invalid variable names in YarnSpinner. These names do not follow the required pattern: they either start with a digit, contain invalid characters, or lack the $ prefix.

```yarn
$2000_years
$[main]
@today
victory
```

--------------------------------

### Set up Flame development environment with Flutter and Melos

Source: https://docs.flame-engine.org/latest/development/contributing.html

Set up the Flame development environment: switch to the stable Flutter channel, install Melos globally, and bootstrap the project dependencies. Run these commands in order from the terminal.

```bash
flutter channel stable

```

```bash
flutter pub global activate melos

```

```bash
melos bootstrap

```

--------------------------------

### Valid variable names in YarnSpinner

Source: https://docs.flame-engine.org/latest/other_modules/jenny/language/expressions/variables.html

Examples of valid variable names in YarnSpinner. All variable names must start with a $ sign followed by a letter or underscore, then any number of letters, digits, or underscores.

```yarn
$i
$WARNING
$_secret_
$door10
$climbed_over_wall_and_avoided_all_guard_patrols
$DoorPassword
```

--------------------------------

### Retrieve cached image with images.fromCache during gameplay

Source: https://docs.flame-engine.org/latest/flame/rendering/images.html

Use images.fromCache to synchronously get a previously loaded image, for example when creating a bullet sprite in a shoot method. The image must have been loaded earlier, otherwise it throws.

```dart
class MyGame extends Game {

  // attributes omitted

  @override
  Future<void> onLoad() async {
    // other loads omitted
    await images.load('bullet.png');
  }

  void shoot() {
    // This is just an example, in your game you probably don't want to
    // instantiate new [Sprite] objects every time you shoot.
    final bulletSprite = Sprite(images.fromCache('bullet.png'));
    _bullets.add(bulletSprite);
  }
}

```

--------------------------------

### Directory structure after adding components

Source: https://docs.flame-engine.org/latest/tutorials/klondike/step2.html

Shows the expected directory structure after creating the four component files (foundation.dart, pile.dart, stock.dart, waste.dart) inside lib/components/. The other files (klondike_game.dart, main.dart, analysis_options.yaml, pubspec.yaml) are already present from the previous chapter.

```text
klondike/
 ├─assets/
 │  └─images/
 │     └─klondike-sprites.png
 ├─lib/
 │  ├─components/
 │  │  ├─foundation.dart
 │  │  ├─pile.dart
 │  │  ├─stock.dart
 │  │  └─waste.dart
 │  ├─klondike_game.dart
 │  └─main.dart
 ├─analysis_options.yaml
 └─pubspec.yaml

```

--------------------------------

### Implement initializeGame method

Source: https://docs.flame-engine.org/latest/tutorials/platformer/step_3.html

Calculates segments to load based on screen width and initializes the Ember player.

```dart
  void initializeGame() {
    // Assume that size.x < 3200
    final segmentsToLoad = (size.x / 640).ceil();
    segmentsToLoad.clamp(0, segments.length);

    for (var i = 0; i <= segmentsToLoad; i++) {
      loadGameSegments(i, (640 * i).toDouble());
    }

    _ember = EmberPlayer(
      position: Vector2(128, canvasSize.y - 70),
    );
    world.add(_ember);
  }
```

--------------------------------

### Example segment0 definition

Source: https://docs.flame-engine.org/latest/tutorials/platformer/step_3.html

A concrete example of defining a segment by populating the segment0 list with Block instances.

```dart
final segment0 = [
  Block(Vector2(0, 0), GroundBlock),
  Block(Vector2(1, 0), GroundBlock),
  Block(Vector2(2, 0), GroundBlock),
  Block(Vector2(3, 0), GroundBlock),
  Block(Vector2(4, 0), GroundBlock),
  Block(Vector2(5, 0), GroundBlock),
  Block(Vector2(5, 1), WaterEnemy),
  Block(Vector2(5, 3), PlatformBlock),
  Block(Vector2(6, 0), GroundBlock),
  Block(Vector2(6, 3), PlatformBlock),
  Block(Vector2(7, 0), GroundBlock),
  Block(Vector2(7, 3), PlatformBlock),
  Block(Vector2(8, 0), GroundBlock),
  Block(Vector2(8, 3), PlatformBlock),
  Block(Vector2(9, 0), GroundBlock),
];
```

--------------------------------

### Create Flutter project with flutter create

Source: https://docs.flame-engine.org/latest/tutorials/bare_flame_game.html

Run this command in the project directory to generate a new Flutter project. The output is omitted for brevity.

```bash
flutter create .

```

--------------------------------

### Check Flutter installation with flutter doctor

Source: https://docs.flame-engine.org/latest/tutorials/bare_flame_game.html

Run flutter doctor to verify the Flutter SDK is installed correctly and accessible. The output shows a summary of installed components; ensure no errors are reported and the Flutter version is at least 3.13.0.

```bash
$ flutter doctor
Doctor summary (to see all details, run flutter doctor -v):
[✓] Flutter (Channel stable, 3.13.7, on macOS 13.6 22G120 darwin-arm64, locale en)
[✓] Android toolchain - develop for Android devices (Android SDK version 33.0.0)
[✓] Xcode - develop for iOS and macOS (Xcode 15.0)
[✓] Chrome - develop for the web
[✓] Android Studio (version 2021.2)
[✓] IntelliJ IDEA Community Edition (version 2022.2.2)
[✓] VS Code (version 1.83.0)
[✓] Connected device (2 available)
[✓] Network resources

• No issues found!

```

--------------------------------

### Project structure after adding assets

Source: https://docs.flame-engine.org/latest/tutorials/space_shooter/step_1.html

Shows the expected project structure after creating the assets/images/ folder and adding the pubspec.yaml entry.

```text
space_shooter/
 ├─assets/
 │  └─images/
 ├─lib/
 │  └─main.dart
 └─pubspec.yaml

```

--------------------------------

### MoveAlongPathEffect: move component along a path

Source: https://docs.flame-engine.org/latest/flame/effects/move_effects.html

MoveAlongPathEffect moves a PositionComponent along a specified path relative to its current position. The first block shows a full game example; the second shows the direct constructor. The path must be singly connected and it is recommended to start at Vector2.zero() to avoid sudden jumps. Optional flags absolute: true makes the path absolute, and oriented: true also rotates the component along the curve.

```dart
import 'dart:ui';

import 'package:doc_flame_examples/flower.dart';
import 'package:flame/effects.dart';
import 'package:flame/game.dart';

class MoveAlongPathEffectGame extends FlameGame {
  bool reset = false;
  @override
  Future<void> onLoad() async {
    final flower = Flower(
      size: 60,
      position: canvasSize / 2,
      onTap: (flower) {
        flower.add(
          MoveAlongPathEffect(
            reset
                ? (Path()..quadraticBezierTo(-100, 0, -50, 50))
                : (Path()..quadraticBezierTo(100, 0, 50, -50)),
            EffectController(duration: 1.5),
          ),
        );
        reset = !reset;
      },
    );
    add(flower);
  }
}

```

```dart
final effect = MoveAlongPathEffect(
  Path()..quadraticBezierTo(100, 0, 50, -50),
  EffectController(duration: 1.5),
);

```

--------------------------------

### Example of a batched bullet group

Source: https://docs.flame-engine.org/latest/flame/rendering/images.html

Example of a group component using HasAutoBatchedChildren to batch SpriteComponent children, such as bullets.

```dart
class BulletGroup extends PositionComponent with HasAutoBatchedChildren {
  // Add SpriteComponent children representing bullets
}

// Add bullets to the group
bulletGroup.add(BulletSpriteComponent(...));

```

--------------------------------

### Complete main.dart for step 1

Source: https://docs.flame-engine.org/latest/tutorials/space_shooter/step_1.html

Complete main.dart file combining the game class, player component, and main function. This is the final code for the first step of the tutorial.

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

void main() {
  runApp(GameWidget(game: SpaceShooterGame()));
}

class Player extends PositionComponent {
  static final _paint = Paint()..color = Colors.white;
  @override
  void render(Canvas canvas) {
    canvas.drawRect(size.toRect(), _paint);
  }
}

class SpaceShooterGame extends FlameGame {
  @override
  Future<void> onLoad() async {
    add(
      Player()
        ..position = size / 2
        ..width = 50
        ..height = 100
        ..anchor = Anchor.center,
    );
  }
}

```

--------------------------------

### Melos Command: doc-build

Source: https://docs.flame-engine.org/latest/development/documentation.html

Builds the documentation site into HTML. Only rebuilds changed documents, so it is usually fast.

```bash
melos doc-build
```

--------------------------------

### Install and run CSpell spellchecker

Source: https://docs.flame-engine.org/latest/development/contributing.html

Install the CSpell spellchecker globally via npm and run the provided script to check spelling locally.

```bash
npm install -g cspell

```

```bash
./scripts/cspell-run.sh

```
Tokens:
Raw