Implement motion blur feature based on the community plugin

[HydrogenC]

This PR implements the motion blur post processing based on the community plugin created by @sphynx-owner . The original repos could be found here: https://github.com/sphynx-owner/godot-motion-blur-addon-simplified and https://github.com/sphynx-owner/JFA_driven_motion_blur_addon.
Closes godotengine/godot-proposals#12258 and godotengine/godot-proposals#2933.
There are some differences compared to the original plugin, notably:

• • Cleaning up of unused resources in shader
• • Cleaning up the code
• • Changed some uniform constants to specification constants, enabling loop unrolling, so the performance is better

This PR is co-authored with @AR-DEV-1 , with me doing the graphics and shaders part and @AR-DEV-1 working with the editor settings parts.
Supported backend: Forward+.

Preview:

Docs not yet written, since the API itself may be subject to change during review. Docs will be finished by @AR-DEV-1 after the API itself gets approved.
The current blocker is that the current implementation exposes too many parameters, we may have to scale the number down and make some of them constant instead.

Note

godot-cpp will also be modified with these changes after the the API itself gets approved. The build for the editor with mono on Linux can be ignored for now.

[HydrogenC]

Already feature complete and workable, but API might be subject to change. We may want the API to get reviewed first before marking this PR as ready.

[AThousandShips]

All the third-party content needs to be correctly attributed, this currently violates their license

Edit: especially seeing how it's so directly copied you even copied typos and TODOs from the original 🙃

[AR-DEV-1]

All the third-party content needs to be correctly attributed, this currently violates their license

I'll do it.

[sphynx-owner]

Amazing work. I finally got to have a look, and I have a few changes to request:

1. motion_blur_jitter_tiles should not be an option, that is my bad. It should always be true. Without it the seams between tiles are obvious.
2. motoin_blur_velocity_depth_test is also a redundant setting, and should be true by default. Again, my bad.
3. target_framerate, framerate_independent, and uncapped_independence should be reintroduced, as they are key features that users thould be able to play with.
4. All of the motion separatiion setting, that is all of these

should be exposed. Their purpose is not clear, and I take the blame for not communicating them clearly enough. They are actually a key feature that make our motion blur effect as powerful as it is. They allow for movement separation between the camera's movement, rotation, and object's movement, allowing users to configure the contribution of each to the final blur separately!

The thresholds are also a cool feature that expand upon the separation, allowing you to configure a velocity threshold for the "activation" of blur for each of these components. This can yield granular control by the user to keep the game view crisp and blur free unless some extreme motions occur.
Something like this:

2026-01-16.12-51-09.mp4

Since this can be a bit cumbersome to have 6 properties, and yield diminishing returns in terms of granularity, we can consider just having one set of lower and upper threshold parameters that would apply to all 3 components at the same time.

Edit: We can maybe come up with clearer way to expose the framerate related settings. It is not clear what these do and would be hard to communicate through doc comments. Also there are a lot of redundant configurations with them, so I imagine some enum to represent common "framerate modes"

Edit 2: For the framerate modes I am thinking:
NATIVE - the blur is determined purely based on the framerate of the game (final_intensity = intensity)
MIN_FRAMERATE - the blur is determined based on the framerate of the game, but below a minimum framerate limit the amount of blur to that framerate (so it is not abnoxious) (final_intensity = intensity * min(1 / minimum_framerate, time_step) / time_step)
FORCE_FRAMERATE - the blur is determined based on a fixed framerate defined by the user, so even at higher framerate it will maintain the same amount of blur (overblurring, but more consistent). (final_intensity = intensity / (target_framerate * time_step))

For the latter 2 modes, a framerate property should be dynamically exposed.

[sphynx-owner]

I apologize for the bother, I should have been cleaner and clearer about the setup.

[AR-DEV-1]

@HydrogenC Please update the PR's description with the following:

(EDIT: THE CHANGES REQUESTED HAVE BEEN MERGED BY THE OP)

[HydrogenC]

All the third-party content needs to be correctly attributed, this currently violates their license

Edit: especially seeing how it's so directly copied you even copied typos and TODOs from the original 🙃

Not really. I made plenty of modifications actually. The TODOs are there because they are not yet resolved so I keep them to hint future contributors. For the TODOs that I have resolved, I already removed them. This doesn't mean that this PR is underworked.
Btw the original author of the community addon @sphynx-owner is also helping us with this PR. Thanks for help. We'll be adding copyright headers for the GLSL files included right over.

[AThousandShips]

This doesn't mean that this PR is underworked.

Nor did I say so!

[jcostello]

Only works for PracticalCameraAttr? Also I notice that then v-sync is disabled I can barely notice the blur

[HydrogenC]

Only works for PracticalCameraAttr? Also I notice that then v-sync is disabled I can barely notice the blur

We can move it elsewhere if required, like to environment. Now it's under practical camera attributes.

[jcostello]

Only works for PracticalCameraAttr? Also I notice that then v-sync is disabled I can barely notice the blur

We can move it elsewhere if required, like to environment. Now it's under practical camera attributes.

Yeah I mean, I dont mind that is there, but its not present in PhysicalCameraAttr

[yusuf-123-3]

When rendering driver is d3d12 this happens:
https://github.com/user-attachments/assets/d39eaf15-a490-4aea-be23-e23d49daa6bf

Properties do not appear until you reopen camera_attributes resource:
https://github.com/user-attachments/assets/da753048-45f6-45e3-b705-617775e0ee3d

This one is hard to see but when you run the project with motion blur enabled a little flickering can be seen:
https://github.com/user-attachments/assets/4757bb7e-e30b-47d4-9d7d-d354c5fd97ac

Only camera rotation gives effect:
https://github.com/user-attachments/assets/0cca69eb-285f-4579-96f8-d18538f4a767

I think some properties should be changed in rendering/camera instead of in the camera_attributes:

[sphynx-skillcap]

Wow this is a lot. The second issue can be fixed with calling notify_property_list_changed most likely. The last issue is not even just camera rotation, the entire blur is broken completely WTH.

[yusuf-123-3]

Wow this is a lot. The second issue can be fixed with calling notify_property_list_changed most likely. The last issue is not even just camera rotation, the entire blur is broken completely WTH.

Intensity is set to 100.0 in that clip if you are talking about that

[AR-DEV-1]

Only works for PracticalCameraAttr? Also I notice that then v-sync is disabled I can barely notice the blur

I think it is fine in PracticalCameraAttr, as the base class (CameraAttr) has only stuff regarding exposure & auto-exposure & PhysicalCameraAttr also has the same, only with frustum added. So, if required, we could change it.

[HydrogenC]

When rendering driver is d3d12 this happens: https://github.com/user-attachments/assets/d39eaf15-a490-4aea-be23-e23d49daa6bf

@AThousandShips I have a small question. I've done some debugging on this problem and I found removing specification constants fixes the problem. Is specification constants unsupported in the D3D12 backend?

[AR-DEV-1]

@AThousandShips I have a small question. I've done some debugging on this problem and I found removing specification constants fixes the problem. Is specification constants not supported in the D3D12 backend?

You may want to also ask @clayjohn

[AR-DEV-1]

Properties do not appear until you reopen camera_attributes resource: https://github.com/user-attachments/assets/da753048-45f6-45e3-b705-617775e0ee3d

Is fixed with notify_property_list_changed()

[AThousandShips]

I unfortunately can't help with rendering questions clay would be a better person to respond, and I'm sure he will when he has the time

[sphynx-owner]

@HydrogenC I have a fix for the 4th issue:

Until we figure out the framerate modes, this can be removed.

[sphynx-owner]

In addition, I set up a little side by side of the different blurs because something did not look good, and I found that you did not correctly remove the velocity_depth_test variable in the blur shader, causing overblurring over geometry:

2026-01-17.20-38-44.mp4

[allenwp]

sphynx-owner, I'm very happy to see your involvement in this PR, even if just from a testing and review perspective. This sort of testing and insight from an expert on the subject is invaluable to the development of these features! Thank you!

[yusuf-123-3]

Every setting in rendering has this (Fastest/Faster/Fast/Average/Slow/Slower/Slowest/Custom) except rendering/camera/motion_blur/motion_blur_tile_size I feel like it breaks convention

Edit: motion_blur_tile_size does not affect performance that much

AMD Radeon RX 5700 XT - i5-11400F - 16 GB memory

Scene:
Preview Sun and Preview Environment
MeshInstance set to BoxMesh 5 meters away from camera
Camera that constantly rotates

Tile Size  20, Samples  4: 592 FPS
Tile Size 200, Samples  4: 577 FPS

Tile Size  20, Samples  8: 485 FPS
Tile Size 200, Samples  8: 455 FPS

Tile Size  20, Samples 16: 323 FPS
Tile Size 200, Samples 16: 292 FPS

Impact of increasing tile size by 10x:
4  samples, FPS drops by 15 (+0.044 ms)
8  samples, FPS drops by 30 (+0.136 ms)
16 samples, FPS drops by 31 (+0.329 ms)

[HydrogenC]

It's mostly probable that the problem is caused by network failure in the midst of rebase. It's pretty tricky and I find it difficult to make a fix. So I squashed the commits to solve the problem. Now at least it returns normal, at a cost of losing detailed commits (they are backed up on another branch though).

[AThousandShips]

Make sure to use git rebase to update the branch and to push with git push --force and this won't happen

[HydrogenC]

Make sure to use git rebase to update the branch and to push with git push --force and this won't happen

I was using the Github App GUI to do the rebase, and it left a mess if the network fails in the middle. 😞

[allenwp]

Docs not yet written, since the API itself may be subject to change during review.

When looking at a PR for the first time, I like to review the newly exposed public facing API by simply looking at the docs files to see what was added. Would it be possible to run doctool to generate the docs? There’s no need to fill in these docs with any final text, but just the empty stubs would make it much easier to, at a glance, see what this new feature adds to Godot’s API. By leaving the generated docs empty or similar, it will be clear to reviewers that this part simply hasn’t been finished yet.

[HydrogenC]

When looking at a PR for the first time, I like to review the newly exposed public facing API by simply looking at the docs files to see what was added. Would it be possible to run doctool to generate the docs? There’s no need to fill in these docs with any final text, but just the empty stubs would make it much easier to, at a glance, see what this new feature adds to Godot’s API. By leaving the generated docs empty or similar, it will be clear to reviewers that this part simply hasn’t been finished yet.

@AR-DEV-1 Will you take this when you have time?

[sphynx-owner]

@AR-DEV-1 the latest commit seems broken. Roque curly brackets.

[zhangjiangen11]

It feels like this excellent plugin is finally nearing completion, and the revival of HDDAGI is just around the corner.

[Saul2022]

It feels like this excellent plugin is finally nearing completion, and the revival of HDDAGI is just around the corner.

Ye though a bit off topic , but keep expectation low for hddagi , nothing can be sure at all until there’s a new pr or some progress being shown.

[allenwp]

One of the main reasons for a feature PR to be merged is that the feature cannot be implemented as a plugin or there are substantial compromises to implementing it as a plugin.

In the description, I see a mention that performance should be better with this PR compared to the plugin, but it would be good to see some real world and benchmark performance comparisons between this PR and the plugin to demonstrate how substantial the performance gains are. This will help validate that this PR is worth the long term maintenance cost.

It would also be good to have this PR's description list and detail any other improvements or benefits to having this feature added to Godot compared to what was possible with the plugin. These will, again, help demonstrate why the long term maintenance of the feature is truly required and cannot be handled by a plugin.

[AThousandShips]

Let's stay on topic

[AR-DEV-1]

File formatting & etc, failing. Will format them

[Jamsers]

Oh my, only noticed this PR today, you're the man @HydrogenC! Unfortunately busy with my day job but as soon as I'm able, I'm gonna get around to testing this PR thoroughly! ❤️

Regarding motion blur in the editor, IIRC in Unreal motion blur is rendered in editor, I think their reasoning is that it can affect how things like animations and camera pans look for example and you'd ideally wanna see how they look without having to run your game. However, in Unity, it's not rendered in editor. Ideally of course a project option that allows you to chose would be best.

Regarding the full suite of options @sphynx-owner has implemented in the plugin, I think for an initial motion blur implementation into core, just the core, fundamental effect should be the priority. Once that's done, we can then implement things like framerate independent motion blur, camera/object separated motion blur, ect, as additional PRs afterwards. I think this is also more in line with how features/enhancements are generally tackled with Godot development?

[HydrogenC]

Regarding the full suite of options @sphynx-owner has implemented in the plugin, I think for an initial motion blur implementation into core, just the core, fundamental effect should be the priority. Once that's done, we can then implement things like framerate independent motion blur, camera/object separated motion blur, ect, as additional PRs afterwards.

Yeah, the current status is that all of these additional and advanced stuff are actually already implemented in this PR. Now the problem is that the number of parameters is above the number that keeps the effect simple so we have to scale them down (which means that the hardcoded parameters will possibility never be added back as configurable ones).

[sphynx-owner]

I personally believe that the current implementation is complete and coherent. There is still some discussion around the tile size property that needs resolving, but given the documentation I added we should be on the same page on what the different proeprties mean at least.

[hsvfan-jan]

I think for an initial motion blur implementation into core, just the core, fundamental effect should be the priority.

Once that's done, we can then implement things like [...] camera/object separated motion blur

I think these are key features that shouldn't be stripped out of this PR. I hope the maintainers won't decide to remove them for the "initial" implementation.

What parameters will be configurable by users can and should be discussed and stripped down if it makes sense, but since motion blur is mostly an artistic tool, I'd argue, it should be treated as such (instead of only a tool to smoothen things out for 30fps games) since not all games will need the same look.