[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 sorted hot reload and nitpicks from one of your previous messages. Hot reload now works for non-instanced and instaned objects (to do that, we're keeping one of the original objects that is being instanced in the scene, so the behavior lifecycle can keep reading the updated property values and pass them to the instanced groups). Everything works per my previous message.

Did not get to your "Use a life-cycle function to step" comment yet.

Updated the extension so you can have a look if something is not to GDevelop standards.

[D8H]

Hello, I didn't look at your changes yet since I wanted to give you back a version as soon as possible.

This is the changes I've made:

• Add actions to configure the wind (using scene variable)
• Call UpdateFoliageSwaying every frame using these variable
• Split SetWindGust into actions to configure the wind gust (relying on the cache JS object)

I hope I didn't break anything. Feel free to improve my changes.

I only attached the project file since I haven't change any resource.

• Project file: Nature Elements Git Demo.zip

[baldieandbaldie-commits]

@D8H @4ian
A quick update on the latest:

• tested all the actions D8H created (thanks!) and everything seems in order
• fixed a pesky bug that was affecting wind direction/angle
• updated the extension description and images so users better know what to expect and how to use it (both on GitHub and in the extension)
• through description, provided links to diferent gust maps so users don't have to create one (still, a basic one is generated on runtime)
• added D8H as an author due to his contribution
• updated the final version to GitHub

Updating the demo tomorrow... Let me know if there's something else that needs to get done.

[baldieandbaldie-commits]

@D8H @4ian demo updated as well.

[D8H]

I think we're closing in on a first release. I wrote a lot, but this is because I tried to be exhaustive this time.

• Property "technical" names should be clear for users because if you want to allow events to access them one day, the generated expressions will take the same names.
  • There shouldn't be 1 letter prefixes to workaround the alphabetical sort (at some point, properties will be displayed in the "right" order)
  • Abbreviations should be avoided because what is obvious for tech-arts probably isn't for beginners ("grad", "poly" and "sat")
  • Technical terms like "UV" are ok since it's what people should search on the web.
  • They shouldn't be too long if possible (they currently aren't too long)
  • They should start with an uppercase for consistency with other extensions from the repository.
  • If you have other projects that use this extension that you want to migrate, the easiest way is to rename the properties in these projects too before updating the extension because the editor automatically rename them in the scene objects.
• Property groups shouldn't be prefixed by a number (the order from the tree will be used at some point)
• Do you think it could be useful to modify some property values by events?
  • It may allow users to do a quality setting menu.
  • Actions and expressions can be generated from the property tree.
• In which ways is "Custom PBR" feature related to this extension?

I have a few questions about the descriptions:

• What is the unit of "wind speed"? Is it pixels per seconds?
• How do the "wind strength" value impact the model? Is it the maximal distance a vertex can move?
• What does "Gradient start/end" means? Is it a ratio of the object depth?
• What do the "wind gust threshold" mean? Is it compared to a 0-1 value of the red channel?
• What does "Poly scale" do? Does it add sub vertices?

Thanks for your patience and good work.

[baldieandbaldie-commits]

@D8H Let me first answer some of your questions quickly, and gonna get to everything else in a bit...

• Custom PBR
  It’s not directly part of wind simulation. It exists because the foliage shader patches materials, so this gives users control over how patched foliage reacts to lighting (for example, you can make leaves look wet like in the rain). It came from testing normal maps and front/back face lighting (grass typically has issues with that), then got expanded. Had it initially under advanced settings, but upon testing it seemed to work well so I included it as a generic feature.

• Wind speed
  It's not pixels/second. It’s an animation speed/frequency multiplier for the sway/gust waves.

• Wind strength
  An amplitude multiplier. It affects how far vertices can move, but the final distance also depends on tip mask, poly scale, sway type, and gust.

• Gradient start/end
  This is what enables users to color their foliage, basically modifying the texture color. That way their 3D models can only have albedo textures and their model can be reused with different colors alltogether. Depending on settings, it uses either UV vertical direction or world/object vertical height. For example, foliage is typicaly burnt by the sun near the top, so more yellow than at its lower parts. Textures alone can't handle that well for foliage, so gradient solve this.

• Wind gust threshold
  Yes, it is compared against a 0–1 texture sample value, currently the red channel/noise value.

• Polyscale
  It does not add vertices. It is a sway response multiplier used to make different mesh densities/sizes bend more consistently. The issue with models is that their complexity can vary, so Polyscale lets the user set how strongly the model should respond to sway. I have built in "auto polyscale" that tries to detect that on its own (if the user leaves its value at 0). It helps, but it's not always perfect.

[baldieandbaldie-commits]

@D8H did a revision per your comments - no more prefixes or abrevations. Fingers crossed that property and group ordering arrives soon 🤞🏻

I also changed internal naming convention to align with your comments. And although it's not user-facing, you mentioned previously that it's important for maintainers to be able to get around, so there it is.

As I changed the property names, everything was updated clearly except for the property options (in my case sway types and culling mode values). Not sure if that's a limitation or a bug, soI tweaked it in the original JSON file.

Tested it, albeit not as thoroughly, and updated the extension. Will update the demo shortly.

Let me know what's next.

EDIT: Demo updated as well.

[D8H]

I think the extension is good to go. Congrats for making this great extension!

• The extension name "NatureElements" is a bit generic.
  • What do you think about using the same name as the behavior "FoliageSwaying3D"?

I made some description changes:

• Extension description
  • Removed the "how to" section. It was only telling to add the behavior and use actions which is not specific to this extension.
  • Removed the "nice to have" section. Listing features that don't exist will make the search give wrong results.
• Behavior description
  • It now starts with a verb.
• Shorter property groups

Modified extension: NatureElements.zip

[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.