Feature/backgdrop occluder (#941)

Author: srcimon

UNRELEASED-CHANGES.md

@@ -1,15 +1,25 @@
 ### 🚀 Features & improvements
 
-- ...
+- Added backdrop occluder shadows (#937)
+- `RopeOccluderComponent` adds a backdrop shadow to ropes
+- `SoftBodyOccluderComponent` adds a backdrop shadow to soft bodies
+- Allow double value strokeWidth for drawing polygons
+- Added `Polygon.stroked(double)`, `.moveTo(Vector)` and `.fromBounds(Bounds)`
+- Added functions to `Line`: `.expand(double)`, `.isLeft(Vector)`, `.isRight(Vector)` and `.contains(Vector)`
+- Rendering non smoothed ropes
+- Added `Vector.normalize()`
 
 ### 🪛 Bug Fixes
 
 - Fixed fast repeating sequence generated by `FastRandom` (#939)
+- Fixed missing segment when drawing polygon outline
+- Fixed rendering polygon and line stroke width not scaling with zoom
+- Fixed light going to occluder edges
 
 ### 🧽 Cleanup & refactoring
 
-- ...
+- Moved path creation to `AwtMapper`
 
 ### 📦 Dependency updates
 
-- ...
+- Bump JUnit to 6.0.3

docs/blog/2026-02-16-illumination-reworked.md

@@ -0,0 +1,28 @@
+---
+title: Illumination reworked
+authors: [ srcimon ]
+tags: [ new-features, milestones ]
+---
+
+Hello everyone,
+
+the last three versions of ScrewBox put huge effort to improve the game illumination:
+
+The overall performance was improved significantly by improving the speed of the internally used image filters and
+algorithms.
+The blurring filter is now 20-30% faster and supports higher blur values for even smoother visuals.
+The time consumed for image opacity inversion was reduced by a staggering 98%.
+
+This increased throughput allows for higher-quality shadow maps and heavier shadow blurring without sacrificing frame
+rates.
+
+![occluders.png](../docs/guides/soft-physics/occluders.png)
+
+I have introduced new directional light source and backdrop occluders:
+
+- Directional light easily simulate natural illumination like sunlight.
+- Backdrop occluders create shadows directly on the background behind objects.
+  Backdrop occluders work in perfect harmony with soft physics entities.
+  The shadows add a new level of immersion to these entities.
+
+<!-- truncate -->

docs/docs/core-modules/graphics/index.md

@@ -267,6 +267,7 @@ The following types of lights and occluders are supported:
 | point light       | a radial light source that will be affected by occluders                                            |
 | spot light        | a radial light source that won't be affected by occluders                                           |
 | directional light | light source that emitts light from from a line                                                     |
+| backdrop occluder | area that cast shadows on the background                                                            |
 | occluder          | area that cast shadows and also can block lights when rendered on top                               |
 | orthographic wall | an orthographic wall that can be illuminated but will cast shadows (used in common rpg perspective) |
 | area light        | a area light effect                                                                                 |

docs/docs/guides/soft-physics/index.md

@@ -157,4 +157,14 @@ cloth.root().add(new ClothRenderComponent(), x -> {
 
 // attach the top border of the flag to the game world 
 cloth.topBorder().forEach(entity -> entity.remove(PhysicsComponent.class));
-```
+```
+
+## Illumination
+
+Soft physics objects also support creating backdrop shadows using the `RopeOccluderComponent` and `SoftBodyOccluderComponent`.
+Because cloth soft bodies also contain a `SoftBodyComponent` they can also make use of the `SoftBodyOccluderComponent`.
+
+Backdrop shadows are quite expensive and should be used with performance in mind, but the effect might be worth it.
+To reduce the performance impact disable the rounding effect in the `ShadowOptions`.
+
+![occluders3.png](occluders.png)

docs/docs/guides/soft-physics/occluders.png

@@ -115,6 +115,8 @@ Get a more inside from the [ropes guide](../guides/soft-physics).
 | `SoftStructureComponent`     | Links one entity to multiple others with flexible links. Used to create flexible structures.            |
 | `RopeComponent`              | Used to mark the start of a rope.                                                                       |
 | `RopeRenderComponent`        | Renders ropes when added to entity also containing a `RopeComponent`.                                   |
+| `RopeOccluderComponent`      | Adds a backdrop shadow to a rope.                                                                       |
+| `SoftBodyOccluderComponent`  | Adds a backdrop shadow to a soft body.                                                                  |
 | `ClothComponent`             | Used to mark the root node of a soft body cloth.                                                        |
 | `ClothRenderComponent`       | Adds rendering using mesh shading of soft bodies with a `ClothComponent`.                               |
 | `SoftBodyComponent`          | Used to mark a chain or loop of entities as a soft body.                                                |
@@ -173,6 +175,7 @@ To use these components call `environment.enableLight()` first.
 | `ConeGlowComponent`         | Adds a cone glow at the entity position.                                                     |
 | `OrthographicWallComponent` | Marks entity as orthographic wall that will only be illuminated from below and cast shadows. |
 | `OccluderComponent`         | Adds shadow casting from the entity bounds.                                                  |
+| `BackdropOccluderComponent` | Adds backdrop shadow casting from the entity bounds.                                         |
 | `StaticOccluderComponent`   | Optimizes performance by combining occluder components that won't move.                      |
 
 ## Particle components

docs/docs/reference/components-overview.md

@@ -3,9 +3,9 @@
 import dev.screwbox.core.Bounds;
 import dev.screwbox.core.Percent;
 import dev.screwbox.core.assets.Asset;
-import dev.screwbox.core.environment.importing.Blueprint;
 import dev.screwbox.core.environment.Entity;
 import dev.screwbox.core.environment.core.TransformComponent;
+import dev.screwbox.core.environment.importing.Blueprint;
 import dev.screwbox.core.environment.light.OccluderComponent;
 import dev.screwbox.core.environment.physics.ColliderComponent;
 import dev.screwbox.core.environment.physics.CollisionSensorComponent;
@@ -27,7 +27,7 @@ public Entity assembleFrom(GameObject object) {
                 .add(new RenderComponent(SPRITE, object.layer().order()))
                 .add(new TransformComponent(Bounds.atPosition(object.position(), 48, 12)))
                 .add(new CollisionSensorComponent(), sensor -> sensor.range = 1)
-                .add(new OccluderComponent(false), x -> x.expand = -2)
+                .add(new OccluderComponent(false))
                 .add(new MovingPlatformComponent(object.properties().getInt("waypoint"), speed));
     }
 

examples/platformer/src/main/java/dev/screwbox/platformer/props/Platfom.java

@@ -1,6 +1,7 @@
 package dev.screwbox.playground;
 
 import dev.screwbox.core.Angle;
+import dev.screwbox.core.Duration;
 import dev.screwbox.core.Engine;
 import dev.screwbox.core.Percent;
 import dev.screwbox.core.ScrewBox;
@@ -12,10 +13,12 @@
 import dev.screwbox.core.environment.core.LogFpsSystem;
 import dev.screwbox.core.environment.core.TransformComponent;
 import dev.screwbox.core.environment.importing.ImportOptions;
+import dev.screwbox.core.environment.light.BackdropOccluderComponent;
 import dev.screwbox.core.environment.light.DirectionalLightComponent;
 import dev.screwbox.core.environment.light.OccluderComponent;
 import dev.screwbox.core.environment.light.PointLightComponent;
 import dev.screwbox.core.environment.light.StaticOccluderComponent;
+import dev.screwbox.core.environment.physics.ChaoticMovementComponent;
 import dev.screwbox.core.environment.physics.ColliderComponent;
 import dev.screwbox.core.environment.physics.CollisionDetailsComponent;
 import dev.screwbox.core.environment.physics.CollisionSensorComponent;
@@ -24,9 +27,16 @@
 import dev.screwbox.core.environment.physics.PhysicsComponent;
 import dev.screwbox.core.environment.physics.StaticColliderComponent;
 import dev.screwbox.core.environment.rendering.RenderComponent;
+import dev.screwbox.core.environment.softphysics.RopeOccluderComponent;
+import dev.screwbox.core.environment.softphysics.RopeRenderComponent;
+import dev.screwbox.core.environment.softphysics.SoftBodyOccluderComponent;
+import dev.screwbox.core.environment.softphysics.SoftBodyRenderComponent;
+import dev.screwbox.core.environment.softphysics.SoftPhysicsSupport;
 import dev.screwbox.core.graphics.Color;
 import dev.screwbox.core.graphics.Sprite;
+import dev.screwbox.core.graphics.options.ShadowOptions;
 import dev.screwbox.core.utils.TileMap;
+import dev.screwbox.playground.misc.InteractionSystem;
 
 import static dev.screwbox.core.Vector.$;
 
@@ -39,13 +49,18 @@ public static void main(String[] args) {
             .move($(40, 40))
             .setZoom(4);
         engine.loop().unlockFps();
+
         engine.graphics().configuration().setLightQuality(Percent.half());
         var map = TileMap.fromString("""
                O   O
             P  # ###    ##
-            #     ## O
-                      O  ##
-            ###    ######
+            #   RRR## O
+              T       O  ##
+            
+            
+            
+            
+            ############    ######
             """);
         engine.environment()
             .enableAllFeatures()
@@ -66,22 +81,41 @@ public static void main(String[] args) {
                     .add(new StaticColliderComponent())
                     .add(new RenderComponent(Sprite.placeholder(Color.GREY, 16)))
                 )
+                .assignComplex('T', (tile, idPool) -> {
+                    var body = SoftPhysicsSupport.createSoftBody(tile.bounds().expand(-2), idPool);
+                    body.root().add(new SoftBodyRenderComponent(Color.ORANGE.opacity(0.5)), r -> r.outlineColor = Color.ORANGE);
+                    body.root().add(new SoftBodyOccluderComponent(ShadowOptions.rounded().backdropDistance(0.4).distortion(Percent.of(0.04))));
+                    body.forEach(node -> node.get(PhysicsComponent.class).friction = 2);
+                    body.forEach(node -> node.add(new LeftRightControlComponent()));
+                    body.forEach(node -> node.add(new JumpControlComponent()));
+                    return body;
+                })
+                .assignComplex('R', (tile, idPool) -> {
+                    var rope = SoftPhysicsSupport.createRope(tile.position().addY(tile.size().height() / -2.0), tile.position().addY(20), 9, idPool);
+                    rope.forEach(node -> node.get(PhysicsComponent.class).friction = 2);
+                    rope.forEach(node -> node.add(new ChaoticMovementComponent(400, Duration.ofMillis(800))));
+                    rope.root()
+                        .add(new RopeOccluderComponent(ShadowOptions.angular().backdropDistance(0.45)))
+                        .add(new RopeRenderComponent(Color.WHITE, 1.25))
+                        .remove(PhysicsComponent.class);
+                    return rope;
+                })
                 .assign('P', tile -> new Entity().bounds(tile.bounds().expand(-8))
-                    .add(new StaticOccluderComponent())
-                    .add(new OccluderComponent(false))
                     .add(new PhysicsComponent(), p -> p.friction = 3)
                     .add(new LeftRightControlComponent())
+                    .add(new BackdropOccluderComponent(ShadowOptions.angular().backdropDistance(0.75)))
                     .add(new JumpControlComponent(), j -> j.acceleration = 300)
                     .add(new CollisionSensorComponent())
                     .add(new CollisionDetailsComponent())
                     .add(new SuspendJumpControlComponent(), s -> s.maxJumps = 2)
                     .add(new RenderComponent(Sprite.placeholder(Color.YELLOW, 8)))))
             .addEntity(new Entity().add(new GravityComponent(Vector.y(500))))
             .addSystem(new LogFpsSystem())
-            .addEntity(new Entity().add(new TransformComponent()).add(new CursorAttachmentComponent()).add(new PointLightComponent(80, Color.BLACK)))
-            .addEntity(new Entity().bounds(map.bounds().expand(1000)).add(new DirectionalLightComponent(), d -> d.angle = Angle.degrees(-10)))
+            .addSystem(new InteractionSystem())
+            .addEntity(new Entity().add(new TransformComponent(0, 0, 120, 40)).add(new CursorAttachmentComponent()).add(new PointLightComponent(60, Color.BLACK)))
             .addSystem(e -> e.environment().tryFetchSingletonComponent(DirectionalLightComponent.class).ifPresent(d -> d.angle = Angle.degrees(e.mouse().position().x() / 4)))
-            .addSystem(e -> e.graphics().canvas().fillWith(Color.BLUE));
+            .addSystem(e -> e.graphics().canvas().fillWith(Color.BLUE))
+            .addSystem(e -> e.graphics().camera().setZoom(e.graphics().camera().zoom() + e.mouse().unitsScrolled() / 10.0));
 
         engine.start();
     }

examples/playground/src/main/java/dev/screwbox/playground/PlaygroundApp.java

@@ -71,7 +71,7 @@
             <dependency>
                 <groupId>org.junit</groupId>
                 <artifactId>junit-bom</artifactId>
-                <version>6.0.2</version>
+                <version>6.0.3</version>
                 <type>pom</type>
                 <scope>import</scope>
             </dependency>

pom.xml

@@ -251,11 +251,55 @@ public Line move(final Vector movement) {
     }
 
     /**
-     * Sets the length to the specified value.
+     * Sets the length to the specified value. Moves only the {@link #end()}.
      *
      * @since 3.22.0
      */
     public Line length(final double distance) {
         return Line.between(start, start.add(end.substract(start).length(distance)));
     }
+
+    /**
+     * Expands the lenght of the line in both directions.
+     *
+     * @since 3.23.0
+     */
+    public Line expand(final double length) {
+        final var delta = end.substract(start);
+        final var x = delta.x() / delta.length() * length * 0.5;
+        final var y = delta.y() / delta.length() * length * 0.5;
+        return Line.between(start.add(-x, -y), end.add(x, y));
+    }
+
+    /**
+     * Return {@code true} if position is left of line.
+     *
+     * @since 3.23.0
+     */
+    public boolean isLeft(final Vector position) {
+        return calculateShoelaceOf(position) < 0;
+    }
+
+    /**
+     * Return {@code true} if position is right of line.
+     *
+     * @since 3.23.0
+     */
+    public boolean isRight(final Vector position) {
+        return calculateShoelaceOf(position) > 0;
+    }
+
+    /**
+     * Return {@code true} if position is on the line
+     *
+     * @since 3.23.0
+     */
+    public boolean contains(final Vector position) {
+        return calculateShoelaceOf(position) == 0;
+    }
+
+    private double calculateShoelaceOf(final Vector position) {
+        return (end.x() - start.x()) * (position.y() - start.y()) -
+               (end.y() - start.y()) * (position.x() - start.x());
+    }
 }