From c2d8c96463061da878774612e28c51a723a26f59 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Mon, 26 Feb 2018 14:10:33 +1300 Subject: [PATCH] Entities collisions JSDoc --- .../entities/src/EntityScriptingInterface.h | 79 +++++++++++++++++++ libraries/shared/src/RegisteredMetaTypes.cpp | 9 +++ libraries/shared/src/RegisteredMetaTypes.h | 14 ++++ 3 files changed, 102 insertions(+) diff --git a/libraries/entities/src/EntityScriptingInterface.h b/libraries/entities/src/EntityScriptingInterface.h index 0a4beed0c3..00c4918f34 100644 --- a/libraries/entities/src/EntityScriptingInterface.h +++ b/libraries/entities/src/EntityScriptingInterface.h @@ -1295,6 +1295,45 @@ public slots: Q_INVOKABLE bool verifyStaticCertificateProperties(const QUuid& entityID); signals: + /**jsdoc + * 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. + * @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 + * the script. + * @param {Uuid} idB - The ID of the other entity in the collision. + * @param {Collision} collision - The details of the collision. + * @returns {Signal} + * @example Change the color of an entity when it collides with another entity. + * var entityScript = (function () { + * function randomInteger(min, max) { + * return Math.floor(Math.random() * (max - min + 1)) + min; + * } + * + * this.collisionWithEntity = function (myID, otherID, collision) { + * Entities.editEntity(myID, { + * color: { + * red: randomInteger(128, 255), + * green: randomInteger(128, 255), + * blue: randomInteger(128, 255) + * } + * }); + * }; + * }); + * + * 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: 128, green: 128, blue: 128 }, + * gravity: { x: 0, y: -9.8, z: 0 }, + * velocity: { x: 0, y: 0.1, z: 0 }, // Kick off physics. + * dynamic: true, + * collisionless: false, // So that collision events are generated. + * script: "(" + entityScript + ")", // Could host the script on a Web server instead. + * lifetime: 300 // Delete after 5 minutes. + * }); + */ void collisionWithEntity(const EntityItemID& idA, const EntityItemID& idB, const Collision& collision); /**jsdoc @@ -1476,9 +1515,49 @@ signals: */ void hoverLeaveEntity(const EntityItemID& entityItemID, const PointerEvent& event); + + /**jsdoc + * Triggered when an avatar enters an entity. + * @function Entities.enterEntity + * @param {Uuid} entityID - The ID of the entity that the avatar entered. + * @returns {Signal} + * @example Change the color of an entity when an avatar enters or leaves. + * var entityScript = (function () { + * this.enterEntity = function (entityID) { + * print("Enter entity"); + * Entities.editEntity(entityID, { + * color: { red: 255, green: 64, blue: 64 }, + * }); + * }; + * this.leaveEntity = function (entityID) { + * print("Leave entity"); + * Entities.editEntity(entityID, { + * color: { red: 128, green: 128, blue: 128 }, + * }); + * }; + * }); + * + * var entityID = Entities.addEntity({ + * type: "Sphere", + * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })), + * dimensions: { x: 3, y: 3, z: 3 }, + * color: { red: 128, green: 128, blue: 128 }, + * collisionless: true, // So that avatar can walk through entity. + * script: "(" + entityScript + ")", // Could host the script on a Web server instead. + * lifetime: 300 // Delete after 5 minutes. + * }); + */ void enterEntity(const EntityItemID& entityItemID); + + /**jsdoc + * Triggered when an avatar leaves an entity. + * @function Entities.enterEntity + * @param {Uuid} entityID - The ID of the entity that the avatar left. + * @returns {Signal} + */ void leaveEntity(const EntityItemID& entityItemID); + /**jsdoc * Triggered when an entity is deleted. * @function Entities.deletingEntity diff --git a/libraries/shared/src/RegisteredMetaTypes.cpp b/libraries/shared/src/RegisteredMetaTypes.cpp index c597db6dc1..a3d312b9c1 100644 --- a/libraries/shared/src/RegisteredMetaTypes.cpp +++ b/libraries/shared/src/RegisteredMetaTypes.cpp @@ -774,6 +774,15 @@ void pickRayFromScriptValue(const QScriptValue& object, PickRay& pickRay) { } } +/**jsdoc + * @typedef {object} Collision + * @property {ContactEventType} type - The contact type of the collision event. + * @property {Uuid} idA - The ID of one of the entities in the collision. + * @property {Uuid} idB - The ID of the other of the entities in the collision. + * @property {Vec3} penetration - The amount of penetration between the two entities. + * @property {Vec3} contactPoint - The point of contact. + * @property {Vec3} velocityChange - The change in relative velocity of the two entities, in m/s. + */ QScriptValue collisionToScriptValue(QScriptEngine* engine, const Collision& collision) { QScriptValue obj = engine->newObject(); obj.setProperty("type", collision.type); diff --git a/libraries/shared/src/RegisteredMetaTypes.h b/libraries/shared/src/RegisteredMetaTypes.h index 3fc81a9c9e..a7c9c0bee3 100644 --- a/libraries/shared/src/RegisteredMetaTypes.h +++ b/libraries/shared/src/RegisteredMetaTypes.h @@ -258,6 +258,20 @@ namespace std { }; } +/**jsdoc + *

The type of a collision contact event. + * + * + * + * + * + * + * + * + * + *
ValueDescription
0Start of the collision.
1Continuation of the collision.
2End of the collision.
+ * @typedef {number} ContactEventType + */ enum ContactEventType { CONTACT_EVENT_TYPE_START, CONTACT_EVENT_TYPE_CONTINUE,