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`
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.
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.
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 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 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.
As-is
As mentioned in #2321, the user needs to propagate double-tap events to the component tree using DoubleTapDetector & propagateToChildren until now.
To-be
Any components that are mixed into the DoubleTapCallbacks receive double-tap-related events.
Same as DragCallbacks, there is no need to add mixin to the game like HasDoubleTapCallbaks as before.
This creates a new component HardwareKeyboardDetector, which is a more advanced version of the KeyboardEvents mixin:
HardwareKeyboardDetector is a component instead of a mixin, which means it can be added/removed by the user at any point;
multiple such detectors can be attached to a game - for example, in a 2-player game one component may be paying attention to arrow keys, while another to WASD keys;
the new component uses Flutter's HardwareKeyboard interface, bypassing the need for a Focus widget;
the component keeps the ordered list of keys that are currently being pressed, which is helpful for games where this order is important;
there is the ability to temporarily pause the reception of key events using keyEventsPaused property.
Created a mixin to handle the margin to the viewport, mostly to remove the code duplication in ButtonComponent and HudButtonComponent, but it can also be useful in other cases when you don't want to wrap your component in HudMarginComponent.
Once the new camera system is in place this will of course have to be replaced.
Since pointerId is already handled by the handle* methods we don't have to expose it in the onDrag* methods, this conforms with the standard set in Tappable.
* Added Component.childrenFactory
* fix some of the lint warnings
* more lint warnings
* remove changelog entry
* more analyzer warnings
* one more warning
* one more warning
* remove more unused imports
* fix more warnings
* another warning
* one more warning
* a lot more warnings
* some more warnings
* fix warnings in flame_svg
* fix warnings in flame_bloc
* Remove OrderedSet override feature
* Remove testRandom change
* Remove unnecessary type checks
* Re-remove deprecated argument in random_test
Co-authored-by: Pasha Stetsenko <stpasha@google.com>
* Camera as an internal component
* Correct respectCamera
* Added changelog entry
* Add super call that will later be removed
* Rename callRender -> callOwnRender
* Don't call render when root
* Remove callOwnRender
* Skip CameraWrapper in own renderTree
* Too complex to have camera as component
* Revert test
* Update docs for respectCamera
* Move down field
* Fix changelog
* Animations, CameraAndViewport, CollisionDetection and Components unified
* Added descriptions to effects
* Rename input games
* Unify input stories
* Add info to parallax section
* Added descriptions to the rendering examples
* Add descriptions to the sprites directory
* Fix utils and rendering section
* Add descriptions to the widgets section
* Delete directory that rebase brought back
* Unify game names
* Added some styleguide docs for examples
* Fix analyze issues
* All files should have _example as suffix
* Made the FollowComponentExample a bit easier to understand
* Change priority of ember
* `ShapeComponent` changes size, position and angle of underlying Shape
* Added description to ShapeComponent
* Fix test
* Update packages/flame/lib/src/components/shape_component.dart
Co-authored-by: Erick <erickzanardoo@gmail.com>
* Add absoluteScale and absoluteAngle to PositionComponent
* Refactor ShapeComponent
* Should be scaled by total scale, not scaled size
* Premature optimization for creation for objects in Polygon
* Use path for default Polygon constructor
* Do not sync component and hitbox shape
* Fix analyze issue
* Add example for flipping with collision detection
* Don't use absoluteScale
* Fix examples
* Fix examples
* Doesn't need super.render
* Fix Circle dartdoc
* Update changelog
* Update names of vertices caches in Polygon
* Update text docs
* Revert "Update text docs"
This reverts commit 73a68a465d76eb0eb50bb3753e57b2f4e3b5a7f4.
* Fix examples
* ShapeComponents docs
* Move example games to the top
* Fix dartdoc comment about polygon vertex relation
* Fix order of polygon vertices in dartdoc
* Fix anchor for PolygonComponent.fromPoints
* Add test with ancestors
* Update doc/components.md
Co-authored-by: Pasha Stetsenko <stpasha@google.com>
* Update doc/components.md
Co-authored-by: Erick <erickzanardoo@gmail.com>
* Rename example classes
* Fix linting issues in examples
* Don't use px
* Use isTrue and isFalse
* Update doc/components.md
Co-authored-by: Erick <erickzanardoo@gmail.com>
* Fixed comments on PR
Co-authored-by: Erick <erickzanardoo@gmail.com>
Co-authored-by: Pasha Stetsenko <stpasha@google.com>
* Add `randomColor` to the `Color` extension
* Add flame rive package to monorepo (#1048)
Add flame rive package to monorepo
* Add random to PaintExtension
* Update examples/pubspec.yaml
Co-authored-by: Erick <erickzanardoo@gmail.com>
Co-authored-by: Renan <6718144+renancaraujo@users.noreply.github.com>
Co-authored-by: Erick <erickzanardoo@gmail.com>
* Game as a component
* Fix component stories
* Effects are now components
* Update effects docs
* Handle swap of parent
* Fix reAddChildren
* Wait for children to be added
* BaseComponent and PositionComponent to be non-abstract
* Simplify HasGameRef
* Revert so that onLoad can be null
* Fix example description
* Effects as components
* Remove gameRef from addChildren
* Fix hasGameRef
* Start migrating effects
* Updated comments of effect fields
* Fix comments
* Continue to fix sequence and combined effects
* Upgrade ordered_set
* Fix position_component_test
* BaseComponent -> Component
* Fix combined and sequence effects
* Await components to be added in tests
* Remove unnecessary game.update in tests
* Fix some tests related to composition
* BaseGame should be used in examples
* Fix CombinedEffect test
* Keyboard code to be based on Component
* Fix keyboard tests
* Fix analyze problems
* Fix sequence_effect
* Fix combined_effect_test
* Store peak state instead of end state
* Fix sequence_effect tests
* Update tutorial
* Fix tutorial 1
* Remove SimplePositionComponentEffect
* Remove unused test variable
* Update docs
* Removed onMount
* Remove onMount
* Add missing dartdoc
* Fix dart docs
* Add super.update where needed
* Move reAddChildren to component
* Reorganize method order in game widget
* preOffset -> initialDelay, postOffset -> peakDelay
* Introduce component.onParentChange
* Remove tests in wrong file
* Fix composed component test
* Add game lifecycle test
* Use BaseGame for mouse cursor test
* Oxygen should (?) not call super.update
* Use BaseGame in keyboard_test
* Fix onLoad to be properly cached
* Re-add unintentionally removed override
* Fix info for collision detection tests
* Add test for correct lifecycle on parent change
* Fix particles example
* Add component lifecycle diagram to the docs
* Add docs for the game lifecycle
* onRemove should be called when a game is removed from the widget
* Fix analyze errors
* prepare should be called from the component itself, not its parent
* Fix dartdoc
* onParentChange -> onMount
* onMount should have void as return type
* Simplify the loaderFuture in GameWidget
* Fix mock_canvas
* Fix rebase problem
* Remove asComponent
* Less complex _loaderFuture
* Add super.update to no_fcs parallax example
* Fix async tests
* Revert _loaderFuture
* Fix analyze issues
* await gameWithCollidables
* Keep epsilon small where it can be
* tappable methods should return bool
* Game lifecycle is now the same as for Component
* Remove mustCallSuper from component.update
* Make onLoadCache protected
* @internal on onLoadCache
* Cache/Memoize debugPaint and debugTextPaint
* Fix imports
* Fix comments
* Always call super.onLoad so that mixins can override it
* Add forgotten super.onLoad
* Bump coverage percentage
* HasCollidables should override update
* Fix Game comments
* Fix some dartdoc
* Apply suggestions from code review
Co-authored-by: Erick <erickzanardoo@gmail.com>
* Game + Loadable as mixins
* Update packages/flame/lib/src/game/game_widget/game_widget.dart
Co-authored-by: Luan Nico <luanpotter27@gmail.com>
* Update loadable docs
* Fix comments
* Move fps_counter
* Fix keyboard example
* Fix dartdoc
* Remove tutorials temporarily
* Fix game lowlevel graph
* Fix resize issue
Co-authored-by: Erick <erickzanardoo@gmail.com>
Co-authored-by: Luan Nico <luanpotter27@gmail.com>
* Add keyboard with focus node implementation
* a
* format and make it stabel compatible
* Add mixin to game
* fixes
* add tests
* format
* docs
* more docs
* Update doc/keyboard-input.md
Co-authored-by: Erick <erickzanardoo@gmail.com>
* rename test
* Apply suggestions from code review
Co-authored-by: Luan Nico <luanpotter27@gmail.com>
* fix test
* Update tutorials/2_sprite_animations_gestures/README.md
Co-authored-by: Luan Nico <luanpotter27@gmail.com>
* docs
* Apply suggestions from code review
Co-authored-by: Jochum van der Ploeg <jochum@vdploeg.net>
* yo
Co-authored-by: Erick <erickzanardoo@gmail.com>
Co-authored-by: Luan Nico <luanpotter27@gmail.com>
Co-authored-by: Jochum van der Ploeg <jochum@vdploeg.net>
