Track structure controller position and add structure sockets

[RecursivePineapple]

This does three things:

• Adds a statically check type-safe block position system, that allows you to move between coordinate systems easily and know your transforms are correct
• Adds code that tracks controller positions (tildes) in structure shape definitions
• Adds 'sockets,' which are essentially fake structure elements that record their position

There are new query methods for controller and socket positions.

The goal of this PR is to reduce the amount of hardcoded numbers in structure implementations.

I tested this in another GT5u PR which should be going up soon. I made sure that multiblocks produced the correct world position for every orientation of a controller.

[Glease]

piece might exist but have no socket. throwing an error would likely cause some headache in downstream repos that needs to introspect a structure e.g. blockrenderer

[RecursivePineapple]

This is meant to be a "assert one and only one socket" type of method. getAllSockets only throws when the piece is missing, but I consider that a logic error regardless of the usage. If something is dynamically scanning for sockets, it should check if the piece exists first (though it doesn't look like that method exists, should I add it?)

[Glease]

doesn't getAllSockets throw when piece have no socket either? you did not eagerly create an entry in socketLocations for every piece. you did so only when it has a socket

[RecursivePineapple]

No, multimaps return an empty collection for keys that don't exist. Since it's a ListMultimap it'll return an empty list.

[Glease]

private final Map<String, ListMultimap<Character, Position>> socketLocations = new HashMap<>();

socketLocations is a HashMap

[RecursivePineapple]

The data is roughly {piece name: {socket char: Position[]}}. The outer piece -> socket map is a hash map, but the socket char -> position map is a multimap. I know it's an ugly unreadable type but I can't think of a way to improve it.

[Glease]

I'm not sure how to convey this better but let's just say this piece of code will throw with an exception saying main is invalid

builder().addShape("main", new String[][] {{"~"}}).build().getAllSockets("main")

[RecursivePineapple]

I figured out what you meant, it should be good now. I added some tests to validate that it's correct.

[Glease]

this is not a full review. just a few thoughts from quickly skimming through the changes

perhaps a few tests as an example of how to use the CoordinateSystem and its subclasses? I know we could always just look at the gt multi that uses it as a reference, but gt5 is quite a volatile repo and things will change without either of us know it.

[RecursivePineapple]

sure, I'll add some tests tomorrow

[RecursivePineapple]

It took me a bit longer than I expected because I had to defer the shape compilation into .build() to simplify the socket code, but everything should be working and tested now.

[Luca-Guettinger]

1 issue with getControllerPosition not copying the internal Position (unlike the socket getters), plus 3 minor nits on dead code and a subtle behavior change.

[Luca-Guettinger]

getControllerPosition returns the internal mutable Position reference. getSocket and getAllSockets both call .copy(), but this doesn't. Since the coordinate system translators mutate positions in place, any caller that transforms the returned position will corrupt the StructureDefinition's internal state. Should return controllers.get(piece).copy() (with a null check) like the socket methods do.

[Luca-Guettinger]

a, b, c are tracked here but never read. Dead stores - the whole isNavigating branch can be removed, the method only needs to map chars to elements.

[Luca-Guettinger]

This check is unreachable. shapes is populated from a HashMap, duplicate keys are impossible.

[Luca-Guettinger]

Deferred compilation means getShapes() now returns an empty map until build() is called. Before this change it was populated during addShape(). Probably nobody depends on this, but it's a subtle behavior change on a public method.