Merge branch 'jMonkeyEngine:master' into capdevon-TestReverb

Author: capdevon

.github/workflows/screenshot-test-comment.yml

@@ -0,0 +1,117 @@
+name: Screenshot Test PR Comment
+
+# This workflow is designed to safely comment on PRs from forks
+# It uses pull_request_target which has higher permissions than pull_request
+# Security note: This workflow does NOT check out or execute code from the PR
+# It only monitors the status of the ScreenshotTests job and posts comments
+# (If this commenting was done in the main worflow it would not have the permissions
+# to create a comment)
+
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  monitor-screenshot-tests:
+    name: Monitor Screenshot Tests and Comment
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    permissions:
+      pull-requests: write
+      contents: read
+    steps:
+      - name: Wait for GitHub to register the workflow run
+        run: sleep 15
+
+      - name: Wait for Screenshot Tests to complete
+        uses: lewagon/wait-on-check-action@v1.3.1
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          check-name: 'Run Screenshot Tests'
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          wait-interval: 10
+          allowed-conclusions: success,skipped,failure
+      - name: Check Screenshot Tests status
+        id: check-status
+        uses: actions/github-script@v6
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const { owner, repo } = context.repo;
+            const ref = '${{ github.event.pull_request.head.sha }}';
+
+            // Get workflow runs for the PR
+            const runs = await github.rest.actions.listWorkflowRunsForRepo({
+              owner,
+              repo,
+              head_sha: ref
+            });
+
+            // Find the ScreenshotTests job
+            let screenshotTestRun = null;
+            for (const run of runs.data.workflow_runs) {
+              if (run.name === 'Build jMonkeyEngine') {
+                const jobs = await github.rest.actions.listJobsForWorkflowRun({
+                  owner,
+                  repo,
+                  run_id: run.id
+                });
+
+                for (const job of jobs.data.jobs) {
+                  if (job.name === 'Run Screenshot Tests') {
+                    screenshotTestRun = job;
+                    break;
+                  }
+                }
+
+                if (screenshotTestRun) break;
+              }
+            }
+
+            if (!screenshotTestRun) {
+              console.log('Screenshot test job not found');
+              return;
+            }
+
+            // Check if the job failed
+            if (screenshotTestRun.conclusion === 'failure') {
+              core.setOutput('failed', 'true');
+            } else {
+              core.setOutput('failed', 'false');
+            }
+      - name: Find Existing Comment
+        uses: peter-evans/find-comment@v3
+        id: existingCommentId
+        with:
+          issue-number: ${{ github.event.pull_request.number }}
+          comment-author: 'github-actions[bot]'
+          body-includes: Screenshot tests have failed.
+
+      - name: Comment on PR if tests fail
+        if: steps.check-status.outputs.failed == 'true'
+        uses: peter-evans/create-or-update-comment@v4
+        with:
+          issue-number: ${{ github.event.pull_request.number }}
+          body: |
+            🖼️ **Screenshot tests have failed.** 
+
+            The purpose of these tests is to ensure that changes introduced in this PR don't break visual features. They are visual unit tests.
+
+            📄 **Where to find the report:**
+            - Go to the (failed run) > Summary > Artifacts > screenshot-test-report
+            - Download the zip and open jme3-screenshot-tests/build/reports/ScreenshotDiffReport.html
+
+            ⚠️ **If you didn't expect to change anything visual:** 
+            Fix your changes so the screenshot tests pass.
+
+            ✅ **If you did mean to change things:** 
+            Review the replacement images in jme3-screenshot-tests/build/changed-images to make sure they really are improvements and then replace and commit the replacement images at jme3-screenshot-tests/src/test/resources.
+
+            ✨ **If you are creating entirely new tests:** 
+            Find the new images in jme3-screenshot-tests/build/changed-images and commit the new images at jme3-screenshot-tests/src/test/resources.
+
+            **Note;**  it is very important that the committed reference images are created on the build pipeline, locally created images are not reliable. Similarly tests will fail locally but you can look at the report to check they are "visually similar".
+
+            See https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-screenshot-tests/README.md for more information
+          edit-mode: replace
+          comment-id: ${{ steps.existingCommentId.outputs.comment-id }}

gradle.properties

@@ -1,5 +1,5 @@
 # Version number: Major.Minor.SubMinor (e.g. 3.3.0)
-jmeVersion = 3.8.0
+jmeVersion = 3.9.0
 
 # Leave empty to autogenerate
 # (use -PjmeVersionName="myVersion" from commandline to specify a custom version name )

jme3-core/src/main/java/com/jme3/audio/Filter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2020 jMonkeyEngine
+ * Copyright (c) 2009-2025 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -35,9 +35,12 @@
 import com.jme3.export.JmeImporter;
 import com.jme3.export.Savable;
 import com.jme3.util.NativeObject;
+import com.jme3.util.clone.Cloner;
+import com.jme3.util.clone.JmeCloneable;
+
 import java.io.IOException;
 
-public abstract class Filter extends NativeObject implements Savable {
+public abstract class Filter extends NativeObject implements Savable, JmeCloneable {
 
     public Filter() {
         super();
@@ -49,12 +52,28 @@ protected Filter(int id) {
 
     @Override
     public void write(JmeExporter ex) throws IOException {
-        // nothing to save
+        // no-op
     }
 
     @Override
     public void read(JmeImporter im) throws IOException {
-        // nothing to read
+        // no-op
+    }
+
+    /**
+     *  Called internally by com.jme3.util.clone.Cloner.  Do not call directly.
+     */
+    @Override
+    public Object jmeClone() {
+        return super.clone();
+    }
+
+    /**
+     * Called internally by com.jme3.util.clone.Cloner. Do not call directly.
+     */
+    @Override
+    public void cloneFields(Cloner cloner, Object original) {
+        // no-op
     }
 
     @Override

jme3-core/src/main/java/com/jme3/audio/Listener.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2012 jMonkeyEngine
+ * Copyright (c) 2009-2025 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -34,6 +34,11 @@
 import com.jme3.math.Quaternion;
 import com.jme3.math.Vector3f;
 
+/**
+ * Represents the audio listener in the 3D sound scene.
+ * The listener defines the point of view from which sound is heard,
+ * influencing spatial audio effects like panning and Doppler shift.
+ */
 public class Listener {
 
     private final Vector3f location;
@@ -42,72 +47,159 @@ public class Listener {
     private float volume = 1;
     private AudioRenderer renderer;
 
+    /**
+     * Constructs a new {@code Listener} with default parameters.
+     */
     public Listener() {
         location = new Vector3f();
         velocity = new Vector3f();
         rotation = new Quaternion();
     }
 
+    /**
+     * Constructs a new {@code Listener} by copying the properties of another {@code Listener}.
+     *
+     * @param source The {@code Listener} to copy the properties from.
+     */
     public Listener(Listener source) {
-        location = source.location.clone();
-        velocity = source.velocity.clone();
-        rotation = source.rotation.clone();
-        volume = source.volume;
+        this.location = source.location.clone();
+        this.velocity = source.velocity.clone();
+        this.rotation = source.rotation.clone();
+        this.volume = source.volume;
+        this.renderer = source.renderer; // Note: Renderer is also copied
     }
 
+    /**
+     * Sets the {@link AudioRenderer} associated with this listener.
+     * The renderer is responsible for applying the listener's parameters
+     * to the audio output.
+     *
+     * @param renderer The {@link AudioRenderer} to associate with.
+     */
     public void setRenderer(AudioRenderer renderer) {
         this.renderer = renderer;
     }
 
+    /**
+     * Gets the current volume of the listener.
+     *
+     * @return The current volume.
+     */
     public float getVolume() {
         return volume;
     }
 
+    /**
+     * Sets the volume of the listener.
+     * If an {@link AudioRenderer} is set, it will be notified of the volume change.
+     *
+     * @param volume The new volume.
+     */
     public void setVolume(float volume) {
         this.volume = volume;
-        if (renderer != null)
-            renderer.updateListenerParam(this, ListenerParam.Volume);
+        updateListenerParam(ListenerParam.Volume);
     }
 
+    /**
+     * Gets the current location of the listener in world space.
+     *
+     * @return The listener's location as a {@link Vector3f}.
+     */
     public Vector3f getLocation() {
         return location;
     }
 
+    /**
+     * Gets the current rotation of the listener in world space.
+     *
+     * @return The listener's rotation as a {@link Quaternion}.
+     */
     public Quaternion getRotation() {
         return rotation;
     }
 
+    /**
+     * Gets the current velocity of the listener.
+     * This is used for Doppler effect calculations.
+     *
+     * @return The listener's velocity as a {@link Vector3f}.
+     */
     public Vector3f getVelocity() {
         return velocity;
     }
 
+    /**
+     * Gets the left direction vector of the listener.
+     * This vector is derived from the listener's rotation.
+     *
+     * @return The listener's left direction as a {@link Vector3f}.
+     */
     public Vector3f getLeft() {
         return rotation.getRotationColumn(0);
     }
 
+    /**
+     * Gets the up direction vector of the listener.
+     * This vector is derived from the listener's rotation.
+     *
+     * @return The listener's up direction as a {@link Vector3f}.
+     */
     public Vector3f getUp() {
         return rotation.getRotationColumn(1);
     }
 
+    /**
+     * Gets the forward direction vector of the listener.
+     * This vector is derived from the listener's rotation.
+     *
+     * @return The listener's forward direction.
+     */
     public Vector3f getDirection() {
         return rotation.getRotationColumn(2);
     }
 
+    /**
+     * Sets the location of the listener in world space.
+     * If an {@link AudioRenderer} is set, it will be notified of the position change.
+     *
+     * @param location The new location of the listener.
+     */
     public void setLocation(Vector3f location) {
         this.location.set(location);
-        if (renderer != null)
-            renderer.updateListenerParam(this, ListenerParam.Position);
+        updateListenerParam(ListenerParam.Position);
     }
 
+    /**
+     * Sets the rotation of the listener in world space.
+     * If an {@link AudioRenderer} is set, it will be notified of the rotation change.
+     *
+     * @param rotation The new rotation of the listener.
+     */
     public void setRotation(Quaternion rotation) {
         this.rotation.set(rotation);
-        if (renderer != null)
-            renderer.updateListenerParam(this, ListenerParam.Rotation);
+        updateListenerParam(ListenerParam.Rotation);
     }
 
+    /**
+     * Sets the velocity of the listener.
+     * This is used for Doppler effect calculations.
+     * If an {@link AudioRenderer} is set, it will be notified of the velocity change.
+     *
+     * @param velocity The new velocity of the listener.
+     */
     public void setVelocity(Vector3f velocity) {
         this.velocity.set(velocity);
-        if (renderer != null)
-            renderer.updateListenerParam(this, ListenerParam.Velocity);
+        updateListenerParam(ListenerParam.Velocity);
+    }
+
+    /**
+     * Updates the associated {@link AudioRenderer} with the specified listener parameter.
+     *
+     * @param param The {@link ListenerParam} to update on the renderer.
+     */
+    private void updateListenerParam(ListenerParam param) {
+        if (renderer != null) {
+            renderer.updateListenerParam(this, param);
+        }
     }
 }