feat: ⚡particles ⚡

[av]

Sample implementation of particles for Flame 🔥 engine.

The central point of the solution is extreme composability, exactly as with Flutter itself. It means that there are enough basic behaviours to cover majority of the use-cases and the rest is covered by extension points.

Please see the doc/examples/particles/lib/main.dart for a proposed particles API and ways to compose them together. Also, please try it locally, it follows the same example format as already established here. The gif above was rendered from running this source.

[luanpotter]

I need some time to take a better look at the code, but I love this feature! Thank you very much!

[av]

Thanks for the initial review!
I'm particularly interested in the feedback on if the new APIs are consistent with current 🔥 Flame codebase.
I will wait for your comments on it and proceed once we're ok with where it settled!

[erickzanardo]

Looks good, I also gonna need a little more time to look give this a better look, but I already left some comments, some additional comments:

Additional to the ImageParticle we could have a SpriteParticle, so we could take a lot of advantages of Flame sprites. Another thing is that the particle system is totally bound to to Flame's component system, so people that does not uses it, will have a hard time to use the Particle system, maybe we could have this outside the Component system from Flame and then create the components that uses it.

Thanks a lot for this PR, this is looking pretty awesome already.

[av]

Thanks a lot for your feedback!

Additional to the ImageParticle we could have a SpriteParticle, so we could take a lot of advantages of Flame sprites

Yes! Hundred times yes! That was is the plan, as well as ComponentParticle which would allow any component to be used as a particle within the particle system. (Think of material producing small bursts of copies of its texture when hit, for example)

Another thing is that the particle system is totally bound to Flame's component system, so people that do not use it, will have a hard time to use the Particle system

This was exactly my first line of thought. But i eventually realised that Component is at very heart of Flame base Game class. So, if you're using Game or it's derivatives - you're likely using Components. And then I realised that using Game is essentially equal to using Flame, so essentially, it didn't make sense anymore to use anything except the component. It also allowed to directly use current component pipelines with:

game.addLater(AbsolutelyAnyParticle());

game.components
  .where((c) => c is Pirate)
  .forEach((c) => c.add(RomParticle));

Which i really liked.
@erickzanardo , please let me know your opinion on use cases above and if we still should migrate Particle from being based on Component!

The rest of comments will be fixed, thanks again for your review :)

[erickzanardo]

Yes! Hundred times yes! That was is the plan, as well as ComponentParticle which would allow any component to be used as a particle within the particle system. (Think of material producing small bursts of copies of its texture when hit, for example)

Awesome!

This was exactly my first line of thought. But i eventually realised that Component is at very heart of Flame base Game class. So, if you're using Game or it's derivatives - you're likely using Components. And then I realised that using Game is essentially equal to using Flame, so essentially, it didn't make sense anymore to use anything except the component. It also allowed to directly use current component pipelines with:

@av Personally, I totally agree with you, I think that using BaseGame is how Flame should be used. But there is a big part of the community that prefer to use Game class instead of BaseGame class, for a variety of reasons, so, because of this we usually like to have features available for both approaches, you will notice that we have the Sprite class and the SpriteComponent class, or for example, FlareAnimation and FlareComponent and so on. I think it would be nice to have the particle system be written agnostic of the Flame component system, and then have Components classes that uses the system, so we can keep with that rational, what do you think?

[av]

But there is a big part of the community that prefer to use Game class instead of BaseGame class

Wasn't aware that this is the case! Then we definitely have to decouple these to Particle and ParticleComponent for a symmetrical use.
I'd say that in this case ParticleComponent could be a simple container, proxying Component lifecycle hooks to a Particle lifecycle hooks, so would be relatively lightweight. With that, though, to add any particles when using a BaseGame, they will be wrapped with ParticleComponent as following:

game.addLate(ParticleComponent(
  paticle: AnyParticle(...)
));

Yet it'd still be possible to use Particle in any other environment directly.
Will implement this in PR as well as include fixes as per comments above 👍
Thanks for the feedback, once again!

[erickzanardo]

Awesome! Looking forward to it!

[luanpotter]

I have a few nits, but the API and overall idea I really, really like. Specially the composability aspect. The one thing I would change though would be to move everything to the particle folder (even the component and mixin), I think that might be more organized (though it's up for debate). Other than that, a huge LGTM from me.

[luanpotter]

About the separating component or not, I don't have a strong opinion about it, I think it would be nice to have it separated unless it adds too much overhead. In which case folks can easily use a Particle Component by hand inside the Game class without using BaseGame at all.

[erickzanardo]

@luanpotter I still think we should separate the Components, since BaseGame does a lot more than only calling update and render methods from components, using a component outside the BaseGame structure can lead to a lot of issues, a common one is when a PostitionComponent is used on a Game instance and everything that is rendered after it has a weird position on the screen, which happens because of transformations that this component does to the canvas and who is responsible today for restoring, is the BaseGame. It would agree with not separating, if we would refactor all of our components classes to not have this kind of side effect, which would then enable it to be safely used outside the BaseGame class, but I think that would be too much work at the moment

[av]

Just updated a PR with another iteration as per our previous discussions:

• Added docs on using this particle system to /docs/particles.md
• Chaining API for initializing effects, just a bit of 🍬 on top
• Particle is now separated from Component
• Built-in particle wrappers for Animation, Sprite, FlareAnimation and Component
• More samples in /docs/examples/particles/main.dart

Next steps for us are:
@av to fix failing build implement fixes as per review after from #190 (comment)

@erickzanardo @luanpotter could you please go through added https://github.com/flame-engine/flame/pull/190/files#diff-a0132f3a4aa29237ea1ffc1f534a5ca7 as well as review the chaining API?

After that, I think we'll be almost ready to merge this one 💪
Thanks for your awesome feedback!

[av]

Ok, this version is ready for a final review, also added:
ScaledParticle for scaling, .rotated, .rotating, .scaled chainables as well as a better example on chaining in /doc/example/particles/lib/main.dart.

From here now will just wait for your final approval and then we're ready to 💥 , 🎉 , 🔴 and any other particle effects in Flame 😸

[av]

Here's the preview of all examples together:

[erickzanardo]

Found some typos but LGTM. Awesome work on this! Thanks!

[av]

Just pushed the last fixes, please take your time for final passes, but feel free to merge any time otherwise!
Thanks for bringing 🔥 to live!

[erickzanardo]

Awesome work @av

I just noticed that this PR is pointing to master, can you please rebase your it to the develop branch, and also could you add an entry to the CHANGELOG.md with this changes? Be sure to add a (thanks @av) at the end of the entry.

With this final two details, this will be ready to be merged!

Thanks again for this awesome contribution.

[av]

Done and done! 🎆🎇

[erickzanardo]

Merged! Thanks @av