Add permeability example and doc entry

demo/index.html

@@ -74,6 +74,7 @@ <h1>Matter.js Demo (Edge Build)</h1>
                     <option value="beachBalls">Beach Balls</option>
                     <option value="stress">Stress 1</option>
                     <option value="stress2">Stress 2</option>
+                    <option value="permeableObjects">Permeable Objects</option>
                 </select>
                 <input id="demo-reset" value="Reset" type="submit">
                 <div class="demo-view-source nav-links">

examples/permeableObjects.js

@@ -0,0 +1,70 @@
+(function() {
+
+    var World = Matter.World,
+        Bodies = Matter.Bodies,
+        Common = Matter.Common,
+        Events = Matter.Events;
+
+    Example.permeableObjects = function(demo) {
+        var engine = demo.engine,
+            world = engine.world,
+            sceneEvents = demo.sceneEvents;
+
+        var redColor = '#C44D58',
+            greenColor = '#C7F464';
+
+        var collider = Bodies.rectangle(400, 300, 500, 50, {
+            isPermeable: true,
+            isStatic: true,
+            render: {
+                strokeStyle: redColor,
+                fillStyle: 'transparent'
+            }
+        });
+
+        World.add(world, collider);
+
+        World.add(world,
+            Bodies.circle(400, 40, 30, {
+                render: {
+                    strokeStyle: greenColor,
+                    fillStyle: 'transparent'
+                }
+            })
+        );
+
+        sceneEvents.push(
+            Events.on(engine, 'collisionStart', function(event) {
+                var pairs = event.pairs;
+
+                for (var i = 0, j = pairs.length; i != j; ++i) {
+                    var pair = pairs[i];
+
+                    if (pair.bodyA === collider) {
+                        pair.bodyB.render.strokeStyle = redColor;
+                    } else if (pair.bodyB === collider) {
+                        pair.bodyA.render.strokeStyle = redColor;
+                    }
+                }
+            }),
+            Events.on(engine, 'collisionEnd', function(event) {
+                var pairs = event.pairs;
+
+                for (var i = 0, j = pairs.length; i != j; ++i) {
+                    var pair = pairs[i];
+
+                    if (pair.bodyA === collider) {
+                        pair.bodyB.render.strokeStyle = greenColor;
+                    } else if (pair.bodyB === collider) {
+                        pair.bodyA.render.strokeStyle = greenColor;
+                    }
+                }
+            })
+        );
+
+        var renderOptions = engine.render.options;
+        renderOptions.wireframes = false;
+        renderOptions.background = '#222';
+        renderOptions.showAngleIndicator = false;
+    };
+})();

src/body/Body.js

@@ -788,6 +788,14 @@ var Axes = require('../geometry/Axes');
      * @default false
      */
 
+    /**
+     * A flag that indicates whether a body is considered permeable. A permeable body triggers collision events, but doesn't react with colliding body physically.
+     *
+     * @property isPermeable
+     * @type boolean
+     * @default false
+     */
+
     /**
      * A flag that indicates whether the body is considered sleeping. A sleeping body acts similar to a static body, except it is only temporary and can be awoken.
      * If you need to set a body as sleeping, you should use `Sleeping.set` as this requires more than just setting this flag.