Update documentation

Author: mphe

FAQ.md

@@ -0,0 +1,29 @@
+# FAQ / Troubleshooting
+
+## Is Web export supported?
+
+Yes, partially.
+The plugin includes a web build, but since it uses GDExtension, a web export template with GDExtension support is required to use it.
+
+According to the [Godot documentation](https://docs.godotengine.org/en/stable/contributing/development/compiling/compiling_for_web.html#gdextension) for web:
+> "The default export templates do not include GDExtension support for performance and compatibility reasons".
+
+That means in order to use the web version of this plugin, you will need a custom web export template compiled with `dlink_enabled=yes`.
+
+To compile it yourself, refer to the official Godot documentation for further information: [Building from source](https://docs.godotengine.org/en/stable/contributing/development/compiling/index.html), [Compiling for the Web](https://docs.godotengine.org/en/stable/contributing/development/compiling/compiling_for_web.html) and [Exporting for the Web](https://docs.godotengine.org/en/latest/tutorials/export/exporting_for_web.html).
+
+Alternatively, you can download prebuilt export templates from another trusted source.
+For example, the [LimboAI addon](https://github.com/limbonaut/limboai) provides web export templates with GDExtension support.
+
+## Ropes lag one frame behind
+
+This is a known issue and related to execution order.
+
+**TL;DR:** Connect to the `NativeRopeServer.on_pre_pre_update` signal and run the rope update code there. It is essentially an alternative to `_physics_process()` that runs just before ropes get updated.
+
+See [Execution Order Documentation](docs/execution_order.md) for a more detailed explanation.
+
+
+## Collisions tunnel through objects / stretch along corners
+
+See [Collisions Documentation](docs/collisions.md).

README.md

@@ -67,6 +67,16 @@ When one of the above nodes is selected, a "*Ropesim*" menu appears in the edito
 * `Preview in Editor`: Toggle live preview in the editor on or off.
 * `Reset Rope`: Reset the selected rope to its resting position.
 
+### Advanced Topics
+- [Collisions Documentation](docs/collisions.md)
+- [Execution Order Documentation](docs/execution_order.md)
+
+
+## FAQ / Troubleshooting
+
+See [FAQ](FAQ.md).
+
+
 ## Showcase
 
 A quick overview of how to use each node.

docs/collisions.md

@@ -0,0 +1,45 @@
+# Collisions
+
+## Overview
+
+At each rope point a circle collision check will be performed. If there is a collision, the rope point will be moved to a safe space.
+This can cause the tunneling and stretching since only discrete areas are checked for collisions, not whole rope segments.
+Usually, with relatively smooth topology, the circle colliders nicely slide along it, but with sharp corners, it will be very difficult to prevent stretching, because they effectively pierce between the colliders and separate them.
+
+## Why Not Check Whole Segments?
+
+Resolving collisions with whole rope segments would involve much more complex logic with respectively larger computation times.
+That kinda defeats the purpose of this plugin.
+The current implementation is simple, fast and good enough for most use-cases.
+If perfect precision is needed, it's probably better to build a rope out of rigidbodies using built-in physics.
+
+## Tweaking Collisions
+
+The following properties can be tweaked to improve collision response:
+
+- `num_segments`
+- `num_constraint_iterations`
+- `collision_radius`
+- `resolve_collisions_while_constraining`
+
+Also very helpful is `render_debug` as it will display the effective collider areas as cyan circles.
+It helps visualizing how much space is covered by colliders and the effect of tuning the above properties (except the last one).
+
+Increasing `num_segments` also increases the amount of collision tests, which results in more precise collision detection.
+I found 10 segments per 100 pixel length a good value, but it very much depends on the use case.
+
+Increasing `num_segments` will very likely also require increasing `num_constraint_iterations` as well to hold the rope together properly.
+For `num_constraint_iterations` there is no rule of thumb. The less iterations, the stretchier the rope will become.
+More iterations make the rope tighter and less bouncy/stretchy, but it will also increase computation time respectively.
+More segments require more constraint iterations to keep the rope equally tight.
+When increasing constraint iterations the rope's length becomes closer to `rope_length` and the colliders move closer together, reducing the gap between them.
+
+`collision_radius` is the radius of the colliders. Larger colliders cover more space and thus reduce tunneling/stretching. It can't solve it completely, though.
+There is also no rule of thumb, you have to play around with it until you find a sweet spot.
+
+Finally, `resolve_collisions_while_constraining` helps a lot to reduce tunneling/stretching by running the collision test after every single constraint iteration instead of once after the constraint step finished.
+Consequently, it also drastically affects the computation time in relation to `num_constraint_iterations`.
+With only a few ropes, it's fine, but with many ropes it can tank the framerate.
+
+As for balancing computation cost, keep an eye on `NativeRopeServer.get_computation_time()`.
+There is a script `rope_examples/scripts/PerformanceLabel.gd` that can be used.

docs/execution_order.md

@@ -0,0 +1,45 @@
+# Execution Order
+
+Ropes are not processed by their node but in the `NativeRopeServer` class, which executes at the start of the physics frame, i.e. when the `SceneTree.physics_frame` signal runs.
+
+Roughly sketched, the order looks like this:
+
+1. `SceneTree.physics_frame`
+    - Rope update
+2. `_process()`
+3. `_physics_process()`
+
+This assumes that the FPS match the physics tickrate, which is usually locked at 60 FPS.
+On a 144 Hz screen for example, it wouldn't match and you get more `_process()` frames than `_physics_process()` possibly making this lag even more noticable.
+
+`NativeRopeServer` provides a set of signals for fine-tuned execution order handling:
+
+- `on_pre_update`
+- `on_pre_pre_update`
+- `on_post_update`
+- `on_post_post_update.`
+
+They get emitted just before/after rope updates.
+
+1. `SceneTree.physics_frame`
+    1. `on_pre_pre_update`
+    2. `on_pre_update`
+    3. Rope update
+    4. `on_post_update`
+    5. `on_post_post_update`
+2. `_process()`
+3. `_physics_process()`
+
+These signals are also used by various rope utilities like `RopeAnchor`, `RopeHandle` or `RopeRendererLine2D` to update the rope's properties or their own just before/after rope updates occur.
+At the moment they use the normal `pre` and `post` signals, not `pre_pre` or `post_post`.
+
+## Solving the One-Frame Delay
+
+Updating the rope position in `_process()` or `_physics_process()` causes a one-frame delay because they run after the rope has already been updated.
+Hence, the result is only visible in the next frame.
+
+The workaround is to connect to `NativeRopeServer.on_pre_pre_update` and update the rope's position there.
+It can essentially be treated as a kind of `_physics_process()` which runs just before rope updates.
+
+You can take a look at the `rope_pulling.tscn` example.
+The player node there uses the same approach.