What's QMeshNode and How it Works? - erayzesen/godot-quarkphysics GitHub Wiki

Why QMesh? Why Not Just Use CollisionShape Like in Every Other 2D Physics Engine?

When switching to an alternative software, seeing a concept you're familiar with under a completely different name and idea can be frustrating. To put it simply, QMeshNode objects are similar to Godot's CollisionShape2D objects but they have many more responsibilities. If our physics engine were only concerned with rigid bodies and collision shapes, it might have been named QCollisionShapeNode.

However, QuarkPhysics is not just about rigid bodies; it also handles soft body dynamics, among other dynamics. For instance, QSoftBodyNode objects require more than just collision shapes. They include particles within a certain radius, springs that connect particles, optional angle constraints, and even additional special settings.

Moreover, objects like QSoftBodyNode require various calculations and information at the start and throughout the simulation. It doesn’t end there—to visually simulate them properly with textures, they also store UV maps.

For these reasons, we refer to them as "mesh" objects. You may not have seen this concept in other 2D physics engines simply because most of them are designed only for rigid body dynamics.

How Do QMeshNode and Its Variants Work? Am I Missing Something?

In the original structure of the physics engine, there are no separate types of QMesh objects. Even in the original code-base, there is technically only one QMesh object.

Objects like QMeshRectNode, QMeshPolygonNode, and QMeshCircleNode simply store data based on your editor settings. When the scene starts, they generate a QMeshNode in the on_enter_tree event using this data. In the original API, the generate structure works like this: QMesh::CreateWithPolygon() , QMesh::CreateWithRect() , QMesh::CreateWithCircle()

Since these objects generate the real QMesh features at runtime, you cannot modify their inspector properties during runtime. By the time the simulation starts, the inspector settings have already been used to create particles, springs, collision polygons, and UV maps. From that point on, your focus should be controlling the simulation, not adjusting inspector properties.

For example, changing the rectangle_size property of a QMeshRectNode at runtime will have no effect. You might consider this a design flaw in Godot’s workflow, and it is certainly open for debate. However, this design was chosen deliberately to simplify the user experience.

A more "correct" approach, while maintaining Godot’s workflow, would have been to have a single QMeshNode object with buttons in the inspector such as "Generate Rectangle," "Generate Polygon," and "Generate Circle". However, this would have introduced unnecessary steps to our workflow, making it impractical—at least for Godot.

Nonetheless, you should be aware of this, as this is the only consciously made design compromise in the extension.

What Can I Do with QMeshNode? I'm Just Trying to Make a Simple Bouncing Ball!

In rigid body scenarios, QMeshNode objects require very little manual intervention. In most cases, a polygon collider based on defined particles (or a single particle with a fixed radius) is sufficient.

However, when working with soft body physics, QMeshNode acts more like a control hub for manipulating and controlling the object.

To clarify:

Rigid body dynamics do not allow individual particles to move freely. Their positions are transformed based on the object's position and rotation. The collision polygon updates accordingly. Most of the control happens at the QRigidBodyNode level rather than the QMeshNode itself.
Soft body dynamics, on the other hand, allow particles to move individually. Constraints can be applied if needed (e.g., QSpringObject, QAngleConstraintObject). Control shifts from the object itself to its particles.QSoftBodyNode objects do not have an absolute position or rotation such as QRigidBodyNode objects during the simulation. The position and rotation you set in the editor only define the initial placement of the particles. (However, you can still retrieve an average position and rotation from QMeshNode during runtime.)

For this reason, when working with soft bodies, you will frequently interact with QMeshNode—even for simple tasks like moving the object.

Rendering Features

Since QMeshNode stores so much data, why not use it for rendering as well?

With vector rendering, QMeshNode objects can be converted into graphical elements. This is especially useful for QSoftBodyNode objects, as they rely heavily on visualization. You can also render textures using structured UV maps. (For example, QMeshRectNode and QMeshPolygonNode automatically generate UV maps.)

If you don’t need this feature, you can simply disable it.

For rigid body objects, which have a fixed absolute position and rotation during simulation, you can add a child Sprite or CanvasItem just like in Godot’s built-in physics engine.

If you aren’t making a quick prototype or don’t need per-frame updates for vector rendering, we recommend disabling it for rigid bodies to save performance.

What is QMeshAdvancedNode?

QMeshAdvancedNode is not fundamentally different from other subclasses of QMeshNode. However, its key feature is that, thanks to our QMeshEditor plugin, you can design QMesh objects with unlimited freedom.

With this plugin, you can create particles, springs, collision polygons, and even UV maps. Additionally, you can export or import these designs in the JSON-based *.qmesh format.

One of Godot’s great features is that you can convert predefined nodes like QMeshRectNode, QMeshPolygonNode, or QMeshCircleNode into this type. (Right click -> Change Type) This allows you to make any modifications or customizations you want, giving you complete control over your QMesh objects.

To learn more about all the methods and properties of QMeshNode, refer to the QMeshNode page.