Vector2 and Vector3 mutability is not self-documented. This is unclear in program design.

For performance reasons, it is possible to want to make a vector mutable.
For API design reasons, it is possible to want to make a vector immutable.

This issue proposes the separation of mutability from the vector classes.

See https://medium.com/@elye.project/read-only-collection-in-kotlin-leads-to-better-coding-40cdfa4c6359 for a similar discussion about kotlin collections.

Fatal error: During inheritance of ArrayAccess: Uncaught ErrorException: Return type of pocketmine\math\Matrix::offsetGet($offset) should either be compatible with ArrayAccess::offsetGet(mixed $offset): mixed, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in phar:///home/pmmp/crash/PocketMine-MP.phar/vendor/pocketmine/math/src/Matrix.php:43

PocketMine-MP version: 4.7.3 [Protocol 544]
Git commit: pmmp/PocketMine-MP@b5a049d
PHP version: 8.1.9
OS: Linux, linux

Composer libraries:

• pocketmine/math 0.4.2@ aacc375

No one expects the manipulation methods of AxisAlignedBB to alter the AABB directly. Allowing this is also a headache.

We already don't use Vector3 as mutable since PM 4.0.

In PHP 8.1, it's possible to use readonly to make all of the properties immutable. In 8.2, we'll be able to make whole classes readonly, but that also prevents inheritance by non-readonly classes.

It may be useful to specify the expected return type of Facing functions with: value-of<Facing::ALL>.

This can break many static analyses, because depending on the PHPstan levels, it will carry over if you pass a simple integer into a function accepting just a few values.

I think this option is worth considering, as it could prevent certain runtime errors in the event of an unaccepted value being supplied?

This issue should be updated to include lists of specific things that should be tested against.

so i was testing the faces from Ray Trace result returns using a pearl no matter from where i throw the pearl the faces will always return Down Side (0) or North Side (2), is it supposed to be like that or that just a bug todo with calculateIntercept in boundingBoxes?

Currently they are limited to integers. There's no obvious purpose to restricting them to integers.

Rotating Facing::UP or Facing::DOWN around the Axis::Y could just return the facing unchanged, instead of throwing an exception, and this would be valid.

Rotating an axis around itself does not change the positions of the ends of any line segment taken from it.

Changes like pmmp/PocketMine-MP#4591 would be much more cleanly implemented if AxisAlignedBB had something like shift(Facing $towards, float $distance).

A zero vector cannot be normalized. Returning a zero vector for normalized zero vector is unexpected and creates interesting bugs (so far, this has usually been seen in conjuction with NAN for yaw/pitch in PocketMine-MP).

An exception should be thrown in this case instead.