Add search keywords for project settings #112107
Conversation
Calinou
added
enhancement
documentation
cherrypick:4.5
Calinou
force-pushed
the
doc-projectsettings-add-keywords
branch
from
819ed3d to
0e16655
Compare
This adds keywords that references possible values for project settings, which makes them easier to find in the class reference search. Note that this currently does not improve search results in the Project Settings dialog's filter bar, as it doesn't make use of class reference keywords yet.
Calinou
force-pushed
the
doc-projectsettings-add-keywords
branch
from
0e16655 to
d610824
Compare
| Defines how the aspect ratio of the base size is preserved when stretching to fit the resolution of the window or screen. | ||
| [b]"ignore"[/b]: Ignore the aspect ratio when stretching the screen. This means that the original resolution will be stretched to exactly fill the screen, even if it's wider or narrower. This may result in nonuniform stretching: things looking wider or taller than designed. | ||
| [b]"keep"[/b]: Keep aspect ratio when stretching the screen. This means that the viewport retains its original size regardless of the screen resolution, and black bars will be added to the top/bottom of the screen ("letterboxing") or the sides ("pillarboxing"). | ||
| [b]"keep_width"[/b]: Keep aspect ratio when stretching the screen. If the screen is wider than the base size, black bars are added at the left and right (pillarboxing). But if the screen is taller than the base resolution, the viewport will be grown in the vertical direction (and more content will be visible to the bottom). You can also think of this as "Expand Vertically". |
There was a problem hiding this comment.
| [b]"keep_width"[/b]: Keep aspect ratio when stretching the screen. If the screen is wider than the base size, black bars are added at the left and right (pillarboxing). But if the screen is taller than the base resolution, the viewport will be grown in the vertical direction (and more content will be visible to the bottom). You can also think of this as "Expand Vertically". | |
| [b]"keep_width"[/b]: Keep aspect ratio when stretching the screen. If the screen is wider than the base size, black bars are added at the left and right (pillarboxing). But if the screen is taller than the base resolution, the viewport will be grown in the vertical direction (and more content will be visible at the bottom). You can also think of this as "Expand Vertically". |
| [b]Note:[/b] By default, or when set to [code]0[/code], the initial window width is the [member display/window/size/viewport_width]. This setting is ignored on iOS, Android, and Web. | ||
| </member> | ||
| <member name="display/window/stretch/aspect" type="String" setter="" getter="" default=""keep""> | ||
| <member name="display/window/stretch/aspect" type="String" setter="" getter="" default=""keep"" keywords="ignore, keep, keep_width, keep_height, expand"> |
There was a problem hiding this comment.
Using keywords to list all possible values in an enumerated property or setting gives away a big flaw in how searches are made in the engine.
That is to say, this should not be the purpose of keywords and, in an ideal world, these values should be present in the class's XML file directly, ready to be queried as needed.
Portray yourself as the common user looking this setting. They may not know the proper term for this, so they may think about something like resolution, scale, ratio, even width or height if we're stretching (pun intended). They may certainly not look for keep_height (underscore included otherwise the keyword doesn't match)
There was a problem hiding this comment.
Some enum values don't make sense to be searched as strings (such as Auto, Disabled, Enabled, Low, Medium, High, Ultra). Therefore, I think it's better to manually populate the list as needed.
| <member name="display/window/stretch/aspect" type="String" setter="" getter="" default=""keep""> | ||
| <member name="display/window/stretch/aspect" type="String" setter="" getter="" default=""keep"" keywords="ignore, keep, keep_width, keep_height, expand"> | ||
| Defines how the aspect ratio of the base size is preserved when stretching to fit the resolution of the window or screen. | ||
| [b]"ignore"[/b]: Ignore the aspect ratio when stretching the screen. This means that the original resolution will be stretched to exactly fill the screen, even if it's wider or narrower. This may result in nonuniform stretching: things looking wider or taller than designed. |
There was a problem hiding this comment.
In all of the following cases, the options available are particular in that they're genuine strings value being stored internally. This is a special case, so our general rule to use bold to list the options available does not apply.
| [b]"ignore"[/b]: Ignore the aspect ratio when stretching the screen. This means that the original resolution will be stretched to exactly fill the screen, even if it's wider or narrower. This may result in nonuniform stretching: things looking wider or taller than designed. | |
| [code]"ignore"[/code]: Ignore the aspect ratio when stretching the screen. This means that the original resolution will be stretched to exactly fill the screen, even if it's wider or narrower. This may result in non-uniform stretching: things looking wider or taller than designed. |
As of writing I have not many suggestions content-wise, but I do think that each option is described a bit inconsistently.
There was a problem hiding this comment.
Just as an addendum, we wrote "non-uniform" vastly more often than "nonuniform" (that is, not at all). Both are synonyms and apparently "nonuniform" is becoming more common, but I wouldn't drop the hyphen for the sake of clarity here.
| [b]Warning:[/b] Godot's damping calculations are simulation tick rate dependent. Changing [member physics/common/physics_ticks_per_second] may significantly change the outcomes and feel of your simulation. This is true for the entire range of damping values greater than 0. To get back to a similar feel, you also need to change your damp values. This needed change is not proportional and differs from case to case. | ||
| </member> | ||
| <member name="physics/2d/physics_engine" type="String" setter="" getter="" default=""DEFAULT""> | ||
| <member name="physics/2d/physics_engine" type="String" setter="" getter="" default=""DEFAULT"" keywords="godotphysics"> |
There was a problem hiding this comment.
While this is a relatively innocent addition, I struggle to imagine anyone looking for godotphysics specifically. It's Godot's own barebones engine that, if it weren't listed, few would think it even has a name other than "Default", especially because it doesn't have its own exclusive section of settings (unlike Jolt). I know a few people that haven't even messed with these physics settings and stuck to the default.
3 participants
This adds keywords that references possible values for project settings, which makes them easier to find in the class reference search.
Note that this currently does not improve search results in the Project Settings dialog's filter bar, as it doesn't make use of class reference keywords yet.
This also adds a description for stretch aspect, which was previously empty.
Preview