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.
when overflow-y, the scroll will be enabled on hover that makes us
scroll through the contents and click what's below
# Description
Initially, the contents section (the right side nav) doesn't scroll when
overflow. This PR adds the functionality to scroll when it overflows
vertically.
Working video:
https://user-images.githubusercontent.com/40348358/227519288-805ae943-0c23-4220-8224-fec168bae599.mov
### a small case to consider
This commit had some complications like having to compromise with having
shrink width. It doesn't much shrink, but does slightly does.
Before this PR:
<img width="1237" alt="Screenshot 2023-03-24 at 17 43 18"
src="https://user-images.githubusercontent.com/40348358/227519653-84c503a2-8ab4-460a-96b7-17c31d60ce62.png">
After this PR:
<img width="1238" alt="Screenshot 2023-03-24 at 17 42 54"
src="https://user-images.githubusercontent.com/40348358/227519701-bce512d7-e6df-459b-a3a1-5762a05f2934.png">
But, I am thinking this can be considered as the readability isn't
effected much as this sidebar only is visible when there is enough space
(more width).
## 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 `[-]`.
-->
- [x] 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?
- [-] Yes, this PR is a breaking change.
- [x] No, this PR is not a breaking change.
## Related Issues
Closes#2423
As mentioned in discord, the current build of the docs loses jQuery
functionality. This is due to sphinx being upgraded to version 6 in
which they removed jQuery and created a stand-alone package for it.
Additionally, in the process of doing that, I noticed the previously
mentioned fix (in the comments) for the `melos doc-setup` about removing
the single quotes to keep it clean didn't make into the final code. I
have updated that as it was previously confirmed to work on all
platforms in: https://github.com/flame-engine/flame/pull/2401
I noticed that the copyright that was in the `conf.py` was locked at
2021 and so I made it go to 2023 as well. This can be removed if not
desired, but thought maybe this had just been overlooked.
Finally, there was an error regarding a duplicate instantiation of a
constant. This had to do with the fact the basic theme provided with
sphinx, the next version after which the docs were based, had a bug fix
implemented:
https://www.sphinx-doc.org/en/master/changes.html#release-5-1-0-released-jul-24-2022.
In their fix, it also broke the way the flames theme works. On a side
note, the docs are using a very outdated version of the basic theme and
should likely be overhauled, but that is outside the scope of this pr.
None the less, after I finally figured out how the basic theme is
inherited and where that lived on my machine, I was able to resolve the
discrepancies and eliminate the conflicting names between the two
themes.
In short, all errors have been resolved and I have confirmed that
mobile, web, search, highlighting, menus, etc. all work - at least on my
machine.
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.
This fixes a problem that we accidentally introduced in a recent PR: the
`shell=True` setting requires that the arguments were passed as a single
string instead of a list. Passing as a string, in turn, is somewhat
problematic because the file names need to be escaped, and there is no
utility function to make this escaping cross-platform.
So, instead we'll use the standard `shell=False`, and invoke
`dartdoc_json.bat` on Windows instead of simply `dartdoc_json`. Hope
this would work.
Embedded flutter-app joints examples didn't work, because flutter-app script expects the example page to be located in the lib folder of a module. Introduced a new subfolder param, to specify where to find the example page.
Verified joints examples apps and code button on the doc page work; Also verified the same for the effects page.
As mentioned in #2395, there are several lingering issues that can be solved by bumping the Python package requirements up. All packages need / can run on Python 3.8+, so the docs do not need to be updated regarding that.
This PR specifically fixes the following warnings:
flame\doc\bridge_packages\bridge_packages.md:4: WARNING: 'myst' reference target not found: ..\bridge_packages\flame_audio\flame_audio.md
....There were a lot of those....
`attrs_image` is deprecated. Use `attrs_inline` instead.
Additionally, this PR adds a new command melos doc-kill which executes the kill-server.py script. This script relies on psutil which has been added to the requirements.txt, but allows a cross platform ability to isolate and kill process threads that are locking the port 8000. This commonly happens when you exit melos doc-serve and the internal web server doesn't die as well. This may not be an issue for Unix platforms, but for Windows users its extremely annoying.
The only alternative for Windows users is to manually do:
netstat -ano | findstr :8000
// Then run:
taskkill /PID XXXXX /F
As I mentioned in the other PR, I split this out so it can be debated mainly for the bump in requirements; however, I feel the benefits are very worth it. I marked this as breaking just because it changes the base package requirements and adds a package which may not qualify as breaking, depending on how you look at it.
Edit: Forgot that this PR also fixes a typo in the melos doc-serve description and corrects the misspelling of everytime to every time.
<!--
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.
-->
@eukleshnin identified issues with building the documents locally on a
Windows workstation. Namely, the following was occurring:
```
reading sources... [ 2%] flame/layout/align_component
Exception occurred:
FileNotFoundError: [WinError 2]
```
This was determined to be a combination of several things.
1. In `dart_domain.py`, the `subprocess.run` calling dartdoc_json did
not have the shell parameter set to true. This solves the error about
the file not being found. This then generates errors that subsequent
references to the `temp_file` did not exist.
2. This was due to the default setting with Python `tempfile` where when
it determines the temp file has been closed, it deletes it; however, it
was still needed, so by setting the `delete=False` parameter, the file
would still remain.
3. Unfortunately, because it still remains, it needs to be deleted once
it is no longer needed. Trying to use `finally:` with the `try` block
failed to produce the results desired, so the temp file name was
registered with the class so it can be deleted in the original calling
function if it exists. This proved successful.
4. Although not critical, the same temp file uses a suffix of `json` so
it was creating files `xxxxjson`. By adding the "." in the suffix, it
creates valid file names now. This doesn't actually fix anything, it
just seemed wrong, so I fixed it to be valid files if ever needed down
the road.
Now that the docs built, there were several warnings that could be
resolved:
1. `Overlays.md` was not referenced in the TOC tree.
2. Since overlays were removed in
https://github.com/flame-engine/flame/pull/2384, the Platformer tutorial
had a link to the old path and it needed to be updated.
Finally and open for discussion, during this process of debugging, I
upgraded all packages to the most current to see what impacts there
were. The following is the old and new potential `requirements.txt`:
```
----Old
linkify-it-py==2.0.0
myst-parser==0.18.1
Pygments==2.12.0
Sphinx==5.0.2
sphinxcontrib-mermaid==0.8.1
sphinx-autobuild==2021.3.14
jinja2==3.1.2
----- New
linkify-it-py==2.0.0
myst-parser==1.0.0
Pygments==2.14.0
Sphinx==6.1.3
sphinxcontrib-mermaid==0.8.1
sphinx-autobuild==2021.3.14
Jinja2==3.1.2
```
The only byproduct of this upgrade was a deprecated package warning for
`attrs_image` in `conf.py` which was updated to `attrs_inline`. I made
that change initially for this PR, but backed it out as I didn't know if
there was a desire to update the `requirements.txt` and felt some
discussion may be warranted.
Regardless, with everything upgraded or left as is, the other fixes
resolve the issues on Windows.
## 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 `[-]`.
-->
- [X] I have followed the [Contributor Guide] when preparing my PR.
- [ ] 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 `///`.
- [ ] 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
---------
Co-authored-by: Lukas Klingsbo <me@lukas.fyi>
This PR adds first layout component: AlignComponent, an equivalent of Align widget in Flutter.
AlignComponent sizes itself to its parent, and then keeps its child aligned to the specified anchor within its own bounding box.
Also adding onParentResize() lifecycle method, which is similar to onGameResize, but fires whenever the parent of the current component changes its size for any reason. (FlameGame is assumed to have the size canvasSize, and will invoke onParentResize whenever the canvas size changes).
Additional layout components are planned to be added in future PRs.
The docs for overlays were a bit hard to find so I broke them out to its
own section.
They could need some some updating too with more examples and
instructions.
# 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>
The link went directly to the Flame channel instead of being an invite link to the server, so it didn't work for people that weren't already on the server.
This PR ensures that all component rebalancing operations are resolved from a single location, after the update stage but before the render stage (thus, components may get reordered during the update, and these changes will go into effect during the rendering step on the same game tick).
This also fixes the problem where the child changing the priorities of its parent would cause a ConcurrentModificationError.
A number of methods that were used to handle rebalancing are now marked as deprecated. From the user's perspective, the only API they should be using is the .priority setter.
This fixes the regression with that the graphs aren't rendering.
Unfortunately they will forever be broken in the v1.6.0 release of the
docs now.
Fix comes from here:
2eaff4220a
The grid position variable is non-private: gridPosition in the PlatformBlock class definition but was used as private: _gridPosition in the onLoad method.
This PR updates the grid position variable in the onLoad to gridPosition.
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.
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.
Component removal is now handled via the ComponentTreeRoot class and its queue of lifecycle events.
The onGameResize event now only fires before the component's onMount, but not before its onLoad.
Migration instructions
If you have components that rely on receiving onGameResize calls before they load, then
you can retrieve the game's size in onLoad manually via findGame()!.size.
As I mentioned on #2310 (comment),
it's inevitable to create an atlas that has 2x width from the original one to support flip, it could bring some limitations. So it would be great to opt out the flip.
Here's the reason why this is needed.
Flip may impact performance if the composed tileset(AKA texture) is big.
The software tiled has shortcuts to go back by cmd(ctrl)-z, rotating by z, and flipping horizontally by x. Imagine that you clicked a tile to the wrong place, you may press cmd-z and so on. In this situation, you can also accidentally press z or x, and as a result, the tile flips! It is fine with some complicated or flip(rotate)-consiousable tiles. But some things like the floor or sky are hard to recognize. I even made a program for my design team to pick out coordinates of where the flipped tiles exist but often there are flips. So, providing a way by simple boolean argument may prevent this.
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.
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.
In Sphinx, there is a concept of a "domain", which enables documenting library object such as classes and functions, and then referencing them from any other place in the documentation. This PR adds such a domain for the Dart language.
With the new approach, a class/function can be documented using the following directive:
```{dartdoc}
📦 flame
:symbol: GameWidget
:file: src/game/game_widget/game_widget.dart
```
The documentation will then be automatically extracted from the referenced file using the dartdoc_json tool (published as a separate package), and then rendered inside the page. The screenshot below shows an example of how DialogueRunner class from Jenny would be rendered:
<image>
Once a symbol has been documented using the dartdoc directive, it can be referenced from other places in the documentation as
{ref}`DialogueRunner`
