Set up a method of generating and accessing a relative depth buffer.

A potential internal implementation could involve an upwards and downwards relative depths, each stored simply as int[<vertical world size>] which would just contain relative depths for each Y level per X-Z column. This could be created via TerraChunkGenerator#generateChunkData, centered around the sample > 0 evaluation. There could also be multiple ways of storing and or accessing these buffers, such as a 2D list, where each depth gets assigned a list of Y levels, allowing for quickly retrieving every surface block (where depth = 1).

YAML 'visualization'

downwards:
  depths-per-height:
    - 0 # y = 255
    - 1
    - 2
    - 3
    - 0 # y = 251
  heights-per-depths:
    - [1, 2, 3, 4, ..] # Depth = 0
    - [5, 8, ...]      # Depth = 1
    ...
upwards:
  depths-per-height:
    - 0 # y = 255
    - 3
    - 2
    - 1
    - 0 # y = 251
  ...

This may be a useful feature for both optimization, and functionality. For example, the pull() TerraScript function could be further optimized to retrieve data from the depth buffer with a method akin to NavigableMap#floorEntry(), rather than running a for loop which makes calls to Block#isEmpty(). Tree Configs and Flora Configs could have an option to only place on surface blocks, reducing the number of unnecessary script executions and block checks respectively by reading from the depth buffer first. Basically a lot of stuff that involves up/down surfaces or involves world checks could probably benefit from this.

Add a set of TerraScript functions which provide access to these buffers, notably for locating nearby 'surface blocks'.

One potential use-case is for structure scripts that need to be placed on the surface, and or need to know where the surface is. This is fine for singular checks, but for more involved scripts, this can get both cumbersome and with slow with poor script implementations.

Having an integrated TerraScript method of accessing terrain depths, and searching for the nearest surface block would provide more power and convenience to pack devs without having to do janky script based checks, and potentially allow for some optimizations to be made.

Access to these buffers would come in the form of various retrieval methods:

• Depth of block

  Return the relative depth (upwards or downwards) of block at Y level within buffer depth buffer.

• List all blocks with depth = N

  Return a list of Y levels which have a certain depth, could be retrieved from the 2D list explained above.
  Useful for applications such as features that should only be placed on top of ground.

• Vertical distance from coordinate to surface block

  Variations of searching for surface blocks:

  • Closest floor block

    A floor block would simply be a block with a relative downwards depth of 1, a list of which could be retrieved from List all blocks with depth = N.
    This would involve finding the nearest floor block inside the downwards buffer, whether that is above or below the specified block.

    • Closest floor block below coordinates

      Same as above but only searching downwards, akin to NavigableMap#floorEntry()

  • Closest ceiling block

    Same as floor block, but with upwards depths instead.

    • Closest ceiling block above coordinates