PhysicsSpace: alter how flags pass to update() and stepSimulation()

Author: stephengold

src/main/java/com/jme3/bullet/PhysicsSpace.java

@@ -727,8 +727,8 @@ public void update(float timeInterval) {
     }
 
     /**
-     * Update the space. This method should be invoked on the thread that
-     * created the space.
+     * Update the space, enabling the default callbacks. This method should be
+     * invoked on the thread that created the space.
      *
      * @param timeInterval the time interval to simulate (in seconds, ≥0)
      * @param maxSteps the maximum number of steps of size {@code accuracy}
@@ -737,29 +737,50 @@ public void update(float timeInterval) {
     public void update(float timeInterval, int maxSteps) {
         assert Validate.nonNegative(timeInterval, "time interval");
         assert Validate.nonNegative(maxSteps, "max steps");
-
-        boolean doEnded = false;
-        boolean doProcessed = false;
-        boolean doStarted = false;
-        update(timeInterval, maxSteps, doEnded, doProcessed, doStarted);
+        update(timeInterval, maxSteps, 0x0);
     }
 
     /**
-     * Update the space. This method should be invoked from the thread that
-     * created the space.
+     * Update the space, enabling the specified callbacks. This method should be
+     * invoked on the thread that created the space.
      *
      * @param timeInterval the time interval to simulate (in seconds, ≥0)
      * @param maxSteps the maximum number of steps of size {@code accuracy}
      * (≥1) or 0 for a single step of size {@code timeInterval}
      * @param doEnded true to enable {@code onContactEnded()} callbacks, false
-     * to skip them
+     * to skip them (default=false)
      * @param doProcessed true to enable {@code onContactProcessed()} callbacks,
-     * false to skip them
+     * false to skip them (default=false)
      * @param doStarted true to enable {@code onContactStarted()} callbacks,
-     * false to skip them
+     * false to skip them (default=false)
      */
     public void update(float timeInterval, int maxSteps, boolean doEnded,
             boolean doProcessed, boolean doStarted) {
+        int stepFlags = 0x0;
+        if (doEnded) {
+            stepFlags |= StepFlag.contactEnded;
+        }
+        if (doProcessed) {
+            stepFlags |= StepFlag.contactProcessed;
+        }
+        if (doStarted) {
+            stepFlags |= StepFlag.contactStarted;
+        }
+
+        update(timeInterval, maxSteps, stepFlags);
+    }
+
+    /**
+     * Update the space with the specified callbacks. This method should be
+     * invoked on the thread that created the space.
+     *
+     * @param timeInterval the time interval to simulate (in seconds, ≥0)
+     * @param maxSteps the maximum number of steps of size {@code accuracy}
+     * (≥1) or 0 for a single step of size {@code timeInterval}
+     * @param stepFlags the desired flags, ORed together (default=0x0)
+     * @see com.jme3.bullet.StepFlag
+     */
+    public void update(float timeInterval, int maxSteps, int stepFlags) {
         assert Validate.nonNegative(timeInterval, "time interval");
         assert Validate.nonNegative(maxSteps, "max steps");
 
@@ -769,8 +790,7 @@ public void update(float timeInterval, int maxSteps, boolean doEnded,
 
         long spaceId = nativeId();
         assert accuracy > 0f : accuracy;
-        stepSimulation(spaceId, timeInterval, maxSteps, accuracy, doEnded,
-                doProcessed, doStarted);
+        stepSimulation(spaceId, timeInterval, maxSteps, accuracy, stepFlags);
     }
 
     /**
@@ -985,7 +1005,8 @@ public void removeCollisionObject(PhysicsCollisionObject pco) {
 
     /**
      * Invoked by native code immediately after a contact manifold is destroyed.
-     * Skipped if stepSimulation() was invoked with doEnded=false.
+     * Skipped if stepSimulation() was invoked without the {@code contactEnded}
+     * flag set.
      * <p>
      * Override this method to customize how contacts are handled.
      *
@@ -1000,7 +1021,8 @@ public void onContactEnded(long manifoldId) {
     /**
      * Invoked by native code immediately after a contact point is refreshed
      * without being destroyed. Skipped for Sphere-Sphere contacts. Skipped if
-     * stepSimulation() was invoked with doProcessed=false.
+     * stepSimulation() was invoked without the {@code contactProcessed} flag
+     * set.
      * <p>
      * Override this method to customize how contacts are handled.
      *
@@ -1016,7 +1038,8 @@ public void onContactProcessed(PhysicsCollisionObject pcoA,
 
     /**
      * Invoked by native code immediately after a contact manifold is created.
-     * Skipped if stepSimulation() was invoked with doStarted=false.
+     * Skipped if stepSimulation() was invoked without the
+     * {@code contactStarted} flag.
      * <p>
      * Override this method to customize how contacts are handled.
      *
@@ -1272,6 +1295,5 @@ native private long createPhysicsSpace(
             setSpeculativeContactRestitution(long spaceId, boolean apply);
 
     native private static void stepSimulation(long spaceId, float timeInterval,
-            int maxSubSteps, float accuracy, boolean enableContactEnded,
-            boolean enableContactProcessed, boolean enableContactStarted);
+            int maxSubSteps, float accuracy, int stepFlags);
 }

src/main/java/com/jme3/bullet/StepFlag.java

@@ -0,0 +1,111 @@
+/*
+ * Copyright (c) 2026 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.bullet;
+
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.logging.Logger;
+
+/**
+ * Named flags used when stepping a {@code PhysicsSpace} simulation.
+ *
+ * @author Stephen Gold sgold@sonic.net
+ * @see com.jme3.bullet.PhysicsSpace#update(float, int, int)
+ */
+final public class StepFlag {
+    // *************************************************************************
+    // constants and loggers
+
+    /**
+     * enable {@code onContactEnded()} callbacks
+     */
+    final public static int contactEnded = 0x1;
+    /**
+     * enable {@code onContactProcessed()} callbacks
+     */
+    final public static int contactProcessed = 0x2;
+    /**
+     * enable {@code onContactStarted()} callbacks
+     */
+    final public static int contactStarted = 0x4;
+    /**
+     * message logger for this class
+     */
+    final public static Logger logger
+            = Logger.getLogger(StepFlag.class.getName());
+    // *************************************************************************
+    // constructors
+
+    /**
+     * A private constructor to inhibit instantiation of this class.
+     */
+    private StepFlag() {
+    }
+    // *************************************************************************
+    // new methods exposed
+
+    /**
+     * Generate a textual description of the specified flags.
+     *
+     * @param flags the step flags to describe, ORed together
+     * @return description (not null, may be empty)
+     */
+    public static String describe(int flags) {
+        Collection<String> flagList = new ArrayList<>(3);
+        if ((flags & contactStarted) != 0x0) {
+            flagList.add("contactStarted");
+        }
+        if ((flags & contactProcessed) != 0x0) {
+            flagList.add("contactProcessed");
+        }
+        if ((flags & contactEnded) != 0x0) {
+            flagList.add("contactEnded");
+        }
+
+        StringBuilder result = new StringBuilder(40);
+        boolean addSeparators = false;
+        for (String flagName : flagList) {
+            if (addSeparators) {
+                result.append(',');
+            } else {
+                addSeparators = true;
+            }
+            result.append(flagName);
+        }
+
+        return result.toString();
+    }
+    // *************************************************************************
+    // native private methods
+
+    native private static void generateJniHeaderFile(); // never invoked
+}

src/main/native/glue/com_jme3_bullet_PhysicsSpace.cpp

@@ -522,17 +522,14 @@ JNIEXPORT void JNICALL Java_com_jme3_bullet_PhysicsSpace_setSpeculativeContactRe
 /*
  * Class:     com_jme3_bullet_PhysicsSpace
  * Method:    stepSimulation
- * Signature: (JFIFZZZ)V
+ * Signature: (JFIFI)V
  */
 JNIEXPORT void JNICALL Java_com_jme3_bullet_PhysicsSpace_stepSimulation
 (JNIEnv *pEnv, jclass, jlong spaceId, jfloat tpf, jint maxSteps,
-        jfloat accuracy, jboolean enableContactEndedCallback,
-        jboolean enableContactProcessedCallback,
-        jboolean enableContactStartedCallback) {
+        jfloat accuracy, jint stepFlags) {
     jmePhysicsSpace * const
             pSpace = reinterpret_cast<jmePhysicsSpace *> (spaceId);
     NULL_CHK(pEnv, pSpace, "The physics space does not exist.",)
 
-    pSpace->stepSimulation(tpf, maxSteps, accuracy, enableContactEndedCallback,
-            enableContactProcessedCallback, enableContactStartedCallback);
+    pSpace->stepSimulation(tpf, maxSteps, accuracy, stepFlags);
 }

src/main/native/glue/com_jme3_bullet_PhysicsSpace.h

@@ -36,6 +36,8 @@
 #if BT_THREADSAFE
 #include "BulletDynamics/Dynamics/btDiscreteDynamicsWorldMt.h"
 #endif
+
+#include "com_jme3_bullet_StepFlag.h"
 #include "jmePhysicsSpace.h"
 #include "jmeClasses.h"
 #include "jmeUserInfo.h"
@@ -437,23 +439,20 @@ void jmePhysicsSpace::preTickCallback(btDynamicsWorld *pWorld,
 }
 
 void jmePhysicsSpace::stepSimulation(jfloat timeInterval, jint maxSteps,
-        jfloat accuracy, jboolean enableContactEndedCallback,
-        jboolean enableContactProcessedCallback,
-        jboolean enableContactStartedCallback) {
-
-    if ((bool) enableContactEndedCallback) {
+        jfloat accuracy, jint stepFlags) {
+    if (stepFlags & com_jme3_bullet_StepFlag_contactEnded) {
         gContactEndedCallback = &contactEndedCallback;
     } else {
         gContactEndedCallback = NULL;
     }
 
-    if ((bool) enableContactProcessedCallback) {
+    if (stepFlags & com_jme3_bullet_StepFlag_contactProcessed) {
         gContactProcessedCallback = &contactProcessedCallback;
     } else {
         gContactProcessedCallback = NULL;
     }
 
-    if ((bool) enableContactStartedCallback) {
+    if (stepFlags & com_jme3_bullet_StepFlag_contactStarted) {
         gContactStartedCallback = &contactStartedCallback;
     } else {
         gContactStartedCallback = NULL;

src/main/native/glue/com_jme3_bullet_StepFlag.h

@@ -101,9 +101,7 @@ class jmePhysicsSpace : public jmeCollisionSpace {
 
     void
     stepSimulation(jfloat timeInterval, jint maxSteps, jfloat accuracy,
-            jboolean enableContactEndedCallback,
-            jboolean enableContactProcessedCallback,
-            jboolean enableContactStartedCallback);
+            jint stepFlags);
 };
 
 #endif // JME_PHYSICS_SPACE_H