{"_id":"5a06037234873d0010b3924f","category":{"_id":"5a06037134873d0010b39202","version":"5a06037134873d0010b391fe","project":"578c4badbd223d2000cc1441","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-07-18T21:08:45.730Z","from_sync":false,"order":3,"slug":"develop","title":"Develop"},"project":"578c4badbd223d2000cc1441","user":"57bb7defafc18c0e00529cf1","parentDoc":null,"version":{"_id":"5a06037134873d0010b391fe","project":"578c4badbd223d2000cc1441","__v":1,"createdAt":"2017-11-10T19:52:17.163Z","releaseDate":"2017-11-10T19:52:17.163Z","categories":["5a06037134873d0010b391ff","5a06037134873d0010b39200","5a06037134873d0010b39201","5a06037134873d0010b39202","5a06037134873d0010b39203","5a06037134873d0010b39204"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.1.0","version":"2.1.0"},"__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-09-16T01:57:34.992Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":14,"body":"Viro contains a simple but powerful Physics engine. This engine enables developers to build interactive experiences that simulate real world forces. This development guide will go through the basics of creating physics objects and offer an overview of the experiences that can be created with them.\n\nIn Viro, almost every 3D control can be physics-enabled through the physicsBody property. For example, to make a ```<ViroBox>``` fall due to gravity, simply add a physicsBody property to the box with a mass and type, as shown below:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<ViroBox\\n\\tposition={[0,1,-3]}\\n  height={1} width={1} length={1}\\n\\tphysicsBody={{\\n\\t\\ttype:'dynamic', mass:1\\n  }}\\n/>\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nEach ```physicsBody``` must have a ```type``` that dictates the behavior of the physics body. Physics bodies may also be given a ```shape``` to represent the collision mesh of the body. This can be automatically inferred if not provided.\n\n##Physics Body Type\nThere are three types of physics bodies available in Viro: Dynamic, Kinematic, and Static. Each has unique movement and interaction behavior. Note also there is a mass requirement associated with each type.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Property\",\n    \"h-1\": \"Static RigidBody\",\n    \"h-2\": \"Kinematic RigidBody\",\n    \"h-3\": \"Dynamic RigidBody\",\n    \"0-0\": \"Mass (in kg)\",\n    \"1-0\": \"Movement Behavior\",\n    \"2-0\": \"Collision Behavior\",\n    \"0-1\": \"- Must have 0 mass.\",\n    \"0-2\": \"- Must have 0 Mass.\",\n    \"0-3\": \"- Positive Mass (cannot be negative).\",\n    \"1-1\": \"- Cannot move.\",\n    \"1-2\": \"- Can be moved under explicit developer/user control.\",\n    \"1-3\": \"- Designed to be moved under simulation (you should not be directly manipulating / animating this object's position). \\n- Can be moved by colliding against other objects, and in response to forces and impulse.\",\n    \"2-1\": \"- Can collide only with dynamic bodies. \\n- Least resource intensive. - Works well with static objects like floor, ground, etc.\",\n    \"2-2\": \"- Can collide with dynamic bodies.\\n- Does not collide with other other kinematic bodies or static bodies.\\n- Cannot be influenced by dynamic bodies. \\n- Behaves like a movable object with infinite mass during collisions (will always push objects away).\\n- Works well with objects you wish to directly move with animations with fine movement detail.\",\n    \"2-3\": \"- Can collide with any body type. \\n- Works well with objects that do not have applied animations, and that are reactive to forces applied in the world.\"\n  },\n  \"cols\": 4,\n  \"rows\": 3\n}\n[/block]\n##Physics Body Shape\nAfter specifying a type, Viro will need to determine the actual shape of the physics object representing the control's geometry. This can be specified through the ```shape``` property in a ```physicsBody```. There are three kinds of shapes that the physics body accepts: *box*, *sphere*, and *compound*, as shown below. \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/1fadf1a-Screen_Shot_2017-09-18_at_5.54.01_PM.png\",\n        \"Screen Shot 2017-09-18 at 5.54.01 PM.png\",\n        381,\n        100,\n        \"#e42720\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Shape\",\n    \"h-1\": \"Parameters\",\n    \"0-0\": \"box\",\n    \"1-0\": \"sphere\",\n    \"2-0\": \"compound\",\n    \"0-1\": \"Accepts width, height, and length of the box in the form [w, h, l]. Will be centered around the origin of the control.\",\n    \"1-1\": \"Accepts a radius parameter. Creates a sphere that will be centered around the origin of your control.\",\n    \"2-1\": \"No parameters. Viro automatically iterates through the compound control's subtree and infers the physics shape.\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\nNote that the shape property is optional. If none is provided, Viro automatically generates a physics box (or sphere) shape that roughly represents that geometric control. You can also toggle a debug flag on the scene to draw all meshes representing physics shapes. This is demonstrated in the image above, and is primarily used for debugging purposes (it comes at a significant performance cost).\n\nIt is important to note that physics objects cannot be recursively stacked. That is, a Viro control that is physics-enabled cannot have sub-nodes or children that also have their own physics-enabled bodies. There is no hierarchy to physics bodies. Compound *shapes*, however -- where multiple geometric objects are compounded together to form a single physics body -- are supported in Viro.\n[block:api-header]\n{\n  \"title\": \"Physics Body Forces\"\n}\n[/block]\nApplying forces to physics enabled Viro controls can be done through an object's ```physicsBody``` property. Viro automatically manages the reconciling of those forces on an object's transform when they are applied. \n\n###Constant Forces\nConstant forces can be useful in situations for moving objects in constant motion; for example, when adding thrust to a spaceship being launched into the sky. To apply a constant directional force, set a single force (or an array of forces) on the physics body's ```force``` property. For each force, you can specify both its *magnitude* (in newtons) and its *location* (on the object). The location property is optional.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/b455b72-ezgif.com-crop_3.gif\",\n        \"ezgif.com-crop (3).gif\",\n        250,\n        250,\n        \"#bba2a2\"\n      ]\n    }\n  ]\n}\n[/block]\nRotational forces are also supported. To apply a constant rotational force, use the ```torque``` property.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/6055046-ezgif.com-crop_4.gif\",\n        \"ezgif.com-crop (4).gif\",\n        250,\n        250,\n        \"#bba3a3\"\n      ]\n    }\n  ]\n}\n[/block]\n###Impulsive Forces and Motion\nImpulse forces are useful in situations where you would like to apply an instantaneous burst of force to an object. These are often useful for launching projectile objects. Rotational impulses are supported as well.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/51bc233-ezgif.com-crop_3.gif\",\n        \"ezgif.com-crop (3).gif\",\n        250,\n        250,\n        \"#baa1a1\"\n      ]\n    }\n  ]\n}\n[/block]\n### Velocity \nDevelopers have access to finer control over object movement via the ```velocity``` property. Doing so will override any forces that are already applied to the object.\n\n## Forces and Drag Behavior\nWith Viro, the default behavior of drag events works with physics-enabled controls; users are still able to drag objects around the scene. Viro handles this by temporarily converting any dragged physics bodies into kinematic types during the drag, then switching back to the original types upon completion of the drag. This can be used to give users the ability to fling objects toward other dynamic-typed physics bodies. An example of this is shown below.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/4ba68fc-ezgif.com-video-to-gif_1.gif\",\n        \"ezgif.com-video-to-gif (1).gif\",\n        600,\n        338,\n        \"#7e8b98\"\n      ],\n      \"caption\": \"Drag and drop physics bodies.\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Physics Body Properties\"\n}\n[/block]\nViro physics bodies have additional properties that the developer can tune to achieve different kinds of behavior. Two of these are friction and restitution. \n\n**Restitution** controls how \"bouncy\" an object or surface is. When two objects collide, some of the energy of the collision is used to deform the collided objects, some is used rebound the objects from one another, and some is lost to heat. Restitution is a measure of how much of that kinetic energy is used for objects to rebound from one another. To take a real-world example, a massive bowling bowl has a low coefficient of restitution -- it doesn't really bounce on the floor -- whereas a basketball has a high coefficient of restitution. \n\nNote the restitution factor is applied on both the objects involved in the collision. In the image below, that means both the floor and each colliding ball. Restitution of 1.0 implies a perfectly elastic collision: kinetic energy is conserved and the ball will bounce right back up to its initial height. A value of 0.0 represents a completely inelastic collision: the ball will stick to the floor after colliding and have zero velocity.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/f0e1dfc-ezgif.com-crop_7.gif\",\n        \"ezgif.com-crop (7).gif\",\n        250,\n        250,\n        \"#b4a4a1\"\n      ]\n    }\n  ]\n}\n[/block]\n**Friction** is used to calculate the force of resistance an object encounters when moving across another. A value of 0.0 implies no friction, whereas a value of 1.0 implies high friction. When two physics bodies are in contact, their respective friction values are used to create a friction coefficient, which is in turn used to compute the applied frictional force for the two colliding objects. In other words, the friction values of both objects are considered. For example, a metal sword has a different coefficient of friction when rubbing against cloth than against wood.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/2096b1c-ezgif.com-crop_8.gif\",\n        \"ezgif.com-crop (8).gif\",\n        250,\n        250,\n        \"#bba3a3\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Physics World\"\n}\n[/block]\nWhile most physics parameters are set through the individual ```physicsBody``` properties of each object, there are some *global* physics properties that can be modified. These are accessed from the ```physicsWorld``` property in ```<ViroScene>```. The following properties are part of ```physicsWorld```:\n\n```gravity``` globally accelerates physics bodies in a specific direction. To make objects float without falling, set ```gravity``` to 0.0. The default is -9.8 m/s in the negative Y direction, to simulate gravity on Earth.\n\n```drawBounds``` will render lines representing the physics shapes for all physics objects in the scene. This is a useful tool for debugging physics bodies. It provides developers visual feedback on where the physics objects are, and how they interact with one another.\n[block:api-header]\n{\n  \"title\": \"Collision Events\"\n}\n[/block]\n**Colliding Objects** \n\nDevelopers can register for collision events that occur for a given Viro control. ```physicsBody``` has an onCollision callback property that is triggered when two physics bodies collide. As shown below, upon collision the collided point and normal are both returned in world coordinates. The ViroTag of the collided object is also returned, which can be used provide information to the callback about what the control has collided against. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"onCollision(collidedTag, collidedPoint, collidedNormal){\\n\\t// collidedPoint - Point at which the collision had occured, in world coords.\\n  // collidedNormal - The normal at the point of collision.\\n  // collidedTag - The ViroTag of the collided object.\\n},\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n**Physics Ray Hit Test** \n\nIn addition to registering for collision callbacks, developers can actively query the scene for collisions with ray intersection tests. This can be done in two ways:\n\n1) **findCollisionsWithRayAsync(from, to, closest, viroTag)**\nThis shoots a single ray into scene starting at ```from``` and ending at ```to```. The ```viroTag``` enables developers to identify this collisionRay event within the collisionCallback of all in-scene physics bodies. If only the nearest result is desired, set the ```closest``` flag to true. This function returns true if any objects have been hit.\n\n2) **findCollisionsWithShapeAsync(from, to, shapeString, shapeParam, viroTag)**\nThis method fires a physics shape into the scene and determines what physics objects collide with the shape. The ```shapeString``` is either \"box\" or \"sphere\", and ```shapeParam``` are shape parameters as described above for boxes and spheres. If ```from != to```, this method *only* invokes the callback of the closest object that has been hit. Otherwise, if ```from == to``` (if this isn't a collision test along a path), then the collision callback is triggered on all collided objects.\n\nYou can view those methods in greater detail [here](http://docs.viromedia.com/docs/viroscene#methods).\n[block:api-header]\n{\n  \"title\": \"PhysicsBody API\"\n}\n[/block]\n######Example use:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<ViroBox\\n\\tposition={[0,1,-3]}\\n  height={1} width={1} length={1}\\n\\tphysicsBody={{\\n\\t\\ttype:'dynamic', \\n    mass:1,\\n    force:{value:[0,0,1]},\\n    torque:[0,30,0],\\n    viroTag=\\\"MySpecialBox\\\",\\n    onCollision={this.onCollide}\\n  }}\\n/>\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"PropKey\",\n    \"h-1\": \"PropType\",\n    \"0-0\": \"**type**\",\n    \"0-1\": \"**PropTypes.oneOf(['dynamic','kinematic','static']).isRequired** \\n\\nThe type of this rigid body. See [here](http://docs.viromedia.com/docs/physics#section-physics-body-type) for more info.\",\n    \"1-0\": \"**mass** \",\n    \"1-1\": \"**PropTypes.number**\\n\\nThe mass of this physics body in kg.\",\n    \"2-0\": \"**shape** \",\n    \"2-1\": \"**PropTypes.shape({\\n        type: PropTypes.oneOf([\\\"box\\\", \\\"sphere\\\", \\\"compound\\\"]).isRequired,\\n        params: PropTypes.arrayOf(PropTypes.number)\\n      })**\\n\\nDescribes the shape that represents this physics body. If not specified, this is inferred from the geometry of the parent control. Users can specify the shape in the form below:\\n\\n|Physics Shapes |Description|\\n|:------|:----------:|\\n|box| Accepts [width, height, length] parameters used for creating the box.\\n|sphere| Accepts radius parameter.\\n|compound| Usually is set on VRONodes to encapsulate multiple objects in a compound shape. This is achieved by recursing down the scene graph and combining the geometries into a single compound physics shape.\\n\\nExample code: \\n```  \\nshape:{type:'box', params:[0.4,0.4,0.2]} \\nshape:{type:'sphere', params:[0.5]}\\n```\",\n    \"3-0\": \"**restitution** \",\n    \"3-1\": \"**PropTypes.number**\\n\\nThe bounciness of an object. Value of 0.0 will not bounce. Value of 1.0 will bounce without any loss of energy.\",\n    \"4-0\": \"**friction** \",\n    \"4-1\": \"**PropTypes.number**\\n\\nDetermines the force of resistance an object or surface encounters when moving across another. Value of 0.0 implies no friction. Value of 1.0 implies high friction.\",\n    \"5-0\": \"**useGravity** \",\n    \"5-1\": \"**PropTypes.bool**\\n\\nIf false, this physics object will ignore all gravitational forces that are applied on this object.\",\n    \"6-0\": \"**enabled** \",\n    \"6-1\": \"**PropTypes.bool**\\n\\nIf false, disables all physics properties on the Viro control (as if there were no physics bodies applied).\",\n    \"7-0\": \"**force** \",\n    \"7-1\": \"**PropTypes.oneOfType([\\n        PropTypes.arrayOf(PropTypes.shape({\\n          value: PropTypes.arrayOf(PropTypes.number),\\n          position: PropTypes.arrayOf(PropTypes.number)\\n        })),\\n        PropTypes.shape({\\n          value: PropTypes.arrayOf(PropTypes.number),\\n          position: PropTypes.arrayOf(PropTypes.number)\\n        }),\\n      ]),**\\n\\nA single force vector or an array of force vectors applied to the physics body. If an array of forces is provided, the corresponding net force will be applied. Force units are in newtons.\",\n    \"8-0\": \"**torque** \",\n    \"8-1\": \"**PropTypes.arrayOf(PropTypes.number)** \\n\\nA single torque vector or an array of torque vectors applied to the physics body. If an array of torque is provided, the corresponding net torque will be applied. Torque units are in newton meters.\",\n    \"9-0\": \"**velocity** \",\n    \"9-1\": \"**PropTypes.arrayOf(PropTypes.number)** \\n\\nUsed to directly move an object without applying a force. Units are m/s. Doing so will override any forces that are already applied on this physics body.\"\n  },\n  \"cols\": 2,\n  \"rows\": 10\n}\n[/block]","excerpt":"","slug":"physics","type":"basic","title":"Physics"}
Viro contains a simple but powerful Physics engine. This engine enables developers to build interactive experiences that simulate real world forces. This development guide will go through the basics of creating physics objects and offer an overview of the experiences that can be created with them. In Viro, almost every 3D control can be physics-enabled through the physicsBody property. For example, to make a ```<ViroBox>``` fall due to gravity, simply add a physicsBody property to the box with a mass and type, as shown below: [block:code] { "codes": [ { "code": "<ViroBox\n\tposition={[0,1,-3]}\n height={1} width={1} length={1}\n\tphysicsBody={{\n\t\ttype:'dynamic', mass:1\n }}\n/>", "language": "text" } ] } [/block] Each ```physicsBody``` must have a ```type``` that dictates the behavior of the physics body. Physics bodies may also be given a ```shape``` to represent the collision mesh of the body. This can be automatically inferred if not provided. ##Physics Body Type There are three types of physics bodies available in Viro: Dynamic, Kinematic, and Static. Each has unique movement and interaction behavior. Note also there is a mass requirement associated with each type. [block:parameters] { "data": { "h-0": "Property", "h-1": "Static RigidBody", "h-2": "Kinematic RigidBody", "h-3": "Dynamic RigidBody", "0-0": "Mass (in kg)", "1-0": "Movement Behavior", "2-0": "Collision Behavior", "0-1": "- Must have 0 mass.", "0-2": "- Must have 0 Mass.", "0-3": "- Positive Mass (cannot be negative).", "1-1": "- Cannot move.", "1-2": "- Can be moved under explicit developer/user control.", "1-3": "- Designed to be moved under simulation (you should not be directly manipulating / animating this object's position). \n- Can be moved by colliding against other objects, and in response to forces and impulse.", "2-1": "- Can collide only with dynamic bodies. \n- Least resource intensive. - Works well with static objects like floor, ground, etc.", "2-2": "- Can collide with dynamic bodies.\n- Does not collide with other other kinematic bodies or static bodies.\n- Cannot be influenced by dynamic bodies. \n- Behaves like a movable object with infinite mass during collisions (will always push objects away).\n- Works well with objects you wish to directly move with animations with fine movement detail.", "2-3": "- Can collide with any body type. \n- Works well with objects that do not have applied animations, and that are reactive to forces applied in the world." }, "cols": 4, "rows": 3 } [/block] ##Physics Body Shape After specifying a type, Viro will need to determine the actual shape of the physics object representing the control's geometry. This can be specified through the ```shape``` property in a ```physicsBody```. There are three kinds of shapes that the physics body accepts: *box*, *sphere*, and *compound*, as shown below. [block:image] { "images": [ { "image": [ "https://files.readme.io/1fadf1a-Screen_Shot_2017-09-18_at_5.54.01_PM.png", "Screen Shot 2017-09-18 at 5.54.01 PM.png", 381, 100, "#e42720" ] } ] } [/block] [block:parameters] { "data": { "h-0": "Shape", "h-1": "Parameters", "0-0": "box", "1-0": "sphere", "2-0": "compound", "0-1": "Accepts width, height, and length of the box in the form [w, h, l]. Will be centered around the origin of the control.", "1-1": "Accepts a radius parameter. Creates a sphere that will be centered around the origin of your control.", "2-1": "No parameters. Viro automatically iterates through the compound control's subtree and infers the physics shape." }, "cols": 2, "rows": 3 } [/block] Note that the shape property is optional. If none is provided, Viro automatically generates a physics box (or sphere) shape that roughly represents that geometric control. You can also toggle a debug flag on the scene to draw all meshes representing physics shapes. This is demonstrated in the image above, and is primarily used for debugging purposes (it comes at a significant performance cost). It is important to note that physics objects cannot be recursively stacked. That is, a Viro control that is physics-enabled cannot have sub-nodes or children that also have their own physics-enabled bodies. There is no hierarchy to physics bodies. Compound *shapes*, however -- where multiple geometric objects are compounded together to form a single physics body -- are supported in Viro. [block:api-header] { "title": "Physics Body Forces" } [/block] Applying forces to physics enabled Viro controls can be done through an object's ```physicsBody``` property. Viro automatically manages the reconciling of those forces on an object's transform when they are applied. ###Constant Forces Constant forces can be useful in situations for moving objects in constant motion; for example, when adding thrust to a spaceship being launched into the sky. To apply a constant directional force, set a single force (or an array of forces) on the physics body's ```force``` property. For each force, you can specify both its *magnitude* (in newtons) and its *location* (on the object). The location property is optional. [block:image] { "images": [ { "image": [ "https://files.readme.io/b455b72-ezgif.com-crop_3.gif", "ezgif.com-crop (3).gif", 250, 250, "#bba2a2" ] } ] } [/block] Rotational forces are also supported. To apply a constant rotational force, use the ```torque``` property. [block:image] { "images": [ { "image": [ "https://files.readme.io/6055046-ezgif.com-crop_4.gif", "ezgif.com-crop (4).gif", 250, 250, "#bba3a3" ] } ] } [/block] ###Impulsive Forces and Motion Impulse forces are useful in situations where you would like to apply an instantaneous burst of force to an object. These are often useful for launching projectile objects. Rotational impulses are supported as well. [block:image] { "images": [ { "image": [ "https://files.readme.io/51bc233-ezgif.com-crop_3.gif", "ezgif.com-crop (3).gif", 250, 250, "#baa1a1" ] } ] } [/block] ### Velocity Developers have access to finer control over object movement via the ```velocity``` property. Doing so will override any forces that are already applied to the object. ## Forces and Drag Behavior With Viro, the default behavior of drag events works with physics-enabled controls; users are still able to drag objects around the scene. Viro handles this by temporarily converting any dragged physics bodies into kinematic types during the drag, then switching back to the original types upon completion of the drag. This can be used to give users the ability to fling objects toward other dynamic-typed physics bodies. An example of this is shown below. [block:image] { "images": [ { "image": [ "https://files.readme.io/4ba68fc-ezgif.com-video-to-gif_1.gif", "ezgif.com-video-to-gif (1).gif", 600, 338, "#7e8b98" ], "caption": "Drag and drop physics bodies." } ] } [/block] [block:api-header] { "title": "Physics Body Properties" } [/block] Viro physics bodies have additional properties that the developer can tune to achieve different kinds of behavior. Two of these are friction and restitution. **Restitution** controls how "bouncy" an object or surface is. When two objects collide, some of the energy of the collision is used to deform the collided objects, some is used rebound the objects from one another, and some is lost to heat. Restitution is a measure of how much of that kinetic energy is used for objects to rebound from one another. To take a real-world example, a massive bowling bowl has a low coefficient of restitution -- it doesn't really bounce on the floor -- whereas a basketball has a high coefficient of restitution. Note the restitution factor is applied on both the objects involved in the collision. In the image below, that means both the floor and each colliding ball. Restitution of 1.0 implies a perfectly elastic collision: kinetic energy is conserved and the ball will bounce right back up to its initial height. A value of 0.0 represents a completely inelastic collision: the ball will stick to the floor after colliding and have zero velocity. [block:image] { "images": [ { "image": [ "https://files.readme.io/f0e1dfc-ezgif.com-crop_7.gif", "ezgif.com-crop (7).gif", 250, 250, "#b4a4a1" ] } ] } [/block] **Friction** is used to calculate the force of resistance an object encounters when moving across another. A value of 0.0 implies no friction, whereas a value of 1.0 implies high friction. When two physics bodies are in contact, their respective friction values are used to create a friction coefficient, which is in turn used to compute the applied frictional force for the two colliding objects. In other words, the friction values of both objects are considered. For example, a metal sword has a different coefficient of friction when rubbing against cloth than against wood. [block:image] { "images": [ { "image": [ "https://files.readme.io/2096b1c-ezgif.com-crop_8.gif", "ezgif.com-crop (8).gif", 250, 250, "#bba3a3" ] } ] } [/block] [block:api-header] { "title": "Physics World" } [/block] While most physics parameters are set through the individual ```physicsBody``` properties of each object, there are some *global* physics properties that can be modified. These are accessed from the ```physicsWorld``` property in ```<ViroScene>```. The following properties are part of ```physicsWorld```: ```gravity``` globally accelerates physics bodies in a specific direction. To make objects float without falling, set ```gravity``` to 0.0. The default is -9.8 m/s in the negative Y direction, to simulate gravity on Earth. ```drawBounds``` will render lines representing the physics shapes for all physics objects in the scene. This is a useful tool for debugging physics bodies. It provides developers visual feedback on where the physics objects are, and how they interact with one another. [block:api-header] { "title": "Collision Events" } [/block] **Colliding Objects** Developers can register for collision events that occur for a given Viro control. ```physicsBody``` has an onCollision callback property that is triggered when two physics bodies collide. As shown below, upon collision the collided point and normal are both returned in world coordinates. The ViroTag of the collided object is also returned, which can be used provide information to the callback about what the control has collided against. [block:code] { "codes": [ { "code": "onCollision(collidedTag, collidedPoint, collidedNormal){\n\t// collidedPoint - Point at which the collision had occured, in world coords.\n // collidedNormal - The normal at the point of collision.\n // collidedTag - The ViroTag of the collided object.\n},", "language": "javascript" } ] } [/block] **Physics Ray Hit Test** In addition to registering for collision callbacks, developers can actively query the scene for collisions with ray intersection tests. This can be done in two ways: 1) **findCollisionsWithRayAsync(from, to, closest, viroTag)** This shoots a single ray into scene starting at ```from``` and ending at ```to```. The ```viroTag``` enables developers to identify this collisionRay event within the collisionCallback of all in-scene physics bodies. If only the nearest result is desired, set the ```closest``` flag to true. This function returns true if any objects have been hit. 2) **findCollisionsWithShapeAsync(from, to, shapeString, shapeParam, viroTag)** This method fires a physics shape into the scene and determines what physics objects collide with the shape. The ```shapeString``` is either "box" or "sphere", and ```shapeParam``` are shape parameters as described above for boxes and spheres. If ```from != to```, this method *only* invokes the callback of the closest object that has been hit. Otherwise, if ```from == to``` (if this isn't a collision test along a path), then the collision callback is triggered on all collided objects. You can view those methods in greater detail [here](http://docs.viromedia.com/docs/viroscene#methods). [block:api-header] { "title": "PhysicsBody API" } [/block] ######Example use: [block:code] { "codes": [ { "code": "<ViroBox\n\tposition={[0,1,-3]}\n height={1} width={1} length={1}\n\tphysicsBody={{\n\t\ttype:'dynamic', \n mass:1,\n force:{value:[0,0,1]},\n torque:[0,30,0],\n viroTag=\"MySpecialBox\",\n onCollision={this.onCollide}\n }}\n/>", "language": "javascript" } ] } [/block] [block:parameters] { "data": { "h-0": "PropKey", "h-1": "PropType", "0-0": "**type**", "0-1": "**PropTypes.oneOf(['dynamic','kinematic','static']).isRequired** \n\nThe type of this rigid body. See [here](http://docs.viromedia.com/docs/physics#section-physics-body-type) for more info.", "1-0": "**mass** ", "1-1": "**PropTypes.number**\n\nThe mass of this physics body in kg.", "2-0": "**shape** ", "2-1": "**PropTypes.shape({\n type: PropTypes.oneOf([\"box\", \"sphere\", \"compound\"]).isRequired,\n params: PropTypes.arrayOf(PropTypes.number)\n })**\n\nDescribes the shape that represents this physics body. If not specified, this is inferred from the geometry of the parent control. Users can specify the shape in the form below:\n\n|Physics Shapes |Description|\n|:------|:----------:|\n|box| Accepts [width, height, length] parameters used for creating the box.\n|sphere| Accepts radius parameter.\n|compound| Usually is set on VRONodes to encapsulate multiple objects in a compound shape. This is achieved by recursing down the scene graph and combining the geometries into a single compound physics shape.\n\nExample code: \n``` \nshape:{type:'box', params:[0.4,0.4,0.2]} \nshape:{type:'sphere', params:[0.5]}\n```", "3-0": "**restitution** ", "3-1": "**PropTypes.number**\n\nThe bounciness of an object. Value of 0.0 will not bounce. Value of 1.0 will bounce without any loss of energy.", "4-0": "**friction** ", "4-1": "**PropTypes.number**\n\nDetermines the force of resistance an object or surface encounters when moving across another. Value of 0.0 implies no friction. Value of 1.0 implies high friction.", "5-0": "**useGravity** ", "5-1": "**PropTypes.bool**\n\nIf false, this physics object will ignore all gravitational forces that are applied on this object.", "6-0": "**enabled** ", "6-1": "**PropTypes.bool**\n\nIf false, disables all physics properties on the Viro control (as if there were no physics bodies applied).", "7-0": "**force** ", "7-1": "**PropTypes.oneOfType([\n PropTypes.arrayOf(PropTypes.shape({\n value: PropTypes.arrayOf(PropTypes.number),\n position: PropTypes.arrayOf(PropTypes.number)\n })),\n PropTypes.shape({\n value: PropTypes.arrayOf(PropTypes.number),\n position: PropTypes.arrayOf(PropTypes.number)\n }),\n ]),**\n\nA single force vector or an array of force vectors applied to the physics body. If an array of forces is provided, the corresponding net force will be applied. Force units are in newtons.", "8-0": "**torque** ", "8-1": "**PropTypes.arrayOf(PropTypes.number)** \n\nA single torque vector or an array of torque vectors applied to the physics body. If an array of torque is provided, the corresponding net torque will be applied. Torque units are in newton meters.", "9-0": "**velocity** ", "9-1": "**PropTypes.arrayOf(PropTypes.number)** \n\nUsed to directly move an object without applying a force. Units are m/s. Doing so will override any forces that are already applied on this physics body." }, "cols": 2, "rows": 10 } [/block]