Add VolumeStream API

[gabizou]

SpongeAPI | SpongeCommon

Merrily Merrily Merrily, Life is but a dream Stream

Volumes enjoy some abstract sense of their knowledge of what sort of entities they contain, and while in the previous major version of SpongeAPI, we had something called BlockWorker, it isn't necessary to have non-generified "Workers" that effectively contained a pre-compiled set of operations to perform on a pre-compiled dataset to apply later, and the trouble with them in the past was that it wasn't possible to virtually "extend" them outside of their purview of a "Block worker works on blocks" and a Biome worker works on biomes" with some operations.

The end result is embracing Java 8's Stream API and some more functional programming concepts to a stream of data to effectively keep the idea of "Here's a stream of things that you can change their output of and then apply them to somewhere else."

Huh? Streams? Outputs? Apply???

(I'm putting a pause on finishing this doc, because while I do want to explain it more thoroughly, it is half past midnight and I need to sleep).

[Yeregorix]

I love the idea of facilitating mirrors and rotations and I have few suggestions:

1. Mirrors is missing UP_DOWN.

2. Rotations is missing FRONT, BACK, FRONT_LEFT, FRONT_TOP, etc.

3. I find LEFT, RIGHT, FRONT and BACK names confusing because these are relative. My right is not the same as your right if you stand in front of me. In the same way I'm not sure of what LEFT_RIGHT means in a 3D world. I would prefer absolute values such as WEST, EAST, NORTH, SOUTH, like there are in other places in the API.

4. About Rotations, CLOCKWISE_90 is unclear whether it's around x, y, or z axis. I guess it's around y but then what about other axes? Why not allow such rotations? A solution could be to define X_CLOCKWISE_90, Y_CLOCKWISE_90 and Z_CLOCKWISE_90.

5. I find Rotation, Orientation and Direction classes to be redundant. Moreover, from a mathematical point of view, there is already a perfect class to represents these things: Quaterniond. Replacing these 3 classes with Quaterniond would solve (2. 3. and 4.).

EDIT: Quaterniond might not be as easy to use as Direction for simple things so keeping a single catalog type wrapping Quaterniond is a solution too.

[dualspiral]

Mirrors is missing UP_DOWN.

I find LEFT, RIGHT, FRONT and BACK names confusing because these are relative. My right is not the same as your right if you stand in front of me. In the same way I'm not sure of what LEFT_RIGHT means in a 3D world. I would prefer absolute values such as WEST, EAST, NORTH, SOUTH, like there are in other places in the API.

Rather, I think the mirrors should be by axis. X_AXIS, Y_AXIS and Z_AXIS would make a lot more sense (but only if x/y/z directional data is included with such things, which I'd expect they are).

Rotations is missing FRONT, BACK, FRONT_LEFT, FRONT_TOP, etc.

Do you mean Orientation? That's intentionally a 2D orientation of an object with a notion of its own orientation relative to something else (Item in an item frame, which way does it point relative to normal expectations?), it was renamed while @gabizou and I were talking about this API. In that sense, it's not missing that at all.

About Rotations, CLOCKWISE_90 is unclear whether it's around x, y, or z axis. I guess it's around y but then what about other axes? Why not allow such rotations? A solution could be to define X_CLOCKWISE_90, Y_CLOCKWISE_90 and Z_CLOCKWISE_90.

Rotations are a 2D rotation operation with no such information, it's simply a "rotate around something". Yes, you would need to couple this with an axis of rotation, but that's specifically not defined here.

I find Rotation, Orientation and Direction classes to be redundant. Moreover, from a mathematical point of view, there is already a perfect class to represents these things: Quaterniond. Replacing these 3 classes with Quaterniond would solve (2. 3. and 4.).

Sure, but your edit sums it up.

EDIT: Quaterniond might not be as easy to use as Direction for simple things so keeping a single catalog type wrapping Quaterniond is a solution too.

Exactly. In fact, I'd go further and say it's not easy to use for most developers at all because they do not have a mathematical background. I've said it before and I'll say it again, we need to remember them. I would not be in favour of removing these classes for that reason alone.

I'd be up for the idea of being able to create some sort of Transformation from a chain of rotations and translations that is then backed by a quaternion, but that might be creeping out of the scope of this PR.

[Yeregorix]

Rather, I think the mirrors should be by axis. X_AXIS, Y_AXIS and Z_AXIS would make a lot more sense (but only if x/y/z directional data is included with such things, which I'd expect they are).

I do prefer this over LEFT_RIGHT but the mention of "axis" still confuses me because a mirror is a plane symmetry and not an axis symmetry.

Do you mean Orientation? That's intentionally a 2D orientation of an object with a notion of its own orientation relative to something else

I thought everything was in 3D. I didn't understood that Orientation was for item frames, I should have read the changes twice 😅. 2D makes a lot of sense for Orientation in this case.

Rotations are a 2D rotation operation with no such information, it's simply a "rotate around something". Yes, you would need to couple this with an axis of rotation, but that's specifically not defined here.

The method BlockState#rotate(Rotation) doesn't take any axis parameter. Either Rotation should be in 3D, either each rotate method should take an axis parameter. Unless Rotation is used elsewhere I would prefer it to be in 3D.

[gabizou]

Going to just put a foot down that the Mirror and Rotation catalogs are 1:1 mappings for what Minecraft supports us to perform as mirrors and rotations on BlockStates. There's little wiggle room to expand further of "top-down" mirroring or adding other possible rotations that the game engine limits what rotations are available.

[Zidane]

I disagree with these defaults. I always thought that a particular volume holder may have a faster way to query this data instead of going through a provider.

Granted this is a default so not like we can't do that..

[gabizou]

It's a default because the Keys exist and it's often better to delegate to those, however, implementation wise they serve the purpose of bypassing the requirement that we re-implement the actual storage of owner/notifier at this time.