+4 votes

In Project Settings > Physics > 2D, there is an option to change the thread model from Single-Safe to Single-Unsafe or Multi-Threaded.

I am working on a 2D action platformer and quite like how my game feels using the Multi-Threaded model.

My questions are:

  1. What are the main differences between these choices?
  2. When would it be good to use one over the other?
  3. Is there any danger in publishing a game using the Multi-Threaded model?
in Engine by (1,549 points)

I'm doing a 2d shooter and were getting lots of unexplained crashes like

ERROR: _unpair_attempt: Condition "!E" is true. At: servers/physics_2d/broad_phase_2d_hash_grid.cpp:57

among others. switching back to "Single-Safe" resolved all of these issues. I get the errors in 3.2.3 and 3.2.4

1 Answer

+1 vote

This article introduces Godot's multithreading model:


That suggests that Godot multi-threaded can run logic, physics updates and rendering in parallel.


The "rendering/threads/thread_model" settings is described as "Thread model for rendering. Rendering on a thread can vastly improve performance, but synchornizing to the main thread can cause a bit more jitter". This suggests that with this setting only rendering is ran in a separate thread.

"Multithreaded" is internally called "RENDERSEPARATETHREAD". Looking at Godot 3.2.3 code, seems that what this does is to wrap the VisualServer calls in a VisualServerWrapMT class and create a thread to consume the rendering commands queue (instead of consuming them sequentially in the main loop). Note that the same class is used for Single-Safe mode, but a separate thread is not used to dispatch commands.

In my code,. "Single Unsafe" crashes, and I have appreciated slightly smoother visuals when using "Multithreaded".


For physics 2D, Multithreaded setting "physics/2d/thread_model" applies to a PhysicsServer attribute called "using threads". Its documentation says:

"Sets whether physics is run on the main thread or a separate one. Running the server on a thread increases performance, but restricts API access to only physics process. Warning: As of Godot 3.2, there are mixed reports about the use of a Multi-Threaded thread model for physics. Be sure to assess whether it does give you extra performance and no regressions when using it."

The implementation internally wraps the PhysicsServer code with a Physics2DServerWrapMT class that can (optionally, in the case of "Multithreaded") do some tasks in a separate thread.

In my current code, this mode seems to work for a short span. Causes modified physics behavior, and ends up crashing the game process after 10-20 seconds.


I assume that none of the "Multithreaded" mode doesn't work or apply to HTML5 builds on current Godot 3.2.x version.

Personally, I don't think it's safe to change this once you have started a project. Note, however, that you can change the rendering threading model (but not the physics model) for an already generated Godot project by using the command line switch:

--render-thread <mode> Render thread mode ('unsafe', 'safe', 'separate').

by (39 points)
edited by

May I ask what makes you say you don't think it's safe to change it once you've started a project?

If you change this setting in mid-development, your existing physics may or may not work, but unless you have designed your code with this in mind you may introduce different behaviours and regressions that you didn't test for in the first place, and the fact that in my code changing this makes it crash (which shows that multithreaded implementations do behave different). That said, my statement is too blunt... just test, and use it if you are comfortable with it.

Welcome to Godot Engine Q&A, where you can ask questions and receive answers from other members of the community.

Please make sure to read How to use this Q&A? before posting your first questions.
Social login is currently unavailable. If you've previously logged in with a Facebook or GitHub account, use the I forgot my password link in the login box to set a password for your account. If you still can't access your account, send an email to webmaster@godotengine.org with your username.