⚠️ If you receive a black screen or a warning when using the WithThreeJS extension in GDevelop v5.3 or later, please see this page.
About the warning "Please add an Enable WithThreeJS object to a scene."

🎉 WithThreeJs is now on the GDevelop Community Extensions!

Distribution of the latest version may take some time. The version currently distributed by the community is 2.0.2. (old 😢)

WithThreeJS Extension for GDevelop

Extension for GDevelop to create simple 3D scenes.
This extension is intended for easy and simple 3D rendering. It does not currently aim for realistic 3D rendering.

💎 Feature

3D Features	WithThreeJS	Built-in 3D
Editor integration	⛅	🌞
3D Collision detection	🌞	🌞 (Extension)
3D Raycast	🌞	🌞 (Extension)
3D Light	🌞	🌞 (My extension)
3D Shadow	🌞	🌞 (My extension)
3D Sound	🌞	☔
3D Background image	🌞	🌞 (My extension)
3D Sprite animation	🌞	🌞 (Extension)
3D Particles	☔	🌞 (Extension)
3D Physics engine	☔	☔
Multiple 3D Cameras	🌞	☔
Grouping 3D Objects	🌞	☔
Parent-child structure	🌞	☔
3D Helpers	🌞	🌞 (My extension)
Post effect	☔	⛅
Supported 3D formats	GLB, OBJ	GLB

📖 How to use

Import the downloaded "WithThreeJS0.0.0.json" file into your project.

There is no manual at this time. Please refer to the following video.

ℹ️ For more information about Behaviors, see "About Behaviors" below.

📺 Please subscribe to my YouTube channel.

There are more videos on my YouTube channel.

Difference between GDevelop axes and 3D Scene axes

Difference between GDevelop units and 3D scene units.

GDevelop units are pixels and 3D scene units are meters.

Camera shooting direction

The camera shoots in the local negative Z axis direction.

About Behaviors.

This extension comes with very powerful behaviors.

The various projection behaviors project 2D objects onto 3D objects. When you create or move a 2D object, the 3D object changes in the same way.

• 3D Sprite Projection Behavior
• 3D Board Projection Behavior
• 3D Plane Projection from Tiled Sprite Behavior
• 3D Box Projection from Tiled Sprite Behavior
• Linked 3D Camera Behavior
• Linked 3D Light Behavior

The features supported by behaviors vary. Please also check the summary below.

ℹ️ Many various 3D actions have no effect on objects using behaviors. Because the 2D object values take precedence.
ℹ️ Do not add more than one of these behaviors to an object.

Please refer to the following video.

About 3D Custom Objects

This extension comes with custom objects.
Custom Objects are similar to Projection Behaviors, but support different features.

• 3D Box Custom Object
• Enable WithThreeJS Custom Object

Please also check the summary below.

About using GLB Model

👣 Where did the "Create 3D Model From Built-In 3D Model" action go?

With an updated GDevelop interface, the action now appears when you select a 3D model.

⚠️ 3D models often have a parent-child structure. Therefore, if you want to use Bounding Box Collision, you need to know the ID (name) of the mesh that has the bounding box in advance.
The simplest solution is to add the 3D Model as a child of the 3D Box.

About importing OBJ files

It has some rules and restrictions.

• Open the OBJ file in a text editor and copy/paste the contents into GDevelop.
• The 3D model must contain UV mapping.
• Texture is required. No MTL files are used, so no material colors are applied.
• For models with multiple materials, specify the textures in GDevelop in that order. (Because of this limitation, it is not possible to set up an OBJ file where multiple models have materials in different orders)

ℹ️ Entering large OBJ strings directly into actions slows down GDevelop. I recommend using Javascript events as shown in the video.

About the Alpha Channel Test

From v0.3.2, "Alpha Channel Test" can be set in "Create 3D Sprite", "Create 3D Plane", "Create 3D Model" and "3D Sprite Projection".
This is a non-rendered transparency reference value.

0 to 1 (Recommended values: 0 or 0.5)

ℹ️ If the texture is opaque, you can set the value to 0 to reduce the drawing load.

About Skybox

To enable Skybox, you need to set an equirectangular image with a 2:1 aspect ratio.

Euler angle problem

As this image shows, you may not always get the values you expect from the rotation.

There is more than one way to represent any given rotation using XYZ (Euler angles). Comparing just one of the XYZ values of a rotation can be confusing.

The simplest solution is to use different variables for each XYZ to manage the rotation. Please refer to "Simple FPS Example" or "Third-person Perspective Example".

For more information on this problem, you may want to search for explanations of Euler and Quaternion by Unity, Unreal Engine, etc.

About 3D Lights

ℹ️ 3D Sprite do not support 3D Lights.
ℹ️ Lighting and drop shadows are different features.

How to enable 3D Shadows

1. Darken the Ambient Light Color of the 3D Scene.
2. Check "Cast Shadow" of 3D Light.
3. Check "Cast Shadow" for the 3D Object that casts a shadow.
4. Check "Receive Shadow" of the 3D Object that receives the shadow.
5. Adjust the 3D Light shadow settings.

This extension provides real-time shadows.
Real-time shadowing is a heavy process. Therefore, it is recommended to minimize the shadow generation range.
It is a good idea to move the light along with the camera so that shadows are generated only where necessary.

ℹ️ 3D Sprite do not support 3D Shadows.
ℹ️ Many game engines often use pre-baked shadows and real-time shadows together, but with this extension it is difficult to use baked shadows and real-time shadows together due to limitations of Three.js.

For examples of adjusting 3D light properties, see this page.

Bounding Box Collision and Oriented Bounding Box Collision

ℹ️ Note that the Oriented Bounding Box is generated based on the unrotated state of the 3D object.

📂 Examples project file

"WithThreeJsExtensionExamples0.0.0.zip" is the examples project.
Open "game.json" in GDevelop.

List of examples included in the project.

• Basic Example (Using Behaviors)
• Basic Example (Using Actions)
• 3D Box With Multiple Textures Example
• GLB vs OBJ
• Loading Large OBJ Format Example
• Platformer Example
• Classic FPS Example
• Background and Fog Example
• Various Billboard Samples
• 8 Direction Character Example
• Bounding Box Collision Example
• 3D Raycast Example [UPDATE! 2.1.0]
• Simple Ground Check Example
• Point on Camera Example [UPDATE! 2.1.0]
• Alpha Channel Test Samples
• Opacity Blend Samples
• Dungeon Example
• Remove 3D Object Example
• Simple Effect Example
• Effect Material Samples
• Simple FPS Example
• Parent-child Relationship Example
• Third-person Perspective Example
• 3D Sound Example
• Multiple Camera Example
• GLB Model Animation Example
• Light Example
• 3D Object Variable Example
• Futuristic Racing Example
• Shadow Example

📃 Summary

ℹ️ The "Projection Scale" and "View Mode" properties that affect Behavior can be set in the "Create 3D Scene" action.

3D Sprite Projection Behavior

Supported: position, animation, flip, scale, opacity, blend mode

• [Expression]
  • Alpha Channel Test
• [String Expression]
  • 3D Object ID

3D Board Projection Behavior

Supported: position, angle, animation, flip, scale, opacity, blend mode

• [Expression]
  • Alpha Channel Test
• [String Expression]
  • 3D Object ID
  • Axis linked to 2D Object Angle
  • Orientation

3D Plane Projection from Tiled Sprite Behavior

Supported: position, angle, image offset, opacity, (blend mode)

• [Expression]
  • Alpha Channel Test
• [String Expression]
  • 3D Object ID
  • Blend Mode

3D Box Projection from Tiled Sprite Behavior

Supported: position, angle, image offset, opacity, (blend mode)

• [Expression]
  • Depth
  • Alpha Channel Test
• [String Expression]
  • 3D Object ID
  • Blend Mode

Linked 3D Camera Behavior

Supported: position, angle

• [Expression]
  • 3D Camera ID
  • Field Of View

Linked 3D Light Behavior

Supported: position, angle

• [Expression]
  • Tilt
• [String Expression]
  • 3D Object ID
  • Type

3D Box Custom Object

The 3D Box can have different textures on its 6 faces.
Supported: position, angle, opacity, (blend mode)
⚠️ This object is high load.

• [Expression]
  • Depth
• [String Expression]
  • 3D Object ID

Enable WithThreeJS Custom Object

This custom object always enables built-in 3D rendering.
Click here for instructions on how to use it.

Function

• 3D Scene
  • [Action]
    • Create 3D Scene
    • Clear 3D Scene
    • Load 3D Texture
    • Load 3D Model From OBJ
• 3D Object
  • [Action]
    • Create 3D Sprite
    • Create 3D Plane
    • Create 3D Box
    • Create 3D Model
    • Create 3D Model From Built-In 3D Model
    • Create 3D Group
    • Move 3D Object
    • Move 3D Object On World
    • Rotate 3D Object
    • Rotate 3D Object Like Head
    • Rotate 3D Object On World
    • Look At 3D Object
    • Look At 3D Camera
    • Remove 3D Object
    • Change 3D Texture
    • Change 3D Object Visibility
    • Change 3D Object Opacity
    • Change 3D Object Scale
    • Change 3D Object DepthWrite
    • Change 3D Object All Animations Speed Scale
    • Change 3D Object Blend Mode
    • Change 3D Object Raycast Detection [NEW! 2.1.0]
    • Resolve Bounding Box Collision
    • Add Child
    • Detach From Parent
    • Set 3D Object ID Of Children To Scene Variable (Deprecated)
    • Set 3D Object ID Of Children To Variable
    • Play 3D Animation
    • Stop 3D Animation
    • Set number to 3D Object Variable
    • Set string to 3D Object Variable
    • Linearly interpolate 3D Object
    • Add Suffix To 3D Object ID
    • Set 3D Object Shadow
  • [Expression]
    • 3D Object Position
    • 3D Object Position On World
    • 3D Object Rotation
    • 3D Object Rotation On World
    • 3D Object Direction
    • 3D Object Opacity
    • 3D Object Scale
    • 3D Object Animation Speed Scale
    • 3D Object Animation Time
    • 3D Object Animation Duration
    • 3D Object Number Variable
    • 3D Object String Variable
    • Distance From 3D Object To 3D Object
    • Bounding Box Collision Result Number
  • [String Expression]
    • 3D Object Parent
  • [Condition]
    • Check Existence Of 3D Object
    • Check Visibility Of 3D Object
    • Check Bounding Box Collision
    • Check 3D Animation Is Playing
    • Check 3D Animation Is Finished
    • Check Oriented Bounding Box Collision
    • Check 3D Object Is Within 3D Camera FOV [NEW! 2.1.0]
• 3D Camera
  • [Action]
    • Move 3D Camera
    • Rotate 3D Camera
    • Rotate 3D Camera On World
    • Rotate 3D Camera Like Head
    • 3D Camera Look At 3D Object
    • Change 3D Camera FOV
    • Change 3D Camera Near
    • Change 3D Camera Far
    • Change 3D Camera Zoom
    • Setup Multiple 3D Cameras
    • Linearly interpolate 3D Camera
  • [Expression]
    • 3D Camera Position
    • 3D Camera Rotation
    • 3D Camera Direction
    • Distance From 3D Camera To 3D Object
    • 3D Camera FOV
    • 3D Camera Near
    • 3D Camera Far
    • 3D Camera Zoom
    • Point Of 3D Object On 3D Camera
    • Point Of World Position On 3D Camera
• 3D Sound
  • [Action]
    • Play 3D Sound
    • Stop 3D Sound
    • Change Master Volume Of 3D Scene
  • [Expression]
    • Master Volume Of 3D Scene
  • [Condition]
    • Check 3D Sound Is Playing
• 3D Light
  • [Action]
    • Create 3D Light
• 3D Raycast
  • [Action]
    • Raycast
    • Raycast From 3D Camera
    • Raycast From 3D Object
    • Place 3D Object Using Raycast Result
  • [Expression]
    • Raycast Result Count
    • Raycast Result Number
  • [String Expression]
    • Raycast Result String
• 3D Debug
  • [Action]
    • Create 3D Axes Helper [UPDATE! 2.1.0]
    • Update Bounding Box Helper [UPDATE! 2.1.0]
    • Output 3D Model Information To Console
    • Output All IDs To Console

💖 Recommended 3D Software

• MagicaVoxel
• Blockbench
• Sprytile (addon for Blender)

👾 Games created with this extension

Bomb Poi Poi

gd.games

Haunted Shadow House

gd.games

Time Trial 3D

gd.games (Liluo.io) / Google Play

🔗 Three.js

Copyright 2010-2023 Three.js Authors
https://github.com/mrdoob/three.js/blob/dev/LICENSE

🍩 Donation

In the future I would like to add many features to this extension. (e.g. particle system, physics, etc.)
However, developing this extension requires a lot of time.
Currently, I'm doing development in between jobs, but if many people support me, I will be able to devote more time to the development.
If you enjoy this extension, please consider downloading the Example project file to maintain this extension. (The Example project file will surely help you.😉)