V12 Documentation - Grid API Changes

[dev7355608]

Hello everyone! We are excited to share improvements to the Grid API with you that are coming with Version 12 (Prototype 1).

• Grid API V2 #10088

Please read the issue carefully and join the discussion if you have any questions, suggestions, or concerns.

Why change the API?

The primary reason that initiated the Grid API overhaul was the fact that the hex grid methods weren't actually based on the hexes but on the "brick wall" grid (red).

This is now no longer the case, and so hex grid API has much improved.

New vs. Old Hex Grid Methods

HexagonalGrid#getCenter(x, y) gave (and still gives) you the center point (red) of hex for any point (x, y) in the rectangle (green). So not all points were mapped to the center point of the containing hex. Now the new HexagonalGrid#getCenterPoint(point) maps any point within the hex to its center point. See 10011, 10012, and 10077.

But we didn't stop there and made other grid improvements as well.

Highlight: Alternative Diagonal Rules in Square Grids

Now we support all the different ways to measure diagonals in square grids. Systems are no longer forced to patch the SquareGrid class to implement their system-defined diagonal rule. See 9998.

Highlight: Improved Grid Rendering

We also improved and enhanced grid rendering. Now the grid is rendered by a specialized grid shader that offers different style options (solid lines, dashed lines, dotted lines, square points, diamond points, round points) as well as control over line thickness. These options are configurable in the Scene config). System and modules have the ability to add their own grid styles. See 10003.

Highlight: Improved Grid Snapping

The new BaseGrid#getSnappedPoint(point, behavior) offers much more control of the kind of snapping compared to the old getSnappedPosition(point, interval). Especially grid snapping in hex grids benefited from these changes. Instead of just an interval the snapping behavior is defined by a snapping mode and a grid resolution. See 10014.

const M = CONST.GRID_SNAPPING_MODES;
const snapped = grid.getSnappedPoint(point, {
   mode: M.CENTER | M.VERTEX, // snap to the nearest center point or vertex
   resolution: 2 // the grid resolution
});

Does this affect me?

If you use the Grid API at all, it's very likely that you are affected by these changes because almost the entire previous Grid API is now deprecated.

For the most part, particularly for square grids, you simply need to replace the old methods with the new methods that replace them. In the case of hex grids, however, you have to pay a bit more attention because the new methods will yield different results when compared to the old methods that are still based on the "brick wall" grid. The old methods remain based on the "brick wall" grid in order to prevent breaking existing code that relies on this behavior.

Breaking changes

• BaseGrid is no longer a PIXI.Container and is no longer responsible for drawing the grid. The GridMesh + GridShader render the grid now. See 10003.
• BaseGrid#options has been removed without replacement. See 10089.
• PlaceablesLayer#gridPrecision is deprecated. Custom PlaceablesLayer will need to override getSnappedPoint instead now if they previously defined gridPrecision, which won't have an effect on snapping in the drag workflow anymore. See 10070.
• Token light/sight ranges and template ranges in legacy hex grids (which are hex grids created pre-V10) may not be migrated as desired. Content providers should check whether their scenes still use legacy hex grids (test if canvas.scene.getFlag("core", "legacyHex") is true). Previously the distance-units-to-pixels conversion in legacy hex grids wasn't working correctly, which has been fixed now: it produced results 15.47% larger than they should be compared to grid ruler measurements. After the migration the radius of token light/sight and templates will be shorter, but now actually match the grid ruler measurements. Ambient lights/sounds are migrated such that they cover the same area on the canvas as before: their ranges are increased by 15.47%. See 10132.
• Assuming your system currently overrides SquareGrid#measureDistances to change the grid measurement in square grids you now set the system default diagonal rule in the system manifest instead. If alternative square grid measurements was a feature of your module, you can now remove this feature: the user can select their preferred diagonal rule via the world setting "Square Grid Diagonals". See 9998.
• The GridHex constructor signature and the type of GridHex#offset had to be changed. See 10082.