Merge pull request #13061 from ctrlaltdavid/21856-f

JSDoc Entity preload, unload, startFarTrigger, etc.

interface/src/scripting/ControllerScriptingInterface.h

@@ -28,7 +28,7 @@ class ScriptEngine;
 /**jsdoc
  * The Controller API provides facilities to interact with computer and controller hardware.
  *
- * <h5>Functions:</h5>
+ * <h5>Functions</h5>
  *
  * <p>Properties</p>
  * <ul>
@@ -143,6 +143,61 @@ class ScriptEngine;
  *   <li>{@link Controller.stopInputPlayback|stopInputPlayback}</li>
  * </ul>
  *
+ * <h5>Entity Methods:</h5>
+ *
+ * <p>The default scripts implement hand controller actions that use {@link Entities.callEntityMethod} to call entity script 
+ * methods, if present in the entity being interacted with.</p>
+ *
+ * <table>
+ *   <thead>
+ *     <tr><th>Method Name</th><th>Description</th><th>Example</th></tr>
+ *   </thead>
+ *   <tbody>
+ *     <tr>
+ *       <td><code>startFarTrigger</code><br /><code>continueFarTrigger</code><br /><code>stopFarTrigger</code></td>
+ *       <td>These methods are called when a user is more than 0.3m away from the entity, the entity is triggerable, and the 
+ *         user starts, continues, or stops squeezing the trigger.</td>
+ *       </td>
+ *       <td>A light switch that can be toggled on and off from a distance.</td>
+ *     </tr>
+ *     <tr>
+ *       <td><code>startNearTrigger</code><br /><code>continueNearTrigger</code><br /><code>stopNearTrigger</code></td>
+ *       <td>These methods are called when a user is less than 0.3m away from the entity, the entity is triggerable, and the 
+ *         user starts, continues, or stops squeezing the trigger.</td>
+ *       <td>A doorbell that can be rung when a user is near.</td>
+ *     </tr>
+ *     <tr>
+ *       <td><code>startDistanceGrab</code><br /><code>continueDistanceGrab</code><br /></td>
+ *       <td>These methods are called when a user is more than 0.3m away from the entity, the entity is either cloneable, or
+ *         grabbable and not locked, and the user starts or continues to squeeze the trigger.</td>
+ *       <td>A comet that emits icy particle trails when a user is dragging it through the sky.</td>
+ *     </tr>
+ *     <tr>
+ *       <td><code>startNearGrab</code><br /><code>continueNearGrab</code><br /></td>
+ *       <td>These methods are called when a user is less than 0.3m away from the entity, the entity is either cloneable, or 
+ *         grabbable and not locked, and the user starts or continues to squeeze the trigger.</td>
+ *       <td>A ball that glows when it's being held close.</td>
+ *     </tr>
+ *     <tr>
+ *       <td><code>releaseGrab</code></td>
+ *       <td>This method is called when a user releases the trigger when having been either distance or near grabbing an 
+ *         entity.</td>
+ *       <td>Turn off the ball glow or comet trail with the user finishes grabbing it.</td>
+ *     </tr>
+ *     <tr>
+ *       <td><code>startEquip</code><br /><code>continueEquip</code><br /><code>releaseEquip</code></td>
+ *       <td>These methods are called when a user starts, continues, or stops equipping an entity.</td>
+ *       <td>A glass that stays in the user's hand after the trigger is clicked.</td>
+ *     </tr>
+ *   </tbody>
+ * </table>
+ * <p>All the entity methods are called with the following two arguments:</p>
+ * <ul>
+ *   <li>The entity ID.</li>
+ *   <li>A string, <code>"hand,userID"</code> &mdash; where "hand" is <code>"left"</code> or <code>"right"</code>, and "userID"
+ *     is the user's {@link MyAvatar|MyAvatar.sessionUUID}.</li>
+ * </ul>
+ *
  * @namespace Controller
  *
  * @property {Controller.Actions} Actions - Predefined actions on Interface and the user's avatar. These can be used as end 

libraries/controllers/src/controllers/impl/MappingBuilderProxy.h

@@ -39,7 +39,9 @@ class UserInputMapper;
  *     methods.</li>
  *     <li>Use {@link Controller.parseMapping} or {@link Controller.loadMapping} to load a {@link Controller.MappingJSON}.</li>
  * </ul>
- * <p>Enable the mapping using {@link MappingObject#enable|enable} or {@link Controller.enableMapping} for it to take effect.
+ *
+ * <p>Enable the mapping using {@link MappingObject#enable|enable} or {@link Controller.enableMapping} for it to take 
+ * effect.</p>
  *
  * <p>Mappings and their routes are applied according to the following rules:</p>
  * <ul>
@@ -49,7 +51,7 @@ class UserInputMapper;
  *     output that already has a route the new route is ignored.</li>
  *     <li>New mappings override previous mappings: each output is processed using the route in the most recently enabled 
  *     mapping that contains that output.</li>
- * </p>
+ * </ul>
  *
  * @class MappingObject
  */

libraries/controllers/src/controllers/impl/RouteBuilderProxy.h

@@ -29,7 +29,8 @@ class ScriptingInterface;
  * <p>A route in a {@link MappingObject} used by the {@link Controller} API.</p>
  *
  * <p>Create a route using {@link MappingObject} methods and apply this object's methods to process it, terminating with 
- * {@link RouteObject#to} to apply it to a <code>Standard</code> control, action, or script function.</p>
+ * {@link RouteObject#to} to apply it to a <code>Standard</code> control, action, or script function. Note: Loops are not 
+ * permitted.</p>
  *
  * <p>Some methods apply to routes with number data, some apply routes with {@link Pose} data, and some apply to both route 
  * types.<p>

libraries/script-engine/src/ScriptEngine.cpp

@@ -2161,6 +2161,32 @@ void ScriptEngine::loadEntityScript(const EntityItemID& entityID, const QString&
     }, forceRedownload);
 }
 
+/**jsdoc
+ * Triggered when the script starts for a user.
+ * <p>Note: Can only be connected to via <code>this.preload = function (...) { ... }</code> in the entity script.</p>
+ * <table><tr><th>Available in:</th><td>Client Entity Scripts</td><td>Server Entity Scripts</td></tr></table>
+ * @function Entities.preload
+ * @param {Uuid} entityID - The ID of the entity that the script is running in.
+ * @returns {Signal}
+ * @example <caption>Get the ID of the entity that a client entity script is running in.</caption>
+ * var entityScript = (function () {
+ *     this.entityID = Uuid.NULL;
+ *
+ *     this.preload = function (entityID) {
+ *         this.entityID = entityID;
+ *         print("Entity ID: " + this.entityID);
+ *     };
+ * );
+ *
+ * var entityID = Entities.addEntity({
+ *     type: "Box",
+ *     position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
+ *     dimensions: { x: 0.5, y: 0.5, z: 0.5 },
+ *     color: { red: 255, green: 0, blue: 0 },
+ *     script: "(" + entityScript + ")",  // Could host the script on a Web server instead.
+ *     lifetime: 300  // Delete after 5 minutes.
+ * });
+ */
 // since all of these operations can be asynch we will always do the actual work in the response handler
 // for the download
 void ScriptEngine::entityScriptContentAvailable(const EntityItemID& entityID, const QString& scriptOrURL, const QString& contents, bool isURL, bool success , const QString& status) {
@@ -2345,6 +2371,13 @@ void ScriptEngine::entityScriptContentAvailable(const EntityItemID& entityID, co
     processDeferredEntityLoads(entityScript, entityID);
 }
 
+/**jsdoc
+ * Triggered when the script terminates for a user.
+ * <p>Note: Can only be connected to via <code>this.unoad = function () { ... }</code> in the entity script.</p>
+ * <table><tr><th>Available in:</th><td>Client Entity Scripts</td><td>Server Entity Scripts</td></tr></table>
+ * @function Entities.unload
+ * @returns {Signal}
+ */
 void ScriptEngine::unloadEntityScript(const EntityItemID& entityID, bool shouldRemoveFromMap) {
     if (QThread::currentThread() != thread()) {
 #ifdef THREAD_DEBUGGING