Primarily this PR is completing Step 5 of Flame's Klondike Tutorial and removing the tbc.md file ("To be continued...").
As at the end of Step 4, the Klondike Game had no animation, other than the drag-and-drop moves to play the game. It also had no ways to detect a win, react to a win or play again without re-loading and re-running the whole app. Step 4 played the Klondike Draw 3 variation of Klondike. Step 5 introduces the easier Klondike Draw 1 variation and provides buttons to:
Choose between Draw 1 and Draw 3,
Start the game again with a new deal, or
Start again with the same deal as before.
The new code and step5.md tutorial text cover Effects and EffectControllers in some detail, with complex examples of their use. The animations include:
Returning dropped but misplaced cards to the places they came from,
Settling dropped and validly placed cards into position,
Flipping cards from Stock Pile to Waste Pile,
Turning cards over on the Tableau piles when the cards above them are moved away,
Collecting multiple cards when the game is over,
Dealing and re-dealing multiple cards,
Allowing a card to be auto-moved onTapUp() to its Foundation Pile if it is ready to go out,
Providing a display of moving cards when/if the player wins.
Previously, as part of Issue #2798, I fixed the Klondike Tutorial app's
step4 executable to use the Flame 1.9.x `world` and `camera` built-in
objects and described the new code in the Step 2 tutorial, where it
first appears in the discussion. However, the Step 2 and Step 3 tutorial
texts have options to execute code and those did not include the new
code. Accordingly, I have cloned the relevant code into
`app/lib/step2/klondike_game.dart` and
`app/lib/step3/klondike_game.dart`. I have also checked that there are
no `*.md` files to be updated. The `step2.md` tutorial file covers Issue
#2799 AFAICS.
Firstly, (re Issue #2799) Flame 1.9.x broke the Klondike Tutorial, which was not set up to use the new built-in world and camera. So I modified the KlondikeGame's onLoad() code to use the built-in world and camera and no longer create its own World and CameraComponent. I also updated the step2.md documentation file, which instructs new users of Flame on how to use the world and the camera, how to set up a game-oriented co-ordinate system and how to fit it into the device screen.
Secondly, (re Issue #2798) Klondike was not adhering to the design stated in the Tutorial, that all 52 Card objects would be owned by the KlondikeGame. During the shuffle and deal sequence it was using removeLast() on the List\<Card\>cards, where the cards are kept, the result being that only 24 of the 52 cards were left in the list after the deal. I have fixed the bug and updated the Tutorial documentation (step4) which discusses how the deal is coded.
This bug does not affect the gameplay as it stands, but it does block the way to future features at the game level, such as an option to re-deal or a win-animation where all cards fly off the screen.
It doesn't make any sense for HasGameReference to have Game as a base instead of FlameGame since the mixin is on Component and clearly in a component tree context, so this PR sets the base to be FlameGame (like HasGameRef).
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.
I have just finished steps 1-4 of the Klondike tutorial and noticed a
couple of minor things that look to be outdated with the current dart /
flame versions.
### Step 3 - `late` keyword isn't required
When following this step the analyser hightlight this rule
[unnecessary_late](https://dart.dev/tools/linter-rules/unnecessary_late)
(introduced in Dart 2.16.0) which states:
> Top-level and static variables with initializers are already evaluated
lazily as if they are marked late.
I updated the notes around why the laziness is important so the reader
can still understand the reasoning.
It just removes a deprecated line that is in the tutorial for building a Klondike game. The final code does not have it and it is no longer necessary to have it in the KlondikeGame class.
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
```
fixing link to bare flame tutorial
<!--
The title of your PR on the line above should start with a [Conventional
Commit] prefix
(`fix:`, `feat:`, `docs:`, `test:`, `chore:`, `refactor:`, `perf:`,
`build:`, `ci:`,
`style:`, `revert:`). This title will later become an entry in the
[CHANGELOG], so please
make sure that it summarizes the PR adequately.
-->
# Description
<!--
Provide a description of what this PR is doing.
If you're modifying existing behavior, describe the existing behavior,
how this PR is changing it,
and what motivated the change. If this is a breaking change, specify
explicitly which APIs were
changed.
-->
## Checklist
<!--
Before you create this PR confirm that it meets all requirements listed
below by checking the
relevant checkboxes with `[x]`. If some checkbox is not applicable, mark
it as `[-]`.
-->
- [ ] I have followed the [Contributor Guide] when preparing my PR.
- [ ] I have updated/added tests for ALL new/updated/fixed
functionality.
- [ ] I have updated/added relevant documentation in `docs` and added
dartdoc comments with `///`.
- [ ] I have updated/added relevant examples in `examples` or `docs`.
## Breaking Change?
<!--
Would your PR require Flame users to update their apps following your
change?
If yes, then the title of the PR should include "!" (for example,
`feat!:`, `fix!:`). See
[Conventional Commit] for details. Also, for a breaking PR uncomment and
fill in the "Migration
instructions" section below.
### Migration instructions
If the PR is breaking, uncomment this header and add instructions for
how to migrate from the
currently released version to the new proposed way.
-->
- [ ] Yes, this PR is a breaking change.
- [x] No, this PR is not a breaking change.
## Related Issues
<!--
Indicate which issues this PR resolves, if any. For example:
Closes#1234
!-->
<!-- Links -->
[Contributor Guide]:
https://github.com/flame-engine/flame/blob/main/CONTRIBUTING.md
[Conventional Commit]: https://conventionalcommits.org
[CHANGELOG]:
https://github.com/flame-engine/flame/blob/main/CHANGELOG.md
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.
# Description
This does two things:
## Use double quotes for SDK constraints
Standardize the usage of single or double quotes to specify sdk
constraints across pubspecs
I see no reason this should not be kept consistent
I also see no reason to prefer one over the other, so I searched the
code base and there are 7 instances of single quote vs 32 of double
quotes, so I favored the later
## Update all SDK constraints to 2.18
Let me know if there are any issues with it, but I believe we should
keep this consistent across all packages.
Also there is a pubspec on root which imply all should be on 2.18
anyway.
## Checklist
- [x] I have followed the [Contributor Guide] when preparing my PR.
- [x] I have updated/added tests for ALL new/updated/fixed
functionality.
- [x] I have updated/added relevant documentation in `docs` and added
dartdoc comments with `///`.
- [x] I have updated/added relevant examples in `examples` or `docs`.
## Breaking Change?
- [ ] Yes, this PR is a breaking change.
- [x] No, this PR is not a breaking change.
<!-- Links -->
[Contributor Guide]:
https://github.com/flame-engine/flame/blob/main/CONTRIBUTING.md
[Conventional Commit]: https://conventionalcommits.org/
[CHANGELOG]:
https://github.com/flame-engine/flame/blob/main/CHANGELOG.md
Co-authored-by: Lukas Klingsbo <me@lukas.fyi>
At the *Other classes* session, when it is mentioned that we need to
create the `components` sub-directory, the tutorial is guiding us to add
it in the root, but on the structure below, it is possible to see that
it should be created inside the `libs` folder instead.
It seems to be better to be more explicit in this paragraph.
This PR is first in a series of refactors that aim to simplify event handling in Flame. The approach is as follows:
Added class GestureDetectorBuilder, which encapsulates the logic of applyGestureDetectors() in a class. This class resides within the Game and initiates widget rebuild whenever any new gesture detectors are added or removed. Note:
[idea] Convert HasTappableComponents/HasDraggableComponents into classes #1733 suggests having a list of interfaces inside the Game class -- this is essentially that list, encapsulated in a class.
Added the MultiDragDispatcher component, which contains the logic that used to be within the HasDraggableComponents mixin. This component is internal; it mounts to a FlameGame directly, and ensures that it is a singleton.
Whenever any DragCallbacks component is added to a game, it automatically adds the MultiDragDispatcher component (unless there is already one), which in turn registers a drag gesture detector with GestureDetectorBuilder and rebuilds the game widget.
The end result is that now in order to make a component draggable you only need to add the DragCallbacks mixin to that component, everything else will be handled by the framework.
Consequently, the HasDraggableComponents mixin is now empty and marked as deprecated.
As discussed previously, this PR moves the Space Shooter Tutorial to the tutorials folder for direct inclusion in the docs. A few things to note, other than basic grammar and formatting, nothing was changed other than migrating the information to the current tutorial format. This should allow the tutorials.flame-engine.org subdomain to be deleted.
Note: Upon moving this tutorial, I discovered it is incomplete and missing the majority of the game.
Also, I realized that I left the android folder and some files that weren't necessary for the platform tutorial and have deleted those.
This PR adds a new event system based on the componentsAtPoint delivery mechanism. These events allow for a proper support of components that implement renderTree() method. The CameraComponent is one such component, with more planned in the future.
Additionally, the following improvements compared to the current tap events added:
- the same component can be tapped with multiple fingers simultaneously;
- a component that received onTapDown is guaranteed to receive onTapUp or onTapCancel later;
- a component that moves away from the point of touch will receive onTapCancel instead of onTapUp (even though the game widget receives onTapUp from Flutter).
Due to the fact that the switch from the current event system to the new event system is potentially a significant breaking change, the new event system is introduced as parallel to the existing one. This way we have more time to test the new system before recommending the switch and deprecating the old one; and the switch itself should feel more gradual.
