Hype Matter Helper (little functions and helper for Physics ⚛)

Version 1.0.0 is a quick drop on GitHub:

4 Likes

That's a LOT of code for a little action. I'm not a programer at all though. I don't doubt your abilities. I've seen you up to your eyeballs in code on this forum before. Maybe I should read through it and learn something for a change! lol. Great work though. I just happen to be playing with the physics part of hype myself lately. but with no code... so this interests me.
thanks,
Randy

1 Like

There are many more functions in there, and in production you will use the minified version of this (1.32KB gzipped, 3.5KB uncompressed). It includes extensive comments to understand it better if you want to tweak it.

Targeting

This function is used to allow a "target" that can either be a Node (querySelector), Nodelist (querySelectorAll) or a selector as a string. This allows to pass in your own node, nodelist or use a selector string that is executed below the current scene element.

hypeDocument.resolveTargetToNodeList

These functions allow batch add or remove a class from a target

hypeDocument.addClassToTarget
hypeDocument.removeClassFromTarget 

Here is a simple example:

// adds the class hello-world to all balls in the scene
hypeDocument.addClassToTarget('.ball', 'hello-world');

// remove the class hello-world to all balls in the scene
hypeDocument.removeClassFromTarget('.ball', 'hello-world');

// remove the class hello-world to all balls in the scene and recursive from the descendants
hypeDocument.removeClassFromTarget('.ball', 'hello-world', true);

Disabling pointer event (recursive)

The approach to disable pointer events is class-based because pointer events work on an individual element and not it's descendants. Meaning, using only element.style.pointerEvents = 'none'; doesn't prevent clicks on descendants of the group (or symbols). The class-based approach implements an universal selector that is added to your page:

.disable-pointer-events, .disable-pointer-events * {
    pointer-events: none !important;
}

To disable pointer events from an element, symbol or group, you can assign the class .disablePointerEvents in the Hype IDE. The class definition is automatically added to the page context when Hype Matter Event is loaded (in HypeDocumentLoad). The following functions enable removing or adding the class dynamically. They are basically a thin wrapper for addClassToTarget in combination with making the necessary class available.

hypeDocument.disablePointerEvents
hypeDocument.enablePointerEvents 

Here is a simple example:

// remove pointer events on all balls
hypeDocument.disablePointerEvents('.ball');

Intersection detection

These functions are documented in code and allow checking if a set of elements intersect based on an element, point or ray. These functions come in very handy for any type of interactive games and are used in Hype Gesture (drag'n'drop).

hypeDocument.queryIntersections
hypeDocument.queryIntersectionsByPoint
hypeDocument.queryIntersectionsByRay

Simple collision group management

The Matter engine uses a group-based system to match collisions. In this case, we are applying or re-enabling a non-collision-group (negative number, see Body - Matter.js Physics Engine API Docs - matter-js 0.17.0). You can undoubtedly use (bit) masks and more to create collision filters for games, but these functions are only to disable and enable collision entirly.

hypeDocument.disablePhysicsCollisions
hypeDocument.enablePhysicsCollisions

Here is a simple example:

// disable collisions on all balls
hypeDocument.disablePhysicsCollisions('.ball');

Matter API simplification / helper

This will be the part that get the most new functions in coming releases. Starting with applyForce as reading through the forum has shown me that it is the most request function and also the function most use wrong. So, I tried to make it as simple to use as possible. The Matter Body API requires a position and a force to be applied to an object. The complete angular momentum and velocity results from combining these values with the position of the object itself. To make things simple the applyForce function in Hype Matter Events assumes the position for the force to be based on the object's transform origin and with an unit vector dimension based on an angle times a force. This makes applying force magnitude really reliable and easy. Furthermore, there is a variation/alias of applyForce called applyForceBasedOnMass (enabling a flag called usePercentOfMass). This allows to apply a force based on a percentage of the mass of an object. Giving all objects a similar velocity as a result, no matter the mass.

You can still provide any absolute or relative position

hypeDocument.applyForce
hypeDocument.applyForceBasedOnMass

Here is a simple example:

// apply force to all balls with force 10 and angle -90 (=upwards, 0=left)
hypeDocument.applyForce('.ball', 10, -90);

// apply force based on 5% of the objects mass
// balls of different sizes have the same velocity afterwards
hypeDocument.applyForceBasedOnMass('.ball', 5, -90);

// add a slightly off center position to apply the force to (relative to the object center). This results in an angular momentum (turning object) while also receiving velocity
hypeDocument.applyForceBasedOnMass('.ball', 10, -90,  {
 	position: {
		x: Math.random()*200-100,
 		y: Math.random()*200-100,
 		relative: true
 	}
}););

3 Likes