Update version and docs

CONTRIBUTING.md

@@ -43,6 +43,16 @@ We use Godot's clang-format hooks that will format your code upon making a commi
 
 We use the standard [Godot PR workflow](https://docs.godotengine.org/en/stable/contributing/workflow/pr_workflow.html). Please submit PRs according to the same process Godot uses.
 
+This includes: 
+* Creating a new branch (not main) before submitting the PR.
+* Never using git merge, or the `sync` button. Only fetch, push, pull.
+* To update your PR to the latest main, rebase it then force push into your branch.
+  * `git pull --rebase upstream main`
+  * `git push -f`
+
+Read the guide above for more details.
+
+
 ## Code Style
 
 ### GDScript

Terrain3D.vcxproj.filters

@@ -301,7 +301,7 @@
       <Filter>4. Shaders</Filter>
     </Text>
     <Text Include="doc\_new_release_process.txt">
-      <Filter>2. Docs</Filter>
+      <Filter>1. Project Files</Filter>
     </Text>
   </ItemGroup>
   <ItemGroup>

doc/_new_release_process.txt

@@ -1,9 +1,9 @@
 Setting up a new release in Terrain3D
 ------------------------------------------
 
-If Storage has changed format:
-* Set src/terrain_3d_storage.h : CURRENT_VERSION
-* Update docs/storage_format.md
+If Data has changed format:
+* Set src/terrain_3d_data.h : CURRENT_VERSION
+* Update docs/data_format.md
 
 Upgrade to new release version:
 * Set src/terrain_3d.h : _version

doc/api/class_terrain3dassets.rst

@@ -334,6 +334,8 @@ Returns the array of all uv scale values used in the texture assets, indexed by
 
 Saves this texture list resource to disk, if saved as an external ``.tres`` or ``.res`` resource file.
 
+path - specifies a directory and file name to use from now on.
+
 .. rst-class:: classref-item-separator
 
 ----

doc/api/class_terrain3ddata.rst

@@ -246,7 +246,7 @@ Emitted when the region map or any map array has been regenerated.
 
 **maps_edited**\ (\ edited_area\: :ref:`AABB<class_AABB>`\ ) :ref:`🔗<class_Terrain3DData_signal_maps_edited>`
 
-This signal is emitted whenever the editor is used to:
+This signal is emitted whenever the editor (:ref:`Terrain3DEditor<class_Terrain3DEditor>`) is used to:
 
 - add or remove a region
 
@@ -491,7 +491,7 @@ R16 or exr are recommended for roundtrip external editing.
 
 R16 can be edited by Krita, however you must know the dimensions and min/max before reimporting. This information is printed to the console.
 
-Res/tres allow storage in any of Godot's native Image formats.
+Res/tres stores in Godot's native data format.
 
 .. rst-class:: classref-item-separator
 

doc/api/class_terrain3dmaterial.rst

@@ -62,6 +62,8 @@ Properties
    +------------------------------------------------------------------+------------------------------------------------------------------------------------------+-----------+
    | :ref:`bool<class_bool>`                                          | :ref:`show_heightmap<class_Terrain3DMaterial_property_show_heightmap>`                   | ``false`` |
    +------------------------------------------------------------------+------------------------------------------------------------------------------------------+-----------+
+   | :ref:`bool<class_bool>`                                          | :ref:`show_instancer_grid<class_Terrain3DMaterial_property_show_instancer_grid>`         | ``false`` |
+   +------------------------------------------------------------------+------------------------------------------------------------------------------------------+-----------+
    | :ref:`bool<class_bool>`                                          | :ref:`show_navigation<class_Terrain3DMaterial_property_show_navigation>`                 | ``false`` |
    +------------------------------------------------------------------+------------------------------------------------------------------------------------------+-----------+
    | :ref:`bool<class_bool>`                                          | :ref:`show_region_grid<class_Terrain3DMaterial_property_show_region_grid>`               | ``false`` |
@@ -412,6 +414,23 @@ Albedo is a white to black gradient depending on height. The gradient is scaled
 
 ----
 
+.. _class_Terrain3DMaterial_property_show_instancer_grid:
+
+.. rst-class:: classref-property
+
+:ref:`bool<class_bool>` **show_instancer_grid** = ``false`` :ref:`🔗<class_Terrain3DMaterial_property_show_instancer_grid>`
+
+.. rst-class:: classref-property-setget
+
+- |void| **set_show_instancer_grid**\ (\ value\: :ref:`bool<class_bool>`\ )
+- :ref:`bool<class_bool>` **get_show_instancer_grid**\ (\ )
+
+Draws the 32x32m cell grid on the terrain, which shows how the instancer data is partitioned.
+
+.. rst-class:: classref-item-separator
+
+----
+
 .. _class_Terrain3DMaterial_property_show_navigation:
 
 .. rst-class:: classref-property
@@ -614,6 +633,8 @@ Returns the RID of the built in shader used with the Rendering Server. This is d
 
 Saves this material resource to disk, if saved as an external ``.tres`` or ``.res`` resource file.
 
+path - specifies a directory and file name to use from now on.
+
 .. rst-class:: classref-item-separator
 
 ----

doc/api/class_terrain3dmeshasset.rst

@@ -54,6 +54,8 @@ Properties
    +---------------------------------------------------------------------------+-------------------------------------------------------------------------------+-------------------+
    | :ref:`PackedScene<class_PackedScene>`                                     | :ref:`scene_file<class_Terrain3DMeshAsset_property_scene_file>`               |                   |
    +---------------------------------------------------------------------------+-------------------------------------------------------------------------------+-------------------+
+   | :ref:`float<class_float>`                                                 | :ref:`visibility_range<class_Terrain3DMeshAsset_property_visibility_range>`   | ``1024.0``        |
+   +---------------------------------------------------------------------------+-------------------------------------------------------------------------------+-------------------+
 
 .. rst-class:: classref-reftable-group
 
@@ -82,37 +84,37 @@ Methods
 Signals
 -------
 
-.. _class_Terrain3DMeshAsset_signal_cast_shadows_changed:
+.. _class_Terrain3DMeshAsset_signal_file_changed:
 
 .. rst-class:: classref-signal
 
-**cast_shadows_changed**\ (\ ) :ref:`🔗<class_Terrain3DMeshAsset_signal_cast_shadows_changed>`
+**file_changed**\ (\ ) :ref:`🔗<class_Terrain3DMeshAsset_signal_file_changed>`
 
-Emitted when :ref:`cast_shadows<class_Terrain3DMeshAsset_property_cast_shadows>` is changed on this mesh asset.
+Emitted when :ref:`scene_file<class_Terrain3DMeshAsset_property_scene_file>` is changed, or if the generated mesh is toggled.
 
 .. rst-class:: classref-item-separator
 
 ----
 
-.. _class_Terrain3DMeshAsset_signal_file_changed:
+.. _class_Terrain3DMeshAsset_signal_id_changed:
 
 .. rst-class:: classref-signal
 
-**file_changed**\ (\ ) :ref:`🔗<class_Terrain3DMeshAsset_signal_file_changed>`
+**id_changed**\ (\ ) :ref:`🔗<class_Terrain3DMeshAsset_signal_id_changed>`
 
-Emitted when :ref:`scene_file<class_Terrain3DMeshAsset_property_scene_file>` is changed, or if the generated mesh is toggled.
+Emitted when :ref:`id<class_Terrain3DMeshAsset_property_id>` is changed.
 
 .. rst-class:: classref-item-separator
 
 ----
 
-.. _class_Terrain3DMeshAsset_signal_id_changed:
+.. _class_Terrain3DMeshAsset_signal_instancer_setting_changed:
 
 .. rst-class:: classref-signal
 
-**id_changed**\ (\ ) :ref:`🔗<class_Terrain3DMeshAsset_signal_id_changed>`
+**instancer_setting_changed**\ (\ ) :ref:`🔗<class_Terrain3DMeshAsset_signal_instancer_setting_changed>`
 
-Emitted when :ref:`id<class_Terrain3DMeshAsset_property_id>` is changed.
+Emitted when instancer specific settings are changed on this mesh asset, such as :ref:`cast_shadows<class_Terrain3DMeshAsset_property_cast_shadows>` or :ref:`visibility_range<class_Terrain3DMeshAsset_property_visibility_range>`.
 
 .. rst-class:: classref-item-separator
 
@@ -193,7 +195,7 @@ Property Descriptions
 - |void| **set_cast_shadows**\ (\ value\: :ref:`ShadowCastingSetting<enum_GeometryInstance3D_ShadowCastingSetting>`\ )
 - :ref:`ShadowCastingSetting<enum_GeometryInstance3D_ShadowCastingSetting>` **get_cast_shadows**\ (\ )
 
-Tells the renderer how to cast shadows from this mesh asset onto the terrain and other objects. This sets ``GeometryInstance3D.ShadowCastingSetting`` on all MultiMeshInstances used by this mesh.
+Tells the renderer how to cast shadows from this mesh asset onto the terrain and other objects. This sets ``GeometryInstance3D.cast_shadow`` on all MultiMeshInstances used by this mesh.
 
 .. rst-class:: classref-item-separator
 
@@ -350,6 +352,23 @@ A user specified name for this asset.
 
 A packed scene to load the mesh from. See the top description.
 
+.. rst-class:: classref-item-separator
+
+----
+
+.. _class_Terrain3DMeshAsset_property_visibility_range:
+
+.. rst-class:: classref-property
+
+:ref:`float<class_float>` **visibility_range** = ``1024.0`` :ref:`🔗<class_Terrain3DMeshAsset_property_visibility_range>`
+
+.. rst-class:: classref-property-setget
+
+- |void| **set_visibility_range**\ (\ value\: :ref:`float<class_float>`\ )
+- :ref:`float<class_float>` **get_visibility_range**\ (\ )
+
+Sets ``GeometryInstance3D.visibility_range_end`` on all MultiMeshInstances used by this mesh. Allows the renderer to cull MMIs beyond this distance. Set to 0 to disable culling.
+
 .. rst-class:: classref-section-separator
 
 ----

doc/api/class_terrain3dregion.rst

@@ -17,7 +17,7 @@ Terrain3DRegion
 Description
 -----------
 
-This resource stores all map data for Terrain3D. See `Controlmap Format <../docs/controlmap_format.html>`__ and `Storage Format Changelog <../docs/storage_format.html>`__.
+This resource stores all map data for Terrain3D. See `Controlmap Format <../docs/controlmap_format.html>`__ and `Data Format Changelog <../docs/data_format.html>`__.
 
 .. rst-class:: classref-reftable-group
 
@@ -27,29 +27,33 @@ Properties
 .. table::
    :widths: auto
 
-   +-------------------------------------+------------------------------------------------------------------+-------------------+
-   | :ref:`Image<class_Image>`           | :ref:`color_map<class_Terrain3DRegion_property_color_map>`       |                   |
-   +-------------------------------------+------------------------------------------------------------------+-------------------+
-   | :ref:`Image<class_Image>`           | :ref:`control_map<class_Terrain3DRegion_property_control_map>`   |                   |
-   +-------------------------------------+------------------------------------------------------------------+-------------------+
-   | :ref:`bool<class_bool>`             | :ref:`deleted<class_Terrain3DRegion_property_deleted>`           |                   |
-   +-------------------------------------+------------------------------------------------------------------+-------------------+
-   | :ref:`bool<class_bool>`             | :ref:`edited<class_Terrain3DRegion_property_edited>`             |                   |
-   +-------------------------------------+------------------------------------------------------------------+-------------------+
-   | :ref:`Image<class_Image>`           | :ref:`height_map<class_Terrain3DRegion_property_height_map>`     |                   |
-   +-------------------------------------+------------------------------------------------------------------+-------------------+
-   | :ref:`Vector2<class_Vector2>`       | :ref:`height_range<class_Terrain3DRegion_property_height_range>` | ``Vector2(0, 0)`` |
-   +-------------------------------------+------------------------------------------------------------------+-------------------+
-   | :ref:`Vector2i<class_Vector2i>`     | :ref:`location<class_Terrain3DRegion_property_location>`         |                   |
-   +-------------------------------------+------------------------------------------------------------------+-------------------+
-   | :ref:`bool<class_bool>`             | :ref:`modified<class_Terrain3DRegion_property_modified>`         |                   |
-   +-------------------------------------+------------------------------------------------------------------+-------------------+
-   | :ref:`Dictionary<class_Dictionary>` | :ref:`multimeshes<class_Terrain3DRegion_property_multimeshes>`   | ``{}``            |
-   +-------------------------------------+------------------------------------------------------------------+-------------------+
-   | :ref:`int<class_int>`               | :ref:`region_size<class_Terrain3DRegion_property_region_size>`   | ``0``             |
-   +-------------------------------------+------------------------------------------------------------------+-------------------+
-   | :ref:`float<class_float>`           | :ref:`version<class_Terrain3DRegion_property_version>`           | ``0.8``           |
-   +-------------------------------------+------------------------------------------------------------------+-------------------+
+   +-------------------------------------+----------------------------------------------------------------------+-------------------+
+   | :ref:`Image<class_Image>`           | :ref:`color_map<class_Terrain3DRegion_property_color_map>`           |                   |
+   +-------------------------------------+----------------------------------------------------------------------+-------------------+
+   | :ref:`Image<class_Image>`           | :ref:`control_map<class_Terrain3DRegion_property_control_map>`       |                   |
+   +-------------------------------------+----------------------------------------------------------------------+-------------------+
+   | :ref:`bool<class_bool>`             | :ref:`deleted<class_Terrain3DRegion_property_deleted>`               |                   |
+   +-------------------------------------+----------------------------------------------------------------------+-------------------+
+   | :ref:`bool<class_bool>`             | :ref:`edited<class_Terrain3DRegion_property_edited>`                 |                   |
+   +-------------------------------------+----------------------------------------------------------------------+-------------------+
+   | :ref:`Image<class_Image>`           | :ref:`height_map<class_Terrain3DRegion_property_height_map>`         |                   |
+   +-------------------------------------+----------------------------------------------------------------------+-------------------+
+   | :ref:`Vector2<class_Vector2>`       | :ref:`height_range<class_Terrain3DRegion_property_height_range>`     | ``Vector2(0, 0)`` |
+   +-------------------------------------+----------------------------------------------------------------------+-------------------+
+   | :ref:`Dictionary<class_Dictionary>` | :ref:`instances<class_Terrain3DRegion_property_instances>`           | ``{}``            |
+   +-------------------------------------+----------------------------------------------------------------------+-------------------+
+   | :ref:`Vector2i<class_Vector2i>`     | :ref:`location<class_Terrain3DRegion_property_location>`             |                   |
+   +-------------------------------------+----------------------------------------------------------------------+-------------------+
+   | :ref:`bool<class_bool>`             | :ref:`modified<class_Terrain3DRegion_property_modified>`             |                   |
+   +-------------------------------------+----------------------------------------------------------------------+-------------------+
+   | :ref:`Dictionary<class_Dictionary>` | :ref:`multimeshes<class_Terrain3DRegion_property_multimeshes>`       | ``{}``            |
+   +-------------------------------------+----------------------------------------------------------------------+-------------------+
+   | :ref:`int<class_int>`               | :ref:`region_size<class_Terrain3DRegion_property_region_size>`       | ``0``             |
+   +-------------------------------------+----------------------------------------------------------------------+-------------------+
+   | :ref:`float<class_float>`           | :ref:`version<class_Terrain3DRegion_property_version>`               | ``0.8``           |
+   +-------------------------------------+----------------------------------------------------------------------+-------------------+
+   | :ref:`float<class_float>`           | :ref:`vertex_spacing<class_Terrain3DRegion_property_vertex_spacing>` | ``1.0``           |
+   +-------------------------------------+----------------------------------------------------------------------+-------------------+
 
 .. rst-class:: classref-reftable-group
 
@@ -240,7 +244,7 @@ Image format: FORMAT_RF, 32-bit per pixel as full-precision floating-point.
 
 Heights sent to the vertex shader on the GPU which modifies the mesh in real-time.
 
-Editing is always done in 32-bit. We do provide an option to save as 16-bit, see :ref:`Terrain3D.save_16_bit<class_Terrain3D_property_save_16_bit>`, which converts to 32-bit on load and back to 16-bit on save. This process is lossy as 16-bit precision gets increasingly worse with every power of 2.
+Editing is always done in 32-bit. We do provide an option to save as 16-bit, see :ref:`Terrain3D.save_16_bit<class_Terrain3D_property_save_16_bit>`.
 
 .. rst-class:: classref-item-separator
 
@@ -263,6 +267,39 @@ The current minimum and maximum height range for this region, used to calculate
 
 ----
 
+.. _class_Terrain3DRegion_property_instances:
+
+.. rst-class:: classref-property
+
+:ref:`Dictionary<class_Dictionary>` **instances** = ``{}`` :ref:`🔗<class_Terrain3DRegion_property_instances>`
+
+.. rst-class:: classref-property-setget
+
+- |void| **set_instances**\ (\ value\: :ref:`Dictionary<class_Dictionary>`\ )
+- :ref:`Dictionary<class_Dictionary>` **get_instances**\ (\ )
+
+A Dictionary that stores the instancer transforms for this region.
+
+The format is instances{mesh_id:int} -> cells{grid_location:Vector2i} -> ( Array\ :ref:`Transform3D<class_Transform3D>`, PackedColorArray, modified:bool ). That is:
+
+- A dictionary keyed by mesh_id that returns:
+
+- A dictionary keyed by the grid location of the 32 x 32m cell that returns:
+
+- A 3-item Array that contains:
+
+- 0: An Array of Transform3Ds
+
+- 1: A PackedColorArray
+
+- 2: A bool that tracks if this cell has been modified
+
+After changing this data, :ref:`Terrain3DInstancer.force_update_mmis<class_Terrain3DInstancer_method_force_update_mmis>` should be called to rebuild the MMIs.
+
+.. rst-class:: classref-item-separator
+
+----
+
 .. _class_Terrain3DRegion_property_location:
 
 .. rst-class:: classref-property
@@ -308,7 +345,7 @@ This region has been modified and will be saved.
 - |void| **set_multimeshes**\ (\ value\: :ref:`Dictionary<class_Dictionary>`\ )
 - :ref:`Dictionary<class_Dictionary>` **get_multimeshes**\ (\ )
 
-A Dictionary indexed by mesh_id that provides the MultiMeshes for this region.
+Deprecated and only exists for upgrading. Use :ref:`instances<class_Terrain3DRegion_property_instances>`.
 
 .. rst-class:: classref-item-separator
 
@@ -344,6 +381,23 @@ The current region size for this region, calculated from the dimensions of the f
 
 The data file version. This is independent of the Terrain3D version, though they often align.
 
+.. rst-class:: classref-item-separator
+
+----
+
+.. _class_Terrain3DRegion_property_vertex_spacing:
+
+.. rst-class:: classref-property
+
+:ref:`float<class_float>` **vertex_spacing** = ``1.0`` :ref:`🔗<class_Terrain3DRegion_property_vertex_spacing>`
+
+.. rst-class:: classref-property-setget
+
+- |void| **set_vertex_spacing**\ (\ value\: :ref:`float<class_float>`\ )
+- :ref:`float<class_float>` **get_vertex_spacing**\ (\ )
+
+Stored instancer transforms are laterally scaled by this value. This value is manage by the instancer on loading or when :ref:`Terrain3D.vertex_spacing<class_Terrain3D_property_vertex_spacing>` is set, and shouldn't be manually adjusted.
+
 .. rst-class:: classref-section-separator
 
 ----

doc/api/class_terrain3dutil.rst

@@ -37,7 +37,7 @@ Or you can instance the class for a shorter alias:
     util.enc_uv_scale(uvscale) | util.enc_auto(autoshader) | \
     util.enc_nav(navigation) | util.enc_hole(hole)
     var color: Color = Color(util.as_float(bits), 0., 0., 1.)
-    storage.set_control(global_pos, color)
+    data.set_control(global_pos, color)
 
 .. rst-class:: classref-reftable-group