World
Each instance of q5play has its own world object, that can be used to control the
Box2D physics simulation. Its most important property is gravity, which has x and y
components.
Note that the physics simulation is deterministic. That means if you run the same code twice, unless you're using random values, you'll get the same result!
Sleeping
world.allowSleeping is true by default.
A sprite starts "sleeping" when it stops moving and doesn't collide with anything new. "Sleeping" sprites get ignored during physics simulation, which usually prevents the Box2D physics engine solver from having to make unnecessary calculations. While this is good for performance, sometimes it can cause problems.
You can wake up a sleeping sprite by setting sprite.sleeping to false. You can also
disable sleeping on a per sprite basis by setting sprite.allowSleeping to false.
Controlling Time
The world.timeScale ratio is set to 1 by default for real time physics simulation.
Set it lower for slow motion. Make it 0 to pause time!
Note that the Box2D physics engine solver is only stable up to a time scale of 2. If you want to
advance the simulation by a larger amount of time, run the world.physicsUpdate
function multiple times.
Click the canvas in the example to make the physics simulation progress in slow motion, 1/4th real time. The Matrix bullet time effect is achieved by making the background of each frame slightly transparent.
world.realTime stores how many real time seconds have elapsed since the start of the
world, including pauses.
world.physicsTime stores how many seconds have elapsed in the physics simulation.
Performance Testing
Set q5play.renderStats to true to display the number of sprites being drawn and FPS
calculations. For more comprehensive results, use your web browser's performance testing tools.
FPS in this context refers to how many frames per second your computer can generate, not including the delay between when frames are actually shown on the screen. The higher the FPS, the better your game is performing.
Generally, having less sprites will make your game perform better.
By default the Box2D physics engine performs 4 substeps each physics update. Decreasing the value of
world.subSteps will make the simulation faster but also less accurate.
I've tested q5play in every web browser and found that Google Chrome performs the best.
Find Sprites
Get an array of sprites found within a point or circle with the world.getSpritesAt
function.
world.getSpriteAt returns the first sprite found, the one with the highest layer value.
Note that sprites must have a collider or overlap sensor to be detected.
Try moving the mouse to make balls stop moving in the example!
Ray Casting
The world.rayCastAll function finds all the sprites (with physics colliders) that
intersects a ray (line).
The world.rayCast function is similar, but only returns the first sprite.
Provide these functions with the ray's start and end points.
Alternatively, set the ray's starting point, direction, and optionally the maximum distance it should travel.
The returned array of sprites is sorted by distance from the ray's starting point, with the closest
sprite first. Each sprite has a sprite.cast object which stores:
intersect: point where the ray intersects the spriteincidence: angle of incidence between the ray and the surface of the sprite at the point of intersectiondistance: distance from the ray's starting point to the point of intersection
Try moving the mouse in the example, when the ray intersects with a sprite, it becomes orange.
Circle Casting
The world.circleCastAll function finds all the sprites (with physics colliders) that
intersects a moving circle.
The world.circleCast function is similar, but only returns the first sprite.
Provide these functions with the cast's start and end points and the radius of the circle.
Just like with ray casting, each sprite that intersects the circle cast is given a
sprite.cast object.
Meter Size
The default world.meterSize is 60, so a sprite with a width of 60 units will be 1 meter
wide in the physics simulation.
The physics simulation can't run well when sprites are too small or too big. Keep the sizing human scale!
Explosions
world.explodeAt applies an explosive force to sprites within the radius of the
explosion!
Try changing the blast radius.
Check out the domino pyramids demo to make super big explosions!