godotengine / godotengine/godot-docs

Background loading doc describes approach that blocks the main thread and causes freezes/lag/stutter

Open
#9,663 3 comments 0 reactions 0 assignees View on GitHub
area:manual enhancement
Dominant language
reStructuredText
Stars
5.7k
Forks
3.8k
Avg merge
1d 20h
Merged PRs (30d)
25

Description

**Your Godot version:**
4.2

**Issue description:**
The background loading page insinuates that using their approach will not block the main thread.

As far as I understand from feedback of other Godot devs, the approach shown in the doc WILL block the thread.

Specifically this call:
`var enemy = enemy_scene.instantiate()`

I think the doc is very misleading to devs.

See: https://forum.godotengine.org/t/background-loading-packed-scenes-without-lag/39887

There is also no stable solution to this problem (afaik) as you cannot really instantiate a node on a different thread.
https://docs.godotengine.org/en/stable/tutorials/performance/thread_safe_apis.html#rendering

```
Instancing nodes that render anything in 2D or 3D (such as Sprite) is not thread-safe by default. To make rendering thread-safe, set the Rendering > Driver > Thread Model project setting to Multi-Threaded.

Note that the Multi-Threaded thread model has several known bugs, so it may not be usable in all scenarios.
```

**URL to the documentation page (if already existing):**
https://docs.godotengine.org/en/stable/tutorials/io/background_loading.html

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.