Update docs - add UI & keyboard shortcut docs

README.md

@@ -1,4 +1,4 @@
-<img src="doc/docs/images/terrain3d.png">
+<img src="https://raw.githubusercontent.com/TokisanGames/Terrain3D/5f5837542a6fff32d8e60c1cca4760afd2f836f6/doc/docs/images/terrain3d.png">
 
 # Terrain3D
 A high performance, editable terrain system for Godot 4.

Terrain3D.vcxproj

@@ -192,6 +192,7 @@
     <None Include="doc\docs\press.md" />
     <None Include="doc\docs\storage_format.md" />
     <None Include="doc\docs\texture_painting.md" />
+    <None Include="doc\docs\user_interface.md" />
     <None Include="doc\index.rst" />
     <None Include="project\addons\terrain_3d\plugin.cfg" />
     <None Include="project\addons\terrain_3d\terrain.gdextension" />

Terrain3D.vcxproj.filters

@@ -211,6 +211,9 @@
     <None Include="doc\docs\instancer.md">
       <Filter>2. Docs</Filter>
     </None>
+    <None Include="doc\docs\user_interface.md">
+      <Filter>2. Docs</Filter>
+    </None>
   </ItemGroup>
   <ItemGroup>
     <Text Include=".readthedocs.yaml">

doc/docs/installation.md

@@ -3,12 +3,14 @@ Installation & Upgrades
 
 ## Requirements
 * Supports Godot 4.2+.
-* Supports Windows, Linux, and macOS. Other platforms are [pending](project_status.md).
+* 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
 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. Allow Godot to restart.
+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. 
@@ -18,12 +20,11 @@ If it isn't working for you, watch the [tutorial videos](tutorial_videos.md) and
 ## Installing Terrain3D in 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.
+3. Run Godot using the console executable so you can see error messages. 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. Create or open a 3D scene and add a new Terrain3D node.
-7. Select Terrain3D in the Scene panel. In the Inspector, click the down arrow to the right of the `storage` resource and save it as a binary `.res` file. The other resources can be left as is or saved as text `.tres`. These external files can be shared with other scenes.
-8. Click Next to learn how to properly [set up your textures](texture_prep.md), or skip to [import data](import_export.md).
+7. Select Terrain3D in the Scene panel. In the Inspector, click the down arrow to the right of the `storage` resource and save it as a binary `.res` file. The other resources can be left as is, or saved as text `.tres`. These external files can be shared with other scenes.
 
 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).
 
@@ -32,7 +33,7 @@ If it isn't working for you, watch the [tutorial videos](tutorial_videos.md) and
 To update Terrain3D: 
 1. Close Godot.
 2. Remove `addons/terrain_3d` from your project folder.
-3. Copy `addons/terrain_3d` from the new release download or from your build directory into your project folder.
+3. Copy `addons/terrain_3d` from the new release download or from your build directory into your project addons folder.
 
 Don't just copy the new folder over the old, as this won't remove any files that we may have intentionally removed.
 
@@ -42,7 +43,7 @@ While later versions of Terrain3D can generally open previous versions, not all
 
 Given the table below, to upgrade 0.8 to the latest version you would need to open your files in 0.8.4 or 0.9 and save them, then open in the latest version and save again.
 
-| Starting Version | Supported Upgrade |
+| Starting Version | Can Upgrade w/ Data Conversion |
 |------------------|-------------------|
 | 0.8.4 - 0.9.0 | Latest |
 | 0.8.0 - 0.8.3 | 0.8.4 - 0.9.0 |

doc/docs/misc.md

@@ -4,23 +4,6 @@ Miscelaneous Features
 This page collects various features that haven't been fully detailed or made their way into specific pages yet.
 
 
-## Keyboard & Mouse Operations
-Aka keyboard shortcuts, Hotkeys or commands (for searching)
-
-### Asset Dock
-* Left-click to select
-* Middle-click to clear, removal is only possible at the end of the list
-* Right-click to edit
-
-### Foliage instancing
-* Hold `CTRL` while painting to remove
-
-
-### Future, Sculpting
-* Hold CTRL to do the opposite operation
-* Hold SHIFT to use the smooth brush
-
-
 ## Terrain3DObjects
 
 This node allows you to snap objects to the terrain when sculpting or moving.

doc/docs/user_interface.md

@@ -0,0 +1,70 @@
+User Interface
+=================
+
+
+**Table of Contents**
+* [Main Viewport Shortcuts](#main-viewport-shortcuts)
+* [Asset Dock](#asset-dock)
+
+
+## Main Viewport Shortcuts
+
+The tool bar on the left provides operations for sculpting, texturing, and other features. Each button has a tooltip that describes what it does.
+
+**Terrain Operations**
+* <kbd>Ctrl + LMB</kbd> - **Inverses the operation** where applicable. Eg. Add or *remove* regions. Raise or *lower* terrain. Create or *remove* holes, foliage, navigation, etc.
+* <kbd>Alt + LMB</kbd> - Change to **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). 
+* <kbd>Ctrl + Alt + LMB</kbd> - Change to **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 a `Remove Lock` option appear on the settings bar to fill in the role of Ctrl.
+
+**Godot Shortcuts**
+* <kbd>Ctrl + Z</kbd> - Undo. You can also view the operations in Godot's `History` panel.
+* <kbd>Ctrl + Shift + Z</kbd> - Redo.
+* <kbd>Ctrl + S</kbd> - Save the scene and all data.
+
+
+---
+
+## Asset Dock
+
+### Dock Position
+
+The asset dock houses the list of textures and meshes available for use in Terrain3D. The contents are stored in the [Terrain3DAssets](../api/class_terrain3dassets.rst) resource shown in the inspector when the Terrain3D node is selected.
+
+```{image} images/ui_asset_dock_bottom.png
+:target: ../_images/ui_asset_dock_bottom.png
+```
+
+Click `Textures` or `Meshes` to switch between the asset types.
+
+The dropdown box allows you to select the dock position. Shown above, it is docked to the bottom panel. Below, it is docked to the right sidebar, in the [bottom right position](https://docs.godotengine.org/en/stable/classes/class_editorplugin.html#class-editorplugin-constant-dock-slot-left-ul).
+
+```{image} images/ui_asset_dock_sidebar.png
+:target: ../_images/ui_asset_dock_sidebar.png
+```
+
+The icon with white and grey boxes in the top right can be used to pop out the dock into its own window. While in this state, there is a pin button that allows you to enable or disable always-on-top.
+
+Next the slider will resize the thumbnails.
+
+Finally, when the dock is in the sidebar, there are three vertical, grey dots, shown in the image above in the top right. This also allows you to change the sidebar position, however setting it here won't save. Ignore this and use our dropdown instead.
+
+
+### Setting Up Assets
+
+#### Adding Assets
+You can add content by dragging a texture onto the `Add Texture` icon, a mesh (as a packed scene: tscn, scn, fbx, glb) onto the `Add Mesh` icon, or clicking either Add button and setting them up. 
+
+Each asset resource type has their own settings described in the API docs for [Terrain3DTextureAsset](../api/class_terrain3dtextureasset.rst) and [Terrain3DMeshAsset](../api/class_terrain3dmeshasset.rst).
+
+#### Operations
+
+<kbd>LMB</kbd> - Select the asset to paint with.
+
+<kbd>RMB</kbd> - Edit the asset in the inspector. You can also click the pencil on the thumbnail.
+
+<kbd>MMB</kbd> - Clear the asset. You can also click the X on the thumbnail. If this asset is at the end of the list, this will also remove it. You can clear and reuse this asset, or change its ID to move it to the end for removal. When using the instancer, this will remove all instances painted on the ground. It will ask for confirmation first.
+
+
+

doc/index.rst

@@ -88,10 +88,11 @@ Geometry clipmap mesh code created by `Mike J. Savage <https://mikejsavage.co.uk
 
    docs/tutorial_videos
    docs/installation
+   docs/user_interface
    docs/texture_prep
    docs/texture_painting
-   docs/import_export
    docs/instancer
+   docs/import_export
    docs/tips
    docs/troubleshooting
    docs/getting_help