feat: PositionComponent now has a built-in Decorator

[st-pasha]

Description

This PR adds the decorator property to PositionComponent, and makes decorators chain-able. That is, decorators function as linked lists, and a new decorator can be appended to the end of such list, and later removed.

The PositionComponent starts with the default decorator: the Transform2DDecorator, which encapsulates the functionality which previously resided within the PositionComponent.renderTree. This allows to:

• apply/remove additional visual effects via .decorator.addLast()/.removeLast();
• replace the Transform2DDecorator with another one -- for example supporting skew, or isometric coordinates, or 3d rotations.

HasDecorator mixin can no longer be applied to a PositionComponent because it already has the decorator "built in".

The decorators Shadow3DDecorator and Rotate3DDecorator, when added to the PositionComponent, will now apply after the coordinate transform of the PositionComponent, as desired. This means that, for example, the shadow's base and rotation pivot point can be specified using the local coordinates of the component.

Checklist

• The title of my PR starts with a Conventional Commit prefix (fix:, feat:, docs: etc).
• I have read the Contributor Guide and followed the process outlined for submitting PRs.
• 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.

Breaking Change

• [-] Yes, this is a breaking change.
• No, this is not a breaking change.
  • This is non-breaking compared to the last released version, but it does change the functionality that currently exists in main.

Related Issues

Closes #1829

[spydon]

Hmm, why have it set up as a linked list? Seems like quite a normal usecase that you'd want to remove, add or swap a decorator in the middle of the chain? Couldn't it just be a normal list, will it really be that much less performant?

[st-pasha]

For the linked list it's pretty straightforward to define methods to add/remove/replace elements in the middle, if needed. So we're not sacrificing any functionality there.

At the same time, the most common use-case is when there are no additional decorators, so the linked list with a single null pointer will be more efficient in this case than a regular list of length 1 (which is likely to have some initial capacity > 1).

In addition, a linked list makes it much easier to call the decorators recursively (each decorator wraps the output of subsequent decorators).

[spydon]

For the linked list it's pretty straightforward to define methods to add/remove/replace elements in the middle, if needed. So we're not sacrificing any functionality there.

At the same time, the most common use-case is when there are no additional decorators, so the linked list with a single null pointer will be more efficient in this case than a regular list of length 1 (which is likely to have some initial capacity > 1).

In addition, a linked list makes it much easier to call the decorators recursively (each decorator wraps the output of subsequent decorators).

Makes sense, could these methods be added in this PR? Or should that be done separately?

[st-pasha]

could these methods be added in this PR? Or should that be done separately?

I'd prefer not to overburden the PR with functionality that is not needed for it. These methods can be added later as the need arises.

[spydon]

Lgtm, but aren't there docs missing?

[st-pasha]

True, i'll add some