Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fully update first 3D Shader page #10554

Merged
merged 1 commit into from
Jan 29, 2025

Conversation

skyace65
Copy link
Contributor

@skyace65 skyace65 commented Jan 28, 2025

Looks like we went through the page at some point and updated the editor screenshots, but not the screenshots of the shader in the editor.

  • All the shader screenshots as well as 2 editor ones that had slight changes have been updated (All have gone through squoosh compression)
  • Updated "[empty]" in the text since it's now "<empty>"
  • Added a line of text about using default shader settings
  • Changed instructions for getting the shader editor open to reflect current behavior
  • Updated the text on what the shader is generated with since vertex() is now generated by default
  • Simplifying the text related to the fragment() function.

@skyace65 skyace65 added enhancement area:manual Issues and PRs related to the Manual/Tutorials section of the documentation topic:shaders labels Jan 28, 2025
@skyace65 skyace65 requested a review from tetrapod00 January 28, 2025 00:30
Copy link
Contributor

@tetrapod00 tetrapod00 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I followed along with the tutorial. The images in the page now match the results of following along in 4.4beta1.

I approve the image changes. However, this page still needs a more significant refresh to fix a few things:

  • Nitpicks around the way we stylize things like setting properties in the inspector
  • Some confusion around the purpose and method of setting the normal values
  • A few other inaccuracies and nitpicks I noticed

I would recommend merging this as-is, and I can try a followup PR to make the more extensive changes.

@@ -63,7 +63,7 @@ Setting up

Add a new :ref:`MeshInstance3D <class_MeshInstance3D>` node to your scene.

In the inspector tab beside "Mesh" click "[empty]" and select "New PlaneMesh".
In the inspector tab beside "Mesh" click "<empty>" and select "New PlaneMesh".
Copy link
Contributor

@tetrapod00 tetrapod00 Jan 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not a fan of how this page spells out how to create new resources by clicking on "<empty>" each time. I feel like a shader tutorial should expect a little more familiarity with the inspector UI than that?

I'd prefer something more like the following:

Suggested change
In the inspector tab beside "Mesh" click "<empty>" and select "New PlaneMesh".
In the inspector tab, set the **Mesh** property to a new PlaneMesh.

Subject to tweaks, and perhaps we do want to spell it out the first time it comes up.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the only page I can think of that actually describes clicking on ""

Copy link
Contributor

@tetrapod00 tetrapod00 Jan 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Search the page for "empty" and it comes up at least four times

Edit: sorry, misread, thought you were disputing the number of times it appears in the page

Copy link
Contributor

@tetrapod00 tetrapod00 Jan 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code_WCtdPb9psl
It comes up a couple other times in other pages. I think it's fine and justified in the Getting Started tutorials, since it makes it extremely clear what to do. My guess is that it's a stylistic convention that was being followed at the time these pages were written.

I think we should move towards describing cases like this as "setting the Whatever property to a new Thing". If necessary we could also add in a general tutorial somewhere in the docs (either in Getting Started or maybe in the Inspector page) about which buttons to click to set properties, so this is explained in one place rather than piecemeal wherever it comes up. Something for another PR.

Comment on lines 309 to 310
``NORMAL_MAP`` in the ``fragment()`` function. This way Godot will handle the
wrapping of texture around the mesh automatically.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The section on setting the normals is a little broken, as indicated in #10501. I think that PR suggests the wrong fix, though.

I believe the intention with the tutorial is that the plane mesh normals are to be corrected by reading from a normal map. But since the normal map texture has high resolution, and the height is changed in vertex() but the normals are changed in fragment(), it not only corrects for the height, but also adds a bunch of extra normal detail. I think the right solution here might be to set the NORMAL value in vertex() rather than setting a normal map here. I'm not 100% sure, though.

Copy link
Member

@mhilbrunner mhilbrunner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving the changes here, I'll leave it to you two whether you're merging this as is and do a followup or do the further fixes in this PR. :)

Good work!

@tetrapod00
Copy link
Contributor

@skyace65 If you want to do any of the rewording away from click on "<empty>" in this PR feel free.

Other than that I would recommend merging this one as-is and leaving the rest for a followup PR, since the changes are a combination of nitpicky style stuff, also may require a proper review from shaders/rendering if we end up changing the instructions around setting the normals. This is already a great improvement as is.

@skyace65
Copy link
Contributor Author

I've made AThousandShips suggested change. @tetrapod00 just merge this as is, I'd rather leave rewording the "click on empty" stuff for another PR.

@tetrapod00 tetrapod00 merged commit 3a42447 into godotengine:master Jan 29, 2025
1 check passed
@tetrapod00
Copy link
Contributor

Thank you, merged! I'll get started on the more extensive changes when I get a chance.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area:manual Issues and PRs related to the Manual/Tutorials section of the documentation enhancement topic:shaders
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants