Godot-docs: 3.1: Document new PhysicsMaterial

[akien-mga]

Godot 3.1 now adds a PhysicsMaterial resource to physics bodies, which is used to set their physics properties (and can be shared between bodies).

The bounce and friction properties of physics bodies have been moved to this new material, so the documentation needs to be changed to take it into account. @AndreaCatania can maybe help whoever would take on this task with understanding the new feature.

Some pages which might need an update

$ rg "bounce" -g'!classes'
getting_started/step_by_step/instancing.rst
98:You can also adjust individual instances. Set the bounce value back to ``0.5``

tutorials/audio/audio_streams.rst
tutorials/physics/rigid_body.rst
15:A rigid body's behavior can be altered by setting its properties such as friction, mass, bounce, etc. These properties can be set in the Inspector or via code. See :ref:`RigidBody <class_RigidBody>` for the full list of properties and their effects.

$ rg "friction" -g'!classes'
tutorials/physics/rigid_body.rst
15:A rigid body's behavior can be altered by setting its properties such as friction, mass, bounce, etc. These properties can be set in the Inspector or via code. See :ref:`RigidBody <class_RigidBody>` for the full list of properties and their effects.

tutorials/physics/using_kinematic_body_2d.rst
24:engine physics properties like gravity or friction. While this means that you

tutorials/physics/physics_introduction.rst
289:other bodies, but are not affected by physics properties like gravity or friction.

Beyond fixing existing references, there should likely be a paragraph (probably in physics_introduction.rst) explaining what the PhysicsMaterial is, how to set it up and the effect of its parameters.

[ZX-WT]

I can do this but I have some question after following the PR about physical bodies. In 3.1, are the properties like friction and bounce all moved to physical material? If none is create, it will used some hidden default value, is this the way? But the physical bodies still have properties like friction and it could be set in script, it is just not exposed in the editor.

The good way to use fully the function of the editor is to create the physical material. This should be demonstrate in the tutorial, right? I might make a note about the scripting part if it is true.

Another thing is to clarify the properties
friction
rough
bounce
absorbent

I understand friction and bounce but what's rough and absorbent? absorb stops the movement from what I experiment but what is rough?

[tbird20d]

The "Bounce" property is mentioned in one of the introductory tutorials. https://docs.godotengine.org/en/3.1/getting_started/step_by_step/instancing.html. However, it appears that this property is no longer exposed in the editor. This is quite confusing (I'm trying to learn Godot this week.) Should the property be added to the editor, or should the tutorial be changed?

Edit: Looks like I spoke too soon. You can edit Bounce if you edit "PhysicsMaterial". I didn't see this earlier since Godot hung when I tried to access this menu. I restarted Godot, and clicked on Ball.tscn, Inspector, right-click PhysicsMaterial, then 'edit', and under properties it has the "Bounce" property. My bad. (I still think the tutorial needs a tweak though.)

[cbscribe]

As the OP indicates, the bounce property and other physics properties has been moved into the PhysicsMaterial. When you add a PhysicsMaterial to the body, you can access these properties in the Inspector. This needs to be updated in the documentation. I'll make a note to update the instancing doc - it also needs updated screenshots.

[tbird20d]

Thanks very much for the response. I'm not sure if this is the right place to continue this. But no matter what I put for the "Bounce" property, it has no effect on the behavior of the balls in the tutorial demo. I've tried changing the Bounce value on an a ball instance. On the ball scene. I created a Ball.tres file, changed the Bounce value, and saved it out. I'm not sure what I'm doing wrong since I'm a newbie to Godotengine.

The engine sometimes hangs after I edit the property. I haven't been able to reliably reproduce the hang.

[cbscribe]

I'm unable to replicate this. I downloaded the zip and opened it in Godot 3.1. I instanced a Ball in the main scene and pressed play. The ball bounced. Checking its properties, the Bounce is set to 0.5. I changed the value in this instance to 0, and running again, the ball does not bounce.

I have not experienced any hangs. Try this: remove the project and download the attached, then start as above with one ball to see if the problem persists. Don't delete the unworking project, because if we can isolate the problem, it may be worth looking at it.

Also, I'm going to update the zip so that it's a 3.1 project. See attached.
instancing.zip

[wisprabbit]

I'm new to Godot, and I'd like to note I also had trouble with the Instancing documentation, trying to edit the bounce property for individual instances. I found the PhysicsMaterial submenu, but editing the bounce property for any instance of the ball scene in the main scene also changes every other instance, as well as the original ball scene. This means that individual instances can't be changed in the way outlined by the tutorial.

KidsCanCode on Discord suggested that this is because the PhysicsMaterial resource works differently now - in 3.0 it apparently was a direct property to a RigidBody node, whereas in 3.1 it seems to be a separately-saved set of values which can be called by a RigidBody? Sorry if I have the details wrong, I don't know my way around Godot yet. YeOldeDM pointed me towards the "make unique" option which appears when right-clicking the PhysicsMaterial, and that has the effect the tutorial wants, but it could be a lot more obvious. (Thanks to KidsCanCode, YeOldeDM and Duroxxigar for helping me on Discord!)

I can see from reading through this issue that this is a known problem, but I wanted to add my experience to help anyone else having trouble with the tutorial.

[lavrod]

Seem that there is a sub menu under PhysicMaterial that you need to select to make specific ball bounce value. Doc on instancing does not mention this sub menu.

[vortexofdoom]

In this tutorial: https://docs.godotengine.org/en/3.1/getting_started/step_by_step/instancing.html the instructions for demonstrating how instances are unique are flawed.

The user needs to explicitly make the PhysicsMaterial of the instance unique right now, as written the current documentation makes you edit the original Ball's PhysicsMaterial.

Changing the gravity scale or something integrated into the RigidBody2D works as explained.

[clayjohn]

@vortexofdoom someone has already made a PR fixing that :)

https://github.com/godotengine/godot-docs/pull/2552

[noidexe]

I can do this but I have some question after following the PR about physical bodies. In 3.1, are the properties like friction and bounce all moved to physical material? If none is create, it will used some hidden default value, is this the way? But the physical bodies still have properties like friction and it could be set in script, it is just not exposed in the editor.

The good way to use fully the function of the editor is to create the physical material. This should be demonstrate in the tutorial, right? I might make a note about the scripting part if it is true.

Another thing is to clarify the properties
friction
rough
bounce
absorbent

I understand friction and bounce but what's rough and absorbent? absorb stops the movement from what I experiment but what is rough?

Based on the code handling it, rough negates friction. Absorbent does the same for bounce.
So friction 1; rough: true is equal to friction -1; rough false.

Also, the claim that the values of friction and bounce go from 0 to 1 is false and also the implications of those numbers.
In the case of bounce, a value of more than 1 seems to do nothing. A value of -1 will make it absorbent.
In the case of friction, a value of 1 doesn't seem to mean maximum friction at all or it needs clarification. I would assume that a value of 1 means it would be impossible to slide an object across a surface if it's touching it, no matter how softly, and that values over 1 would be meaningless. Values over 1 are not rejected by the editor and do increase friction, so I think the editor tooltip is probably wrong.

[vorblen]

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