[Experimental] [3D foliage swaying] Sway foliage of 3D objects according to wind

[github-actions]

Description

This extension adds wind swaying ability and optional GPU instancing to 3D objects (trees, grass, bushes) with frustum and distance culling.

Features:

• Real-time foliage wind animation for 3D scenes
• Multiple sway types: Grass, Bush, Tree Trunk (dead tree), and Tree Leaves (more coming soon)
• Works with both regular meshes and GPU-instanced foliage for better performance
• Global wind controls: strength, speed, and wind direction
• Optional gust system with texture-driven gust masks
• Optional visual tuning: gradient tint, saturation/contrast, PBR tweaks
• Distance-based fading/culling for better performance
• Automatic foliage shader/material patching (including shadow materials)
• Runtime-safe live updates for wind/gust parameters
• Scene/object cleanup logic to reduce memory leaks and stale resources
  
  

Comes with:

• Foliage swaying behavior — sets parameters for individual 3D foliage object (grass, tree, bush)
• Wind sway actions — sets/updates wind parameters (optional)
• Wind gust actions — sets/updates wind gust parameters (optional)
  
  

How to use the extension:

1. Import your 3D object (tree, bush, grass...) and add the Foliage swaying behavior to it.

2. Choose from various object settings and parameters, then add the object to your scene.
   
   

3. Optionally set general wind and gust parameters at the beginning of the scene. If not, default values will be used.
   
   

4. Play your scene.
   
   

Current limitations, issues, and guidelins:

• Collision is not yet supported for GPU instanced objects but is planned.

• The mesh complexity auto-detection (Polyscale parameter) is not perfect and can produce inconsistent sway intensity across assets. If you encounter overly strong or weak sways, experiment with the Polyscale value to make your asset's sway consistent. Use the debug option to find the auto-selected value, then increase or decrease it.

• Foliage material auto-detection works well and can usually be left empty, but there are edge cases with multi-material objects. If you don't have access to the source file of your 3D object, you can find your object's material name using the debug option in object's Foliage swaying behavior.

• The optional wind gust texture can create natural-looking gusts and is worth creating. If not, one will be automatically created. To make one yourself, use only black and red colors (black will be ignored and red will be the actual gust map). For the best results, create a tileable 512x512 image or download one of the examples below. 01 / 02 / 03 / 04
  
  

• Hot reload supports all basic behavior property changes, excluding Sway settings (Material to sway, Sway type, Enable uniform sway toggle) and Distance culling, Debug output, GPU instancing, and Custom PBR settings toggles. However, if PBR settings are enabled as you start the preview, changes to specific PBR values will be updated on hot-reload.
  
  

Future nice-to-haves:

• More swaying types
• Polygon-based foliage scattering
• Collision for instanced objects
• Split camera culling vs shadow caster culling to avoid frustum edge cases (mostly early shadow pop-outs for instanced objects)
• Rewrite shader swaying logic to eliminate PolyScale completely
• Basic LOD system
• Further optimize shader math
  
  

Checklist

• I've followed all of the best practices.
• I confirm that this extension can be integrated to this GitHub repository, distributed and MIT licensed.
• I am aware that the extension may be updated by anyone, and do not need my explicit consent to do so.

Example file

FoliageSwaying3D.zip (1.0.6)

Extension file

FoliageSwaying3D.zip (1.0.6)

---

Extension by @baldieandbaldie-commits

You can update the extension on this "Pull Request" by commenting the update command: in the comment field, type !update, then drag and drop a zip file with your extension file in the commenting field, like how you initially submitted the extension. It should look like this:

!update [MyExtension.zip](https://github.com/GDevelopApp/GDevelop-extensions/files/12709661/MyExtension.zip)

It can take a few seconds for the file to fully upload and show as the above. Once it is like shown above, click "Comment" and let the bot do the rest!

[D8H]

Thank you for submitting an extension. The result looks impressive.

The code is quite big. Does it come from a library or did you wrote it specifically for this extension?

• If it comes from a library, you can add a link to its repository to help maintainers update it in the future.
• If you wrote it specifically for this extension, it would be great to add type annotations ("JSDoc", using notes like @typedef, @param or @type) to at least functions and global variables (or make it a lib if it's more convenient).
  • The editor doesn't remember type declarations set in one JS-event in other JS events, so you may find it easier to have the whole code in one place (for instance the 3D particle emitter extension has a library + dedicated code inside the DefineHelperClasses function)

A few suggestions from a quick look:

• gdjs should be use as the global scope instead of window or even runtimeScene if it makes sense to reset the state at scene changes.
• You don't need to surround your code with a function, this is already part of JS-events.

(function (runtimeScene, eventsFunctionContext) {
})(runtimeScene, eventsFunctionContext);

Let me know if this makes sense and if you can make these changes or part of it. This will help update the extension when new GDevelop versions are released.

[4ian]

Tried it and it looks very very cool. It's a big extension but let's see if we can get it inside the experimental extensions!

[baldieandbaldie-commits]

@D8H @4ian Thanks folks. The code was specifically created for this extension. Your comments make a lot of sense. Give me some time and I'll update as much as possible with your comments in mind.

[baldieandbaldie-commits]

!update NatureElements.zip

[github-actions]

Extension updated with errors:

❌ 1 Error found in extension 'NatureElements':

  ⟶ ❌ [JavaScript disallowed properties]: JavaScript usage of the extension 'NatureElements' must be checked by the reviewer:
{
  allowedProperties: [
    'makeUuid',
    'rgbToHex',
    'rgbOrHexToRGBColor',
    'rgbToHexNumber',
    'hexNumberToRGB',
    'hexToRGBColor',
    'rgbOrHexStringToNumber',
    'hexNumberToRGBArray',
    'copyArray',
    'staticArray',
    'staticArray2',
    'staticObject',
    'toDegrees',
    'toRad',
    'random',
    'randomFloat',
    'randomFloatInRange',
    'randomInRange',
    'randomWithStep',
    'evtTools',
    'Variable',
    'RuntimeObject',
    'Logger'
  ],
  disallowedProperty: '__foliageSway',
  objectName: 'gdjs'
}
{
  allowedProperties: [
    'getVariables',
    'getLayer',
    'getGame',
    'getBackgroundColor',
    'getName',
    'createObject',
    'createObjectsFrom',
    'setBackgroundColor',
    'sceneJustResumed',
    'requestChange',
    'hasLayer',
    'enableDebugDraw'
  ],
  disallowedProperty: 'getTimeManager',
  objectName: 'runtimeScene'
}


❌ 1 Error found in extensions - please fix it before generating the registry.
No fatal error found the extension can be updated but still need fixes.

[D8H]

Hello, just to make sure, are you waiting for feedback or are you still working on the extension?

[baldieandbaldie-commits]

Hello, just to make sure, are you waiting for feedback or are you still working on the extension?

I've done the refactoring per your comments. Tried updating a few days ago but got an error (again). See here

Currently traveling, but I'll give it another go later today. Got a nice new demo as well.

[D8H]

Actually, this is not an error, your update came though, you can see the commit above.
The reviewer will update a file to list which engine features the extension uses.

[baldieandbaldie-commits]

@D8H awesome! I'll update the demo as well in a bit. It uses the incorrect extension version anyways.

[4ian]

Again, looks awesome. Give us a few days to see how we can get this in the experimental extensions :)

[baldieandbaldie-commits]

Again, looks awesome. Give us a few days to see how we can get this in the experimental extensions :)

Thanks, @4ian ! I'm in no rush :) Altho I'd love to swap in a better, more custom-tailored demo (example file).

[D8H]

This preference has been added recently and it might help you:

[baldieandbaldie-commits]

This preference has been added recently and it might help you:

@D8H Thanks!

[baldieandbaldie-commits]

@D8H JS type errors fixed. Updated the extension file.

[4ian]

Is the demo/example file up to date on your first message, or are you working on it separately?

[baldieandbaldie-commits]

Is the demo/example file up to date on your first message, or are you working on it separately?

@4ian File was too large to upload via GitHub. I’ll clean it up in the next few days. For now, I updated the demo with a Dropbox link.

EDIT: Got the Demo down to 40 MB but was unable to replace it, getting "failed to upload" error. Dropbox link updated with the smaller file.

[D8H]

Some of the variables are typed with Object or any. This won't really help avoiding mistakes or for the autocompletion.
This documentation section should help you to attach your features to gdjs. As you can see in the code block from the doc, class and function are declared locally and added to gdjs at the end. This allows you to get a bit of autocompletion directly and improve it by adding type annotations on the classes and functions declarations.

• https://wiki.gdevelop.io/gdevelop5/events/js-code/javascript-in-extensions/#embed-javascript-libraries-in-extensions

THREE.TextureLoader shouldn't be used directly because it won't work if the resource name is not a valid path. You can get the Texture of a resource like this:

runtimeScene.getGame().getImageManager().getThreeTexture(resourceName);

Feel free to ask if something is unclear.

[4ian]

For the demo keep it on Dropbox and we'll import it in the GDevelop-examples repository when the time is good.

"Time is good" is a bit vague, but in my mind we should aim for:

• As much types as possible (though I understand sometimes it feels complicated for nothing... let's try our best).
• Using runtimeScene.getGame().getImageManager().getThreeTexture (this seems like an important step otherwise we'll get issue with people using this and the object/extension breaking when they rename a resource or change it).

For type annotations, I'm wondering though if we should really do something to allow extension to have "extension wide" types (so that you would get autocompletions in every single code block in the extension). We'll have to think about it...

[baldieandbaldie-commits]

@D8H @4ian Easter feedback... that takes some real dedication 😅 I'll get to it!

[baldieandbaldie-commits]

@D8H @4ian Extension updated, based on your guidance.

• Moved the shared helper/runtime code to a gdjs namespace and kept mutable state on runtimeScene, following the extension pattern from the docs
• Removed the previous direct THREE.TextureLoader path for gust textures and now resolve project textures through GDevelop’s image manager
• Tightened the JSDoc typing across the shared runtime/state boundaries and replaced broad typing with narrower bridge types where the runtime is dynamic
• Also cleaned up comments so they match the current architecture
• And updated JSON and Dropbox Demo

Let me know if this is what you had in mind, and if there's anything else to tackle.

[D8H]

I didn’t have much time to check so I just have a few questions:

• About getBehaviorSafe, what kind of issues lead you to these try-catch?
  • I guess this section should help: https://wiki.gdevelop.io/gdevelop5/events/js-code/javascript-in-extensions/#get-an-object-behavior-in-javascript
• Why do use the unknown type?
• Is there any reason for not declaring any class in the code?
• Why do you start the code with ;(function() {?
• About FoliageRuntimeObjectBridge type, I guess that gdjs.RuntimeObject3D will be easier to understand for maintainers.
• If you want, you can click on the sentence on top click here to choose objects to pass object to JavaScript instead of eventsFunctionContext.getObjects("Object")

It’s probably not worth sending an updating. I can continue checking the current version.

[baldieandbaldie-commits]

• About getBehaviorSafe, what kind of issues lead you to these try-catch?

  • I guess this section should help: https://wiki.gdevelop.io/gdevelop5/events/js-code/javascript-in-extensions/#get-an-object-behavior-in-javascript

The try-catch was defensive, mostly because the behavior identifier changed during refactors. This can be simplified now.

• Why do use the unknown type?

Can you let me know if once a behavior property type is defined in the editor, is its runtime JS type guaranteed to match it exactly? If so, I can tighten several unknown types. Used it just as a stricter boundary type while replacing broader any / Object typing.

• Is there any reason for not declaring any class in the code?

No particular architectural reason. If there is a preferred GDevelop-side convention for classes, I can adapt to it. Let me know.

• Why do you start the code with ;(function() {?

Simply as a defensive IIFE wrapper. Not strictly required, but felt like a safe pattern. I'll remove it.

• About FoliageRuntimeObjectBridge type, I guess that gdjs.RuntimeObject3D will be easier to understand for maintainers.

Agreed.

• If you want, you can click on the sentence on top click here to choose objects to pass object to JavaScript instead of eventsFunctionContext.getObjects("Object")

Somehow I have completely missed this 🙈 Perhaps a call for a UI upgrade? 🙃

It’s probably not worth sending an updating. I can continue checking the current version.

Let me know what else you find, and I'll revise it all at once.

[D8H]

To give you a view of what we're trying to do:

• the first step and my main priority is to make the code easier to navigate for reviewers and maintainers (hence why a lot of my comments related to this)
• and then we can discuss ways to improve user-friendlyness

This is not necessarily a long process, just explaining my reasoning. I might be able to help doing some changes at some point.

Simply as a defensive IIFE wrapper. Not strictly required, but felt like a safe pattern. I'll remove it.

If you look at the top and the bottom of an empty JS event, you will notice that the code is inside a JS function, it's not the global scope.

Somehow I have completely missed this 🙈 Perhaps a call for a UI upgrade? 🙃

Indeed, it would be better to have a button that actually look like one. It may take a while before we have the time to improve it. On that note, I added 2 sections about object and resource parameters in the doc.

No particular architectural reason. If there is a preferred GDevelop-side convention for classes, I can adapt to it. Let me know.

If you can define classes, it will help me understand which part of the code it related to which data.

Can you let me know if once a behavior property type is defined in the editor, is its runtime JS type guaranteed to match it exactly? If so, I can tighten several unknown types. Used it just as a stricter boundary type while replacing broader any / Object typing.

Most property types are either numbers or strings. Acessing _behaviorData directly may work, but there are getters like _getMyProperty that are more futur proof. Sadly, property names are case sensitive so you may have to rename them to have more readable getter names. You can learn more about them in this section of the documentation.

When I can, I try not to use these getters either. If you take a look at the 3D particle emitter extension, for each property, there are 1 action and 1 expression to access them from the main events. Their skeletons can be generated by the editor as explained at the end of this section.

In this extensions, these couples of functions are used for several purposes:

• Let extension users change the property values on the fly
• Initialize the object at creation (by passing the new value to the JS code)
• Update the object at hot-reload

The good part is that:

• If the object or behavior initialize correctly, you can expect the actions and hot-reload to also work since they rely on the same thing
• The property value is passed by the events as a parameter so if one day we need to change how property code is generated, it will continue to work

But, sometimes it's just more convenient to use _getMyProperty(). So it's not a strong rule.

[baldieandbaldie-commits]

@D8H Alright, all of this makes sense. Thanks for sharing the links also. Let me know when it's ok to do a revision - maybe befor you dive in deeper?

[baldieandbaldie-commits]

@D8H @4ian updated the extension (including name change to FoliageSwaying3D), GitHub page, example demo, and any leftover references to "Nature Elements".

Thanks for all your help, and let me know if there's anything else that needs to get done.

[4ian]

Great stuff! We should be good to ship this, we will mention it in the next update changelog (with some beautiful screenshots) and we should probably think about a lightweight example once this is shipped so more people can discover it from GDevelop itself! :)

[baldieandbaldie-commits]

Great stuff! We should be good to ship this, we will mention it in the next update changelog (with some beautiful screenshots) and we should probably think about a lightweight example once this is shipped so more people can discover it from GDevelop itself! :)

@4ian That's awesome! Let me know if you need help with that. I'd love to assist.

[D8H]

The extension should be in the extension store in a few minutes. Thanks again!

[baldieandbaldie-commits]

The extension should be in the extension store in a few minutes. Thanks again!

Let me check that off my bucket list ✅🎉
Thanks again for your help!

[Bouh]

Hi @baldieandbaldie-commits ,

The extension looks promising. I tried using it, but I have a few questions.

I made this video below showing the behavior on a bush.
You’ll notice that when the preview starts, the bush is completely deformed.
I searched through the extension description in-app but couldn’t find anything about it.

• Then I came across this GitHub page and found the “How To,” which mentions other strength and speed options. Why wasn’t this “How To” mentioned in the in-app extension description?
  So I added the actions at the start of the scene with different values because the default oness was so high, see the video for my values.

• And one last question about the gust system: I understand the purpose of using a texture as mask on the wind. I downloaded yours, but I don’t really know what to do with it, where to place it, or how I’m supposed to use the system with the texture. A dedicated “How To” for that would also help a lot.

2026-05-20.10-55-52.mp4

I think you’re quite aware of usability concerns, and it’s really important to have those “How To” guides because, with the current presentation of the extension, I need another resource (this GitHub page) to understand how to use it.

The worst part is having to search inside the app without understanding what’s going on.

[D8H]

Don't worry about @Bouh message. We'll discuss it internally and improve some property descriptions if needed on our end.

[baldieandbaldie-commits]

@D8H all good, I have no issues answering a few questions. Perhaps other folks with similar issues will find it helpful.

@Bouh the SwayResponse (previously Polyscale) is what creates this "issue". First thing you should try is to play with that setting, and make your objects sway uniformly. Then changing values for wind and gust will make more sense. Although I did try to use auto-detection for SwayResponse, the object complexity is so versatile and this is the best thing I came up with (so the value is fine-tuned manually and different for every object). If you do that, all the default settings for wind and gust should work well. Happy to explore if you think there's another, better way of doing this.

The complete description and "how-to" was a part of the extension but got removed for some reason - I assume your team has their way of doing this, as D8H suggested. I'm all for being detailed, so if the team needs anything, I'm here to help... but perhaps a detailed page is required to elaborate each of the available properties.

For wind gust, there are a bunch of actions you can use to make it to your liking. All the gust properties should already be explained in the extension, unless that got removed for some reason. The texture is not necessary (if no texture, one will be created dynamically), and it adds a specific wind "shape" so the wind doesn't look linear.

[D8H]

I put the sway properties on top to make it more obvious to users that they have to start by setting these values.

If you start working on an update one day, please click on "Re-install" first to make sure you have all the tiny adjustments we might do.

[baldieandbaldie-commits]

@D8H oh there will definitely be more work done on this... thanks for the update, will follow your instructions.

[4ian]

@baldieandbaldie-commits Hello! I was looking at the example but it's fairly heavy (easily take 15+ seconds on my macbook pro in a black screen on the first frame, probably to create all the objects). It's also fairly big at ~40MB. Do you think it would be possible to make a slightly "lighter" example?
That would help to have it part of the official GDevelop examples searchable from inside the engine. Let me know! :)

[baldieandbaldie-commits]

Do you think it would be possible to make a slightly "lighter" example?

For sure. How light does it need to be? I think I could get it down to 20MB. Perhaps even lower if we remove sounds (altho I'd hate to do that 😄 )

[baldieandbaldie-commits]

@4ian ...or were you looking for a completely new example?

[Bouh]

@4ian ...or were you looking for a completely new example?

@baldieandbaldie-commits

You can reduce the terrain size using the Decimate modifier in Blender.

• Skybox textures can be saved as JPGs with lower quality. PNG includes an alpha channel that isn't useful here, and 1536 pixels per side is also quite large.

• On some trees, I noticed overlapping vertices. I can reduce one of them from 6k vertices to 2.2k just by using Merge by Distance. Make sure to do this everywhere, because visually the asset remains the same, but it's much heavier than necessary due to the excessive vertex count.

• For audio files, especially the .wav files, run them through a site like freeconvert.com. You can reduce a file from 8177 KB to 1 KB.

After all that, if the example is still taking too long to load, then the issue is no longer asset loading. At that point, it will likely be the time required to generate the grass.

[baldieandbaldie-commits]

@Bouh thanks, I'm familiar with all of this, except for the overlapping vertices on the trees - they are a free asset pack widely used, so I'm surprised this is the case. I did optimise the file size earlier, but guess I still wanted things to be visually too perfect, hence the file size. So I'll follow these instructions and do a superlightweight example to the best of my abilities, altho the visuals will be compromised - still, it's better to have a real example up to GDevelop's standards people can learn from.

That said, the slow load I believe is happening not because of the file size, but because in order to make the extension work properly, GDevelop objects need to be created in the scene first, then destroyed as they are being instanced. Usually objects are placed manually so this can happen much quicker (there's no creating them), but for my testing purposes I scattered them via script (created > instanced > destroyed).

Anyhow, I'll hop onto this and try to do a few tests that could speed things up further. Thanks for your help!

[CrowbarCoder]

Hi @baldieandbaldie-commits,
I was wondering are the assets for the trees, bushes and grass in the example for public domain use, and who made them, or do I need to credit? I'm thinking of using in my game template.
Thanks!
Crowbar Coder

[baldieandbaldie-commits]

Hi @baldieandbaldie-commits, I was wondering are the assets for the trees, bushes and grass in the example for public domain use, and who made them, or do I need to credit? I'm thinking of using in my game template. Thanks! Crowbar Coder

They're from Stylized Nature MegaKit (standard tier) by the great Quaternius. Assets are under CC0 license.

[CrowbarCoder]

Oh thats great so I can use them in my game commercially.

[baldieandbaldie-commits]

@4ian @D8H @Bouh The example has been shrunk down and the Dropbox file updated. The project file size is now 9.7 MB, including the 1.2 MB autosave file that I forgot to remove 😄

Roughly, here is what I’ve done:

• reduced total number of 3D models used from 30 to 11
• optimized images and textures for all 3D models
• optimized all sounds
• (re)checked that all assets are under a CC0 license

As I suspected previously, file size optimization does not have a significant impact on scene loading time after the preloader. The issue lies in the scattering script, which was never meant to go into “production”, but I used it to avoid placing hundreds of thousands of objects manually.

For now, I have not changed this script because the plan is to supplement this extension with a custom action that will scatter and instance foliage across polygonal areas. It will hopefully be able to instance millions of objects in the blink of an eye. That’s my next larger task.

That said, for the sake of getting the example out to users, I’ve done this little trick that makes the scene load in 3 seconds instead of 15 (after the preloader).

If this is good enough for you, feel free to use the updated Dropbox file.

Let me know if there’s anything else you feel needs tweaking.