This occurred to me after a discussion on the [new FCS component
PR](https://github.com/flame-engine/flame/pull/2694#discussion_r1312450113).
As per usual, @spydon has opened my eyes to the ultimate truth:
We should rename loads of files, and it shall affect almost no one.
The idea is to (1) add a "Text" prefix to all text-rendering-related
classes and (2) rename the existing `Text*` to `InlineText*` (which is
what they are).
This PR is a bit big, but the changes should hopefully be simple to
review, and can be broken down into:
* Add a proper base class for the node inheritance chain, call it
TextNode (while working on Flame Markdown I realized the value this will
have to me)
* Rename the old TextNode to InlineTextNode
* Rename DocumentNode to DocumentRoot because it is not a node
* Rename Element to TextElement
* Rename the old TextElement to InlineTextElement
* Rename Style to FlameTextStyle (note: we could consider dropping the
Flame here)
* Rename the old FlameTextStyle to InlineTextStyle
* Update the docs accordingly
* Add some more diagrams and explanations to the docs, following the new
nomenclature
* I also updated our "internal" imports to use the text module to make
life so much easier (this could arguably be done in a separate PR, but I
honestly think it's easier to review together, please lmk if you prefer
me to split).
These are all breaking changes but likely won't actually affect most
users (see below).
While this is breaking, it should hopefully not affect most users,
because these are all infrastructure classes that most people aren't
using directly. If you are using the FCS components, or the renderers
`TextPaint` or `SpriteFontRenderer` directly, this should have zero
effect to you.
If you are using the Nodes, Stlyes or Elements directly, or have a
custom TextRenderer, see below.
Migrating should be a simple matter of renaming your type references:
* from TextNode to InlineTextNode
* from TextElement to InlineTextElement
* from Element to TextElement
* from FlameTextStyle to InlineTextStyle
* from Style to FlameTextStyle
Make sure to do it in the appropriate order not to cause any
double-replace issues.
If you are importing via the module `package:flame/text.dart`, which we
highly encourage, you should not have to change any import statements
whatsoever.
This will:
kill the TextRenderer inheritance chain
incorporate the functionality of the base TextRenderer in the base TextFormatter
rename TextFormatter to TextRenderer and appropriate references
That is because both essentially do the same job; encompass the style (or "how") information about how to render text, but using two slightly different interfaces. While that could allow for more flexibility, it is a faux choice that needlessly complicates the pipeline. By having a single interface to comply with, we still allow for custom renders while at the same time making all the code downstream simpler to use and understand.
This is part of my ongoing effort to simplify the text rendering
pipeline.
My ultimate goal is to:
* get rid of renders
* rename formatters to renderers
* make the interface complies to both
All details are specified here:
https://github.com/flame-engine/flame/pull/2663
As a first step to break down that huge PR, this makes a small change to
TextElements to make them more useful
This PR will:
### rename render -> draw
draw becomes the "internal", underlying impl, raw method, that just
draws the element w/ any custom options
### add a new render method that takes in more options
this does not need to be extended by every impl.
this is for end users and accepts parameters like position and anchor to
be more in line with the renderer interface
This is technically a breaking change but should have no effect for
users, unless you are creating your own custom `TextElement`s. In that
case, to migrate:
* rename your `render` method to `draw`
This PR introduces a new HasVisibility mixin on Component. It prevents the renderTree method from progressing if the isVisible property is false. It therefore prevents the component and all it's children from rendering.
The purpose of this mixin is to allow showing and hiding a component without removing it from the tree.
An important note is that the component (and all it's children) will still be on the tree. They will continue to receive update events, and all other lifecycle events. If the user has implemented input such as tap events, or collision detection, or any other interactivity, this will continue to operate without affect (unless it relies on the render step - such as per-pixel collision detection).
This is expected behaviour. If it is not desired, the user needs to account for it (by checking isVisible in their code) or someone needs to create another mixin for HasEnabled or HasActive which would prevent these other actions 😁
I am very happy to make changes, take suggestions, etc!
Fix a handful of lint issues across the codebase, identified using DCM.
Nothing controversial, I expect; slowly getting these out of the way so
we can focus on discussing bigger things.
This is a first step towards enabling DCM for Flame. Though I have tested with all rules, and am working on selecting, assessing, and fixing violations, as a first step, we can merge the infrastructural changes to flame_lint to and GitHub actions.
As a proof of concept, I am enabling two rules for which we have no violations.
I will followup with enabling more rules, adding discussions for controversial changes, and fixing non-controversial violations.
The viewport should receive events before the world, otherwise all huds will get the events after the world components, if there are any world components underneath them.
This change introduces a very simple pool for `CollisionProspect`s so
that those objects don't have to be re-created each tick.
It means that the `CollisionProspect` needs to be mutable though, so the
code becomes a little bit harder to read since sets can't be used
anymore.
The Parallax already supported filter quality, but the loader methods were missing parameters for it to be passed to the loaded instances, making it impossible (unless manually loading) to set a filter quality in a parallax.
By setting a filter quality to none (which on flutter means that the next neighbour algorithm will be user) on pixel art sprites we can keep the crisp look that that style of art demands.
Adds a new key api on FCS, which will allow users to get a component from the tree, without needing to iterate over all the children or a parent descendants.
This PR adds a new method to Game which allows advancing the game loop by a certain amount of time while the engine is paused. By default it assumes one frame to be ~16 ms, but it can be controlled while calling stepEngine
The idea is to allow easy frame by frame inspection of the game. It can even be added to FlameStudio as part of the start/pause buttons on the toolbar.
https://user-images.githubusercontent.com/33748002/233453501-b9f90d49-1834-4f0f-9536-77629cfcadbc.mp4
The previous implementation of the NineTileBox calculates identically sized tiles in a 3x3 grid and does not allow the user to customise this. For example, a 60x60 pixel sprite will be cut into 20x20 pixel tiles. This MR allows the user to specify the sizes of the fixed-width and fixed-height rows and columns so that a completely custom grid is possible.
Example with the following sprite and custom grid sizes.
Note that the stretchable row and column are only 1 pixel wide/high in this example.
This PR adds the following lint rules to our list:
```
always_put_required_named_parameters_first
avoid_multiple_declarations_per_line
avoid_positional_boolean_parameters
avoid_returning_null_for_void
avoid_returning_this
avoid_unnecessary_containers
enable_null_safety
library_private_types_in_public_api
no_leading_underscores_for_library_prefixes
no_leading_underscores_for_local_identifiers
prefer_null_aware_method_calls
tighten_type_of_initializing_formals
unnecessary_late
use_setters_to_change_properties
```
And these rules were considered, and some changes were made according to
them as a clean-up, but in many places they didn't make sense
(`prefer_asserts_with_message` I would have included, but there were too
many places that needed to be changes):
```
collection_methods_unrelated_type
prefer_asserts_with_message
avoid_renaming_method_parameters
```
This updates flame_audio to use the recently released audioplayers 4.0.0
Migration instructions:
AudioPool has moved to AudioPlayers, but we still export it from
flame_audio, so the only thing you have to do if you import AudioPool
directly is to change the import to:
import 'package:flame_audio/flame_audio.dart';
This PR is the second in a series of refactors that aim to simplify event handling in Flame. The approach is as follows:
Added the MultiTapDispatcher component, which contains the logic that used to be within the HasTappableComponents mixin. This component is internal; it mounts to a FlameGame directly, and ensures that it is a singleton.
Whenever any TapCallbacks component is added to a game, it automatically adds the MultiTapDispatcher component (unless there is already one), which in turn registers a tap gesture detector with GestureDetectorBuilder and rebuilds the game widget.
The end result is that now in order to make a component tappable you only need to add the TapCallbacks mixin to that component, everything else will be handled by the framework.
Consequently, the HasTappableComponents mixin is now empty and marked as deprecated.
This PR adds a new mixin on Component. When attached to a component, it allows scaling the delta time of that component as well as all its children by a non-negative factor. The idea is to allows slowing down or speeding up the gameplay by change the scaling factor.
Note: This approach works only for framerate independent game logic. Code in update() that is not dependent on delta time will remain unaffected by time scale.
The flutter_svg version used on flame_svg was outdated, which causes us to lose precious pub points:
This updates the library by migrating a bit of the code (it was def a breaking change on their side, but shouldn't be on ours).
This change makes it possible to have the collision detection system further down in the tree than on the FlameGame, this enables you to have collision detection on the World component for example.
Today it doesn't work if you have several worlds where the components are overlapping across the worlds, since the hitboxes live on top level.
So now you can use a World like this:
class CollisionDetectionWorld extends World with HasCollisionDetection {}
and all hitboxes added in there will only react with other hitboxes added to that world.
