diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bb7a9fd7..30ea7d43 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -88,7 +88,7 @@ Private & Public: Other formatting: * One blank line between functions -* All code passed through clang-format. See below +* All code passed through clang-format. See above ## Documentation diff --git a/LICENSE.txt b/LICENSE.txt index b4293b70..14089b67 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2023 Cory Petkovsek, Roope Palmroos, and Contributors. +Copyright (c) 2024 Cory Petkovsek, Roope Palmroos, and Contributors. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/Terrain3D.vcxproj b/Terrain3D.vcxproj index 76390882..ed9989a3 100644 --- a/Terrain3D.vcxproj +++ b/Terrain3D.vcxproj @@ -186,6 +186,7 @@ + @@ -213,7 +214,7 @@ - + diff --git a/Terrain3D.vcxproj.filters b/Terrain3D.vcxproj.filters index 95e1b520..ac8c334c 100644 --- a/Terrain3D.vcxproj.filters +++ b/Terrain3D.vcxproj.filters @@ -223,6 +223,7 @@ 1. Project Files + @@ -237,7 +238,7 @@ 2. Docs - + 2. Docs diff --git a/doc/api/class_terrain3d.rst b/doc/api/class_terrain3d.rst index 2136d87c..a2c23d03 100644 --- a/doc/api/class_terrain3d.rst +++ b/doc/api/class_terrain3d.rst @@ -77,21 +77,27 @@ Methods .. table:: :widths: auto - +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Mesh` | :ref:`bake_mesh`\ (\ lod\: :ref:`int`, filter\: :ref:`HeightFilter`\ ) | - +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`PackedVector3Array` | :ref:`generate_nav_mesh_source_geometry`\ (\ global_aabb\: :ref:`AABB`, require_nav\: :ref:`bool` = true\ ) | - +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Camera3D` | :ref:`get_camera`\ (\ ) | - +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Vector3` | :ref:`get_intersection`\ (\ src_pos\: :ref:`Vector3`, direction\: :ref:`Vector3`\ ) | - +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`EditorPlugin` | :ref:`get_plugin`\ (\ ) | - +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`set_camera`\ (\ camera\: :ref:`Camera3D`\ ) | - +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`set_plugin`\ (\ plugin\: :ref:`EditorPlugin`\ ) | - +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Mesh` | :ref:`bake_mesh`\ (\ lod\: :ref:`int`, filter\: :ref:`HeightFilter`\ ) |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedVector3Array` | :ref:`generate_nav_mesh_source_geometry`\ (\ global_aabb\: :ref:`AABB`, require_nav\: :ref:`bool` = true\ ) |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Camera3D` | :ref:`get_camera`\ (\ ) |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`RID` | :ref:`get_collision_rid`\ (\ ) |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Terrain3DEditor` | :ref:`get_editor`\ (\ ) |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`get_intersection`\ (\ src_pos\: :ref:`Vector3`, direction\: :ref:`Vector3`\ ) | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`EditorPlugin` | :ref:`get_plugin`\ (\ ) |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_camera`\ (\ camera\: :ref:`Camera3D`\ ) | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_editor`\ (\ editor\: :ref:`Terrain3DEditor`\ ) | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_plugin`\ (\ plugin\: :ref:`EditorPlugin`\ ) | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -485,7 +491,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`Mesh` **bake_mesh**\ (\ lod\: :ref:`int`, filter\: :ref:`HeightFilter`\ ) :ref:`🔗` +:ref:`Mesh` **bake_mesh**\ (\ lod\: :ref:`int`, filter\: :ref:`HeightFilter`\ ) |const| :ref:`🔗` Generates a static ArrayMesh for the terrain. @@ -501,7 +507,7 @@ Generates a static ArrayMesh for the terrain. .. rst-class:: classref-method -:ref:`PackedVector3Array` **generate_nav_mesh_source_geometry**\ (\ global_aabb\: :ref:`AABB`, require_nav\: :ref:`bool` = true\ ) :ref:`🔗` +:ref:`PackedVector3Array` **generate_nav_mesh_source_geometry**\ (\ global_aabb\: :ref:`AABB`, require_nav\: :ref:`bool` = true\ ) |const| :ref:`🔗` Generates source geometry faces for input to nav mesh baking. Geometry is only generated where there are no holes and the terrain has been painted as navigable. @@ -517,7 +523,7 @@ Generates source geometry faces for input to nav mesh baking. Geometry is only g .. rst-class:: classref-method -:ref:`Camera3D` **get_camera**\ (\ ) :ref:`🔗` +:ref:`Camera3D` **get_camera**\ (\ ) |const| :ref:`🔗` Returns the camera the terrain is currently snapping to. @@ -525,6 +531,30 @@ Returns the camera the terrain is currently snapping to. ---- +.. _class_Terrain3D_method_get_collision_rid: + +.. rst-class:: classref-method + +:ref:`RID` **get_collision_rid**\ (\ ) |const| :ref:`🔗` + +Returns the RID of the active StaticBody. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Terrain3D_method_get_editor: + +.. rst-class:: classref-method + +:ref:`Terrain3DEditor` **get_editor**\ (\ ) |const| :ref:`🔗` + +Returns the current Terrain3DEditor instance, if it has been set. + +.. rst-class:: classref-item-separator + +---- + .. _class_Terrain3D_method_get_intersection: .. rst-class:: classref-method @@ -555,7 +585,7 @@ It does require the use of an editor render layer (21-32) that should be dedicat .. rst-class:: classref-method -:ref:`EditorPlugin` **get_plugin**\ (\ ) :ref:`🔗` +:ref:`EditorPlugin` **get_plugin**\ (\ ) |const| :ref:`🔗` Returns the EditorPlugin connected to Terrain3D. @@ -575,6 +605,18 @@ Sets the camera the terrain snaps to. ---- +.. _class_Terrain3D_method_set_editor: + +.. rst-class:: classref-method + +|void| **set_editor**\ (\ editor\: :ref:`Terrain3DEditor`\ ) :ref:`🔗` + +Sets the current Terrain3DEditor instance. + +.. rst-class:: classref-item-separator + +---- + .. _class_Terrain3D_method_set_plugin: .. rst-class:: classref-method diff --git a/doc/api/class_terrain3dassets.rst b/doc/api/class_terrain3dassets.rst index 995fcc05..a2993447 100644 --- a/doc/api/class_terrain3dassets.rst +++ b/doc/api/class_terrain3dassets.rst @@ -44,13 +44,13 @@ Methods +-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`create_mesh_thumbnails`\ (\ id\: :ref:`int` = -1, size\: :ref:`Vector2i` = Vector2i(128, 128)\ ) | +-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Terrain3DMeshAsset` | :ref:`get_mesh_asset`\ (\ id\: :ref:`int`\ ) | + | :ref:`Terrain3DMeshAsset` | :ref:`get_mesh_asset`\ (\ id\: :ref:`int`\ ) |const| | +-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`int` | :ref:`get_mesh_count`\ (\ ) | + | :ref:`int` | :ref:`get_mesh_count`\ (\ ) |const| | +-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Terrain3DTextureAsset` | :ref:`get_texture`\ (\ id\: :ref:`int`\ ) | + | :ref:`Terrain3DTextureAsset` | :ref:`get_texture`\ (\ id\: :ref:`int`\ ) |const| | +-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`int` | :ref:`get_texture_count`\ (\ ) | + | :ref:`int` | :ref:`get_texture_count`\ (\ ) |const| | +-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`save`\ (\ ) | +-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -208,7 +208,7 @@ Generates mesh asset preview thumbnails for the asset dock, stored within each m .. rst-class:: classref-method -:ref:`Terrain3DMeshAsset` **get_mesh_asset**\ (\ id\: :ref:`int`\ ) :ref:`🔗` +:ref:`Terrain3DMeshAsset` **get_mesh_asset**\ (\ id\: :ref:`int`\ ) |const| :ref:`🔗` Returns the specified Terrain3DMeshAsset resource. @@ -220,7 +220,7 @@ Returns the specified Terrain3DMeshAsset resource. .. rst-class:: classref-method -:ref:`int` **get_mesh_count**\ (\ ) :ref:`🔗` +:ref:`int` **get_mesh_count**\ (\ ) |const| :ref:`🔗` Returns the number of mesh assets in the list. @@ -232,7 +232,7 @@ Returns the number of mesh assets in the list. .. rst-class:: classref-method -:ref:`Terrain3DTextureAsset` **get_texture**\ (\ id\: :ref:`int`\ ) :ref:`🔗` +:ref:`Terrain3DTextureAsset` **get_texture**\ (\ id\: :ref:`int`\ ) |const| :ref:`🔗` Returns the Terrain3DTextureAsset with the requested ID. @@ -244,7 +244,7 @@ Returns the Terrain3DTextureAsset with the requested ID. .. rst-class:: classref-method -:ref:`int` **get_texture_count**\ (\ ) :ref:`🔗` +:ref:`int` **get_texture_count**\ (\ ) |const| :ref:`🔗` Returns the number of texture slots used. diff --git a/doc/api/class_terrain3deditor.rst b/doc/api/class_terrain3deditor.rst index ed2dc77c..b5a9bfb6 100644 --- a/doc/api/class_terrain3deditor.rst +++ b/doc/api/class_terrain3deditor.rst @@ -30,13 +30,13 @@ Methods +--------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`apply_undo`\ (\ maps\: :ref:`Dictionary`\ ) | +--------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Operation` | :ref:`get_operation`\ (\ ) | + | :ref:`Operation` | :ref:`get_operation`\ (\ ) |const| | +--------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Terrain3D` | :ref:`get_terrain`\ (\ ) | + | :ref:`Terrain3D` | :ref:`get_terrain`\ (\ ) |const| | +--------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Tool` | :ref:`get_tool`\ (\ ) | + | :ref:`Tool` | :ref:`get_tool`\ (\ ) |const| | +--------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`is_operating`\ (\ ) | + | :ref:`bool` | :ref:`is_operating`\ (\ ) |const| | +--------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`operate`\ (\ position\: :ref:`Vector3`, camera_direction\: :ref:`float`\ ) | +--------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -84,27 +84,11 @@ Additive operations. Subtractive operations. -.. _class_Terrain3DEditor_constant_MULTIPLY: - -.. rst-class:: classref-enumeration-constant - -:ref:`Operation` **MULTIPLY** = ``2`` - -Multiplicative operations. - -.. _class_Terrain3DEditor_constant_DIVIDE: - -.. rst-class:: classref-enumeration-constant - -:ref:`Operation` **DIVIDE** = ``3`` - -Divisive operations. - .. _class_Terrain3DEditor_constant_REPLACE: .. rst-class:: classref-enumeration-constant -:ref:`Operation` **REPLACE** = ``4`` +:ref:`Operation` **REPLACE** = ``2`` Replacing operations. @@ -112,7 +96,7 @@ Replacing operations. .. rst-class:: classref-enumeration-constant -:ref:`Operation` **AVERAGE** = ``5`` +:ref:`Operation` **AVERAGE** = ``3`` Averaging operations. @@ -120,7 +104,7 @@ Averaging operations. .. rst-class:: classref-enumeration-constant -:ref:`Operation` **GRADIENT** = ``6`` +:ref:`Operation` **GRADIENT** = ``4`` Gradient operations. @@ -128,7 +112,7 @@ Gradient operations. .. rst-class:: classref-enumeration-constant -:ref:`Operation` **OP_MAX** = ``7`` +:ref:`Operation` **OP_MAX** = ``5`` The number of elements in this enum. @@ -146,7 +130,7 @@ enum **Tool**: :ref:`🔗` .. rst-class:: classref-enumeration-constant -:ref:`Tool` **HEIGHT** = ``0`` +:ref:`Tool` **HEIGHT** = ``1`` Sculpt heights. @@ -154,7 +138,7 @@ Sculpt heights. .. rst-class:: classref-enumeration-constant -:ref:`Tool` **TEXTURE** = ``1`` +:ref:`Tool` **TEXTURE** = ``2`` Paint textures. @@ -162,7 +146,7 @@ Paint textures. .. rst-class:: classref-enumeration-constant -:ref:`Tool` **COLOR** = ``2`` +:ref:`Tool` **COLOR** = ``3`` Paint on the color map. @@ -170,7 +154,7 @@ Paint on the color map. .. rst-class:: classref-enumeration-constant -:ref:`Tool` **ROUGHNESS** = ``3`` +:ref:`Tool` **ROUGHNESS** = ``4`` Paint a roughness modifier, aka wetness. @@ -178,7 +162,7 @@ Paint a roughness modifier, aka wetness. .. rst-class:: classref-enumeration-constant -:ref:`Tool` **ANGLE** = ``4`` +:ref:`Tool` **ANGLE** = ``9`` Paint textures rotated by an angle. @@ -186,7 +170,7 @@ Paint textures rotated by an angle. .. rst-class:: classref-enumeration-constant -:ref:`Tool` **SCALE** = ``5`` +:ref:`Tool` **SCALE** = ``10`` Paint textures scaled by a value. @@ -194,7 +178,7 @@ Paint textures scaled by a value. .. rst-class:: classref-enumeration-constant -:ref:`Tool` **AUTOSHADER** = ``6`` +:ref:`Tool` **AUTOSHADER** = ``5`` Paint where the shader automatically textures. @@ -202,7 +186,7 @@ Paint where the shader automatically textures. .. rst-class:: classref-enumeration-constant -:ref:`Tool` **HOLES** = ``7`` +:ref:`Tool` **HOLES** = ``6`` Paint where vertices will be invalidated to leave holes. @@ -210,7 +194,7 @@ Paint where vertices will be invalidated to leave holes. .. rst-class:: classref-enumeration-constant -:ref:`Tool` **NAVIGATION** = ``8`` +:ref:`Tool` **NAVIGATION** = ``7`` Paint where navigation will be generated. @@ -218,7 +202,7 @@ Paint where navigation will be generated. .. rst-class:: classref-enumeration-constant -:ref:`Tool` **INSTANCER** = ``9`` +:ref:`Tool` **INSTANCER** = ``8`` Paint MultiMesh instances on the ground. @@ -226,7 +210,7 @@ Paint MultiMesh instances on the ground. .. rst-class:: classref-enumeration-constant -:ref:`Tool` **REGION** = ``10`` +:ref:`Tool` **REGION** = ``0`` Add/remove regions. @@ -263,7 +247,7 @@ Undo the previous changes, with the reverted images in the array. Used by Godot, .. rst-class:: classref-method -:ref:`Operation` **get_operation**\ (\ ) :ref:`🔗` +:ref:`Operation` **get_operation**\ (\ ) |const| :ref:`🔗` Returns the current operation. @@ -275,7 +259,7 @@ Returns the current operation. .. rst-class:: classref-method -:ref:`Terrain3D` **get_terrain**\ (\ ) :ref:`🔗` +:ref:`Terrain3D` **get_terrain**\ (\ ) |const| :ref:`🔗` Returns the instance of Terrain3D this class is conneced to. @@ -287,7 +271,7 @@ Returns the instance of Terrain3D this class is conneced to. .. rst-class:: classref-method -:ref:`Tool` **get_tool**\ (\ ) :ref:`🔗` +:ref:`Tool` **get_tool**\ (\ ) |const| :ref:`🔗` Returns the current tool selected in the editor plugin. @@ -299,7 +283,7 @@ Returns the current tool selected in the editor plugin. .. rst-class:: classref-method -:ref:`bool` **is_operating**\ (\ ) :ref:`🔗` +:ref:`bool` **is_operating**\ (\ ) |const| :ref:`🔗` Returns true if currently brushing. diff --git a/doc/api/class_terrain3dinstancer.rst b/doc/api/class_terrain3dinstancer.rst index 958ef4d3..091e7b68 100644 --- a/doc/api/class_terrain3dinstancer.rst +++ b/doc/api/class_terrain3dinstancer.rst @@ -49,23 +49,29 @@ Methods .. table:: :widths: auto - +--------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`add_instances`\ (\ global_position\: :ref:`Vector3`, params\: :ref:`Dictionary`\ ) | - +--------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`add_multimesh`\ (\ mesh_id\: :ref:`int`, multimesh\: :ref:`MultiMesh`, transform\: :ref:`Transform3D` = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0)\ ) | - +--------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`add_transforms`\ (\ mesh_id\: :ref:`int`, transforms\: :ref:`Array`\[:ref:`Transform3D`\], colors\: :ref:`Array`\[:ref:`Color`\] = []\ ) | - +--------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`clear_by_mesh`\ (\ mesh_id\: :ref:`int`\ ) | - +--------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`clear_by_offset`\ (\ region_offset\: :ref:`Vector2i`, mesh_id\: :ref:`int`\ ) | - +--------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`clear_by_region_id`\ (\ region_id\: :ref:`int`, mesh_id\: :ref:`int`\ ) | - +--------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`remove_instances`\ (\ global_position\: :ref:`Vector3`, params\: :ref:`Dictionary`\ ) | - +--------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`set_cast_shadows`\ (\ mesh_id\: :ref:`int`, mode\: :ref:`ShadowCastingSetting`\ ) | - +--------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_instances`\ (\ global_position\: :ref:`Vector3`, params\: :ref:`Dictionary`\ ) | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_multimesh`\ (\ mesh_id\: :ref:`int`, multimesh\: :ref:`MultiMesh`, transform\: :ref:`Transform3D` = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0)\ ) | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_transforms`\ (\ mesh_id\: :ref:`int`, transforms\: :ref:`Array`\[:ref:`Transform3D`\], colors\: :ref:`Array`\[:ref:`Color`\] = []\ ) | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`append_multimesh`\ (\ region_offset\: :ref:`Vector2i`, mesh_id\: :ref:`int`, transforms\: :ref:`Array`\[:ref:`Transform3D`\], colors\: :ref:`Array`\[:ref:`Color`\], clear\: :ref:`bool` = false\ ) | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear_by_mesh`\ (\ mesh_id\: :ref:`int`\ ) | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear_by_offset`\ (\ region_offset\: :ref:`Vector2i`, mesh_id\: :ref:`int`\ ) | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear_by_region_id`\ (\ region_id\: :ref:`int`, mesh_id\: :ref:`int`\ ) | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Dictionary` | :ref:`get_mmis`\ (\ ) |const| | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_instances`\ (\ global_position\: :ref:`Vector3`, params\: :ref:`Dictionary`\ ) | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_cast_shadows`\ (\ mesh_id\: :ref:`int`, mode\: :ref:`ShadowCastingSetting`\ ) | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`update_transforms`\ (\ aabb\: :ref:`AABB`\ ) | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -114,6 +120,18 @@ This function adds the :ref:`Terrain3DMeshAsset.height_offset`, mesh_id\: :ref:`int`, transforms\: :ref:`Array`\[:ref:`Transform3D`\], colors\: :ref:`Array`\[:ref:`Color`\], clear\: :ref:`bool` = false\ ) :ref:`🔗` + +Appends new transforms to existing multimeshes. Multimesh transform arrays cannot be modified and must be rebuilt. This will make a new array with both old and new transforms. `Clear` will skip the old array. + +.. rst-class:: classref-item-separator + +---- + .. _class_Terrain3DInstancer_method_clear_by_mesh: .. rst-class:: classref-method @@ -150,6 +168,18 @@ Removes both MultiMeshInstance nodes attached to the tree, and MultiMeshes in St ---- +.. _class_Terrain3DInstancer_method_get_mmis: + +.. rst-class:: classref-method + +:ref:`Dictionary` **get_mmis**\ (\ ) |const| :ref:`🔗` + +Returns the dictionary containing the MultiMeshInstance3D nodes, which are hidden children of Terrain3D. The dictionary is keyed by Vector3i(region_offset.x, region_offset.y, mesh_id). + +.. rst-class:: classref-item-separator + +---- + .. _class_Terrain3DInstancer_method_remove_instances: .. rst-class:: classref-method @@ -170,6 +200,18 @@ Uses parameters asset_id, size, strength, fixed_scale, random_scale, to randomly Tells the renderer how to cast shadows from this mesh asset onto the terrain and other objects. This sets ``GeometryInstance3D.ShadowCastingSetting`` on all MultiMeshInstances for the specified mesh. This function is called by :ref:`Terrain3DMeshAsset.cast_shadows`, but you can also call it manually. +.. rst-class:: classref-item-separator + +---- + +.. _class_Terrain3DInstancer_method_update_transforms: + +.. rst-class:: classref-method + +|void| **update_transforms**\ (\ aabb\: :ref:`AABB`\ ) :ref:`🔗` + +Reviews all existing instance transforms within an AABB and adjusts their heights to match the terrain. + .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` diff --git a/doc/api/class_terrain3dmaterial.rst b/doc/api/class_terrain3dmaterial.rst index b02428c2..dd51ea6f 100644 --- a/doc/api/class_terrain3dmaterial.rst +++ b/doc/api/class_terrain3dmaterial.rst @@ -88,18 +88,20 @@ Methods :widths: auto +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`RID` | :ref:`get_material_rid`\ (\ ) | + | :ref:`RID` | :ref:`get_material_rid`\ (\ ) |const| | +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`RID` | :ref:`get_region_blend_map`\ (\ ) | + | :ref:`RID` | :ref:`get_region_blend_map`\ (\ ) |const| | +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Variant` | :ref:`get_shader_param`\ (\ name\: :ref:`StringName`\ ) | + | :ref:`Variant` | :ref:`get_shader_param`\ (\ name\: :ref:`StringName`\ ) |const| | +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`RID` | :ref:`get_shader_rid`\ (\ ) | + | :ref:`RID` | :ref:`get_shader_rid`\ (\ ) |const| | +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`save`\ (\ ) | +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`set_shader_param`\ (\ name\: :ref:`StringName`, value\: :ref:`Variant`\ ) | +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`update`\ (\ ) | + +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -555,7 +557,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`RID` **get_material_rid**\ (\ ) :ref:`🔗` +:ref:`RID` **get_material_rid**\ (\ ) |const| :ref:`🔗` Returns the RID of the material used with the Rendering Server. This is set per instance of this class. @@ -567,7 +569,7 @@ Returns the RID of the material used with the Rendering Server. This is set per .. rst-class:: classref-method -:ref:`RID` **get_region_blend_map**\ (\ ) :ref:`🔗` +:ref:`RID` **get_region_blend_map**\ (\ ) |const| :ref:`🔗` Returns the RID of the 512x512 texture used with the RenderingServer. It depicts a blurry map of region locations and is used for smoothly blending world noise into sculpted terrain. @@ -579,7 +581,7 @@ Returns the RID of the 512x512 texture used with the RenderingServer. It depicts .. rst-class:: classref-method -:ref:`Variant` **get_shader_param**\ (\ name\: :ref:`StringName`\ ) :ref:`🔗` +:ref:`Variant` **get_shader_param**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` Retrieve a parameter from the active shader (built-in or override shader). @@ -591,7 +593,7 @@ Retrieve a parameter from the active shader (built-in or override shader). .. rst-class:: classref-method -:ref:`RID` **get_shader_rid**\ (\ ) :ref:`🔗` +:ref:`RID` **get_shader_rid**\ (\ ) |const| :ref:`🔗` Returns the RID of the built in shader used with the Rendering Server. This is different from any shader override which has its own RID. @@ -619,6 +621,18 @@ Saves this material resource to disk, if saved as an external ``.tres`` or ``.re Set a parameter in the active shader (built-in or override shader). +.. rst-class:: classref-item-separator + +---- + +.. _class_Terrain3DMaterial_method_update: + +.. rst-class:: classref-method + +|void| **update**\ (\ ) :ref:`🔗` + +Recompiles the current shader and sends all uniform values to it again. + .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` diff --git a/doc/api/class_terrain3dmeshasset.rst b/doc/api/class_terrain3dmeshasset.rst index 73fdcb29..0d4ddf2c 100644 --- a/doc/api/class_terrain3dmeshasset.rst +++ b/doc/api/class_terrain3dmeshasset.rst @@ -68,9 +68,9 @@ Methods +-----------------------------------+----------------------------------------------------------------------------------------------------+ | :ref:`Mesh` | :ref:`get_mesh`\ (\ index\: :ref:`int` = 0\ ) | +-----------------------------------+----------------------------------------------------------------------------------------------------+ - | :ref:`int` | :ref:`get_mesh_count`\ (\ ) | + | :ref:`int` | :ref:`get_mesh_count`\ (\ ) |const| | +-----------------------------------+----------------------------------------------------------------------------------------------------+ - | :ref:`Texture2D` | :ref:`get_thumbnail`\ (\ ) | + | :ref:`Texture2D` | :ref:`get_thumbnail`\ (\ ) |const| | +-----------------------------------+----------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -387,7 +387,7 @@ Returns the specified Mesh resource indicated. Only id 0 is used currently. .. rst-class:: classref-method -:ref:`int` **get_mesh_count**\ (\ ) :ref:`🔗` +:ref:`int` **get_mesh_count**\ (\ ) |const| :ref:`🔗` Returns the number of Mesh resources found in the scene file and stored. @@ -399,7 +399,7 @@ Returns the number of Mesh resources found in the scene file and stored. .. rst-class:: classref-method -:ref:`Texture2D` **get_thumbnail**\ (\ ) :ref:`🔗` +:ref:`Texture2D` **get_thumbnail**\ (\ ) |const| :ref:`🔗` Returns the thumbnail generated by :ref:`Terrain3DAssets`. diff --git a/doc/api/class_terrain3dstorage.rst b/doc/api/class_terrain3dstorage.rst index f1507ac1..47353f1e 100644 --- a/doc/api/class_terrain3dstorage.rst +++ b/doc/api/class_terrain3dstorage.rst @@ -58,51 +58,51 @@ Methods +--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`add_region`\ (\ global_position\: :ref:`Vector3`, images\: :ref:`Array`\[:ref:`Image`\] = [], update\: :ref:`bool` = true\ ) | +--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Error` | :ref:`export_image`\ (\ file_name\: :ref:`String`, map_type\: :ref:`MapType`\ ) | + | :ref:`Error` | :ref:`export_image`\ (\ file_name\: :ref:`String`, map_type\: :ref:`MapType`\ ) |const| | +--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`force_update_maps`\ (\ map_type\: :ref:`MapType` = 3\ ) | +--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`float` | :ref:`get_angle`\ (\ global_position\: :ref:`Vector3`\ ) | + | :ref:`float` | :ref:`get_angle`\ (\ global_position\: :ref:`Vector3`\ ) |const| | +--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Color` | :ref:`get_color`\ (\ global_position\: :ref:`Vector3`\ ) | + | :ref:`Color` | :ref:`get_color`\ (\ global_position\: :ref:`Vector3`\ ) |const| | +--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`int` | :ref:`get_control`\ (\ global_position\: :ref:`Vector3`\ ) | + | :ref:`int` | :ref:`get_control`\ (\ global_position\: :ref:`Vector3`\ ) |const| | +--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`float` | :ref:`get_height`\ (\ global_position\: :ref:`Vector3`\ ) | + | :ref:`float` | :ref:`get_height`\ (\ global_position\: :ref:`Vector3`\ ) |const| | +--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Image` | :ref:`get_map_region`\ (\ map_type\: :ref:`MapType`, region_index\: :ref:`int`\ ) | + | :ref:`Image` | :ref:`get_map_region`\ (\ map_type\: :ref:`MapType`, region_index\: :ref:`int`\ ) |const| | +--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Array`\[:ref:`Image`\] | :ref:`get_maps`\ (\ map_type\: :ref:`MapType`\ ) | + | :ref:`Array`\[:ref:`Image`\] | :ref:`get_maps`\ (\ map_type\: :ref:`MapType`\ ) |const| | +--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Array`\[:ref:`Image`\] | :ref:`get_maps_copy`\ (\ map_type\: :ref:`MapType`\ ) | + | :ref:`Array`\[:ref:`Image`\] | :ref:`get_maps_copy`\ (\ map_type\: :ref:`MapType`\ ) |const| | +--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Vector3` | :ref:`get_mesh_vertex`\ (\ lod\: :ref:`int`, filter\: :ref:`HeightFilter`, global_position\: :ref:`Vector3`\ ) | + | :ref:`Vector3` | :ref:`get_mesh_vertex`\ (\ lod\: :ref:`int`, filter\: :ref:`HeightFilter`, global_position\: :ref:`Vector3`\ ) |const| | +--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Vector3` | :ref:`get_normal`\ (\ global_position\: :ref:`Vector3`\ ) | + | :ref:`Vector3` | :ref:`get_normal`\ (\ global_position\: :ref:`Vector3`\ ) |const| | +--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Color` | :ref:`get_pixel`\ (\ map_type\: :ref:`MapType`, global_position\: :ref:`Vector3`\ ) | + | :ref:`Color` | :ref:`get_pixel`\ (\ map_type\: :ref:`MapType`, global_position\: :ref:`Vector3`\ ) |const| | +--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`int` | :ref:`get_region_count`\ (\ ) | + | :ref:`int` | :ref:`get_region_count`\ (\ ) |const| | +--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`int` | :ref:`get_region_index`\ (\ global_position\: :ref:`Vector3`\ ) | + | :ref:`int` | :ref:`get_region_index`\ (\ global_position\: :ref:`Vector3`\ ) |const| | +--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`int` | :ref:`get_region_index_from_offset`\ (\ region_offset\: :ref:`Vector2i`\ ) | + | :ref:`int` | :ref:`get_region_index_from_offset`\ (\ region_offset\: :ref:`Vector2i`\ ) |const| | +--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Vector2i` | :ref:`get_region_offset`\ (\ global_position\: :ref:`Vector3`\ ) | + | :ref:`Vector2i` | :ref:`get_region_offset`\ (\ global_position\: :ref:`Vector3`\ ) |const| | +--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Vector2i` | :ref:`get_region_offset_from_index`\ (\ region_index\: :ref:`int`\ ) | + | :ref:`Vector2i` | :ref:`get_region_offset_from_index`\ (\ region_index\: :ref:`int`\ ) |const| | +--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`float` | :ref:`get_roughness`\ (\ global_position\: :ref:`Vector3`\ ) | + | :ref:`float` | :ref:`get_roughness`\ (\ global_position\: :ref:`Vector3`\ ) |const| | +--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`float` | :ref:`get_scale`\ (\ global_position\: :ref:`Vector3`\ ) | + | :ref:`float` | :ref:`get_scale`\ (\ global_position\: :ref:`Vector3`\ ) |const| | +--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Vector3` | :ref:`get_texture_id`\ (\ global_position\: :ref:`Vector3`\ ) | + | :ref:`Vector3` | :ref:`get_texture_id`\ (\ global_position\: :ref:`Vector3`\ ) |const| | +--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`has_region`\ (\ global_position\: :ref:`Vector3`\ ) | + | :ref:`bool` | :ref:`has_region`\ (\ global_position\: :ref:`Vector3`\ ) |const| | +--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`import_images`\ (\ images\: :ref:`Array`\[:ref:`Image`\], global_position\: :ref:`Vector3` = Vector3(0, 0, 0), offset\: :ref:`float` = 0.0, scale\: :ref:`float` = 1.0\ ) | +--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Image` | :ref:`layered_to_image`\ (\ map_type\: :ref:`MapType`\ ) | + | :ref:`Image` | :ref:`layered_to_image`\ (\ map_type\: :ref:`MapType`\ ) |const| | +--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`remove_region`\ (\ global_position\: :ref:`Vector3`, update\: :ref:`bool` = true\ ) | +--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -531,7 +531,7 @@ Parameters: .. rst-class:: classref-method -:ref:`Error` **export_image**\ (\ file_name\: :ref:`String`, map_type\: :ref:`MapType`\ ) :ref:`🔗` +:ref:`Error` **export_image**\ (\ file_name\: :ref:`String`, map_type\: :ref:`MapType`\ ) |const| :ref:`🔗` Exports the specified map type as one of r16/raw, exr, jpg, png, webp, res, tres. @@ -561,7 +561,7 @@ Regenerates the TextureArrays that house the requested map types. Using the defa .. rst-class:: classref-method -:ref:`float` **get_angle**\ (\ global_position\: :ref:`Vector3`\ ) :ref:`🔗` +:ref:`float` **get_angle**\ (\ global_position\: :ref:`Vector3`\ ) |const| :ref:`🔗` Returns the angle, aka uv rotation, painted on the control map at the requested position. Values are fixed to 22.5 degree intervals, for a maximum of 16 angles. 360 / 16 = 22.5. Calls :ref:`get_pixel`. @@ -573,7 +573,7 @@ Returns the angle, aka uv rotation, painted on the control map at the requested .. rst-class:: classref-method -:ref:`Color` **get_color**\ (\ global_position\: :ref:`Vector3`\ ) :ref:`🔗` +:ref:`Color` **get_color**\ (\ global_position\: :ref:`Vector3`\ ) |const| :ref:`🔗` Returns the associated pixel on the color map at the requested position. Calls :ref:`get_pixel`. @@ -585,7 +585,7 @@ Returns the associated pixel on the color map at the requested position. Calls : .. rst-class:: classref-method -:ref:`int` **get_control**\ (\ global_position\: :ref:`Vector3`\ ) :ref:`🔗` +:ref:`int` **get_control**\ (\ global_position\: :ref:`Vector3`\ ) |const| :ref:`🔗` Returns the associated pixel on the control map at the requested position. Calls :ref:`get_pixel`. @@ -597,7 +597,7 @@ Returns the associated pixel on the control map at the requested position. Calls .. rst-class:: classref-method -:ref:`float` **get_height**\ (\ global_position\: :ref:`Vector3`\ ) :ref:`🔗` +:ref:`float` **get_height**\ (\ global_position\: :ref:`Vector3`\ ) |const| :ref:`🔗` Returns the height at the requested position. If the position is close to a vertex, the pixel height on the heightmap is returned. Otherwise the value is interpolated from the 4 vertices surrounding the position. @@ -613,7 +613,7 @@ Calls :ref:`get_pixel`. .. rst-class:: classref-method -:ref:`Image` **get_map_region**\ (\ map_type\: :ref:`MapType`, region_index\: :ref:`int`\ ) :ref:`🔗` +:ref:`Image` **get_map_region**\ (\ map_type\: :ref:`MapType`, region_index\: :ref:`int`\ ) |const| :ref:`🔗` Returns the Image for the specified map type and region. E.g. Returns the region_size height map Image at the first defined region 0. @@ -625,7 +625,7 @@ Returns the Image for the specified map type and region. E.g. Returns the region .. rst-class:: classref-method -:ref:`Array`\[:ref:`Image`\] **get_maps**\ (\ map_type\: :ref:`MapType`\ ) :ref:`🔗` +:ref:`Array`\[:ref:`Image`\] **get_maps**\ (\ map_type\: :ref:`MapType`\ ) |const| :ref:`🔗` Returns an Array of Images containing all of the regions for the specified map type. @@ -637,7 +637,7 @@ Returns an Array of Images containing all of the regions for the specified map t .. rst-class:: classref-method -:ref:`Array`\[:ref:`Image`\] **get_maps_copy**\ (\ map_type\: :ref:`MapType`\ ) :ref:`🔗` +:ref:`Array`\[:ref:`Image`\] **get_maps_copy**\ (\ map_type\: :ref:`MapType`\ ) |const| :ref:`🔗` Returns a copy of the Array of Images containing all of the regions for the specified map type. @@ -649,7 +649,7 @@ Returns a copy of the Array of Images containing all of the regions for the spec .. rst-class:: classref-method -:ref:`Vector3` **get_mesh_vertex**\ (\ lod\: :ref:`int`, filter\: :ref:`HeightFilter`, global_position\: :ref:`Vector3`\ ) :ref:`🔗` +:ref:`Vector3` **get_mesh_vertex**\ (\ lod\: :ref:`int`, filter\: :ref:`HeightFilter`, global_position\: :ref:`Vector3`\ ) |const| :ref:`🔗` Returns the position of a terrain vertex at a certain LOD. If there is a hole at the position, it returns ``NAN`` in the vector's Y coordinate. @@ -667,7 +667,7 @@ Returns the position of a terrain vertex at a certain LOD. If there is a hole at .. rst-class:: classref-method -:ref:`Vector3` **get_normal**\ (\ global_position\: :ref:`Vector3`\ ) :ref:`🔗` +:ref:`Vector3` **get_normal**\ (\ global_position\: :ref:`Vector3`\ ) |const| :ref:`🔗` Returns the terrain normal at the specified position. This function uses :ref:`get_height`. @@ -681,7 +681,7 @@ Returns ``Vector3(NAN, NAN, NAN)`` if the requested position is a hole or outsid .. rst-class:: classref-method -:ref:`Color` **get_pixel**\ (\ map_type\: :ref:`MapType`, global_position\: :ref:`Vector3`\ ) :ref:`🔗` +:ref:`Color` **get_pixel**\ (\ map_type\: :ref:`MapType`, global_position\: :ref:`Vector3`\ ) |const| :ref:`🔗` Returns the pixel for the map type associated with the specified position. @@ -695,7 +695,7 @@ Returns ``Color(NAN, NAN, NAN, NAN)`` if the position is outside of defined regi .. rst-class:: classref-method -:ref:`int` **get_region_count**\ (\ ) :ref:`🔗` +:ref:`int` **get_region_count**\ (\ ) |const| :ref:`🔗` Returns the number of allocated regions. @@ -707,7 +707,7 @@ Returns the number of allocated regions. .. rst-class:: classref-method -:ref:`int` **get_region_index**\ (\ global_position\: :ref:`Vector3`\ ) :ref:`🔗` +:ref:`int` **get_region_index**\ (\ global_position\: :ref:`Vector3`\ ) |const| :ref:`🔗` Returns the index into the :ref:`region_offsets` array for the region associated with the specified position. @@ -719,7 +719,7 @@ Returns the index into the :ref:`region_offsets` **get_region_index_from_offset**\ (\ region_offset\: :ref:`Vector2i`\ ) :ref:`🔗` +:ref:`int` **get_region_index_from_offset**\ (\ region_offset\: :ref:`Vector2i`\ ) |const| :ref:`🔗` Returns the current region ID based on a Vector2i region offset. @@ -731,7 +731,7 @@ Returns the current region ID based on a Vector2i region offset. .. rst-class:: classref-method -:ref:`Vector2i` **get_region_offset**\ (\ global_position\: :ref:`Vector3`\ ) :ref:`🔗` +:ref:`Vector2i` **get_region_offset**\ (\ global_position\: :ref:`Vector3`\ ) |const| :ref:`🔗` Converts a world space position to region space. For a region_size of 1024 this basically means ``global_position/1024.0``. Also see :ref:`region_offsets`. @@ -743,7 +743,7 @@ Converts a world space position to region space. For a region_size of 1024 this .. rst-class:: classref-method -:ref:`Vector2i` **get_region_offset_from_index**\ (\ region_index\: :ref:`int`\ ) :ref:`🔗` +:ref:`Vector2i` **get_region_offset_from_index**\ (\ region_index\: :ref:`int`\ ) |const| :ref:`🔗` Returns a Vector2i region offset based on the current region ID. @@ -755,7 +755,7 @@ Returns a Vector2i region offset based on the current region ID. .. rst-class:: classref-method -:ref:`float` **get_roughness**\ (\ global_position\: :ref:`Vector3`\ ) :ref:`🔗` +:ref:`float` **get_roughness**\ (\ global_position\: :ref:`Vector3`\ ) |const| :ref:`🔗` Returns the roughness modifier (wetness) on the color map alpha channel associated with the specified position. Calls :ref:`set_pixel`. @@ -767,7 +767,7 @@ Returns the roughness modifier (wetness) on the color map alpha channel associat .. rst-class:: classref-method -:ref:`float` **get_scale**\ (\ global_position\: :ref:`Vector3`\ ) :ref:`🔗` +:ref:`float` **get_scale**\ (\ global_position\: :ref:`Vector3`\ ) |const| :ref:`🔗` Returns the uv scale painted on the control map at the requested position. The value is a percentage difference from 100% scale. Eg. +20% or -40%. Calls :ref:`get_pixel`. @@ -779,7 +779,7 @@ Returns the uv scale painted on the control map at the requested position. The v .. rst-class:: classref-method -:ref:`Vector3` **get_texture_id**\ (\ global_position\: :ref:`Vector3`\ ) :ref:`🔗` +:ref:`Vector3` **get_texture_id**\ (\ global_position\: :ref:`Vector3`\ ) |const| :ref:`🔗` Returns ``Vector3(base texture id, overlay id, blend value)``. @@ -799,7 +799,7 @@ Observing how this is done in The Witcher 3, there are only about 6 sounds used .. rst-class:: classref-method -:ref:`bool` **has_region**\ (\ global_position\: :ref:`Vector3`\ ) :ref:`🔗` +:ref:`bool` **has_region**\ (\ global_position\: :ref:`Vector3`\ ) |const| :ref:`🔗` Returns true if the specified position has a region allocated. @@ -831,7 +831,7 @@ Imports an Image set (Height, Control, Color) into this resource. It does NOT no .. rst-class:: classref-method -:ref:`Image` **layered_to_image**\ (\ map_type\: :ref:`MapType`\ ) :ref:`🔗` +:ref:`Image` **layered_to_image**\ (\ map_type\: :ref:`MapType`\ ) |const| :ref:`🔗` Returns an Image of the given map type that contains all regions in one large image. If the world has multiple islands, this function will return an image large enough to encompass all used regions, with black areas in between the islands. diff --git a/doc/classes/Terrain3D.xml b/doc/classes/Terrain3D.xml index 05394c11..1e3875a6 100644 --- a/doc/classes/Terrain3D.xml +++ b/doc/classes/Terrain3D.xml @@ -9,7 +9,7 @@ - + @@ -19,7 +19,7 @@ [code skip-lint]filter[/code] - Controls how vertex Y coordinates are generated from the height map. See [enum Terrain3DStorage.HeightFilter]. - + @@ -29,12 +29,24 @@ [code skip-lint]require_nav[/code] - If true, this function will only generate geometry for terrain marked navigable. Otherwise, geometry is generated for the entire terrain within the AABB (which can be useful for dynamic and/or runtime nav mesh baking). - + Returns the camera the terrain is currently snapping to. + + + + Returns the RID of the active StaticBody. + + + + + + Returns the current Terrain3DEditor instance, if it has been set. + + @@ -50,7 +62,7 @@ It does require the use of an editor render layer (21-32) that should be dedicated while using this function. See [member render_mouse_layer]. - + Returns the EditorPlugin connected to Terrain3D. @@ -63,6 +75,13 @@ Sets the camera the terrain snaps to. + + + + + Sets the current Terrain3DEditor instance. + + diff --git a/doc/classes/Terrain3DAssets.xml b/doc/classes/Terrain3DAssets.xml index 5b902615..f49d7ba8 100644 --- a/doc/classes/Terrain3DAssets.xml +++ b/doc/classes/Terrain3DAssets.xml @@ -16,27 +16,27 @@ Generates mesh asset preview thumbnails for the asset dock, stored within each mesh asset. Specify id -1 to generate all. - + Returns the specified Terrain3DMeshAsset resource. - + Returns the number of mesh assets in the list. - + Returns the Terrain3DTextureAsset with the requested ID. - + Returns the number of texture slots used. diff --git a/doc/classes/Terrain3DEditor.xml b/doc/classes/Terrain3DEditor.xml index 6cc11dc2..201b503c 100644 --- a/doc/classes/Terrain3DEditor.xml +++ b/doc/classes/Terrain3DEditor.xml @@ -15,25 +15,25 @@ Undo the previous changes, with the reverted images in the array. Used by Godot, not users. - + Returns the current operation. - + Returns the instance of Terrain3D this class is conneced to. - + Returns the current tool selected in the editor plugin. - + Returns true if currently brushing. @@ -96,55 +96,49 @@ Subtractive operations. - - Multiplicative operations. - - - Divisive operations. - - + Replacing operations. - + Averaging operations. - + Gradient operations. - + The number of elements in this enum. - + Sculpt heights. - + Paint textures. - + Paint on the color map. - + Paint a roughness modifier, aka wetness. - + Paint textures rotated by an angle. - + Paint textures scaled by a value. - + Paint where the shader automatically textures. - + Paint where vertices will be invalidated to leave holes. - + Paint where navigation will be generated. - + Paint MultiMesh instances on the ground. - + Add/remove regions. diff --git a/doc/classes/Terrain3DInstancer.xml b/doc/classes/Terrain3DInstancer.xml index 6b7d9618..7234cdcb 100644 --- a/doc/classes/Terrain3DInstancer.xml +++ b/doc/classes/Terrain3DInstancer.xml @@ -46,6 +46,17 @@ This function adds the [member Terrain3DMeshAsset.height_offset] to the transform along its local Y axis. + + + + + + + + + Appends new transforms to existing multimeshes. Multimesh transform arrays cannot be modified and must be rebuilt. This will make a new array with both old and new transforms. `Clear` will skip the old array. + + @@ -69,6 +80,12 @@ Removes both MultiMeshInstance nodes attached to the tree, and MultiMeshes in Storage for the specified region id and mesh id. + + + + Returns the dictionary containing the MultiMeshInstance3D nodes, which are hidden children of Terrain3D. The dictionary is keyed by Vector3i(region_offset.x, region_offset.y, mesh_id). + + @@ -85,5 +102,12 @@ Tells the renderer how to cast shadows from this mesh asset onto the terrain and other objects. This sets [code skip-lint]GeometryInstance3D.ShadowCastingSetting[/code] on all MultiMeshInstances for the specified mesh. This function is called by [member Terrain3DMeshAsset.cast_shadows], but you can also call it manually. + + + + + Reviews all existing instance transforms within an AABB and adjusts their heights to match the terrain. + + diff --git a/doc/classes/Terrain3DMaterial.xml b/doc/classes/Terrain3DMaterial.xml index 518c71c5..8af18185 100644 --- a/doc/classes/Terrain3DMaterial.xml +++ b/doc/classes/Terrain3DMaterial.xml @@ -11,26 +11,26 @@ - + Returns the RID of the material used with the Rendering Server. This is set per instance of this class. - + Returns the RID of the 512x512 texture used with the RenderingServer. It depicts a blurry map of region locations and is used for smoothly blending world noise into sculpted terrain. - + Retrieve a parameter from the active shader (built-in or override shader). - + Returns the RID of the built in shader used with the Rendering Server. This is different from any shader override which has its own RID. @@ -50,6 +50,12 @@ Set a parameter in the active shader (built-in or override shader). + + + + Recompiles the current shader and sends all uniform values to it again. + + diff --git a/doc/classes/Terrain3DMeshAsset.xml b/doc/classes/Terrain3DMeshAsset.xml index aa527d13..c848aab7 100644 --- a/doc/classes/Terrain3DMeshAsset.xml +++ b/doc/classes/Terrain3DMeshAsset.xml @@ -24,13 +24,13 @@ Returns the specified Mesh resource indicated. Only id 0 is used currently. - + Returns the number of Mesh resources found in the scene file and stored. - + Returns the thumbnail generated by [Terrain3DAssets]. diff --git a/doc/classes/Terrain3DStorage.xml b/doc/classes/Terrain3DStorage.xml index 03a0f095..16f151f2 100644 --- a/doc/classes/Terrain3DStorage.xml +++ b/doc/classes/Terrain3DStorage.xml @@ -22,7 +22,7 @@ - p_update - rebuild the maps if true. Set to false if bulk adding many regions, then true on the last one or use [method force_update_maps]. - + @@ -40,28 +40,28 @@ Regenerates the TextureArrays that house the requested map types. Using the default [enum MapType] TYPE_MAX(3) will regenerate all map types. - + Returns the angle, aka uv rotation, painted on the control map at the requested position. Values are fixed to 22.5 degree intervals, for a maximum of 16 angles. 360 / 16 = 22.5. Calls [method get_pixel]. - + Returns the associated pixel on the color map at the requested position. Calls [method get_pixel]. - + Returns the associated pixel on the control map at the requested position. Calls [method get_pixel]. - + @@ -70,7 +70,7 @@ Calls [method get_pixel]. - + @@ -78,21 +78,21 @@ Returns the Image for the specified map type and region. E.g. Returns the region_size height map Image at the first defined region 0. - + Returns an Array of Images containing all of the regions for the specified map type. - + Returns a copy of the Array of Images containing all of the regions for the specified map type. - + @@ -104,7 +104,7 @@ [code skip-lint]global_position[/code] - X and Z coordinates of the vertex. Heights will be sampled around these coordinates. - + @@ -112,7 +112,7 @@ Returns [code skip-lint]Vector3(NAN, NAN, NAN)[/code] if the requested position is a hole or outside of defined regions. - + @@ -121,55 +121,55 @@ Returns [code skip-lint]Color(NAN, NAN, NAN, NAN)[/code] if the position is outside of defined regions. - + Returns the number of allocated regions. - + Returns the index into the [member region_offsets] array for the region associated with the specified position. - + Returns the current region ID based on a Vector2i region offset. - + Converts a world space position to region space. For a region_size of 1024 this basically means [code skip-lint]global_position/1024.0[/code]. Also see [member region_offsets]. - + Returns a Vector2i region offset based on the current region ID. - + Returns the roughness modifier (wetness) on the color map alpha channel associated with the specified position. Calls [method set_pixel]. - + Returns the uv scale painted on the control map at the requested position. The value is a percentage difference from 100% scale. Eg. +20% or -40%. Calls [method get_pixel]. - + @@ -180,7 +180,7 @@ Observing how this is done in The Witcher 3, there are only about 6 sounds used (snow, foliage, dirt, gravel, rock, wood), and except for wood, they are not pixel perfect. Wood is easy to do by detecting if the player is walking on wood meshes. The other 5 sounds are played when the player is in an area where the textures are blending. So it might play rock while over a dirt area. This shows pixel perfect accuracy is not important. It will still provide a seamless audio visual experience. - + @@ -201,7 +201,7 @@ [code skip-lint]scale[/code] - Scale all height values by this factor (applied after offset). - + diff --git a/doc/docs/building_from_source.md b/doc/docs/building_from_source.md index fce85efd..91771d22 100644 --- a/doc/docs/building_from_source.md +++ b/doc/docs/building_from_source.md @@ -27,7 +27,12 @@ remote: Compressing objects: 100% (79/79), done. remote: Total 125 (delta 56), reused 94 (delta 36), pack-reused 0 Receiving objects: 100% (125/125), 42.20 KiB | 194.00 KiB/s, done. Resolving deltas: 100% (56/56), done. +``` + +## 3. Initialize the submodule repository + +``` $ cd Terrain3D Terrain3D$ git submodule init @@ -44,7 +49,7 @@ Note the version it checked out: **9d1c396**... This hash number is important for the next section. -## 3. Identify the appropriate godot-cpp version +## 4. Identify the appropriate godot-cpp version The checked out version of the godot-cpp submodule needs to match the version of your Godot engine build. e.g. Godot Engine 4.0.2 official build with godot-cpp checked out to a 4.0.2 branch. The early days of Godot 4.x were very strict and required the exact same major, minor, and patch versions. Since then, the requirements have loosened. For instance we've matched godot-cpp 4.1.3 with Godot engine 4.1.3 through 4.2.1 without issue. @@ -109,7 +114,7 @@ Date: Wed Mar 1 15:32:44 2023 +0100 ``` -## 4. Check out the correct version +## 5. Check out the correct version Once you have identified the proper tag or commit string, and you have updated the godot-cpp submodule (step 3), you just need to check it out. If using a commit string, you may use either the full hash or just the first 6-8 characters, so `9d1c396` would also match 4.0-stable. These examples will change the godot-cpp repository to 4.0-stable and 4.02-stable, respectively: @@ -127,7 +132,7 @@ HEAD is now at 7fb46e9 gdextension: Sync with upstream commit 7a0977ce2c558fe621 ``` -## 5. Build the extension +## 6. Build the extension By default `scons` will build the debug library which works for the editor and debug exports. You can add `target=template_release` to build the release version. @@ -150,7 +155,7 @@ scons: done building targets. ``` -## 6. Set up the extension in Godot +## 7. Set up the extension in Godot 1. Build Terrain3D, then ensure binary libraries exist in `project/addons/terrain_3d/bin`. 2. Close Godot. (Not required the first time, but necessary when updating the files on subsequent builds.) diff --git a/doc/docs/collision.md b/doc/docs/collision.md new file mode 100644 index 00000000..9957cc71 --- /dev/null +++ b/doc/docs/collision.md @@ -0,0 +1,77 @@ +Collision +======================= + +One of the most important things about a terrain is knowing where it is. Terrain3D provides several methods for detecting terrain height. + +Using collision is not the only way, nor even the best or fastest way. But we'll start with it as it is the most common. + +## Physics Based Collision & Raycasting + +Collision is generated at runtime using the physics server. Regular PhysicsBodies will interact with this collision as expected. To detect ground height, use a [ray cast](https://docs.godotengine.org/en/stable/tutorials/physics/ray-casting.html). However, outside of regions, there is no collision, so raycasts won't hit. + +Normally the editor doesn't generate collision, but some addons or other activities do need editor collision. To generate it, enable `Terrain3D/Debug/Show Collision`, or set `Terrain3D.debug_show_collision`. You can run in game with this enabled. + +This debug option will generate collision one time when enabled or at startup. If the terrain is sculpted afterwards, this collision will be inaccurate to the visual mesh until it is disabled and enabled again. On a Core-i9 12900H, generating collision takes about 145ms per region, so updating it several times per second while sculpting is not practical. Currently all regions are regenerated, rather than only modified regions so it is not optimal. You can follow [PR#278](https://github.com/TokisanGames/Terrain3D/pull/278) for an improved system. + +See the [Terrain3D API](../api/class_terrain3d.rst) for various functions that configure the collision priority, layers, and mask. + +## Raycasting Without Physics + +It is possible to cast a ray from any position and any direction and detect the collision point on the terrain using the GPU instead of the physics engine. + +Sending the source point and ray direction to [Terrain3D.get_intersection()](../api/class_terrain3d.rst#class-terrain3d-method-get-intersection) will return the intersection point on success. + +Being GPU based, this function works outside of regions. + +This function works fine if called *only once per frame*, such as for a mouse pointer detecting terrain position. More than once per frame will produce conflicts. + +You can review [editor.gd](https://github.com/TokisanGames/Terrain3D/blob/v0.9.1-beta/project/addons/terrain_3d/editor/editor.gd#L129-L143) to see an example of projecting the mouse position onto the terrain using this function. + +Use it only when you don't already know the X, Z collision point. + + +## Query Height At Any Position + +If you already know the X, Z position, use `get_height()`: + +```gdscript + var height: float = terrain.storage.get_height(global_position) +``` + +`NAN` is returned if the position is a hole, or outside of regions. + +This is ideal for one lookup. Use the next option for greater efficiency. + + +## Query Many Heights + +If you wish to look up thousands of heights, it will be faster to retrieve the heightmap Image for the region and query the data directly. + +However, note that `get_height()` above will [interpolate between vertices](https://github.com/TokisanGames/Terrain3D/blob/5bab86ff311159356dd4d837ea2c340f59d139b6/src/terrain_3d_storage.cpp#L493-L502), while this code will not. + +```gdscript + var region_index: int = terrain.storage.get_region_index(global_position) + var img: Image = terrain.storage.get_map_region(Terrain3DStorage.TYPE_HEIGHT, region_index) + for y in img.get_height(): + for x in img.get_width(): + var height: float = img.get_pixel(x, y).r +``` + +---- + +## Additional Tips + + +### Getting The Normal + +After getting the height, you may also wish to get the normal with `Terrain3DStorage.get_normal(global_position)`. The normal is the vector3 pointing perpendulcar to the terrain face. + + +### Visualizing Collision + +To see the collision shape, first enable `Terrain3D/Debug/Show Collision` as described above. + +To see it in the editor, in the Godot `Perspective` menu, enable `View Gizmos`. Disable this option on slow systems. + +To see debug collision in game, in the Godot `Debug` menu, enable `Visible Collision Shapes` and run the scene. + diff --git a/doc/docs/games.md b/doc/docs/games.md index 243e9203..cb096893 100644 --- a/doc/docs/games.md +++ b/doc/docs/games.md @@ -1,10 +1,11 @@ # Games Using Terrain3D -Terrain3D is being used in the following games. To add yours, submit it in the #game-dev channel on [our discord server](https://tokisan.com/discord). +Terrain3D is being used in the following games. To add yours, submit it to the #game-dev channel on [our discord server](https://tokisan.com/discord). | Game | Studio | Description | -|---|---|---| +|------|--------|-------------| | [Out of the Ashes](https://tokisan.com/out-of-the-ashes/) | [Tokisan Games](https://twitter.com/TokisanGames) | Story driven medieval adventure | [Memora Wanderer](https://twitter.com/Maytch) | Maytch | Cute nostalgic RPG | [No Gasoline](https://store.steampowered.com/app/2835350/No_Gasoline/) | [Mount Retro](https://twitter.com/mountretro) | Co-Op/Solo, Adventure-Simulation-Puzzle | [RotorSim](https://immaculate-lift-studio.itch.io/godot-flight-simulator-alpha) | [Immaculate Lift](https://www.youtube.com/channel/UC-9JixNs1FFE6T5DGwZ6O5Q) | Retro helicopter simulation +| [Jungle Demo](https://wrobot.itch.io/jungledemo) | [WrobotGames](https://x.com/wrobot123) | Godot rendering demo in a jungle diff --git a/doc/docs/images/ui_tools.png b/doc/docs/images/ui_tools.png index bcdb71b2..b4212f3a 100644 Binary files a/doc/docs/images/ui_tools.png and b/doc/docs/images/ui_tools.png differ diff --git a/doc/docs/installation.md b/doc/docs/installation.md index 2ce01752..426e9aa5 100644 --- a/doc/docs/installation.md +++ b/doc/docs/installation.md @@ -1,23 +1,44 @@ Installation & Upgrades ========================== +**Table of Contents** +* [Requirements](#requirements) +* [Installing Terrain3D](#installing-terrain3d) +* [Upgrading Terrain3D](#upgrading-terrain3d) + ## Requirements * Supports Godot 4.2+. * Supports Windows, Linux, and macOS. * macOS users should [build from source](building_from_source.md) or [adjust security settings](https://github.com/TokisanGames/Terrain3D/issues/227) to use the binary release. * Mobile, Web, SteamDeck, & Compatibility renderer are [experimental or pending](mobile_web.md). -## Running the demo +## Installing Terrain3D + +### From The Asset Library +Terrain3D is listed in the Asset Library [here](https://godotengine.org/asset-library/asset/3134), but you can download it directly within Godot. +1. Setup a project within Godot. +2. Click `AssetLib` at the top of the Godot window. +3. Search for `Terrain3D`, and click the entry from `TokisanGames`. +4. Click `Download`. +5. Godot will ask you to install files into `addons` and `demo`. Demo is optional, but highly recommended for troubleshooting. Click `Install`. +6. Restart when Godot prompts. +7. In `Project Settings / Plugins`, ensure that Terrain3D is enabled. +8. Select `Project / Reload Current Project` to restart once more. +9. Open `demo/Demo.tscn`. You should see a terrain. Run the scene by pressing `F6`. + +If it isn't working for you, watch the [tutorial videos](tutorial_videos.md) and read [Troubleshooting](troubleshooting.md) and [Getting Help](getting_help.md). + +### Manually Running The Demo 1. Download the [latest binary release](https://github.com/TokisanGames/Terrain3D/releases) and extract the files, or [build the plugin from source](building_from_source.md). 2. Run Godot using the console executable so you can see error messages. 3. In the Project Manager, import the demo project and open it. Restart when it prompts. 4. In `Project Settings / Plugins`, ensure that Terrain3D is enabled. 5. Select `Project / Reload Current Project` to restart once more. -6. If the demo scene doesn't open automatically, open `demo/Demo.tscn`. You should see a terrain. Run the scene by pressing F6. +6. If the demo scene doesn't open automatically, open `demo/Demo.tscn`. You should see a terrain. Run the scene by pressing `F6`. If it isn't working for you, watch the [tutorial videos](tutorial_videos.md) and read [Troubleshooting](troubleshooting.md) and [Getting Help](getting_help.md). -## Installing Terrain3D in your project +### Manually Into Your Project 1. Download the [latest binary release](https://github.com/TokisanGames/Terrain3D/releases) and extract the files, or [build the plugin from source](building_from_source.md). 2. Copy `addons/terrain_3d` to your project folder as `addons/terrain_3d`. 3. Run Godot using the console executable so you can see error messages. Restart when it prompts. @@ -37,7 +58,7 @@ To update Terrain3D: Don't just copy the new folder over the old, as this won't remove any files that we may have intentionally removed. -## Upgrade Path +### Upgrade Path While later versions of Terrain3D can generally open previous versions, not all data will be loaded unless the supported upgrade path is followed. We occasionally deprecate or rename classes and provide upgrade paths to convert data for a limited time. diff --git a/doc/docs/nightly_builds.md b/doc/docs/nightly_builds.md index 52124181..fe160883 100644 --- a/doc/docs/nightly_builds.md +++ b/doc/docs/nightly_builds.md @@ -22,3 +22,10 @@ They are exactly the same construction as the releases except for the commit use ``` If have trouble with the unsigned macOS released builds or wish to contribute, learn how to [Build from Source](building_from_source.md) on your own system. + + +## PR Builds + +You can also test builds of PRs. Instead of specifying the `main` branch above, select the branch listed at the top of the PR. Or click the `Checks` tab, then `Build All` to see the summary page, which has the artifact. + +If looking at a PR from another contributor, you'll need to look at their repository. Click the `from` branch at the top of the PR to go to their repo. Then click `Actions` to get the latest build from the appropriate branch. \ No newline at end of file diff --git a/doc/docs/press.md b/doc/docs/press.md index 72a095cd..17d87fd1 100644 --- a/doc/docs/press.md +++ b/doc/docs/press.md @@ -4,9 +4,15 @@ Terrain3D has been featured in the following media: | Organization | Published | Link 1 | Link 2| |---|---|---|---| +| 80 Level | July 19, 2024 | [Article](https://80.lv/articles/you-can-now-paint-texture-rotation-scale-with-godot-s-terrain3d/) | [Tweet](https://x.com/80Level/status/1814253864545042946) | Blips | Dec 26, 2023 | [Article](https://blog.blips.fm/articles/terrain3d-a-terrain-system-for-godot-4-enters-beta-phase) | 80 Level | Dec 19, 2023 | [Article](https://80.lv/articles/this-free-terrain-system-for-godot-engine-enters-beta/) | [Tweet](https://twitter.com/80Level/status/1736937052946543084) | 80 Level | July 27, 2023 | [Article](https://80.lv/articles/terrain3d-a-free-terrain-system-for-godot-engine/) | [Tweet](https://twitter.com/80Level/status/1684473704972177409) | Blips | July 24, 2023 | [Article](https://blog.blips.fm/articles/terrain3d-a-new-terrain-system-for-godot-4) | Godot Engine | July 19, 2023 | [Article](https://godotengine.org/article/dev-snapshot-godot-4-2-dev-1/) | GameFromScratch | July 18, 2023 | [Video](https://www.youtube.com/watch?v=NwJEXOglBrQ) | [Article](https://gamefromscratch.com/terrain3d-a-new-terrain-engine-for-godot/) + + + + + diff --git a/doc/docs/integrating.md b/doc/docs/programming_languages.md similarity index 51% rename from doc/docs/integrating.md rename to doc/docs/programming_languages.md index 8475a9a1..00a30dcc 100644 --- a/doc/docs/integrating.md +++ b/doc/docs/programming_languages.md @@ -1,9 +1,9 @@ -Integrating with Terrain3D +Programming Languages =========================== -This page is for more advanced gamedevs who want to access Terrain3D from other languages like C# or those developing tools & addons. +Any language Godot supports should be able to work with Terrain3D via the GDExtension interface. This includes [C#](https://docs.godotengine.org/en/stable/tutorials/scripting/c_sharp/index.html), and [several others](https://docs.godotengine.org/en/stable/tutorials/scripting/gdextension/what_is_gdextension.html#supported-languages). -Any language Godot supports should be able to work with Terrain3D via the GDExtension interface. +Here are some tips for integrating with Terrain3D. ```{image} images/integrating_gdextension.png :target: ../_images/integrating_gdextension.png @@ -107,58 +107,11 @@ These options are for programming scenarios where a user action is intented to p print("Found terrain") ``` -## Understanding Regions -Terrain3D provides users non-contiguous 1024x1024 sized regions on a 16x16 region grid. So a user might have a 1k x 2k island in one corner of the world and a 4k x 4k island elsewhere. In between are empty regions, visually flat space where they could place an ocean. In these empty regions, no vram is consumed, nor collision generated. -Outside of regions, raycasts won't hit anything, and querying terrain intersections will return NANs or INF (i.e. >3.4e38). +## Detecting Terrain Height -You can determine if a given location is within a region by using `Terrain3DStorage.get_region_index(global_position)`. It will return -1 if the XZ location is not within a region. Y is ignored. - - -## Detecting Terrain Height or Position - -There are multiple ways to detect an intersection with the terrain. After which you may wish to use `Terrain3DStorage.get_normal(global_position)`. - -### Query the height at any position - -You can ask Terrain3DStorage for the height at any given location: - -```gdscript - var height: float = terrain.storage.get_height(global_position) -``` - -Nan is returned if the position is a hole, or not within a region. - -This is ideal for one lookup. However, if you wish to look up thousands of heights, it might be faster to retrieve the heightmap Image for the region and query it directly. However, note that `get_height()` will interpolate between vertices, while this code will not. - -```gdscript - var region_index: int = terrain.storage.get_region_index(global_position) - var img: Image = terrain.storage.get_map_region(Terrain3DStorage.TYPE_HEIGHT, region_index) - for y in img.get_height(): - for x in img.get_width(): - var height: float = img.get_pixel(x, y).r -``` - - -### Raycasting with Physics - -Normally, collision is not generated in the editor. If `Terrain3D.debug_show_collision` is enabled, it will generate collision in the editor and you can do a normal raycast. This mode also works fine while running in a game. - -This debug option will generate collision one time when enabled or at startup. If the terrain is sculpted afterwards, this collision will be inaccurate to the visual mesh until it is disabled and enabled again. On a Core-i9 12900H, generating collision takes about 145ms per region, so updating it several times per second while sculpting is not practical. Currently all regions are regenerated, rather than only modified regions so it is not optimal. - -There is no collision outside of regions, so raycasts won't hit. - -See the Godot docs to learn how to use physics based [Ray-casting](https://docs.godotengine.org/en/stable/tutorials/physics/ray-casting.html). - - -### Raycasting without Physics - -It is possible to cast a ray from any given position and detect the collision point on the terrain using the GPU instead of the physics engine. - -Sending the source point and ray direction to [Terrain3D.get_intersection()](../api/class_terrain3d.rst#class-terrain3d-method-get-intersection) will return the intersection point on success. - -You can review [editor.gd](https://github.com/TokisanGames/Terrain3D/blob/v0.9.1-beta/project/addons/terrain_3d/editor/editor.gd#L129-L143) to see an example of projecting the mouse position onto the terrain using this function. +See [Collision](collision.md) for several methods. ## Getting Updates on Terrain Changes diff --git a/doc/docs/project_status.md b/doc/docs/project_status.md index 85615a85..ab2e3f23 100644 --- a/doc/docs/project_status.md +++ b/doc/docs/project_status.md @@ -11,19 +11,19 @@ See the [Roadmap](https://github.com/users/TokisanGames/projects/3/views/1) for | **Platforms** | Terrain editing and exported games work on Windows, Linux, macOS. [Mobile and web platforms](mobile_web.md) are experimental. | **Languages** | GDScript, C++, C# all work, as should any language Godot supports. See [Integrating With Terrain3D](integrating.md) | **Editing** | -| Sculpting Operations | Raise, Lower, Flatten, Expand (Multiply away from 0), Reduce (Divide towards 0), Slope and Smooth. It can be improved over time. -| Painting Operations | Texture, Color, Wetness (roughness) with Height blending. +| Sculpting Operations | Raise, Lower, Slope, Smooth. +| Painting Operations | Texture, Color, Wetness with Height blending. | GPU Sculpting| [Pending](https://github.com/TokisanGames/Terrain3D/issues/174). Currently painting occurs on the CPU in C++. It's reasonably fast, but we have a soft limit of 200 on the brush size, as larger sizes lag. -| Advanced texturing| [Pending](https://github.com/TokisanGames/Terrain3D/discussions/64) and [this](https://github.com/TokisanGames/Terrain3D/discussions/4). eg. Paintable uv scale / slope / rotation, 2-layer texture blending, 3D projection. We intend to implement all of these and adopt techniques provided by The Witcher 3 team. (See [System Architecture](system_architecture.md)) +| Advanced texturing| Paintable uv scale / rotation, 2-layer texture blending implemented. Pending slope painting, 3D projection, and more advanced texture blending. | **Environment** | -| Foliage | Meshes without collision can be painted on the terrain and instanced via our Terrain3DInstancer. In the future, collision may be generated. Alternatively, you could create a particle shader for automatic placement. -| Object placement | Placed scenes outside of a MultiMeshInstance node is [out of scope](https://github.com/TokisanGames/Terrain3D/issues/47). See 3rd party tools below. +| Foliage | Meshes without collision can be painted on the terrain and instanced via our Terrain3DInstancer which is a MultiMeshInstance painter. In the future, collision may be generated. Alternatively, you could create a particle shader for automatic placement. +| Object placement | Objects that shouldn't be in a MultiMeshInstance node is [out of scope](https://github.com/TokisanGames/Terrain3D/issues/47). See 3rd party tools below. | Holes | Supported since 0.9. See [#60](https://github.com/TokisanGames/Terrain3D/issues/60#issuecomment-1817623935) | Water | Use [WaterWays](https://github.com/Arnklit/Waterways) for rivers, or [Realistic Water Shader](https://github.com/godot-extended-libraries/godot-realistic-water/) or [Infinite Ocean](https://stayathomedev.com/tutorials/making-an-infinite-ocean-in-godot-4/) for lakes or oceans. | Destructibility | Real-time modification is technically possible by fetching the height and control maps and directly modifying them. That's how the editor works. But most gamedevs who want destructible terrains are better served by [Zylann's Voxel Tools](https://github.com/Zylann/godot_voxel). | Non-destructive layers | Used for things like river beds, roads or paths that follow a curve and tweak the terrain. It's [possible](https://github.com/TokisanGames/Terrain3D/issues/129) in the future, but low priority. | **Physics** | -| Godot | Works within regions you define in your world. No collision outside of those. +| Godot | Works within the regions you define in your world. No collision outside of those. | Jolt | [Godot-Jolt](https://github.com/godot-jolt/godot-jolt) v0.6+ works as a drop-in replacement for Godot Physics. The above restriction applies. | **Navigation Server** | Supported. See [Navigation](navigation.md) | **Data** | diff --git a/doc/docs/tips.md b/doc/docs/tips.md index 71b20469..6cd0b5e2 100644 --- a/doc/docs/tips.md +++ b/doc/docs/tips.md @@ -1,21 +1,28 @@ Tips ====== -## General +## Understanding Regions -* Always run Godot with the [console](troubleshooting.md#use-the-console) open so you can see errors and messages from the engine. The output panel is slow and inadequate. +Terrain3D provides users non-contiguous 1024x1024 sized regions on a 16x16 region grid. So a user might have a 1k x 2k island in one corner of the world and a 4k x 4k island elsewhere. In between are empty regions, visually flat space where they could place an ocean. In these empty regions, no vram is consumed, nor collision generated. -* When another mesh intersects with Terrain3D far away from the camera, such as in the case of water on a beach, the two meshes can flicker as the renderer can't decide which mesh should be displayed in front. This is also called Z-fighting. You can greatly reduce it by increasing `Camera3D.near` to 0.25. You can also set it for the editor camera in the main viewport by adjusting `View/Settings/View Z-Near`. +The regions are visible if `View Gizmos` is enabled in the Godot `Perspective` menu. + +You pay in memory and vram for each region you have, so be aware of their use. If you're going to have a small world that will fit within 1024m^2, then don't sculpt it around the origin point (0, 0). That would allocate 4 regions. Instead sculpt it around (512, 512) so that all of your data can fit within 1 region. + +Outside of regions, there is no collision. Raycasts won't hit anything. Querying terrain heights or other data will result in NANs or INF. Look through the API for specific return values. + +You can determine if a given location is within a region by using `Terrain3DStorage.get_region_index(global_position)`. It will return -1 if the XZ location is not within a region. Y is ignored. -* Many of the brush settings can be manually entered by clicking the number next to the sliders. Some can extend beyond the maximum slider value. ## Performance * The Terrain3DMaterial shader has some advanced features that look nice but consume some performance. You can get better performance by disabling them: - * Set `WorldNoise` to `Flat` or `None` + * Set `WorldBackground` to `Flat` or `None` * Disable `Auto Shader` * Disable `Dual Scaling` -* `WorldNoise` exposes additional shader settings, such as octaves and LOD. You can adjust these settings for performance. However this world generating noise is expensive. Consider not using it at all in a commercial game, and instead obscure your background with meshes, or use an HDR skybox. +* `WorldBackground` as `Noise` exposes additional shader settings, such as octaves and LOD. You can adjust these settings for performance. However this world generating noise is expensive. Consider not using it at all in a commercial game, and instead obscure your background with meshes, or use an HDR skybox. * Reduce the size of the mesh and levels of detail by reducing `Mesh/Size` (`mesh_size`) or `Mesh/Lods` (`mesh_lods`) in the `Terrain3D` node. +* Don't use `Terrain3D/Renderer/Cull Margin`. It should only be needed if using the noise background. Otherwise the AABB should be correctly calculated via editing, so there is no need to expand the cull margin. Keeping it enabled can cost more processing time. + ## Shaders diff --git a/doc/docs/troubleshooting.md b/doc/docs/troubleshooting.md index 0754ea72..260ba51f 100644 --- a/doc/docs/troubleshooting.md +++ b/doc/docs/troubleshooting.md @@ -1,129 +1,147 @@ Troubleshooting ================= -## Tutorial Videos - Make sure to watch the [tutorial videos](tutorial_videos.md) which show proper installation and setup. +Also see [Tips](tips.md) which may have other helpful information. -## Use the Console +**Table of Contents** +* [Installation](#installation) +* [Texture Setup](#texture-setup) +* [Crashing](#crashing) +* [Usage](#usage) +* [Using the Console](#using-the-console) +* [Debug Logs](#debug-logs) -As a gamedev, you should always be running with the console open. This means you ran `Godot_v4.*_console.exe` or ran Godot in a terminal window. -```{image} images/console_exec.png -:target: ../_images/console_exec.png -``` +## Installation -This is what it looks like this when you have the console open. +### Unable to load addon script from path -```{image} images/console_window.png -:target: ../_images/console_window.png -``` +`Unable to load addon script from path: xxxxxxxxxxx. This might be due to a code error in that script. Disabling the addon at 'res://addons/terrain_3d/plugin.cfg' to prevent further errors."` -Godot, Terrain3D, and every other addon gives you additional information here, and when things don't work properly, these messages often tell you exactly why. +Most certainly you've installed the plugin improperly. These are the common causes: -Godot also has an `Output` panel at the bottom of the screen, but it is slow, will skip messages if it's busy, and not all messages appear there. +1) You downloaded the repository code, not a [binary release](https://github.com/TokisanGames/Terrain3D/releases). +2) You moved the files into the wrong directory. The Terrain3D files should be in `project/addons/terrain_3d`. `Editor.gd` should be found at `res://addons/terrain_3d/editor/editor.gd`. [See an example issue here](https://github.com/TokisanGames/Terrain3D/issues/200). -## Debug Logs +Basically, the required library isn't where it's supposed to be. The error messages will tell you exactly the file name and path it's looking for. View that location on your hard drive. On windows you might be looking for `libterrain.windows.debug.x86_64.dll`. Does that file exist where it's looking in the logs? Probably not. Download the correct package, and review the instructions to install the files in the right location. -Terrain3D has debug logs for everything, which it can dump to the [console](#use-the-console). These logs *may* also be saved to Godot's log files on disk. +### After installation, there are no tools. The texture list is blank in the demo. +Click the Terrain3D node in the scene tree. Also see the next entry. -Set `Terrain3D.debug_level` to `Info` or `Debug` and you'll get copious activity logs that will help troubleshoot problems. +### After clicking the Terrain3D node, there are no editor tools or texture panel. -You can also enable debugging from the command line by running Godot with `--terrain3d-debug=` where `` is one of `ERROR`, `INFO`, `DEBUG`, `DEBUG_CONT`. Debug Continuous (DEBUG_CONT) is for repetitive messages such as those that appear on camera movement. +Enable the plugin in project settings. Review the [installation instructions](installation.md). -To run the demo from the command line with debugging, open a terminal, and change to the project folder (where `project.godot` is): +### The editor tools panel is there, but the buttons are blank or missing. -Adjust the file paths to your system. The console executable is not needed since you're already running these commands in a terminal window. +Restart Godot twice before using it. Review the [installation instructions](installation.md). -``` -# 1. Change to the project folder -cd +### Start up is very slow, and/or the scene or storage file is huge. -# 2a. Run the project with debugging enabled at startup - --terrain3d-debug=DEBUG +Save the storage resource as a binary `.res` file, as described in the [installation instructions](installation.md). You've likely saved it as text `.tres`, or didn't save it separately at all, which means a ton of terrain data is saved as text in the scene. -# 2b. Or run the editor with debugging enabled at startup - -e --terrain3d-debug=DEBUG +Alternatively, you have a large terrain and are generating collision for all of it. Disable collision, or set it to dynamic to create only a small collision around the camera (pending implementation, see [PR #278](https://github.com/TokisanGames/Terrain3D/pull/278)). +--- -# E.g. To run the demo with debug messages -cd /c/gd/Terrain3D/project -/c/gd/bin/Godot_v4.1.3-stable_win64.exe --terrain3d-debug=DEBUG +## Texture Setup -# Load the editor with debug messages -/c/gd/bin/Godot_v4.1.3-stable_win64.exe -e --terrain3d-debug=DEBUG -``` +### Added a texture, now the terrain is white -When asking for help on anything you can't solve yourself, you'll need to provide a full log from your console or file system. As long as Godot doesn't crash, it saves the log files on your drive. In Godot select, `Editor, Open Editor Data/Settings Menu`. On windows this opens `%appdata%\Godot` (e.g. `C:\Users\%username%\AppData\Roaming\Godot`). Look under `app_userdata\\logs`. Otherwise, you can copy and paste messages from the console window above. +Your console also reports: `Albedo/Normal textures do not have same size!` -## Common Issues +Your console also reports: `Texture # albedo / normal, size / format... doesn't match size of first texture... They must be identical.` -### Startup Errors +The new texture doesn't match the format or size of the existing ones. [Texture Preparation](texture_prep.md) descibes the requirements, which includes the same format and size for each. Double click a texture in the filesystem and Godot will tell you what it is. You can also click the texture in the inspector when editing an entry in the asset dock to see the same thing. -#### After clicking the Terrain3D node, there are no editor tools or texture panel. -Enable the plugin, as described in the [installation instructions](installation.md). +--- +## Crashing -#### The editor tools panel is there, but the buttons are blank or missing. +### Godot crashes on load -Restart Godot twice before using, as described in the [installation instructions](installation.md). +If this is the first startup after installing the plugin, this is normal due to a bug in the engine currently. Restart Godot. +If it still crashes, try the demo scene. -#### Start up is very slow. Or the scene or storage file is huge. +If that doesn't work, most likely the library version does not match the engine version. If you downloaded a release binary, download the exactly matching engine version. If you built from source review the [instructions](building_from_source.md) to make sure your `godot-cpp` directory exactly matches the engine version you want to use. -Save the storage resource as a binary `.res` file, as described in the [installation instructions](installation.md). You've likely saved it as text `.tres`, or didn't save it separately at all, which means a ton of terrain data is saved as text in the scene. +If the demo scene does work, you have an issue in your project. It could be a setting or file given to Terrain3D, or it could be anywhere else in your project. Divide and conquer. Copy your project and start ripping things out until you find the cause. -Alternatively, you have a large terrain and are generating collision for all of it. Disable collision, or set it to dynamic to create only a small collision around the camera (pending implementation, see [PR #278](https://github.com/TokisanGames/Terrain3D/pull/278)). +### Exported game crashes on startup +First make sure your game works running in the editor. Then ensure it works as a debug export with the console open. If there are challenges, you can enable [Terrain3D debugging](#debug-logs) before exporting with debug so you can see activity. Only then, test in release mode. -#### Unable to load addon script from path +Make sure you have both the debug and release binaries on your system, or have built Terrain3D in [both debug and release mode](building_from_source.md#5-build-the-extension), and that upon export both libraries are in the export directory (eg. `libterrain.windows.debug.x86_64.dll` and `libterrain.windows.release.x86_64.dll`). If you don't have the necessary libraries, your game will close instantly upon startup. -`Unable to load addon script from path: xxxxxxxxxxx. This might be due to a code error in that script. Disabling the addon at 'res://addons/terrain_3d/plugin.cfg' to prevent further errors."` +--- -Most certainly you've installed the plugin improperly. These are the common causes: +## Usage -1) You downloaded the repository code, not a [binary release](https://github.com/TokisanGames/Terrain3D/releases). +### Camera flickering -2) You moved the files into the wrong directory. The Terrain3D files should be in `project/addons/terrain_3d`. `Editor.gd` should be found at `res://addons/terrain_3d/editor/editor.gd`. [See an example issue here](https://github.com/TokisanGames/Terrain3D/issues/200). +When another mesh intersects with Terrain3D far away from the camera, such as in the case of water on a beach, the two meshes can flicker as the renderer can't decide which mesh should be displayed in front. This is also called Z-fighting. You can greatly reduce it by increasing `Camera3D.near` to 0.25. You can also set it for the editor camera in the main viewport by adjusting `View/Settings/View Z-Near`. -Basically, the required library isn't where it's supposed to be. The error messages will tell you exactly the file name and path it's looking for. View that location on your hard drive. On windows you might be looking for `libterrain.windows.debug.x86_64.dll`. Does that file exist where it's looking in the logs? Probably not. Download the correct package, and review the instructions to install the files in the right location. +### Segments of the terrain disappear on camera movement +You can increase `Renderer/Cull Margin`. For sculpted regions this should not be necessary as sculpting sets the AABB for the meshes already. However for shader based backgrounds like WorldBackground, it has no AABB and needs an increased cull margin if it is higher than the sculpted areas. This consumes performance so it is ideal if not used. -### Crashing -#### Godot Crashes on Load +--- -If this is the first startup after installing the plugin, this is normal due to a bug in the engine currently. Restart Godot. +## Using the Console -If it still crashes, try the demo scene. +As a gamedev, you should always be running with the console open. This means you ran `Godot_v4.*_console.exe` or ran Godot in a terminal window. -If that doesn't work, most likely the library version does not match the engine version. If you downloaded a release binary, download the exactly matching engine version. If you built from source review the [instructions](building_from_source.md) to make sure your `godot-cpp` directory exactly matches the engine version you want to use. +```{image} images/console_exec.png +:target: ../_images/console_exec.png +``` -If the demo scene does work, you have an issue in your project. It could be a setting or file given to Terrain3D, or it could be anywhere else in your project. Divide and conquer. Copy your project and start ripping things out until you find the cause. +This is what it looks like this when you have the console open. -#### Exported Game Crashes On Startup +```{image} images/console_window.png +:target: ../_images/console_window.png +``` -First make sure your game works running in the editor. Then ensure it works as a debug export with the console open. If there are challenges, you can enable [Terrain3D debugging](#debug-logs) before exporting with debug so you can see activity. Only then, test in release mode. +Godot, Terrain3D, and every other addon gives you additional information here, and when things don't work properly, these messages often tell you exactly why. -Make sure you have both the debug and release binaries on your system, or have built Terrain3D in [both debug and release mode](building_from_source.md#5-build-the-extension), and that upon export both libraries are in the export directory (eg. `libterrain.windows.debug.x86_64.dll` and `libterrain.windows.release.x86_64.dll`). If you don't have the necessary libraries, your game will close instantly upon startup. +Godot also has an `Output` panel at the bottom of the screen, but it is slow, will skip messages if it's busy, and not all messages appear there. + + +## Debug Logs -### Importing Textures +Terrain3D has debug logs for everything, which it can dump to the [console](#use-the-console). These logs *may* also be saved to Godot's log files on disk. -#### WARNING: Terrain3D::_texture_is_valid: Invalid format. Expected DXT5 RGBA8. +Set `Terrain3D.debug_level` to `Info` or `Debug` and you'll get copious activity logs that will help troubleshoot problems. -Read [Preparing Textures](texture_prep.md) to learn how to properly channel pack your textures. +You can also enable debugging from the command line by running Godot with `--terrain3d-debug=` where `` is one of `ERROR`, `INFO`, `DEBUG`, `DEBUG_CONT`. Debug Continuous (DEBUG_CONT) is for repetitive messages such as those that appear on camera movement. -#### Albedo/Normal textures do not have same size! and the terrain turns white +To run the demo from the command line with debugging, open a terminal, and change to the project folder (where `project.godot` is): -Read [Preparing Textures](texture_prep.md) and review your textures for odd sizes. All textures must be the same size. eg. If the first set is 2k, all other textures need to be 2k as well. +Adjust the file paths to your system. The console executable is not needed since you're already running these commands in a terminal window. -## Debug Collision +``` +# 1. Change to the project folder +cd -Collision is generated at runtime using the physics server. Normally these collision shapes are not visible. +# 2a. Run the project with debugging enabled at startup + --terrain3d-debug=DEBUG -To see collision in the editor, enable `Terrain3D.debug_show_collision`, or in the inspector, Debug `show_collision`. It won't regenerate the collision when you edit, but you can disable and reenable this flag to regenerate. +# 2b. Or run the editor with debugging enabled at startup + -e --terrain3d-debug=DEBUG + + +# E.g. To run the demo with debug messages +cd /c/gd/Terrain3D/project +/c/gd/bin/Godot_v4.1.3-stable_win64.exe --terrain3d-debug=DEBUG + +# Load the editor with debug messages +/c/gd/bin/Godot_v4.1.3-stable_win64.exe -e --terrain3d-debug=DEBUG +``` + +When asking for help on anything you can't solve yourself, you'll need to provide a full log from your console or file system. As long as Godot doesn't crash, it saves the log files on your drive. In Godot select, `Editor, Open Editor Data/Settings Menu`. On windows this opens `%appdata%\Godot` (e.g. `C:\Users\%username%\AppData\Roaming\Godot`). Look under `app_userdata\\logs`. Otherwise, you can copy and paste messages from the console window above. -To see collision in game, enable `Terrain3D.debug_show_collision`, and in the editor menu, enable `Debug/Visible Collision Shapes`. \ No newline at end of file diff --git a/doc/docs/user_interface.md b/doc/docs/user_interface.md index b3772efb..d9f37d75 100644 --- a/doc/docs/user_interface.md +++ b/doc/docs/user_interface.md @@ -22,11 +22,12 @@ The following mouse and keyboard shortcuts are available: **Terrain Operations** * LMB - Click the terrain to sculpt or paint. +* Shift + LMB - **Smooth**. * Ctrl + LMB - **Inverses the operation** where applicable. Eg. Add or *remove* regions. Raise or *lower* terrain. Create or *remove* holes, foliage, navigation, etc. * Alt + LMB - **Lift floors** mode. Sculpting only. This lifts up lower portions of the terrain without affecting higher terrain around it. Use it along the bottom of cliff faces. See [videos demonstrating before and after](https://github.com/TokisanGames/Terrain3D/pull/409). * Ctrl + Alt + LMB - **Flatten peaks** mode. Sculpting only. The inverse of the above. This reduces peaks and ridges without affecting lower terrain around it. -Note: Touchscreen users have an `Invert` checkbox on the settings bar which acts like Ctrl to inverse operations. +Note: Touchscreen users have an `Invert` checkbox on the settings bar which acts like Ctrl to inverse operations. **Godot Shortcuts** * Ctrl + Z - Undo. You can also view the operations in Godot's `History` panel. @@ -44,11 +45,13 @@ Depending on which tool is selected on the toolbar, various tool settings will a :target: ../_images/ui_tool_settings.jpg ``` -On the left, many tools offer a brush selection. If you wish to change them, you can do so in `addons/terrain_3d/brushes` using your OS folder explorer. The folder is hidden to Godot. These files are 100x100 alpha masks saved as EXR. Larger sizes should work fine, but will be slow if too big. +Many tool settings offer a slider with a fixed range, and an input box where you can manually enter a much larger setting. -Next are a variety of settings specific to the tool, which should be self explanatory. See [Foliage Instancing](instancer.md) for specific details on its settings. +Most are self explanatory. See [Foliage Instancing](instancer.md) for specific details on its settings. -Lastly, on the right is the advanced menu. Most options are self explanatory. `Jitter` is what causes the brush to spin while painting. Reduce it to zero if you don't want the brush to rotate. +On the right is the advanced menu. One noteworthy setting is `Jitter`, which is what causes the brush to spin while painting. Reduce it to zero if you don't want this. + +Brushes can be edited in the `addons/terrain_3d/brushes` directory, using your OS folder explorer. The folder is hidden to Godot. The files are 100x100 alpha masks saved as EXR. Larger sizes should work fine, but will be slow if too big. --- diff --git a/doc/index.rst b/doc/index.rst index 973d2f87..16a7e157 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -102,12 +102,13 @@ Geometry clipmap mesh code created by `Mike J. Savage