Add missing Script JSDoc

This commit is contained in:
David Rowe 2019-05-21 09:49:21 +12:00
parent 0a0a25139c
commit ca7ddece8b
4 changed files with 199 additions and 61 deletions

View file

@ -1770,6 +1770,7 @@ signals:
/**jsdoc /**jsdoc
* Triggered on the client that is the physics simulation owner during the collision of two entities. Note: Isn't triggered * Triggered on the client that is the physics simulation owner during the collision of two entities. Note: Isn't triggered
* for a collision with an avatar. * for a collision with an avatar.
* <p>See also, {@link Script.addEventHandler}.</p>
* @function Entities.collisionWithEntity * @function Entities.collisionWithEntity
* @param {Uuid} idA - The ID of one entity in the collision. For an entity script, this is the ID of the entity containing * @param {Uuid} idA - The ID of one entity in the collision. For an entity script, this is the ID of the entity containing
* the script. * the script.
@ -1882,6 +1883,7 @@ signals:
/**jsdoc /**jsdoc
* Triggered when a mouse button is clicked while the mouse cursor is on an entity, or a controller trigger is fully * Triggered when a mouse button is clicked while the mouse cursor is on an entity, or a controller trigger is fully
* pressed while its laser is on an entity. * pressed while its laser is on an entity.
* <p>See also, {@link Script.addEventHandler}.</p>
* @function Entities.mousePressOnEntity * @function Entities.mousePressOnEntity
* @param {Uuid} entityID - The ID of the entity that was pressed. * @param {Uuid} entityID - The ID of the entity that was pressed.
* @param {PointerEvent} event - Details of the event. * @param {PointerEvent} event - Details of the event.
@ -1906,6 +1908,7 @@ signals:
/**jsdoc /**jsdoc
* Repeatedly triggered while the mouse cursor or controller laser moves on an entity. * Repeatedly triggered while the mouse cursor or controller laser moves on an entity.
* <p>See also, {@link Script.addEventHandler}.</p>
* @function Entities.mouseMoveOnEntity * @function Entities.mouseMoveOnEntity
* @param {Uuid} entityID - The ID of the entity that was moved on. * @param {Uuid} entityID - The ID of the entity that was moved on.
* @param {PointerEvent} event - Details of the event. * @param {PointerEvent} event - Details of the event.
@ -1916,6 +1919,7 @@ signals:
/**jsdoc /**jsdoc
* Triggered when a mouse button is released after clicking on an entity or the controller trigger is partly or fully * Triggered when a mouse button is released after clicking on an entity or the controller trigger is partly or fully
* released after pressing on an entity, even if the mouse pointer or controller laser has moved off the entity. * released after pressing on an entity, even if the mouse pointer or controller laser has moved off the entity.
* <p>See also, {@link Script.addEventHandler}.</p>
* @function Entities.mouseReleaseOnEntity * @function Entities.mouseReleaseOnEntity
* @param {Uuid} entityID - The ID of the entity that was originally pressed. * @param {Uuid} entityID - The ID of the entity that was originally pressed.
* @param {PointerEvent} event - Details of the event. * @param {PointerEvent} event - Details of the event.
@ -1942,6 +1946,7 @@ signals:
/**jsdoc /**jsdoc
* Triggered when a mouse button is clicked while the mouse cursor is on an entity. Note: Not triggered by controller. * Triggered when a mouse button is clicked while the mouse cursor is on an entity. Note: Not triggered by controller.
* <p>See also, {@link Script.addEventHandler}.</p>
* @function Entities.clickDownOnEntity * @function Entities.clickDownOnEntity
* @param {Uuid} entityID - The ID of the entity that was clicked. * @param {Uuid} entityID - The ID of the entity that was clicked.
* @param {PointerEvent} event - Details of the event. * @param {PointerEvent} event - Details of the event.
@ -1952,6 +1957,7 @@ signals:
/**jsdoc /**jsdoc
* Repeatedly triggered while a mouse button continues to be held after clicking an entity, even if the mouse cursor has * Repeatedly triggered while a mouse button continues to be held after clicking an entity, even if the mouse cursor has
* moved off the entity. Note: Not triggered by controller. * moved off the entity. Note: Not triggered by controller.
* <p>See also, {@link Script.addEventHandler}.</p>
* @function Entities.holdingClickOnEntity * @function Entities.holdingClickOnEntity
* @param {Uuid} entityID - The ID of the entity that was originally clicked. * @param {Uuid} entityID - The ID of the entity that was originally clicked.
* @param {PointerEvent} event - Details of the event. * @param {PointerEvent} event - Details of the event.
@ -1962,6 +1968,7 @@ signals:
/**jsdoc /**jsdoc
* Triggered when a mouse button is released after clicking on an entity, even if the mouse cursor has moved off the * Triggered when a mouse button is released after clicking on an entity, even if the mouse cursor has moved off the
* entity. Note: Not triggered by controller. * entity. Note: Not triggered by controller.
* <p>See also, {@link Script.addEventHandler}.</p>
* @function Entities.clickReleaseOnEntity * @function Entities.clickReleaseOnEntity
* @param {Uuid} entityID - The ID of the entity that was originally clicked. * @param {Uuid} entityID - The ID of the entity that was originally clicked.
* @param {PointerEvent} event - Details of the event. * @param {PointerEvent} event - Details of the event.
@ -1971,6 +1978,7 @@ signals:
/**jsdoc /**jsdoc
* Triggered when the mouse cursor or controller laser starts hovering on an entity. * Triggered when the mouse cursor or controller laser starts hovering on an entity.
* <p>See also, {@link Script.addEventHandler}.</p>
* @function Entities.hoverEnterEntity * @function Entities.hoverEnterEntity
* @param {Uuid} entityID - The ID of the entity that is being hovered. * @param {Uuid} entityID - The ID of the entity that is being hovered.
* @param {PointerEvent} event - Details of the event. * @param {PointerEvent} event - Details of the event.
@ -1980,6 +1988,7 @@ signals:
/**jsdoc /**jsdoc
* Repeatedly triggered when the mouse cursor or controller laser moves while hovering over an entity. * Repeatedly triggered when the mouse cursor or controller laser moves while hovering over an entity.
* <p>See also, {@link Script.addEventHandler}.</p>
* @function Entities.hoverOverEntity * @function Entities.hoverOverEntity
* @param {Uuid} entityID - The ID of the entity that is being hovered. * @param {Uuid} entityID - The ID of the entity that is being hovered.
* @param {PointerEvent} event - Details of the event. * @param {PointerEvent} event - Details of the event.
@ -1989,6 +1998,7 @@ signals:
/**jsdoc /**jsdoc
* Triggered when the mouse cursor or controller laser stops hovering over an entity. * Triggered when the mouse cursor or controller laser stops hovering over an entity.
* <p>See also, {@link Script.addEventHandler}.</p>
* @function Entities.hoverLeaveEntity * @function Entities.hoverLeaveEntity
* @param {Uuid} entityID - The ID of the entity that was being hovered. * @param {Uuid} entityID - The ID of the entity that was being hovered.
* @param {PointerEvent} event - Details of the event. * @param {PointerEvent} event - Details of the event.
@ -1999,6 +2009,7 @@ signals:
/**jsdoc /**jsdoc
* Triggered when an avatar enters an entity. * Triggered when an avatar enters an entity.
* <p>See also, {@link Script.addEventHandler}.</p>
* @function Entities.enterEntity * @function Entities.enterEntity
* @param {Uuid} entityID - The ID of the entity that the avatar entered. * @param {Uuid} entityID - The ID of the entity that the avatar entered.
* @returns {Signal} * @returns {Signal}
@ -2032,6 +2043,7 @@ signals:
/**jsdoc /**jsdoc
* Triggered when an avatar leaves an entity. * Triggered when an avatar leaves an entity.
* <p>See also, {@link Script.addEventHandler}.</p>
* @function Entities.leaveEntity * @function Entities.leaveEntity
* @param {Uuid} entityID - The ID of the entity that the avatar left. * @param {Uuid} entityID - The ID of the entity that the avatar left.
* @returns {Signal} * @returns {Signal}

View file

@ -987,6 +987,31 @@ void ScriptEngine::addEventHandler(const EntityItemID& entityID, const QString&
}; };
}; };
/**jsdoc
* The name of an entity event. When the entity event occurs, any function that has been registered for that event via
* {@link Script.addEventHandler} is called with parameters per the entity event.
* <table>
* <thead>
* <tr><th>Event Name</th><th>Entity Event</th></tr>
* </thead>
* <tbody>
* <tr><td><code>"enterEntity"</code></td><td>{@link Entities.enterEntity}</td></tr>
* <tr><td><code>"leaveEntity"</code></td><td>{@link Entities.leaveEntity}</td></tr>
* <tr><td><code>"mousePressOnEntity"</code></td><td>{@link Entities.mousePressOnEntity}</td></tr>
* <tr><td><code>"mouseMoveOnEntity"</code></td><td>{@link Entities.mouseMoveOnEntity}</td></tr>
* <tr><td><code>"mouseReleaseOnEntity"</code></td><td>{@link Entities.mouseReleaseOnEntity}</td></tr>
* <tr><td><code>"clickDownOnEntity"</code></td><td>{@link Entities.clickDownOnEntity}</td></tr>
* <tr><td><code>"holdingClickOnEntity"</code></td><td>{@link Entities.holdingClickOnEntity}</td></tr>
* <tr><td><code>"clickReleaseOnEntity"</code></td><td>{@link Entities.clickReleaseOnEntity}</td></tr>
* <tr><td><code>"hoverEnterEntity"</code></td><td>{@link Entities.hoverEnterEntity}</td></tr>
* <tr><td><code>"hoverOverEntity"</code></td><td>{@link Entities.hoverOverEntity}</td></tr>
* <tr><td><code>"hoverLeaveEntity"</code></td><td>{@link Entities.hoverLeaveEntity}</td></tr>
* <tr><td><code>"collisionWithEntity"</code></td><td>{@link Entities.collisionWithEntity}</td></tr>
* </tbody>
* </table>
*
* @typedef {string} Script.EntityEvent
*/
connect(entities.data(), &EntityScriptingInterface::enterEntity, this, makeSingleEntityHandler("enterEntity")); connect(entities.data(), &EntityScriptingInterface::enterEntity, this, makeSingleEntityHandler("enterEntity"));
connect(entities.data(), &EntityScriptingInterface::leaveEntity, this, makeSingleEntityHandler("leaveEntity")); connect(entities.data(), &EntityScriptingInterface::leaveEntity, this, makeSingleEntityHandler("leaveEntity"));
@ -2147,7 +2172,7 @@ void ScriptEngine::loadEntityScript(const EntityItemID& entityID, const QString&
} }
/**jsdoc /**jsdoc
* Triggered when the script starts for a user. * Triggered when the script starts for a user. See also, {@link Script.entityScriptPreloadFinished}.
* <p>Note: Can only be connected to via <code>this.preload = function (...) { ... }</code> in the entity script.</p> * <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> * <table><tr><th>Available in:</th><td>Client Entity Scripts</td><td>Server Entity Scripts</td></tr></table>
* @function Entities.preload * @function Entities.preload
@ -2161,7 +2186,7 @@ void ScriptEngine::loadEntityScript(const EntityItemID& entityID, const QString&
* this.entityID = entityID; * this.entityID = entityID;
* print("Entity ID: " + this.entityID); * print("Entity ID: " + this.entityID);
* }; * };
* ); * });
* *
* var entityID = Entities.addEntity({ * var entityID = Entities.addEntity({
* type: "Box", * type: "Box",

View file

@ -110,7 +110,14 @@ public:
* @hifi-server-entity * @hifi-server-entity
* @hifi-assignment-client * @hifi-assignment-client
* *
* @property {string} context * @property {string} context - The context that the script is running in:
* <ul>
* <li><code>"client"</code>: An Interface or avatar script.</li>
* <li><code>"entity_client"</code>: A client entity script.</li>
* <li><code>"entity_server"</code>: A server entity script.</li>
* <li><code>"agent"</code>: An assignment client script.</li>
* </ul>
* <em>Read-only.</em>
*/ */
class ScriptEngine : public BaseScriptEngine, public EntitiesScriptEngineProvider { class ScriptEngine : public BaseScriptEngine, public EntitiesScriptEngineProvider {
Q_OBJECT Q_OBJECT
@ -153,6 +160,7 @@ public:
/**jsdoc /**jsdoc
* Stops and unloads the current script. * Stops and unloads the current script.
* <p><strong>Warning:</strong> If an assignment client script, the script gets restarted after stopping.</p>
* @function Script.stop * @function Script.stop
* @param {boolean} [marshal=false] - Marshal. * @param {boolean} [marshal=false] - Marshal.
* <p class="important">Deprecated: This parameter is deprecated and will be removed.</p> * <p class="important">Deprecated: This parameter is deprecated and will be removed.</p>
@ -255,38 +263,53 @@ public:
bool hasValidScriptSuffix(const QString& scriptFileName); bool hasValidScriptSuffix(const QString& scriptFileName);
/**jsdoc /**jsdoc
* Gets the context that the script is running in: Interface/avatar, client entity, server entity, or assignment client.
* @function Script.getContext * @function Script.getContext
* @returns {string} * @returns {string} The context that the script is running in:
* <ul>
* <li><code>"client"</code>: An Interface or avatar script.</li>
* <li><code>"entity_client"</code>: A client entity script.</li>
* <li><code>"entity_server"</code>: A server entity script.</li>
* <li><code>"agent"</code>: An assignment client script.</li>
* </ul>
*/ */
Q_INVOKABLE QString getContext() const; Q_INVOKABLE QString getContext() const;
/**jsdoc /**jsdoc
* Checks whether the script is running as an Interface or avatar script.
* @function Script.isClientScript * @function Script.isClientScript
* @returns {boolean} * @returns {boolean} <code>true</code> if the script is running as an Interface or avatar script, <code>false</code> if it
* isn't.
*/ */
Q_INVOKABLE bool isClientScript() const { return _context == CLIENT_SCRIPT; } Q_INVOKABLE bool isClientScript() const { return _context == CLIENT_SCRIPT; }
/**jsdoc /**jsdoc
* Checks whether the application was compiled as a debug build.
* @function Script.isDebugMode * @function Script.isDebugMode
* @returns {boolean} * @returns {boolean} <code>true</code> if the software was compiled as a debug build, <code>false</code> if it was
* compiled as a release build.
*/ */
Q_INVOKABLE bool isDebugMode() const; Q_INVOKABLE bool isDebugMode() const;
/**jsdoc /**jsdoc
* Checks whether the script content is a client entity script.
* @function Script.isEntityClientScript * @function Script.isEntityClientScript
* @returns {boolean} * @returns {boolean} <code>true</code> if the script is running as a client entity script, <code>false</code> if it isn't.
*/ */
Q_INVOKABLE bool isEntityClientScript() const { return _context == ENTITY_CLIENT_SCRIPT; } Q_INVOKABLE bool isEntityClientScript() const { return _context == ENTITY_CLIENT_SCRIPT; }
/**jsdoc /**jsdoc
* Checks whether the script context is a server entity script.
* @function Script.isEntityServerScript * @function Script.isEntityServerScript
* @returns {boolean} * @returns {boolean} <code>true</code> if the script is running as a server entity script, <code>false</code> if it isn't.
*/ */
Q_INVOKABLE bool isEntityServerScript() const { return _context == ENTITY_SERVER_SCRIPT; } Q_INVOKABLE bool isEntityServerScript() const { return _context == ENTITY_SERVER_SCRIPT; }
/**jsdoc /**jsdoc
* Checks whether the script is running as an assignment client script.
* @function Script.isAgentScript * @function Script.isAgentScript
* @returns {boolean} * @returns {boolean} <code>true</code> if the script is running as an assignment client script, <code>false</code> if it
* isn't.
*/ */
Q_INVOKABLE bool isAgentScript() const { return _context == AGENT_SCRIPT; } Q_INVOKABLE bool isAgentScript() const { return _context == AGENT_SCRIPT; }
@ -294,24 +317,40 @@ public:
// NOTE - these are intended to be public interfaces available to scripts // NOTE - these are intended to be public interfaces available to scripts
/**jsdoc /**jsdoc
* Adds a function to the list of functions called upon the occurrence of an entity event on a particular entity.
* @function Script.addEventHandler * @function Script.addEventHandler
* @param {Uuid} entityID * @param {Uuid} entityID - The ID of the entity.
* @param {string} eventName * @param {Script.EntityEvent} eventName - The name of the entity event.
* @param {function} handler * @param {function} handler - The function to call when the entity event occurs on the entity. It can be either the name
* of a function or an in-line definition.
* @example <caption>Report when a mouse press occurs on a particular entity.</caption>
* 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 },
* lifetime: 300 // Delete after 5 minutes.
* });
*
* function reportMousePress(entityID, event) {
* print("Mouse pressed on entity: " + JSON.stringify(event));
* }
*
* Script.addEventHandler(entityID, "mousePressOnEntity", reportMousePress);
*/ */
Q_INVOKABLE void addEventHandler(const EntityItemID& entityID, const QString& eventName, QScriptValue handler); Q_INVOKABLE void addEventHandler(const EntityItemID& entityID, const QString& eventName, QScriptValue handler);
/**jsdoc /**jsdoc
* Removes a function from the list of functions called upon the occurrence of an entity event on a particular entity.
* @function Script.removeEventHandler * @function Script.removeEventHandler
* @param {Uuid} entityID * @param {Uuid} entityID - The ID of the entity.
* @param {string} eventName * @param {Script.EntityEvent} eventName - The name of the entity event.
* @param {function} handler * @param {function} handler - The name of the function to no longer call when the entity event occurs on the entity.
*/ */
Q_INVOKABLE void removeEventHandler(const EntityItemID& entityID, const QString& eventName, QScriptValue handler); Q_INVOKABLE void removeEventHandler(const EntityItemID& entityID, const QString& eventName, QScriptValue handler);
/**jsdoc /**jsdoc
* Starts running another script in Interface. * Starts running another script in Interface.
* <p><strong>Note:</strong> Only works for Interface and avatar scripts.</p> * <table><tr><th>Available in:</th><td>Interface Scripts</td><td>Avatar Scripts</td></tr></table>
* @function Script.load * @function Script.load
* @param {string} filename - The URL of the script to load. This can be relative to the current script's URL. * @param {string} filename - The URL of the script to load. This can be relative to the current script's URL.
* @example <caption>Load a script from another script.</caption> * @example <caption>Load a script from another script.</caption>
@ -336,8 +375,8 @@ public:
* @function Script.include * @function Script.include
* @variation 0 * @variation 0
* @param {string[]} filenames - The URLs of the scripts to include. Each can be relative to the current script. * @param {string[]} filenames - The URLs of the scripts to include. Each can be relative to the current script.
* @param {function} [callback=null] - The function to call back when the scripts have been included. It can be an in-line * @param {function} [callback=null] - The function to call back when the scripts have been included. It can be either the
* function or the name of a function. * name of a function or an in-line definition.
*/ */
Q_INVOKABLE void include(const QStringList& includeFiles, QScriptValue callback = QScriptValue()); Q_INVOKABLE void include(const QStringList& includeFiles, QScriptValue callback = QScriptValue());
@ -346,8 +385,8 @@ public:
* asynchronously, otherwise it is included synchronously (i.e., script execution blocks while the file is included). * asynchronously, otherwise it is included synchronously (i.e., script execution blocks while the file is included).
* @function Script.include * @function Script.include
* @param {string} filename - The URL of the script to include. It can be relative to the current script. * @param {string} filename - The URL of the script to include. It can be relative to the current script.
* @param {function} [callback=null] - The function to call back when the script has been included. It can be an in-line * @param {function} [callback=null] - The function to call back when the script has been included. It can be either the
* function or the name of a function. * name of a function or an in-line definition.
* @example <caption>Include a script file asynchronously.</caption> * @example <caption>Include a script file asynchronously.</caption>
* // First file: scriptA.js * // First file: scriptA.js
* print("This is script A"); * print("This is script A");
@ -370,14 +409,18 @@ public:
// MODULE related methods // MODULE related methods
/**jsdoc /**jsdoc
* Provides access to methods or objects provided in an external JavaScript or JSON file.
* See {@link https://docs.highfidelity.com/script/js-tips.html} for further details.
* @function Script.require * @function Script.require
* @param {string} module * @param {string} module - The module to use. May be a JavaScript file or the name of system model such as
* <code>"sppUi"</code>.
*/ */
Q_INVOKABLE QScriptValue require(const QString& moduleId); Q_INVOKABLE QScriptValue require(const QString& moduleId);
/**jsdoc /**jsdoc
* @function Script.resetModuleCache * @function Script.resetModuleCache
* @param {boolean} [deleteScriptCache=false] * @param {boolean} [deleteScriptCache=false] - Delete script cache.
* @deprecated This function is deprecated and will be removed.
*/ */
Q_INVOKABLE void resetModuleCache(bool deleteScriptCache = false); Q_INVOKABLE void resetModuleCache(bool deleteScriptCache = false);
@ -390,7 +433,7 @@ public:
/**jsdoc /**jsdoc
* Calls a function repeatedly, at a set interval. * Calls a function repeatedly, at a set interval.
* @function Script.setInterval * @function Script.setInterval
* @param {function} function - The function to call. This can be an in-line function or the name of a function. * @param {function} function - The function to call. This can be either the name of a function or an in-line definition.
* @param {number} interval - The interval at which to call the function, in ms. * @param {number} interval - The interval at which to call the function, in ms.
* @returns {object} A handle to the interval timer. This can be used by {@link Script.clearInterval}. * @returns {object} A handle to the interval timer. This can be used by {@link Script.clearInterval}.
* @example <caption>Print a message every second.</caption> * @example <caption>Print a message every second.</caption>
@ -403,7 +446,7 @@ public:
/**jsdoc /**jsdoc
* Calls a function once, after a delay. * Calls a function once, after a delay.
* @function Script.setTimeout * @function Script.setTimeout
* @param {function} function - The function to call. This can be an in-line function or the name of a function. * @param {function} function - The function to call. This can be either the name of a function or an in-line definition.
* @param {number} timeout - The delay after which to call the function, in ms. * @param {number} timeout - The delay after which to call the function, in ms.
* @returns {object} A handle to the timeout timer. This can be used by {@link Script.clearTimeout}. * @returns {object} A handle to the timeout timer. This can be used by {@link Script.clearTimeout}.
* @example <caption>Print a message once, after a second.</caption> * @example <caption>Print a message once, after a second.</caption>
@ -447,8 +490,16 @@ public:
Q_INVOKABLE void clearTimeout(QObject* timer) { stopTimer(reinterpret_cast<QTimer*>(timer)); } Q_INVOKABLE void clearTimeout(QObject* timer) { stopTimer(reinterpret_cast<QTimer*>(timer)); }
/**jsdoc /**jsdoc
* Prints a message to the program log.
* <p>Alternatively, you can use {@link print}, {@link console.log}, or one of the other {@link console} methods.</p>
* @function Script.print * @function Script.print
* @param {string} message * @param {string} message - The message to print.
*/
/**jsdoc
* Prints a message to the program log.
* <p>This is an alias of {@link Script.print}.</p>
* @function print
* @param {string} message - The message to print.
*/ */
Q_INVOKABLE void print(const QString& message); Q_INVOKABLE void print(const QString& message);
@ -467,20 +518,25 @@ public:
Q_INVOKABLE QUrl resolvePath(const QString& path) const; Q_INVOKABLE QUrl resolvePath(const QString& path) const;
/**jsdoc /**jsdoc
* Gets the path to the resources directory for QML files.
* @function Script.resourcesPath * @function Script.resourcesPath
* @returns {string} * @returns {string} The path to the resources directory for QML files.
*/ */
Q_INVOKABLE QUrl resourcesPath() const; Q_INVOKABLE QUrl resourcesPath() const;
/**jsdoc /**jsdoc
* Starts timing a section of code in order to send usage data about it to High Fidelity. Shouldn't be used outside of the
* standard scripts.
* @function Script.beginProfileRange * @function Script.beginProfileRange
* @param {string} label * @param {string} label - A name that identifies the section of code.
*/ */
Q_INVOKABLE void beginProfileRange(const QString& label) const; Q_INVOKABLE void beginProfileRange(const QString& label) const;
/**jsdoc /**jsdoc
* Finishes timing a section of code in order to send usage data about it to High Fidelity. Shouldn't be used outside of
* the standard scripts.
* @function Script.endProfileRange * @function Script.endProfileRange
* @param {string} label * @param {string} label - A name that identifies the section of code.
*/ */
Q_INVOKABLE void endProfileRange(const QString& label) const; Q_INVOKABLE void endProfileRange(const QString& label) const;
@ -488,9 +544,10 @@ public:
// Entity Script Related methods // Entity Script Related methods
/**jsdoc /**jsdoc
* Checks whether an entity has an entity script running.
* @function Script.isEntityScriptRunning * @function Script.isEntityScriptRunning
* @param {Uuid} entityID * @param {Uuid} entityID - The ID of the entity.
* @returns {boolean} * @returns {boolean} <code>true</code> if the entity has an entity script running, <code>false</code> if it doesn't.
*/ */
Q_INVOKABLE bool isEntityScriptRunning(const EntityItemID& entityID) { Q_INVOKABLE bool isEntityScriptRunning(const EntityItemID& entityID) {
QReadLocker locker { &_entityScriptsLock }; QReadLocker locker { &_entityScriptsLock };
@ -524,34 +581,41 @@ public:
Q_INVOKABLE void unloadAllEntityScripts(); Q_INVOKABLE void unloadAllEntityScripts();
/**jsdoc /**jsdoc
* Calls a method in an entity script.
* @function Script.callEntityScriptMethod * @function Script.callEntityScriptMethod
* @param {Uuid} entityID * @param {Uuid} entityID - The ID of the entity running the entity script.
* @param {string} methodName * @param {string} methodName - The name of the method to call.
* @param {string[]} [parameters=[]] * @param {string[]} [parameters=[]] - The parameters to call the specified method with.
* @param {Uuid} [remoteCallerID=Uuid.NULL] * @param {Uuid} [remoteCallerID=Uuid.NULL] - An ID that identifies the caller.
*/ */
Q_INVOKABLE void callEntityScriptMethod(const EntityItemID& entityID, const QString& methodName, Q_INVOKABLE void callEntityScriptMethod(const EntityItemID& entityID, const QString& methodName,
const QStringList& params = QStringList(), const QStringList& params = QStringList(),
const QUuid& remoteCallerID = QUuid()) override; const QUuid& remoteCallerID = QUuid()) override;
/**jsdoc /**jsdoc
* Calls a method in an entity script.
* @function Script.callEntityScriptMethod * @function Script.callEntityScriptMethod
* @param {Uuid} entityID * @param {Uuid} entityID - Entity ID.
* @param {string} methodName * @param {string} methodName - Method name.
* @param {PointerEvent} event * @param {PointerEvent} event - Pointer event.
* @deprecated This function is deprecated and will be removed.
*/ */
Q_INVOKABLE void callEntityScriptMethod(const EntityItemID& entityID, const QString& methodName, const PointerEvent& event); Q_INVOKABLE void callEntityScriptMethod(const EntityItemID& entityID, const QString& methodName, const PointerEvent& event);
/**jsdoc /**jsdoc
* Calls a method in an entity script.
* @function Script.callEntityScriptMethod * @function Script.callEntityScriptMethod
* @param {Uuid} entityID * @param {Uuid} entityID - Entity ID.
* @param {string} methodName * @param {string} methodName - Method name.
* @param {Uuid} otherID * @param {Uuid} otherID - Other entity ID.
* @param {Collision} collision * @param {Collision} collision - Collision.
* @deprecated This function is deprecated and will be removed.
*/ */
Q_INVOKABLE void callEntityScriptMethod(const EntityItemID& entityID, const QString& methodName, const EntityItemID& otherID, const Collision& collision); Q_INVOKABLE void callEntityScriptMethod(const EntityItemID& entityID, const QString& methodName, const EntityItemID& otherID, const Collision& collision);
/**jsdoc /**jsdoc
* Manually runs the JavaScript garbage collector which reclaims memory by disposing of objects that are no longer
* reachable.
* @function Script.requestGarbageCollection * @function Script.requestGarbageCollection
*/ */
Q_INVOKABLE void requestGarbageCollection() { collectGarbage(); } Q_INVOKABLE void requestGarbageCollection() { collectGarbage(); }
@ -625,15 +689,17 @@ signals:
/**jsdoc /**jsdoc
* @function Script.scriptLoaded * @function Script.scriptLoaded
* @param {string} filename * @param {string} filename - File name.
* @returns {Signal} * @returns {Signal}
* @deprecated This signal is deprecated and will be removed.
*/ */
void scriptLoaded(const QString& scriptFilename); void scriptLoaded(const QString& scriptFilename);
/**jsdoc /**jsdoc
* @function Script.errorLoadingScript * @function Script.errorLoadingScript
* @param {string} filename * @param {string} filename - File name.
* @returns {Signal} * @returns {Signal}
* @deprecated This signal is deprecated and will be removed.
*/ */
void errorLoadingScript(const QString& scriptFilename); void errorLoadingScript(const QString& scriptFilename);
@ -685,38 +751,44 @@ signals:
void cleanupMenuItem(const QString& menuItemString); void cleanupMenuItem(const QString& menuItemString);
/**jsdoc /**jsdoc
* Triggered when a script prints a message to the program log via {@link Script.print}, {@link print},
* {@link console.log}, {@link console.info}, {@link console.warn}, {@link console.error}, or {@link console.debug}.
* @function Script.printedMessage * @function Script.printedMessage
* @param {string} message * @param {string} message - The message.
* @param {string} scriptName * @param {string} scriptName - The name of the script that generated the message.
* @returns {Signal} * @returns {Signal}
*/ */
void printedMessage(const QString& message, const QString& scriptName); void printedMessage(const QString& message, const QString& scriptName);
/**jsdoc /**jsdoc
* Triggered when a script generates an error or {@link console.error} is called.
* @function Script.errorMessage * @function Script.errorMessage
* @param {string} message * @param {string} message - The error message.
* @param {string} scriptName * @param {string} scriptName - The name of the script that generated the error message.
* @returns {Signal} * @returns {Signal}
*/ */
void errorMessage(const QString& message, const QString& scriptName); void errorMessage(const QString& message, const QString& scriptName);
/**jsdoc /**jsdoc
* Triggered when a script generates a warning or {@link console.warn} is called.
* @function Script.warningMessage * @function Script.warningMessage
* @param {string} message * @param {string} message - The warning message.
* @param {string} scriptName * @param {string} scriptName - The name of the script that generated the warning message.
* @returns {Signal} * @returns {Signal}
*/ */
void warningMessage(const QString& message, const QString& scriptName); void warningMessage(const QString& message, const QString& scriptName);
/**jsdoc /**jsdoc
* Triggered when a script generates an information message or {@link console.info} is called.
* @function Script.infoMessage * @function Script.infoMessage
* @param {string} message * @param {string} message - The information message.
* @param {string} scriptName * @param {string} scriptName - The name of the script that generated the information message.
* @returns {Signal} * @returns {Signal}
*/ */
void infoMessage(const QString& message, const QString& scriptName); void infoMessage(const QString& message, const QString& scriptName);
/**jsdoc /**jsdoc
* Triggered when the running state of the script changes, e.g., from running to stopping.
* @function Script.runningStateChanged * @function Script.runningStateChanged
* @returns {Signal} * @returns {Signal}
*/ */
@ -731,21 +803,24 @@ signals:
/**jsdoc /**jsdoc
* @function Script.loadScript * @function Script.loadScript
* @param {string} scriptName * @param {string} scriptName - Script name.
* @param {boolean} isUserLoaded * @param {boolean} isUserLoaded - Is user loaded.
* @returns {Signal} * @returns {Signal}
* @deprecated This signal is deprecated and will be removed.
*/ */
void loadScript(const QString& scriptName, bool isUserLoaded); void loadScript(const QString& scriptName, bool isUserLoaded);
/**jsdoc /**jsdoc
* @function Script.reloadScript * @function Script.reloadScript
* @param {string} scriptName * @param {string} scriptName - Script name.
* @param {boolean} isUserLoaded * @param {boolean} isUserLoaded - Is user loaded.
* @returns {Signal} * @returns {Signal}
* @deprecated This signal is deprecated and will be removed.
*/ */
void reloadScript(const QString& scriptName, bool isUserLoaded); void reloadScript(const QString& scriptName, bool isUserLoaded);
/**jsdoc /**jsdoc
* Triggered when the script has stopped.
* @function Script.doneRunning * @function Script.doneRunning
* @returns {Signal} * @returns {Signal}
*/ */
@ -761,9 +836,28 @@ signals:
void entityScriptDetailsUpdated(); void entityScriptDetailsUpdated();
/**jsdoc /**jsdoc
* Triggered when the script starts for the user. See also, {@link Entities.preload}.
* <table><tr><th>Available in:</th><td>Client Entity Scripts</td><td>Server Entity Scripts</td></tr></table>
* @function Script.entityScriptPreloadFinished * @function Script.entityScriptPreloadFinished
* @param {Uuid} entityID * @param {Uuid} entityID - The ID of the entity that the script is running in.
* @returns {Signal} * @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;
*
* Script.entityScriptPreloadFinished.connect(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.
* });
*/ */
// Emitted when an entity script has finished running preload // Emitted when an entity script has finished running preload
void entityScriptPreloadFinished(const EntityItemID& entityID); void entityScriptPreloadFinished(const EntityItemID& entityID);

View file

@ -33,10 +33,11 @@ public:
/**jsdoc /**jsdoc
* @function Script.lintScript * @function Script.lintScript
* @param {string} sourceCode * @param {string} sourceCode - Source code.
* @param {string} fileName * @param {string} fileName - File name.
* @param {number} [lineNumber=1] * @param {number} [lineNumber=1] - Line number.
* @returns {object} * @returns {object} Object.
* @deprecated This function is deprecated and will be removed.
*/ */
Q_INVOKABLE QScriptValue lintScript(const QString& sourceCode, const QString& fileName, const int lineNumber = 1); Q_INVOKABLE QScriptValue lintScript(const QString& sourceCode, const QString& fileName, const int lineNumber = 1);
@ -80,9 +81,15 @@ signals:
// Script.signalHandlerException is exposed by QScriptEngine. // Script.signalHandlerException is exposed by QScriptEngine.
/**jsdoc /**jsdoc
* Triggered when a script generates an unhandled exception.
* @function Script.unhandledException * @function Script.unhandledException
* @param {object} exception * @param {object} exception - The details of the exception.
* @returns {Signal} * @returns {Signal}
* @example <caption>Report the details of an unhandled exception.</caption>
* Script.unhandledException.connect(function (exception) {
* print("Unhandled exception: " + JSON.stringify(exception));
* });
* var properties = JSON.parse("{ x: 1"); // Invalid JSON string.
*/ */
void unhandledException(const QScriptValue& exception); void unhandledException(const QScriptValue& exception);