Basic SpriteComponent shader tutorial

[kornellapu]

Hey kind people!

I have met a curious mind through Flame Engine's Discord server, who wanted to use shaders with Flame Engine.
Well now that is two of us who could use some basic shader tutorial, so I decided to capture what was my solution.
But please keep in mind, I am learning the engine too and there can be better solutions.
You can experiment, and if you have suggestions please share with us! Thanks ^.^

Summary

This tutorial give you a brief understanding how to create and use basic shaders on SpriteComponents with PostProcess and PostProcessComponent using Dart/Flutter and Flame Engine frameworks.

My intention was to keep this tutorial as beginner friendly as possible.
So the tutorial starts at ground zero, at installation and preparation (feel free to skip any steps).
Then goes through creating three classes (other than the game and world) and then wire them together.
At the end it will give you a working shader example which you can tweak it further as you wish.

The basic tutorial consists of 1 + 4 sections.
The Appendix section holds one section. Which goes beyond the basics: adding user input responses.

For the basic tutorial, we will create a simple outline shader for sprites which has a transparent layer as background.

This tutorial intended to on transparent images, like .png files.

---

Created at 2025.12.22 by Kornél (Hoodead) Lapu
The used versions are
Flutter: 3.10.4
Dart: 3.10.4
Flame Engine: 1.34.0

---

Setup

0.1 Tools
First of all you need to install the frameworks (duh!).
You can find the instructions of installing Flutter here and after that for Flame Engine here.

I am using Windows OS and Visual Studio Code for development, the links are for this setup, for other platforms you can consult the documentation, I assume there are other options too.

At the end of installation you should have a working project.
If you dont have it or you already installed then, create a folder for your project, I will use this for example:
C:\Projects\basic_shader_tutorial
Open your folder in VS Code.
Press Ctr + J to open terminal window in VS Code.
Execute the following commands, to create new flutter project in current directory:
flutter create .
Now you have a new flutter project.
Yeey!

0.2 Extensions
While installing through VS Code you are asked to install extensions for Dart and Flutter, I recommend it to add one.

Also we need something to work with fragment (aka pixel) shaders in .frag files, so we need some GLSL highlight or linting. I suggest you to go ahead and download one from the Extensions tab in VS Code.
I used a syntax highlighter: GLSL Syntax for VS Code from GeForceLegend, but it is really up to your preferences.

0.3 Image resource
I will use an image (sword.png) created by lapu_land__.

If you fancy to add your own resource, don't hesitate and I also encourage you, to do so.
The important part is to have transparent background in the .png file.

Create the folder where you
Copy the choosen file under your assets folder in the project, something like this:
C:\Projects\basic_shader_tutorial\assets\images\sword.png

Do not forget to add the containing folder to assets in pubspec.yaml and save:

#... omitted for brevity

flutter:  
  assets:  
    - "assets/images/"  

Pretty much that's it for Setup. We are working with vanilla Flame Engine settings, with nearly vanilla VS Code.

main.dart [1/4]

1.1. Widget, Game and World
Basic stuff, similar to Flame Getting Started.
Replace the whole main.dart file with the following:

import 'package:flutter/widgets.dart';

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

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

class MyWorld extends World {
  @override
  Future<void> onLoad() async {
    print("The world is MINE!");
  }
}

Save and run it from the VS Code terminal (Ctrl + J).
The command is: flutter run. then choose your device from the available list.

You should see a black background in a new window.
The console will contain the "The world is MINE!" message, maybe you have to scroll a little bit upwards, because of the printed flutter commands.

Allright, here we have an empty but working application.

Component(s) [2/4]

Let's create the component where we render our sprite and apply the shader.

For clarity and some modularity I separated the sprite into two classes:

• one for having a standard sprite class (purpose: general sprite and event handling)
• one for applying a post process as a wrapper class (purpose: specific shader application)

Now if I want to modify the shader of the sword only, I dont have to modify the underlying sprite class or
I can "freely" modify the sprite and add input event mixins to it or add childrens, if it is a composite sprite so on and so on without modifying the shader post process class.

Not the best code structure but it is quick and simple. Feel free to modify and experiment.

2.1 Sprite
Create a new file named sword_component.dart (or instead of "sword" use what you have of course):

import 'dart:async';
import 'package:flame/components.dart';

class SwordSprite extends SpriteComponent{
  @override
  Future<void> onLoad() async {
    sprite = await Sprite.load('sword.png');
    size = sprite!.srcSize;

    return super.onLoad();
  }
}

2.2 Wrapper
Here comes the wrapper class for applying shaders and post process, in the same file
(or in a separate one, but don't forget to link them together afterwards via import)
create another class:

//... 
import 'package:flame/post_process.dart';

import 'package:basic_shader_tutorial/outline_postprocess.dart'; // We will create this later
//... 

class SwordSpritePostProcessed extends PostProcessComponent{
  SwordSpritePostProcessed({super.position, super.anchor})
  : super(
    children: [SwordSprite()],
    postProcess: OutlinePostProcess(anchor: anchor ?? Anchor.topLeft),
  );
}

2.3 Result
So for me the final sword_component.dart file looks like this:

import 'dart:async';

import 'package:flame/components.dart';
import 'package:flame/post_process.dart';

import 'package:basic_shader_tutorial/outline_postprocess.dart';

class SwordSpritePostProcessed extends PostProcessComponent{
  SwordSpritePostProcessed({super.position, super.anchor})
  : super(
    children: [SwordSprite()],
    postProcess: OutlinePostProcess(anchor: anchor ?? Anchor.topLeft),
  );
}

class SwordSprite extends SpriteComponent{
  @override
  Future<void> onLoad() async {
    sprite = await Sprite.load('sword.png');
    size = sprite!.srcSize;

    return super.onLoad();
  }
}

So here you will get a syntax error because OutlinePostProcess() does not exists nor the imported package.. yet!
Let's create those next!

Post process(es) [3/4]

Here we are preparing for shaders.
This PostProcess is the handler of the fragment (pixel) shader, and this class is responsible for creating shader resources and for keeping the uniform variables updated.
We also can store shader "settings" here (through uniforms) if you want it to be modifiable in runtime, for example enabling and disabling effects.

Also I created an extension for Color to Vector4 conversion, this should be in a "utility" class to be accessable to other classes too without referencing this specific file.
For clarity I omitted creating a new file.

3.1 Post process

We create the missing class in a new file, name it to outline_postprocess.dart:

import 'dart:ui';

import 'package:flutter/material.dart';

import 'package:flame/components.dart';
import 'package:flame/post_process.dart';

extension on Color {
  Vector4 toVector4() {
    return Vector4(r, g, b, a);
  }
}

class OutlinePostProcess extends PostProcess {
  double outlineSize;
  Color outlineColor;
  Anchor anchor;

  OutlinePostProcess({
    this.outlineSize = 7.0,
    this.outlineColor = Colors.purpleAccent,
    this.anchor = Anchor.topLeft
  });

  late final FragmentProgram _fragmentProgram;
  late final FragmentShader _fragmentShader = _fragmentProgram.fragmentShader();
  late final myPaint = Paint()..shader = _fragmentShader;

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

    _fragmentProgram = await FragmentProgram.fromAsset('assets/shaders/outline.frag');
  }

  @override
  void postProcess(Vector2 size, Canvas canvas) {
    final preRenderedSubtree = rasterizeSubtree();

    _fragmentShader.setFloatUniforms((value) {
      value
        ..setVector(size)
        ..setFloat(outlineSize)
        ..setVector(outlineColor.toVector4());
    });

    _fragmentShader.setImageSampler(0, preRenderedSubtree);

    canvas
      ..save()
      ..translate( -size.x*anchor.x, -size.y*anchor.y )
      ..drawRect(Offset.zero & size.toSize(), myPaint)
      ..restore();
  }
}

Okay so if the linking / importing is right the syntax error will go away.

The outline should be "under" the image, so I added the PostProcessComponent as the parent of the SpriteComponent, which would mean the post process (shader) is rendered first, and then the SpriteComponent with the image overwriting the layer of the shader.
You can test it by stacking only SpriteComponents within each other. The last (deepest) child will be rendered on top.

Using any kind of PostProcessComponent will "overwrite" the rendering order and the post process will decide what will be the final color of the rendered pixel (check out the added hints for the class and it's source code for details).

This structure allows us to simply use rasterizeSubtree(), which will implicitly rasterize all added children.

Let's run the application.
Ctrl + J.
flutter run then choose your platform.
Nothing, but darkness...

3.2 Usage

Well we did create the components and postprocess classes but we did not added any of those to the game itself.

Go to the main.dart and add two components to the world with a little positional offsets:

import 'package:flutter/material.dart';

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

import 'package:basic_shader_tutorial/sword_component.dart';

void main() {
  runApp(
    GameWidget(
      game: MyGame()
    ),
  );
}

class MyGame extends FlameGame {
  MyGame() : super(world: MyWorld());

  @override
  Color backgroundColor() => Colors.green;
}

class MyWorld extends World {
  @override
  Future<void> onLoad() async {
    add(
      SwordSprite()
      ..position = Vector2(-200, 0)
      ..anchor = Anchor.center
    );

    add(
      SwordSpritePostProcessed(
        position: Vector2(200, 0),
        anchor: Anchor.center
      )
    );
  }
}

In the new main.dart I replaced the FlameGame with a custom class where I override the background color, because I have a black-and-white image. You can change it to suit your images too.

Also change the position of components based on the size of my images and window size.

Run the application again.

What? There is only one sprite? Why? You may ask, my fellow tutorial buddy.
The reason is printed early in the console, if you whish to trace it.

There is no such file what we would like to load as a shader file in OutlinePostProcess:
[...] Unhandled Exception: Exception: Asset 'assets/shaders/outline.frag' not found [...]

I promise there won't be more missing files after the next section.

outline.frag [4/4]

In this section we will create the fragment (pixel) shader program which runs on the GPU then add as a resource.

It is important to note, we are going to program the GPU, so this code will need a little bit of different thinking from what we did before.

The reason is that, the fragment shader runs for each pixel on the screen.
Pff.. and?
Well that means, you should not excessively branch or loop, because it will be calculated, iterated, or be checked for each pixel in each frame.
I am serious, a 1K screen (like mine) has 1920 * 1080 pixels => 2 073 600 pixels in full screen mode.
A for loop of 16*16 will create 256 * 2 073 600 => 530 841 600 iterations per frame in worst case.
Yikes..
So please be mindful what are you doing and how in your shader.
You can think of it like, it nearly has O² scale, because of the "per pixel" execution, where the input size is based on the width and height of the screen.

Also the shader optimization is out of the scope of this tutorial.
But there are guards, to escape as early as possible.

Everything is ready to create the GLSL based shader.

4.1 Shader code
Create new directory at \assets\shaders and a file named outline.frag.
For example, in my project it looks like this:
C:\Projects\basic_shader_tutorial\assets\shaders\outline.frag

Open the outline.frag file and add the following lines:

#version 460 core

precision mediump float;

#include <flutter/runtime_effect.glsl>

uniform vec2 uSize;
uniform float uOutlineWidth;
uniform vec4 uOutlineColor;
uniform sampler2D uTexture;

const int MAX_SAMPLE_DISTANCE = 8;

out vec4 fragColor;

void main() {
  vec2 uv = FlutterFragCoord().xy / uSize;
  vec4 texColor = texture(uTexture, uv);
    
  // If the current pixel is not transparent, render the original color
  if (texColor.a > 0.0) {
    fragColor = texColor;
    return;
  }
    
  // Check surrounding pixels for outline
  vec2 texelSize = 1.0 / uSize;
  bool foundOpaqueNearby = false;
    
  // Sample in the bounding square pattern around the current pixel
  // You must use static const loop counts in GLSL
  for (int x = -MAX_SAMPLE_DISTANCE; x <= MAX_SAMPLE_DISTANCE; x++) {
    for (int y = -MAX_SAMPLE_DISTANCE; y <= MAX_SAMPLE_DISTANCE; y++) {
      if (x == 0 && y == 0) continue;
      
      // Checking the real distance, instead of square based (manhattan) distance
      float distance = sqrt(float( x*x + y*y ));
      if (distance > uOutlineWidth) continue;
      
      // Sample the offsetted pixel from the current pixel (uv)
      vec2 offset = vec2(float(x), float(y)) * texelSize;
      vec4 sampleColor = texture(uTexture, uv + offset);
      
      if (sampleColor.a > 0.0) {
        // We found solid color in the iteration --> sprite is nearby
        foundOpaqueNearby = true;
        break;
      }
    }
    // Also break out from outer loop, if found a solid color next to current pixel
    if (foundOpaqueNearby) break;
  }
    
  if (foundOpaqueNearby) {
    fragColor = uOutlineColor;
  } else {
    fragColor = vec4(0.0, 0.0, 0.0, 0.0);
  }
}

So.. what does this shader do?
Grabbing each transparent pixel and checking: is it next to an opaque pixel?
If yes, then color it as the outline color (passed in as an uniform variable), else it will be full transparent.

That is why the transparency of the .png image was important in the beginning (at Requirements section).

Remark:
The loop of a GLSL shader accepts only a compile time constant.
So as far as I know we can not use the outline width, because that is a uniform, which are not present in the shader at compile time.
This is altering the shader behaviour if the outline uniform is set to a bigger value than this shader sampler distance. It should be set accordingly and manually in the shader too.

4.2 Shader resource
To let the flutter linking process know about this shader asset we have to add it to the pubspec.yaml file before compilation.

Open the pubspec.yaml and write the following lines under what we already added:

#... still omitted for brevity

flutter:
  assets:
    - assets/images/
  # the new lines:
  shaders:
    - assets/shaders/outline.frag

Save it and let the automatic pub get command to run.
Now the resource will be loaded when the project is next compiled.

Now run the application.
Open the console (Ctrl + J).
Execute flutter run, then choose your platform.

Tadaa!
You should see two sprites in the window.
The left is without an outline, the right one is with a colored outline from the shader.

We are done with the basic tutorial.
Yippyy!

It's time for you to experiment!

Takeaways

According to my logic, there are three layers of using shaders in Flame Engine, where:

• the component layer: SpriteComponent and PostProcessComponent
  • connecting shaders to Flame components and holding game logic, and user handling user inputs
• post process layer: PostProcess
  • the link between components and holding runtime settings, behaviour logic, updating uniforms for shaders
• the GLSL shader: .frag file
  • the core shader code

There is an option to alter shader behaviour from the component logic too if you are using PostProcessComponent.
Check Appendix A.

---

I hope this tutorial helped you to understand the basics!
Don't forget, if you know better solutions: go for it! You can tweak this solution to your needs, happy coding!

If you found some errors or mistakes please let me know in the comments and I will look after them and update the tutorial accordingly.

The repository of this tutorial is available here, and it is set to the end of the basic tutorial.
The Appendix files are present, but commented out.

After downloading the repo, it is possible that you have to run flutter create . from the root folder, to reinitialize it.

And if you are using any part of the shader codes, please credit me as
Kornél (Hoodead) Lapu
or buy me a coffee here.
Thanks in advance!

Also don't forget to support the superb Flame Engine community too.
Cheers!

---

---

Appendix A - User input

This section we will add a Flame mixin to handle some mouse hover events and change the underlying shader behaviour.

A.1 Event handling
Open the sword_component.dart file or where your PostProcessComponent is located.
Add the HoverCallbacks mixin to the class, to have something like this:

//... other imports
import 'package:flame/events.dart';

class SwordSpritePostProcessed extends PostProcessComponent with HoverCallbacks {
    //... omitted for brevity
}

After that add one private field and the two function to react to hover enter and exit into the class.
(The cancel event should be handled too but for clarity, I omitted).

Color? _originalPostProcessColor;

@override
void onHoverEnter() {
    super.onHoverEnter();
    
    final OutlinePostProcess outlinePostProcess = postProcess as OutlinePostProcess;
    _originalPostProcessColor = outlinePostProcess.outlineColor;
    outlinePostProcess.outlineColor = Colors.blue;
}

@override
void onHoverExit() {
    final OutlinePostProcess outlinePostProcess = postProcess as OutlinePostProcess;
    outlinePostProcess.outlineColor = _originalPostProcessColor ?? Colors.purpleAccent;

    super.onHoverExit();
}

At this point the solution was not working for me with these modifications.

As I debugged, I found out the size property of PostProcessComponent was not handled as I expected, though the value of size property was not a zero vector at runtime.

I decided to elevate some part of the code from PostProcessComponent into SwordSpritePostProcessed and handle the children changing there.

After I explicitly set the size property it was working as intended, attached to onChildrenChanged event to let it work with multiple children (but not tested that part).

After that the expected bounding box became the target.

At the end the sword_component.dart file became this:

import 'dart:async';

import 'package:flame/components.dart';
import 'package:flame/post_process.dart';

import 'package:basic_shader_tutorial/outline_postprocess.dart';

// Appendix: A 
/**/
import 'package:flame/events.dart';
import 'package:flutter/material.dart';
/**/

class SwordSpritePostProcessed extends PostProcessComponent 
// Appendix A:
/**/
with HoverCallbacks 
/**/
{
  SwordSpritePostProcessed({super.position, super.anchor})
  : super(
    children: [SwordSprite()],
    postProcess: OutlinePostProcess(anchor: anchor ?? Anchor.topLeft),
  );

  // Appendix A:
  /**/
  @override
  void onChildrenChanged(Component component, ChildrenChangeType changeType) {
    _recalculateBoundingSize();

    super.onChildrenChanged( component, changeType);
  }
  
  // I have to recalculate the size property manually, it was not working without it
  // Even if the code is the similar in the super class.
  void _recalculateBoundingSize() {
    final Vector2 boundingBox = Vector2.zero();
    
    final rectChildren = children.query<PositionComponent>();
    if( !rectChildren.isEmpty ){
      final boundingRect = rectChildren
        .map((child) => child.toRect())
        .reduce((a, b) => a.expandToInclude(b))
      ;

      boundingBox.setValues(boundingRect.width, boundingRect.height);
    }
    
    size = boundingBox;
  }

  Color? _originalPostProcessColor;

  @override
  void onHoverEnter() {
    super.onHoverEnter();
    
    final OutlinePostProcess outlinePostProcess = postProcess as OutlinePostProcess;
    _originalPostProcessColor = outlinePostProcess.outlineColor;
    outlinePostProcess.outlineColor = Colors.blue;
  }

  @override
  void onHoverExit() {
    final OutlinePostProcess outlinePostProcess = postProcess as OutlinePostProcess;
    outlinePostProcess.outlineColor = _originalPostProcessColor ?? Colors.purpleAccent;
    
    super.onHoverExit();
  }
  /**/
  
}

class SwordSprite extends SpriteComponent{
  @override
  Future<void> onLoad() async {
    sprite = await Sprite.load('sword.png');
    size = sprite!.srcSize;

    return super.onLoad();
  }
}

The result is, when you hover over the sprite bounding box, the outline shader changes to blue, because we set that in the hover event.
If the mouse exits the box, then it is resetted to the original color.

This is how it should look like:

That is the end of Appendix A.

[spydon]

Would you be interested in adding this tutorial to the official docs as s PR? :)

[kornellapu]

Thank you for asking! Yes, I am interested! ^.^ I will open a PR in the following days!

[kornellapu]

Just a quick note about a schedule change: I have to postpone the PR after January 8, 2026.