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 :slightly_smiling_face:

New pages

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

• [x] Large world coordinates (double-precision physics) https://github.com/godotengine/godot-docs/pull/6314
• [x] 3D resolution scaling (FSR) https://github.com/godotengine/godot-docs/pull/6331
• [x] 3D antialiasing https://github.com/godotengine/godot-docs/pull/6267
  • MSAA, TAA, FXAA, supersampling (resolution scale above 1.0).
• [x] 2D antialiasing https://github.com/godotengine/godot-docs/pull/6267
  • MSAA – mention what it affects and what it doesn't in 2D.
• [x] Variable rate shading (VRS) https://github.com/godotengine/godot-docs/pull/6402
• [x] 3D particle systems https://github.com/godotengine/godot-docs/pull/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.
• [x] Volumetric fog https://github.com/godotengine/godot-docs/pull/6162
• [x] Mesh LOD https://github.com/godotengine/godot-docs/pull/6161
• [x] Visibility ranges https://github.com/godotengine/godot-docs/pull/6161
• [x] Occlusion culling https://github.com/godotengine/godot-docs/pull/6160
  • Using the raster-based approach, different from portals and rooms in 3.x.
• [x] Introduction to global illumination https://github.com/godotengine/godot-docs/pull/6216
  • Mention faking outdoor GI with a second DirectionalLight as an alternative to Godot's GI methods: https://github.com/godotengine/godot-proposals/issues/3353#issuecomment-930413969
  • 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).
• [x] Signed distance field global illumination https://github.com/godotengine/godot-docs/pull/6216
  • Tweaking performance figures, avoiding light leaks, etc.
• [x] Decals https://github.com/godotengine/godot-docs/pull/6178
  • See https://youtu.be/CrOI5HUAPCg?t=9760 for inspiration.
• [x] GDExtension https://github.com/godotengine/godot-docs/pull/6212
  • See https://godotengine.org/article/introducing-gd-extensions for inspiration.
• [x] Upgrading to Godot 4 https://github.com/godotengine/godot-docs/pull/6393
  • See https://github.com/godotengine/godot-docs/issues/4960.
• [x] Global and per-instance shader uniforms https://github.com/godotengine/godot-docs/pull/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.
• [x] Using compute shaders https://github.com/godotengine/godot-docs/pull/6159
  • Documentation about writing and running compute shaders using local RenderingDevices. See also https://github.com/godotengine/godot-docs/issues/4834.
• [x] Using low-level GLSL shaders https://github.com/godotengine/godot-docs/pull/6159
  • Documentation about loading custom GLSL shaders (advanced users only).
  • See the end of https://godotengine.org/article/vulkan-progress-report-7 for inspiration.
• [x] Custom performance monitors https://github.com/godotengine/godot-docs/pull/6409
  • Documentation about creating and viewing the output of custom performance monitors.
• [x] Animation retargeting https://github.com/godotengine/godot-docs/pull/6322
  • See https://godotengine.org/article/animation-retargeting-in-godot-4-0 for inspiration.
• [x] Physical light units https://github.com/godotengine/godot-docs/pull/6390
  • Documentation about enabling, meaning of various units, pitfalls to watch out for.
• [ ] Run-time model loading
  • See https://github.com/godotengine/godot-docs/issues/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.

• [x] Engine's compilation guides at https://docs.godotengine.org/en/latest/development/compiling/index.html needs to be updated after the merge of https://github.com/godotengine/godot/pull/66242. https://github.com/godotengine/godot-docs/pull/6316 https://github.com/godotengine/godot-docs/pull/6375
• [x] Environment and post-processing https://github.com/godotengine/godot-docs/pull/6273
• [x] Using Fonts https://github.com/godotengine/godot-docs/pull/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.
• [x] Import process https://github.com/godotengine/godot-docs/pull/6782
• [x] Importing images https://github.com/godotengine/godot-docs/pull/6782
• [x] Importing audio samples https://github.com/godotengine/godot-docs/pull/6782
• [x] Importing 3D scenes https://github.com/godotengine/godot-docs/pull/6603 + https://github.com/godotengine/godot-docs/pull/6800
• [ ] Size and anchors (UI)
• [x] 2D tilemaps and tilesets https://github.com/godotengine/godot-docs/pull/6760
• [ ] 2D skeletal animation
  • See https://github.com/godotengine/godot-docs/issues/6388.
• [x] 2D lights and shadows https://github.com/godotengine/godot-docs/pull/6424
  • Mention directional 2D lights, specular mapping and the new shadow smoothing options (different from the ones in 3.x).
• [x] 3D lights and shadows https://github.com/godotengine/godot-docs/pull/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.
• [x] Voxel GI (replaces the old GI Probes page) https://github.com/godotengine/godot-docs/pull/6216
• [x] Baked lightmaps (mention the GPU lightmapper and LightmapGI node) https://github.com/godotengine/godot-docs/pull/6216
• [ ] High-level multiplayer
  • See https://github.com/godotengine/godot-docs/issues/6741.
  • See https://godotengine.org/article/multiplayer-changes-godot-4-0-report-2 for inspiration.
• [x] Internationalizing games https://github.com/godotengine/godot-docs/pull/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 (https://github.com/godotengine/godot/pull/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 :slightly_smiling_face:

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:

• https://github.com/godotengine/godot/pull/43115
• https://github.com/godotengine/godot/pull/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 :slightly_smiling_face: 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 :slightly_smiling_face:

[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 https://github.com/godotengine/godot-docs/issues/4834. A dedicated documentation page is welcome 🙂

[dotlogix]

I created a PR for a tutorial for compute shaders #6159

[FreshlyBrewedCode]

As far as I can tell the new 3D import workflow using the advanced import dialog (https://github.com/godotengine/godot/pull/47166) is still undocumented as well as the new animation retargeting system (https://github.com/godotengine/godot-proposals/issues/4510).

Generally, I find the current documentation regarding the 3D asset pipeline and import workflow rather confusing when working with Godot 4.

[FreshlyBrewedCode]

Edit: I created a separate issue for rewriting/improving the "importing 3D scenes" page: #6201

[fire]

Can you move this 3d formats task to a new issue to give us space to work 👍

[paddy-exe]

I started work on GDExtension docs👍🏻

[TheYellowArchitect]

https://docs.godotengine.org/en/latest/getting_started/step_by_step/instancing.html

The instancing.zip project (3.x by default) if auto-converted gets this error on running it

Also wall collision images don't match but I'm a newbie and don't know if that's a bug or not

Edit: nvm, its already known https://github.com/godotengine/godot-docs/pull/6187

[shinspiegel]

The tilemap was heavily changed. But the latest on the docs does not show these changes, does have anyone working on this topic? Otherwise, I would like to start working on this one. But I'm not an English specialist and I would love to have some native speaker or someone proficient with the language to fix/correct my mistakes if possible.

If there is some work being done, I would appreciate help/reviewing this one.

[TheYellowArchitect]

@shinspiegel if not me, then someone else will definitely fix the typos and grammar mistakes or clarifications needed. Go for it :tada:

[Black-Virtue]

Was about to add info on NavigationPolygon, it's missing it's properties and info on how to use them, but it's listed as 100% on the class reference status and when looking to edit I was greeted by a "do not edit, automatically generated" boilerplate. Is it actually safe to edit? and if not what steps should I go through to add the information?

[Black-Virtue]

@shinspiegel having recently bumped around trying to understand it myself I'll gladly look through and help with any wording, though I've not explored all of it's new features yet.

[gelvinp]

I'm updating the 4.0 GDScript warning system tutorial to the new annotation syntax, but it seems like it doesn't work all the time (trying to reproduce the third screenshot demonstrating ignoring the unreachable_code warning, and the warning just...isn't ignored). I'm gonna open an issue on the engine about that (there are multiple open already), but should I wait for that to be fixed before taking screenshots and PR'ing it all, or should I PR the changes with the new syntax now but have the screenshots either mismatched or not working?

[thadguidry]

6533 as well.

[lesleyrs]

@gelvinp Same problem with @warning_ignore(shadowed_variable).

[scriptsengineer]

UI pages need to be added to this list

[Calinou]

UI pages need to be added to this list

Which pages specifically? Many of them seem to be updated for 4.0 already: https://github.com/godotengine/godot-docs/tree/master/tutorials/ui

[scriptsengineer]

Indeed some have been updated, but an important one is https://github.com/godotengine/godot-docs/blob/master/tutorials/ui/size_and_anchors.rst Changed the way to use anchors in the editor

[YuriSizov]

Yes, it needs a rewrite to reflect the new workflow and editor UI changes (note that the underlying system is still the same, although some properties have been renamed).

[naturally-intelligent]

The 'Importing Images' tutorial needs to be updated:

https://docs.godotengine.org/en/latest/tutorials/assets_pipeline/importing_images.html https://github.com/godotengine/godot-docs/blob/master/tutorials/assets_pipeline/importing_images.rst

For example the texture Filter inside of Flags has been moved into CanvasItem

[Exerionius]

WorkerThreadPool class was added in Godot 4.0 and it is not on this list. There is no documentation for it: https://docs.godotengine.org/en/latest/classes/class_workerthreadpool.html

[Calinou]

WorkerThreadPool class was added in Godot 4.0 and it is not on this list. There is no documentation for it: docs.godotengine.org/en/latest/classes/class_workerthreadpool.html

This issue is only about manual pages, not class reference pages. We already have a tracker for class reference completion: https://godotengine.github.io/doc-status/

There's an open pull request documenting WorkerThreadPool, but it needs a review: https://github.com/godotengine/godot/pull/65268

For other classes, pull requests for the class reference should be opened against https://github.com/godotengine/godot's master branch, not godot-docs.

[Exerionius]

This issue is only about manual pages, not class reference pages.

Sorry for my misunderstanding, it's not very clear to be honest.

[raggi]

Using CharacterBody2D/3D code snippets need an update for move_and_slide parameter removal

[Calinou]

Using CharacterBody2D/3D code snippets need an update for move_and_slide parameter removal

Using CharacterBody2D should be updated already by https://github.com/godotengine/godot-docs/pull/6614. Did you read the /latest branch of the documentation?

However, there's still a separate Kinematic Character (2D) page which needs to be updated: https://github.com/godotengine/godot-docs/blob/master/tutorials/physics/kinematic_character_2d.rst I've added it to the list, but its name is awkward now that KinematicBody was renamed to CharacterBody.

[popcar2]

The Optimizing a build for size page doesn't seem to include the new Custom Engine Build Configuration feature found in Project --> Customize Engine Build Configuration. I think the options described in the current page like disabling advanced GUI objects might be redundant now that you can just choose what you want to exclude with your build config file.