Skip to content

Extension update: <3D Sprite> #1957

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
github-actions wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Extension update: <3D Sprite> #1957

github-actions wants to merge 1 commit into from

Conversation

@github-actions
Copy link
Contributor

@github-actions github-actions bot commented Dec 16, 2025

Changes

Bug Fixes

Fixed Sudden Background Appearance Issue

  • Resolved rendering artifacts where backgrounds would suddenly appear or flash during sprite rendering
  • Improved depth buffer management with proper depthWrite, depthTest, and depthFunc settings
  • Added polygon offset (polygonOffsetFactor: -1, polygonOffsetUnits: -1) to prevent z-fighting between overlapping surfaces
  • Enhanced alpha testing with alphaTest: 0.5 threshold to eliminate semi-transparent pixel artifacts
  • Implemented premultiplied alpha blending for cleaner transparency handling

JavaScript Compatibility Fix

  • Replaced optional chaining operator (?.) with traditional null checking for better compatibility with GDevelop's JavaScript runtime
  • Ensures the extension works across all GDevelop versions without syntax errors

New Features

Advanced Material System

  • Double-sided rendering - Sprites now render correctly from both front and back
  • Enhanced shadow support - Objects can now cast and receive shadows properly
  • Tone mapping integration - Improved color accuracy and lighting response
  • Fog support - Sprites properly interact with scene fog effects
  • Emissive lighting - Added subtle glow effect with configurable intensity

Dynamic Auto-Rotation System- Velocity-based pitch rotation - Sprites automatically tilt based on vertical movement speed (max 15°)

  • Velocity-based yaw rotation - Sprites lean into horizontal movement direction (max 10°)
  • Smooth interpolation - All rotations use lerp for fluid, natural motion
  • Toggle support - Can be enabled/disabled via setAutoRotation(bool)

Depth Perspective Effects

  • Distance-based scaling - Objects automatically scale down as they move further away
  • Height-based scaling - Additional scaling factor based on Y position for enhanced depth perception
  • Realistic 3D feel - Creates convincing pseudo-3D perspective in 2D scenes

Dynamic Render Ordering

  • Z-position based sorting - Automatic render order calculation using Z and Y coordinates
  • Prevents visual layering issues - Ensures sprites render in correct depth order
  • Manual depth offset - Additional control via setDepthOffset(number) method

Enhanced Control Methods

  • setDepthOffset(offset) - Manually adjust sprite depth position
  • setAutoRotation(enabled) - Toggle automatic rotation behavior on/off
  • setRotationAngle(axis, angle) - Set specific rotation angles on X, Y, or Z axis

Performance Optimizations

  • Frustum culling enabled - Off-screen objects are automatically skipped
  • Vertex color support - Added vertex color attributes for advanced rendering techniques
  • Optimized rotation order - Using YXZ order for more natural sprite orientation

Technical Improvements

  • Improved collision mask handling - Better support for custom collision shapes
  • Enhanced AABB calculations - More accurate bounding box updates
  • Material update optimization - Settings now properly sync on frame changes
  • Better shadow rendering - Separated castShadow and shadowSide controls
Image

How to use the new features

Auto Rotation

Enable dynamic tilting based on movement:

sprite3DRenderer.setAutoRotation(true);  // Enable (default)
sprite3DRenderer.setAutoRotation(false); // Disable

Manual Rotation

Set specific angles in degrees:

sprite3DRenderer.setRotationAngle('x', 45);  // Pitch
sprite3DRenderer.setRotationAngle('y', 30);  // Yaw
sprite3DRenderer.setRotationAngle('z', 90);  // Roll

Depth Offset

Adjust sprite layering:

sprite3DRenderer.setDepthOffset(10);   // Move forward
sprite3DRenderer.setDepthOffset(-10);  // Move backward
sprite3DRenderer.setDepthOffset(0);    // Reset

Automatic Features

These work automatically with no code needed:

  • Depth-based scaling (distant objects appear smaller)
  • Shadow casting and receiving
  • Improved transparency rendering
  • Z-fighting prevention

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

Sprite3DExample.zip

Extension file

Sprite3D.zip

Extension by @Carrotstudio0

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!

@github-actions github-actions bot requested a review from a team as a code owner December 16, 2025 20:49
@github-actions github-actions bot added the 🔄 Extension update An update for an existing extension label Dec 16, 2025
Bouh
Bouh reviewed Dec 17, 2025
View reviewed changes
Copy link
Member

@Bouh Bouh left a comment •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here is a first review, need probably a bit more review from the OP of the extension before a validation.

extensions/community/Sprite3D.json
Comment on lines -109 to -110
"",
" // Add a point, if necessary (Avoid recreating a point if it already exists).",
Copy link
Member

@Bouh Bouh Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Put this comment back.

extensions/community/Sprite3D.json
Comment on lines -101 to -102
"",
" // Add a polygon, if necessary (Avoid recreating a polygon if it already exists).",
Copy link
Member

@Bouh Bouh Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Put this comment back.

extensions/community/Sprite3D.json
Comment on lines +246 to +250
" // Professional visual effects",
" if (material.emissive) {",
" material.emissive = new THREE.Color(0x111111);",
" material.emissiveIntensity = 0.2;",
" }",
Copy link
Member

@Bouh Bouh Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This will override the existing material if any.
Not recommended to set these values in stone.

extensions/community/Sprite3D.json
" material.depthWrite = true;",
" material.depthTest = true;",
" material.transparent = true;",
" material.side = THREE.DoubleSide;",
Copy link
Member

@Bouh Bouh Dec 17, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

material.side = THREE.DoubleSide;",

This wasn’t the default behavior, so all previous projects using the extension will now have their sprites visible on both faces. From creator point of view if this wasn’t intended, it introduces a regression in the extension and breaks compatibility with existing projects.

extensions/community/Sprite3D.json
Comment on lines -64 to -65
" // Ensure a forward compatibility when vertexColors will be set to true",
" // in the engine to allow to tint 3D sprites.",
Copy link
Member

@Bouh Bouh Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Get back the original comments.

extensions/community/Sprite3D.json
Comment on lines +320 to +322
" setAutoRotation(enabled) {",
" this.autoRotate = enabled;",
" }",
Copy link
Member

@Bouh Bouh Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is never used?

@Carrotstudio0
Copy link

Carrotstudio0 commented Dec 17, 2025

@Bouh I have a question because I am new to GitHub. Can you tell me what I should do now? I am a little confused.

@4ian
Copy link
Collaborator

4ian commented Dec 17, 2025 •
edited
Loading

@Carrotstudio0 Please take some time to familiarize yourself with GitHub and then answer the comment. Ask an AI if needed to explain you what it is :) This won't be difficult once you are used to it.

Also please rework the description to avoid any description generated by an AI as explain in another post. AI generated descriptions are counter productive.

@Carrotstudio0
Copy link

Carrotstudio0 commented Dec 17, 2025 •
edited
Loading

@Bouh
I have made the changes, but I don't know how to send them to you (since my ability to edit is limited). What should I do?

@github-actions
Copy link
Contributor Author

github-actions bot commented Dec 17, 2025

✅ Successfully updated the extension.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@Bouh Bouh Bouh left review comments

Assignees

No one assigned

Labels

🔄 Extension update An update for an existing extension

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@Carrotstudio0 @4ian @Bouh