Documentation pages to add or update for Godot 4.0

[Calinou]

Note: This issue is only for manual pages. For class reference pages, refer to the automatically updated tracker: https://godotengine.github.io/doc-status/

Help for working on these pages is welcome. If you're going to start writing a new page or rewrite an existing one, please leave a comment to state which page you're going to work on 🙂

New pages

Pages to write for features that were not present in Godot 3.x.

• Large world coordinates (double-precision physics) Add a page on large world coordinates (double-precision floats) #6314
• 3D resolution scaling (FSR) Add a page on 3D resolution scaling #6331
• 3D antialiasing Add documentation pages on 2D and 3D antialiasing #6267
  • MSAA, TAA, FXAA, supersampling (resolution scale above 1.0).
• 2D antialiasing Add documentation pages on 2D and 3D antialiasing #6267
  • MSAA – mention what it affects and what it doesn't in 2D.
• Variable rate shading (VRS) Add a page on variable rate shading (VRS) #6402
• 3D particle systems Add 3D Particles Documentation #5535
  • We don't have a page dedicated to 3D particles yet. This page should mention how to set up attractors, collision and trails. Setting up manual emission in a shader should be done in a dedicated page about particle shaders, since it's an advanced feature.
• Volumetric fog Add a page on volumetric fog and FogVolumes #6162
• Mesh LOD Add pages on mesh LOD and visibility ranges #6161
• Visibility ranges Add pages on mesh LOD and visibility ranges #6161
• Occlusion culling Add a page on occlusion culling #6160
  • Using the raster-based approach, different from portals and rooms in 3.x.
• Introduction to global illumination Revamp global illumination documentation #6216
  • Mention faking outdoor GI with a second DirectionalLight as an alternative to Godot's GI methods: Move DirectionalLight3D's shadow mode to a project setting godot-proposals#3353 (comment)
    • Faking indoor GI with OmniLights or SpotLights is also an option. It's still done in many AAA games today, but it involves a lot more manual work. It's still viable for dynamic lights when your GI solution of choice does not support real-time GI of moving lights (such as LightmapGI or SDFGI).
• Signed distance field global illumination Revamp global illumination documentation #6216
  • Tweaking performance figures, avoiding light leaks, etc.
• Decals Add a page on decals #6178
  • See https://youtu.be/CrOI5HUAPCg?t=9760 for inspiration.
• GDExtension Addition of GDExtension docs #6212
  • See https://godotengine.org/article/introducing-gd-extensions for inspiration.
• Upgrading to Godot 4 Add a Godot 3 to Godot 4 upgrade guide #6393
  • See Write a migration guide for Godot 4 #4960.
• Global and per-instance shader uniforms Document global and per-instance uniforms in Shading language #6414
  • Also document how to support specifying textures in per-instance uniforms. For portability reasons, you can't actually use textures in instance uniforms, but you can specify a texture array as a standard uniform and specify the layer to sample from as a instance uniform integer.
• Using compute shaders Adding example code for compute shaders #6159
  • Documentation about writing and running compute shaders using local RenderingDevices. See also Minimal Compute Shader Example #4834.
• Using low-level GLSL shaders Adding example code for compute shaders #6159
  • Documentation about loading custom GLSL shaders (advanced users only).
  • See the end of https://godotengine.org/article/vulkan-progress-report-7 for inspiration.
• Custom performance monitors Add a page on custom performance monitors #6409
  • Documentation about creating and viewing the output of custom performance monitors.
• Animation retargeting Add tutorials for blend animation and retargeting #6322
  • See https://godotengine.org/article/animation-retargeting-in-godot-4-0 for inspiration.
• Physical light units Add a page on physical light units #6390
  • Documentation about enabling, meaning of various units, pitfalls to watch out for.
• Run-time model loading
  • See godot 4 glTF runtime loader #6385.
• CanvasItem clipping (masking) and grouping
  • 2D lights and shadows page should refer to this page in place of the former Mask blend mode.

Pages to rewrite

These pages need rewrites from scratch with new screenshots.

• Engine's compilation guides at https://docs.godotengine.org/en/latest/development/compiling/index.html needs to be updated after the merge of SCons: Unify tools/target build type configuration godot#66242. Document the Unification of tools/target build type configuration #6316 Change build flags in Godot 4 docs to current variants #6375
• Environment and post-processing Update Environment and post-processing documentation for 4.0 #6273
• Using Fonts Update Using Fonts page for 4.0 #6373
  • Mention font fallbacks, variable fonts, OpenType variants, subpixel positioning and LCD subpixel optimization. Also mention that ligatures and emoji are fully supported since 4.0.
• Import process Update resource importing documentation for Godot 4.0 #6782
• Importing images Update resource importing documentation for Godot 4.0 #6782
• Importing audio samples Update resource importing documentation for Godot 4.0 #6782
• Importing 3D scenes Update Importing 3D scenes documentation for Godot 4.0 #6603 + Update Importing 3D scenes documentation for Godot 4.0 #6800
• Size and anchors (UI)
• 2D tilemaps and tilesets Update TileSets and TileMaps documentation for Godot 4.0 #6760
• 2D skeletal animation
  • See Skeleton 2D docs do not match Godot 4 #6388.
• 2D lights and shadows Update the 2D lights and shadows page for Godot 4.0 #6424
  • Mention directional 2D lights, specular mapping and the new shadow smoothing options (different from the ones in 3.x).
• 3D lights and shadows Update 3D lights and shadows documentation for 4.0 #6355
  • Mention the soft shadow properties.
  • Document setting up projectors for both spot and omni lights (omni lights require panorama textures).
  • Mention performance tuning and project settings.
• Kinematic Character (2D)
• 2D particle systems
  • Mention how to set up attractors, collision and trails. Setting up manual emission in a shader should be done in a dedicated page about particle shaders, since it's an advanced feature.
• Voxel GI (replaces the old GI Probes page) Revamp global illumination documentation #6216
• Baked lightmaps (mention the GPU lightmapper and LightmapGI node) Revamp global illumination documentation #6216
• High-level multiplayer
  • See Outdated info godot 4 (multiplater ENet) #6741.
  • See https://godotengine.org/article/multiplayer-changes-godot-4-0-report-2 for inspiration.
• Internationalizing games Update internationalization docs for 4.0 #6418
  • Mention translation contexts and pluralization.

[YuriSizov]

You can add almost every page on the editor as they all need new screenshots and in some cases updated descriptions too.

[Calinou]

You can add almost every page on the editor as they all need new screenshots and in some cases updated descriptions too.

Indeed, although I think tracking screenshot updates on existing pages should be done in a separate tracker issue. I want to focus on significant text changes here.

[skyace65]

I already have a PR in progress for lights and shadows. #4570. I'll add in the extra stuff you've mentioned here, though I still need help with fog fade and transmittance bias.

The said does it make sense to work on stuff for 4.0 now? There's no alpha yet so the UI can still change. This PR you made (godotengine/godot#48561) is still waiting to get merged and I wouldn't be surprised to see more UI changes between now and an alpha.

[and-rad]

@Calinou What do you want us to do if we stumble across outdated manual pages? Mention them here to get them added to the list or open a new issue, possibly tagging them with Godot 4.0? I'm currently running through the latest documentation and am finding a lot of outdated info. I don't want that to go to waste.

[Calinou]

@Calinou What do you want us to do if we stumble across outdated manual pages? Mention them here to get them added to the list or open a new issue, possibly tagging them with Godot 4.0? I'm currently running through the latest documentation and am finding a lot of outdated info. I don't want that to go to waste.

Feel free to mention a list here, although I'm already working on rewriting the global illumination docs right now (including GIProbe and BakedLightmap).

[and-rad]

Dope. Here's the first couple I found:

The Multiple Resolutions page talks about different stretch modes and mentions the three modes Disabled, 2D, and Viewport. In the current master branch, there's canvas_items instead of 2D, which I assume is still the same mode, but under a different name.

The Size and anchors page talks about "margins". This concept seems to have been renamed to "Offset" with the functionality remaining the same as far as I can see.

The screenshots on both of these pages need to be updated too. There was mention of a separate tracker that should be created for that, but it looks like that hasn't happened yet. Should I set up one while I'm at it or wait for someone from the "core" team to do it?

[Calinou]

The screenshots on both of these pages need to be updated too. There was mention of a separate tracker that should be created for that, but it looks like that hasn't happened yet. Should I set up one while I'm at it or wait for someone from the "core" team to do it?

There are some changes planned to the GUI system's containers and margin system, so I would wait until beta stage to make editor screenshots.

Still, pretty much all editor screenshots should be remade, since a new editor theme was designed for Godot 4.0. Feel free to create a separate tracker issue that lists individual image files that need to be remade.

[and-rad]

The Handling quit requests page seems to be completely outdated. It appears that the MainLoop.NOTIFICATION_WM_QUIT_REQUEST event, which the entire article revolves around, has been removed from the engine.

I noticed that most of the pages I mentioned are tutorials and I know there are plans to remove tutorials from the docs. Would it make sense to keep posting them vs. letting the problem solve itself when the tutorials get removed eventually?

[and-rad]

Now that feature warnings have been added to the engine, the Feature Tags page might have to be updated to include relevant information about how the warnings work.

[and-rad]

As far as I can see, the Reset Animation feature is not documented anywhere, either in the class reference or any of the tutorials. There is a single mention of a related property in the API documentation, but nothing that would clear up any questions users might have about the feature.

[and-rad]

@Calinou I'd like to work on the documentation of 3D particle systems. I'm currently getting familiar with the GPU particle system, so I would want to start with that. I'd also provide a translation while I'm at it (German in my case).

[Calinou]

@Calinou I'd like to work on the documentation of 3D particle systems. I'm currently getting familiar with the GPU particle system, so I would want to start with that. I'd also provide a translation while I'm at it (German in my case).

Sure, feel free to start working on a 3D particle systems page 🙂

I would only focus on GPUParticles usage for now. Topics to cover would be:

• Setting up a particle (ProcessMaterial, draw passes, etc)
• Subemitters
• Attractors
• Collision (the various collision nodes, their upsides/downsides, and how to enable collisions in the particle node)
• Trails

Manual emission requires a custom particle shader, which is likely outside the scope of a basic particle tutorial.

[and-rad]

The animation RESET track is not documented. Relevant PRs:

• Add animation reset track feature godot#43115
• Allow to add RESET values from existing keys godot#55653

[Calinou]

The animation RESET track is not documented.

The RESET track functionality is also present in Godot 3.4, so this is not exclusive to Godot 4.0. This issue is for items that should only be documented in Godot 4.0, so I'd open a separate issue for the RESET track documentation.

[and-rad]

My bad, you're right. I created a separate issue.

[and-rad]

I'm almost done with 3D particles and would like to do the localization overhaul next. If all goes well, I should have both ready by end of March.

[and-rad]

I have a suggestion for a new section: Accessibility.

According to the discussion on proposal 983, there is already quite a lot built into the engine that devs can use to make their games more accessible. TTS was also improved recently. I think it's time to start collecting all that info in a dedicated documentation section.

[Calinou]

I have a suggestion for a new section: Accessibility.

According to the discussion on proposal 983, there is already quite a lot built into the engine that devs can use to make their games more accessible. TTS was also improved recently. I think it's time to start collecting all that info in a dedicated documentation section.

I think a dedicated documentation section for accessibility makes sense if we can group enough items under that section. We can have a TTS manual page, but is there anything else in the core engine worth covering for accessibility?

[and-rad]

Here are some that I've implemented in past games:

• Rebinding keys. This is not usually seen as an a11y feature, but mostly because it's so common anyway.
• Font and UI scaling. Not even so much how to do it for individual controls, but how to hook this up so that every UI element updates when scaling settings are changed by users.
• Colorblind filters. This has become very easy with the addition of global shader params. At least that's how I did it in the past.
• Text-To-Speech. This is probably not fully production ready yet. But once it is, it should allow reading out button labels, maybe even dedicated a11y labels that contain text that is different from the normal label. Also things like "This is the main menu. The button in the lower right corner quits the game".
• Object highlighting. You can highlight objects in the game world with different colors while desaturating the surroundings to improve detectability. This is usually done with post processing shaders.

Here are some resources on how TLOU2 did it:

• https://www.playstation.com/en-us/games/the-last-of-us-part-ii/accessibility/
• https://www.youtube.com/watch?v=PWJhxsZb81U

You can do a lot of these with Godot already, so I'm proposing to add a dedicated section that teaches people how.

[Calinou]

Colorblind filters. This has become very easy with the addition of global shader params. At least that's how I did it in the past.

Colorblind filters are generally considered an antipattern in accessibility guidelines, so I wouldn't cover them. They can help as a stopgap, but it's not possible to make a colorblind person see a color that they can't see. A proper implementation of a colorblind-friendly mode avoids relying on color as the only source of information. This should ideally be done by default, so that all players benefit from this out of the box.

Adding subtitles is another thing that is worth documenting, but a good implementation requires more than a few lines of code. Therefore, I think it's best covered by an add-on.

The rest sounds good to me, although font and UI scaling should probably be covered in Multiple resolutions instead to keep the information centralized. We can then link to the relevant section on the accessibility page. Since Godot 3.4, there's a scale factor property so you don't have to resize every control and font manually (although individual resizing is still possible, and made easier in Godot 4.0 thanks to per-Control font sizes).

Object highlighting. You can highlight objects in the game world with different colors while desaturating the surroundings to improve detectability. This is usually done with post processing shaders.

Post-processing is a viable solution here, but it's not the cheapest and it can be less flexible sometimes. I think adjusting materials at load-time can go a long way here, while having zero run-time cost. Ultimately, both approaches should be covered, but material adjustment is probably the one that should be preferred if you have enough time to implement it.

For example, you could adjust the albedo color (and possibly make it slightly overbright), or enable emission to make highlighted objects glow in the dark.

If you want to go for that "clay model" look of TLoU2 in its object highlighting mode, you can remove the albedo textures entirely, set a bright albedo color and keep the normal maps.

[and-rad]

Those are good suggestions, but I want to clarify this part:

Colorblind filters are generally considered an antipattern in accessibility guidelines, so I wouldn't cover them

I know what you're talking about (at least I think I do), but that's probably not what I mean. I'm not talking about shifting hues of an entire scene, turning grass purple and water orange. That is dumb, no question. What I'm talking about is this: You have a bunch of clickable UI elements, one of them is special so it has a different color. What you do is you let players set a different color for elements of this kind or you define presets per colorblindness mode with the goal to still set it apart from the surroundings. But you don't touch the other elements.

Sorry if this actually was what you were talking about. Your second point still stands regardless. Color should not be the only source of information.

[Calinou]

What I'm talking about is this: You have a bunch of clickable UI elements, one of them is special so it has a different color. What you do is you let players set a different color for elements of this kind or you define presets per colorblindness mode with the goal to still set it apart from the surroundings. But you don't touch the other elements.

In that case, that sounds good to me 🙂
I find it useful when games allow adjusting team colors, and while it takes some time to apply consistently everywhere, it can be worth the effort.

[markwongsk]

Hi, I'm wondering if the gdscript grammar page should fall under the "needs to be updated" category. https://docs.godotengine.org/en/stable/development/file_formats/gdscript_grammar.html. Our team is currently trying out Godot 4.0 alpha from Godot 3.5 and we're also looking to update some of our tooling (like linters) which will probably need an updated BNF to work off.

[Calinou]

The GDScript grammar page was added shortly before GDScript was rewritten, so it's missing some things (including the % shorthand for scene-unique nodes, which works in a way similar to $). Pull requests to update it are welcome 🙂

[dotlogix]

I would like to provide sth for compute shaders.
Do we have any existing documentation/projects I could document, extend and also port to C#?

I am currently experimenting with C# compute shader based noise generation.
Could be a good example of a more advanced use case and works with a lot of data.

[Calinou]

I would like to provide sth for compute shaders. Do we have any existing documentation/projects I could document, extend and also port to C#?

I am currently experimenting with C# compute shader based noise generation. Could be a good example of a more advanced use case and works with a lot of data.

See #4834. A dedicated documentation page is welcome 🙂

[NezcalSpindrake]

Page says "up to date for Godot 4.0" but the tutorials and resources are for Godot 3.5 on the page https://docs.godotengine.org/en/stable/classes/class_collisionshape2d.html

[yurkkon]

Today I did the "my first 3D game" tutorial. I did it in Godot 4. In the initial banner, it says that the pages are outdated, but I did the tutorial just fine. Except the Animation system now changed, and you cannot copy and paste animation as before. Only the Animation part should be updated. I discovered the solution for Godot 4, but I do not know how to update the tutorial's webpage.

Also, the "my first 2D game" tutorial, I did it a week ago with Godot 4 and everything it's good.

[AlfishSoftware]

I've noticed 2 errors in pages that claim to be up-to-date for Godot 4.0.

---

https://docs.godotengine.org/en/4.0/classes/class_arraymesh.html#class-arraymesh-method-regen-normal-maps
This is confusing for me and possibly an error, considering the description was different in 3.6 (note, however, that the method name is different). Will it really generate just tangents? Or just normals? Or both? And if it's not tangents, is there a way to generate tangents directly, without SurfaceTool?

4.x: void regen_normal_maps() Regenerates tangents for each of the ArrayMesh's surfaces.
3.6: void regen_normalmaps() Will regenerate normal maps for the ArrayMesh.

By the way this page seems to imply you can't generate normals automatically from ArrayMesh API, so you'd have to use SurfaceTool for that. Which is it?

Using an ArrayMesh is slightly faster than using a SurfaceTool, but the API is a little more challenging. Additionally, SurfaceTool has a few quality of life methods such as generate_normals() and index().

Or am I just confusing things? Is generating normals != generating normal maps == generating tangents?

---

https://docs.godotengine.org/en/4.0/classes/class_surfacetool.html#class-surfacetool-method-commit
There's a FIXME here, so I believe the page shouldn't say it's up-to-date until this FIXME is solved:

ArrayMesh commit(ArrayMesh existing=null, int flags=0) [...]
FIXME: Document possible values for flags, it changed in 4.0. Likely some combinations of ArrayFormat.

[NaleVex]

On 2D Navigation Overview page there are links in "see also" box:
You can see how 2D navigation works in action using the 2D Navigation Polygon and Grid-based Navigation with AStarGrid2D demo projects

Both demos are for GD 3.5

[smolten]

I'm a Unity user trying out Godot Mono, excuse me if I'm in the wrong place
(using Godot v4.1.stable.mono.official [970459615])

GDScript classes "JSON" and "HTTPRequest" are now "Json" and "HttpRequest" in Mono

• JSON example is only in gdscript, no mono
  https://docs.godotengine.org/en/stable/classes/class_json.html
• HTTPRequest does have a C# example, but it won't compile as "HTTPRequest", must be "HttpRequest"
  https://docs.godotengine.org/en/stable/classes/class_httprequest.html

PS: Thanks to Capitalization >:( and awful AI advice, I tried compiling Godot with mono from source (seeing lots of Error 1's from scons....), which Thankfully I discovered I did NOT have to do...

[LennartH]

Page Godot notifications says that it's up to date for Godot 4.1, but the GDScript snippet for _init vs. initialization vs. export isn't valid syntax anymore

• The line export(String) var test = "one" setget set_test needs to be rewritten.
• The mentioned differentiation between test = "three" and self.test = "three" also isn't correct anymore (see note in Properties GDScript reference)

[imartc04]

Page https://docs.godotengine.org/en/stable/classes/class_hingejoint3d.html#class-hingejoint3d-property-motor-target-velocity

I think properties of joints should include units (if the property is an adimensional coefficient also indicate it) and the range of values. The problem Im having is that Im trying to parse joint parameter from other source to godot joints and without possible ranges nor units one cannot make a proper conversion. In some cases the units can be deduced from equations in the engine code. This issue happens for all joint3D classes

Also I will mention that the HingeJoint3D implementation seems not to implement the angular limit restrictions
File : godot_hinge_joint_3d.cpp

Code :

//apply motor
		if (m_enableAngularMotor) {
			//todo: add limits too
			Vector3 angularLimit(0, 0, 0);

			Vector3 velrel = angVelAroundHingeAxisA - angVelAroundHingeAxisB;
			real_t projRelVel = velrel.dot(axisA);

			real_t desiredMotorVel = m_motorTargetVelocity;
			real_t motor_relvel = desiredMotorVel - projRelVel;

			real_t unclippedMotorImpulse = m_kHinge * motor_relvel;
			//todo: should clip against accumulated impulse
			real_t clippedMotorImpulse = unclippedMotorImpulse > m_maxMotorImpulse ? m_maxMotorImpulse : unclippedMotorImpulse;
			clippedMotorImpulse = clippedMotorImpulse < -m_maxMotorImpulse ? -m_maxMotorImpulse : clippedMotorImpulse;
			Vector3 motorImp = clippedMotorImpulse * axisA;

			if (dynamic_A) {
				A->apply_torque_impulse(motorImp + angularLimit);
			}
			if (dynamic_B) {
				B->apply_torque_impulse(-motorImp - angularLimit);
			}
		}

As you can see there is a //todo: add limits too . Not directly business of this repo but docs should reflect the status of the code they are versioning right?

Thanks for the effort
regards

[PitouGames]

Page https://docs.godotengine.org/en/stable/contributing/development/compiling/compiling_for_windows.html#creating-windows-export-templates

• The text
  If you plan on replacing the standard export templates, copy these to the following location, replacing <version> with the version identifier (such as 3.1.1.stable or 3.2.dev):
  could be updated to mention 4.x.

• The path seems wrong, on my machine the folder is %USERPROFILE%\AppData\Roaming\Godot\export_templates\<version>\ instead of templates.

• The \ triggers wired syntax highlight for no reason.

[AThousandShips]

This is incorrect, see:

• Sprite2D.gd not sprite_2d.gd in scripting_first_script.rst #8494
• Snake-case .tscn, .gd and _on_* callbacks #7370

This is done by choice and should not be reverted, instead the screenshot should be fixed

[ArekKubinski]

This is incorrect, see:

* [Sprite2D.gd not sprite_2d.gd in scripting_first_script.rst #8494](https://github.com/godotengine/godot-docs/pull/8494)

* [Snake-case .tscn, .gd and _on_* callbacks #7370](https://github.com/godotengine/godot-docs/pull/7370)

This is done by choice and should not be reverted, instead the screenshot should be fixed

So I deleted the comment cause I am new and felt embarrassed but after researching this topic it looks like docs are changing to snake case because devs use them, but after downloading Godot 4.1 binary for linux straight from the site it auto generated this file Sprite2D.gd and not sprite_2d.gd as docs that claims to be consistent with version 4.1 suggests. I know this discussion is about 4.0 but i didn't found any opened issue about 4.1 so I'm thinking this is right place to submit this. It can also be that I am using binary from site instead of using godot from github but then whats the point of hosting binary on site.

[AThousandShips]

See:

• The "Attach Node Script" dialog should suggest snake_case file names, consistent with the documentation godot-proposals#1211

[Exerionius]

it auto generated this file Sprite2D.gd and not sprite_2d.gd as docs that claims to be consistent with version 4.1 suggests

@ArekKubinski you need to save the scene as snake_case first. When you attach a script to the root of this scene the autogenerated name for the script file will also be in snake case.

If the scene is new and not saved yet it doesn't work and falls back to PascalCase.

[RadiantUwU]

#8715

[MisterE123]

#6741 is closed as completed ... should the multiplayer docs be marked complete in the checklist?

[GigglingGalaxy]

Navigation Elements Docs Thoughts:

When I read the Navigation docs (and Signal docs, but I don't have time to explain those), here are the places I glitch out. IDK if I am your "audience" for the docs, so this all may be irrelevant. As an audience, I am someone who is self-taught, very very little programming background (like "goto line 32" on an Apple 2+), was able to do navigation easily in Unity, has been working Godot daily for about 2 years, and is just now really understanding things like the difference between a method and a function and a call and a signal.

On this doc (and several Navigation elements' docs), https://docs.godotengine.org/en/stable/tutorials/navigation/navigation_using_navigationpaths.html
In the first script:

basic query for a navigation path in 3D using the default navigation map

It doesn't say which node to add the script to.
I am trying to understand all Nav things, and from what I glean, the nav map is generated so it's not like a node that I make and put into the hierarchy, right? So, just a clarification of which node I'd use that basic query on.

Scroll Down on that page ^^^ to header:
Navigation mesh script templates
(https://docs.godotengine.org/en/stable/tutorials/navigation/navigation_using_navigationmeshes.html#navigation-mesh-script-templates)
The following script uses the NavigationServer to parse source geometry from the scene tree, bakes a navigation mesh, and updates a navigation region with the updated navigation mesh.

^^^ That sounds like you'd add the script on the NavMesh, but it says "Inherits Node3D" at the top of the script. So that means it's not on a mesh node, or a NavigationRegion node. Where do best practices say I should put it? I'm just learning Navigation stuff and though I have read the docs over several times, I get lost on where to add which script. Side note, I do think it is clear NavAgent stuff can go in its parent's character body or node script. So, needed is below.

Need: a simple, clear line about which node to put scripts on when giving a script as custom way to do a nav thing. Example: "Attach this script to a NavigationRegion3D parent node of type Node3D, or to the NavigationRegion3D itself."

Need: keep the great documentation going down to each node--especially NavigationAgent3D--w/examples (including NavAgent + mesh or + array path or + idk what else can be used). I can't give an example because I cannot figure out how to do the actual "hey, NavAgent, it's time to move to point A" function (which seems should use set_target_location, but that's called in Physics, and set_movement_location is called in setup, so I get lost as to what exactly should be called where, and if I am supposed to add a function separately other than the ones in the docs).

I see this script in NavAgent Docs under Actor as CharacterBody3D: https://docs.godotengine.org/en/stable/tutorials/navigation/navigation_using_navigationagents.html

And this script in Obtaining a Navigation Path: https://docs.godotengine.org/en/stable/tutorials/navigation/navigation_using_navigationpaths.html

But another one somewhere else which I cannot find now where it says this in physics:
` var current_agent_position: Vector3 = global_position
var next_path_position: Vector3 = navigation_agent.get_next_path_position()

velocity = current_agent_position.direction_to(next_path_position) * movement_speed
move_and_slide()`

It is unclear when to use which, and/or how to include target_desired_distance in either of these scripts. Does it somehow automatically know that the desired distance is the end of the path? When I run either of these scripts my NavAgent parent cuts across the field and doesn't follow the set/baked NavRegion in any way. I set all on same Nav and collision layers.

Issue: the exact way to get NavAgent to start moving when you want it to.
Why: I'm an unskilled coder, and so when I see the movement and movement_target inside physics, and moving is called with physics stuff, I can't understand when/where to say "don't do that physics function move until this other thing sends you this signal, then you can execute your physics movement and move to point B(target_location)". If I try to reference anything in Physics from outside that func, it doesn't recognize the function (says not called in script) which I understand bc it was only called in Physics. Do I call it again outside of Physics? What goes in the functions on the signals like "on_target_reached" or "on_nav_finished"? I get notified it stopped, but how do I tell it to wait to start, or where end is, or where beginning is when all that is happening back in the physics function? How does it know the end?

It is mostly clear when we need each element and where that goes in the hierarchy, but then in order to: "Navigation paths can be directly queried from the NavigationServer," when I don't know where the NavServer script goes--if it even goes on a node at all? And after reading the Server docs, I had decided I didn't need to be that detailed. But also didn't see there where my script would get run from?

Why: I only want my curve points (which I made into a CSGpolygon3D so they could be the nav mesh for the node NavRegion) as my NavAgent path, and I only want to do that so I can control Agent starting to move on his path (on signal when something else happens) because I do NOT want him to cut across the field, he should stay on the road (my curve/polygon/Path3d base thing, which is the only thing in the navmesh).

I cannot use Pathfollow3D because I don't want my NPC as a child of that (long story why). But would that with Remote Transform REPLACE navigation?

I have not looked into adding curve points as array for NavMesh--so I can say "move to the third index point now" (I think the idea is what the last script shows on that page: "The following script uses the NavigationServer to update a navigation region with procedurally generated navigation mesh data." Even though I don't need to generate the curve/path--I already made it a node. Before I try that, I want to know where the NavigationServer script goes, and understand how to control my navAgent to sit there at point A until thing happens, start moving when thing happens, then keep moving to point B, then stop and wave hello at the end. But none of the docs drill down to actually controlling your NavAgent outside the actual physics function.

The current outside tutorials all either have a continuous loop OR set target_path to random in Physics so those don't help. I just downloaded the 3d Navmesh tutorial sample project thing. I will look how it's set up and try to mimic that in mine. BUT if the docs had (maybe in a Navigation intro?) explained more simply which to use in what use cases (for best load balance, best visuals, best stay right on this exact path, etc),

Need: So, at no point are "path follow" or "remote transform" mentioned as alternatives. Are they? If so...
Perhaps a "Note" box which says:
If you want to do ______, consider PathFollow(linked: https://docs.godotengine.org/en/stable/classes/class_pathfollow3d.html)
If you want to do _____, it might not be worth the weight of Navigation on your memory so use Remote Transform (linked: https://docs.godotengine.org/en/stable/classes/class_remotetransform3d.html).

Where I glitch out is would either of these be used INSTEAD of using NavigationRegion + Curve/Path points you use NavRegion with your NavAgent3D on that remote path??? or do you only need your player/npc as the remote node and your curve and you're good to go? Pathfollow doc says: "It is useful for making other nodes follow a path, without coding the movement pattern". But then goes on to say you would set the value to update movement, which would be coding the pattern using the path you made, wouldn't it? Even so, if I cannot have that moving node as a child, I cannot use path follow, right? It says: "After setting the target_position property, the get_next_path_position method must be used once every physics frame to update the internal path logic of the navigation agent. The vector position it returns should be used as the next movement position for the agent's parent node." So if I want to choose my next_path_position on the path...???

I am unclear as to whether Remote Transform could be used on a NavAgent (or if there's some other way to specifically tell them when to go where). So somehow helping us understand actually moving the NavAgent on the specific path part of the NavMesh, Region, Curve, etc would REALLY help I think.

I wonder: Remote Transform has no mention of PathFollow3D or NavigationMesh/Region/Agent ...could they work together? Should they? Is Remote Transform redundant if using NavAgent? Is a "Remote Node" basically the same as NavAgent?

That's how someone at my level tries to use the docs to handle Navigation of an NPC who literally only needs to walk when NodeX visibility changes (signal to NavAgent parent), along a simple curve path, and stop when he gets to point B. I can't even imagine trying to get him to avoid obstacles. In fact, I just moved everything out of the way of his path (NavRegion NavMesh CSGPolygone from a curve) so I wouldn't have to lol. I hope this helps, and isn't just really annoying.

[FunnyFiveever]

Your First 2D game >> Finishing up >> Background
The background guide seems to be described insufficiently. If only a ColorRect is added as a background, it may lead to players being invisible. This could be due to them being on the same Z-axis

[Jadael]

This seems like a good place to leave this note as opposed to a whole new issue- we just noticed that the documentation about Format Strings doesn't mention how to escape the % character anywhere (you use %%). It's also difficult to search for on Google because results about the non-Format Strings dominate the results, so maybe the main String doc should reference it somehow too.

[AThousandShips]

@Jadael what do you mean? It's right here with its own section

[Jadael]

@Jadael what do you mean? It's right here with its own section

How strange. I literally found that page, read through it, figured it probably was %%, and even did a Ctrl+F to look for "%%", not even an hour ago. I guess can only assume I did something wrong somehow.

[Jaldvox]

A big greeting 👋 😉 from Spain.,