Refactor collision detection: CameraCollider interface + SceneCameraCollider

Agent-Logs-Url: https://github.com/jMonkeyEngine/jmonkeyengine/sessions/0532228e-79c6-460d-b67d-1b8d6f455024

Co-authored-by: riccardobl <4943530+riccardobl@users.noreply.github.com>

Author: Copilot

jme3-core/src/main/java/com/jme3/input/CameraCollider.java

@@ -0,0 +1,70 @@
+/*
+ * Copyright (c) 2009-2024 jMonkeyEngine
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ *   notice, this list of conditions and the following disclaimer.
+ *
+ * * Redistributions in binary form must reproduce the above copyright
+ *   notice, this list of conditions and the following disclaimer in the
+ *   documentation and/or other materials provided with the distribution.
+ *
+ * * Neither the name of 'jMonkeyEngine' nor the names of its contributors
+ *   may be used to endorse or promote products derived from this software
+ *   without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package com.jme3.input;
+
+import com.jme3.math.Vector3f;
+
+/**
+ * Interface for camera collision detection used by {@link ChaseCamera}.
+ * Implementations determine how the chase camera interacts with the scene
+ * when there is geometry between the target and the camera.
+ *
+ * <p>A {@code CameraCollider} receives the target's world position and the
+ * desired camera position, and may adjust the camera position in-place to
+ * prevent it from clipping through geometry.</p>
+ *
+ * <p>The built-in implementation is {@link SceneCameraCollider}, which uses
+ * ray-casting against one or more scene {@link com.jme3.scene.Node Nodes}.
+ * Custom implementations can integrate with physics engines or any other
+ * collision system.</p>
+ *
+ * @see ChaseCamera#setCameraCollider(CameraCollider)
+ * @see SceneCameraCollider
+ */
+public interface CameraCollider {
+
+    /**
+     * Adjusts the camera position to avoid passing through scene geometry.
+     *
+     * <p>Implementations should test for obstructions between
+     * {@code targetPosition} and {@code camPosition} and, if any are found,
+     * update {@code camPosition} in-place so that the camera stays in front of
+     * the obstruction.</p>
+     *
+     * @param targetPosition the world position of the chase camera's target
+     *                       (read-only)
+     * @param camPosition    the desired camera position before collision
+     *                       adjustment; updated in-place with the adjusted
+     *                       position if a collision is detected
+     */
+    void collide(Vector3f targetPosition, Vector3f camPosition);
+}

jme3-core/src/main/java/com/jme3/input/ChaseCamera.java

@@ -31,19 +31,15 @@
  */
 package com.jme3.input;
 
-import com.jme3.collision.CollisionResult;
-import com.jme3.collision.CollisionResults;
 import com.jme3.export.InputCapsule;
 import com.jme3.export.JmeExporter;
 import com.jme3.export.JmeImporter;
 import com.jme3.input.controls.*;
 import com.jme3.math.FastMath;
-import com.jme3.math.Ray;
 import com.jme3.math.Vector3f;
 import com.jme3.renderer.Camera;
 import com.jme3.renderer.RenderManager;
 import com.jme3.renderer.ViewPort;
-import com.jme3.scene.Node;
 import com.jme3.scene.Spatial;
 import com.jme3.scene.control.Control;
 import com.jme3.util.clone.Cloner;
@@ -143,11 +139,7 @@ public class ChaseCamera implements ActionListener, AnalogListener, Control, Jme
 
     protected boolean zoomin;
     protected boolean hideCursorOnRotate = true;
-    protected boolean checkCollision = false;
-    protected Node collisionNode = null;
-    protected float collisionMinDistance = 0.1f;
-    private final CollisionResults collisionResults = new CollisionResults();
-    private final Ray collisionRay = new Ray();
+    protected CameraCollider cameraCollider = null;
 
     /**
      * Constructs the chase camera
@@ -532,8 +524,8 @@ protected void updateCamera(float tpf) {
                 //computing the position
                 computePosition();
                 //checking for collision with the environment
-                if (checkCollision && collisionNode != null) {
-                    checkCameraCollision();
+                if (cameraCollider != null) {
+                    cameraCollider.collide(target.getWorldTranslation(), pos);
                 }
                 //setting the position at last
                 cam.setLocation(pos.addLocal(lookAtOffset));
@@ -544,8 +536,8 @@ protected void updateCamera(float tpf) {
                 distance = targetDistance;
                 computePosition();
                 //checking for collision with the environment
-                if (checkCollision && collisionNode != null) {
-                    checkCameraCollision();
+                if (cameraCollider != null) {
+                    cameraCollider.collide(target.getWorldTranslation(), pos);
                 }
                 cam.setLocation(pos.addLocal(lookAtOffset));
             }
@@ -1024,102 +1016,31 @@ public Vector3f getUpVector() {
     }
 
     /**
-     * Checks for collisions between the camera and the collision node.
-     * If a collision is detected along the ray from the target to the
-     * computed camera position, the camera is moved to
-     * {@code collisionMinDistance} units in front of the collision point
-     * to prevent clipping through geometry.
-     */
-    protected void checkCameraCollision() {
-        Vector3f targetPos = target.getWorldTranslation();
-        // Direction from target to computed camera position
-        Vector3f camDir = pos.subtract(targetPos);
-        float maxDist = camDir.length();
-        if (maxDist < FastMath.ZERO_TOLERANCE) {
-            return;
-        }
-        camDir.normalizeLocal();
-        collisionRay.setOrigin(targetPos);
-        collisionRay.setDirection(camDir);
-        collisionRay.setLimit(maxDist);
-
-        collisionResults.clear();
-        collisionNode.collideWith(collisionRay, collisionResults);
-
-        if (collisionResults.size() > 0) {
-            CollisionResult closest = collisionResults.getClosestCollision();
-            float collisionDist = closest.getDistance();
-            if (collisionDist < maxDist) {
-                // Place camera just in front of the collision point
-                float adjustedDist = Math.max(collisionDist - collisionMinDistance, 0);
-                pos.set(targetPos).addLocal(camDir.mult(adjustedDist));
-            }
-        }
-    }
-
-    /**
-     * Returns whether camera collision detection with the environment is enabled.
+     * Returns the {@link CameraCollider} used to prevent the camera from
+     * passing through scene geometry, or {@code null} if collision detection
+     * is disabled (the default).
      *
-     * @return true if collision detection is enabled, false otherwise (default=false)
+     * @return the current camera collider, or {@code null}
      */
-    public boolean isCheckCollision() {
-        return checkCollision;
+    public CameraCollider getCameraCollider() {
+        return cameraCollider;
     }
 
     /**
-     * Enables or disables camera collision detection with the environment.
-     * When enabled, the camera will not pass through geometry in the
-     * collision node. This feature is disabled by default.
+     * Sets the {@link CameraCollider} that will be used to prevent the camera
+     * from passing through scene geometry. Set to {@code null} (the default)
+     * to disable collision detection.
      *
-     * @param checkCollision true to enable collision detection, false to disable
-     * @see #setCollisionNode(Node)
-     */
-    public void setCheckCollision(boolean checkCollision) {
-        this.checkCollision = checkCollision;
-    }
-
-    /**
-     * Returns the node used for camera collision detection.
-     *
-     * @return the collision node, or null if none is set
-     */
-    public Node getCollisionNode() {
-        return collisionNode;
-    }
-
-    /**
-     * Sets the node to use for camera collision detection.
-     * When the chase camera has collision detection enabled, it will cast
-     * a ray from the target to the camera position and stop the camera
-     * before any geometry in this node.
-     *
-     * @param collisionNode the node to collide with (alias created), or null to disable
-     * @see #setCheckCollision(boolean)
-     */
-    public void setCollisionNode(Node collisionNode) {
-        this.collisionNode = collisionNode;
-    }
-
-    /**
-     * Returns the minimum distance to maintain between the camera and a
-     * collision point when collision detection is enabled.
-     *
-     * @return the minimum distance (in world units, default=0.1)
-     */
-    public float getCollisionMinDistance() {
-        return collisionMinDistance;
-    }
-
-    /**
-     * Sets the minimum distance to maintain between the camera and a
-     * collision point when collision detection is enabled. The camera will
-     * be placed this far in front of any detected collision.
+     * <p>The built-in {@link SceneCameraCollider} supports ray-casting against
+     * one or more scene nodes with optional per-geometry exclusion via
+     * userData. Custom implementations can integrate with physics engines or
+     * any other collision system.</p>
      *
-     * @param collisionMinDistance the desired minimum distance (in world units,
-     * default=0.1)
+     * @param cameraCollider the collider to use, or {@code null} to disable
+     * @see SceneCameraCollider
      */
-    public void setCollisionMinDistance(float collisionMinDistance) {
-        this.collisionMinDistance = collisionMinDistance;
+    public void setCameraCollider(CameraCollider cameraCollider) {
+        this.cameraCollider = cameraCollider;
     }
 
     public boolean isHideCursorOnRotate() {