Godot-docs: Incomplete/ Inacurate Documentation for PhysicsMaterial Class

[mjones409]

Describe the project you are working on:

I am working on a 3d character controller using rigidbody physics

Describe the problem or limitation you are having in your project:

Trying to get the physics just right and can't find all my options in the documentation.

Describe the feature / enhancement and how it helps to overcome the problem or limitation:

The PhysicsMaterial class has no explaination in the documentation for "absorbent" or "rough". In the case of rough, the property does not even exist anymore because I can not access it in my script.

Describe how your proposal will work, with code, pseudocode, mockups, and/or diagrams:

My proposal will help the Godot team keep up with their documentation for the engine. Not a huge issue, just trying to make the team aware.

If this enhancement will not be used often, can it be worked around with a few lines of script?:

It will take no coding, only a documentation update

Is there a reason why this should be core and not an add-on in the asset library?:

PhysicsMaterial is in core Godot so its explaination should be in the core documentation.

[clayjohn]

This was transferred because incomplete documentation is considered a bug. We didn't design the docs to be empty, so it's not a feature proposal to suggest that someone fill them out.

[vorblen]

From my testing, it seems that "absorbent" just causes the "bounce" value to be negative(1 to -1 and -1 to 1). But all values for "bounce" that are 0 and below, seem to act the same. So to me, this option seems a bit superfluous. Therefore I think it should be removed.

As for "rough", I didn't see any difference.

[Calinou]

cc @AndreaCatania

[AndreaCatania]

In the physics material the rough and absorbent parameters got added to introduce the precedence concept.

Let's imagine you have two bodies interacting each other: The first is the a floor with friction = 1.0 the latter is a cube with friction = 0.0; by default the physics engine takes the lowest friction, so the box would slide on the floor.

However, you may want that the floor is able to stop all objects no matter what. You have to set rough == true to so to make the box stop on the floor.

Floor friction: 1
Box friction: 0
-------------------------
Result friction 0

Floor with roughness

Floor friction: [ROUGH] 1
Box friction: 0
-------------------------
Result friction 1

Floor with partial roughness

Floor friction: [ROUGH] 0.5
Box friction: 0
-------------------------
Result friction 0.5

---

The same concept applies to the absorbent parameter. By default the physics engine combines the restitutions of both objects, unless one is marked as absorbent. The absorbent quantity is subtracted from the bounciness of the other body:

Floor bounciness: 0 
Box bounciness: 1
-------------------------
Result bounciness 1

Floor is absorbent:

Floor bounciness: [ABSORBENT] 1
Box bounciness: 1
-------------------------
Result bounciness 0

Floor is partially absorbent:

Floor bounciness: [ABSORBENT] 0.2
Box bounciness: 1
-------------------------
Result bounciness 0.8

[vorblen]

If absorbance just changes the bounciness calculation from:

Box bounciness + Floor bounciness

to:

Box bounciness - Floor bounciness [ABSORBENT]

couldn't the user just make the floor bounciness negative, achieving the same result, removing any need for the absorbance function:

Box bounciness + (-Floor bounciness)

[AndreaCatania]

Yes. This is exactly what the ABSORBENT notation does, it was introduced to make it much more user friendly.

[vorblen]

https://github.com/godotengine/godot/pull/39546

[skyace65]

@vorblen for future reference, when you make a PR if you put closes in the description followed by #ISSUENUMBER or a link to the issue, that issue gets closed automatically when the PR is merged.

[vorblen]

But that PR was for godotengine / godot whereas this issue is on godotengine / godot-docs. Is there any way automatically close an issue form another repo?

[Calinou]

Is there any way automatically close an issue form another repo?

Yes, you can close-reference an issue from another repository if it's on the same organization. You'll need to paste the full link to it instead of just writing its hash-number like #1234.

Anyway, I'll close this issue as it was fixed by https://github.com/godotengine/godot/pull/39546. Thanks for your contribution!