q5play 4.2.0 → 4.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "q5play",
-	"version": "4.2.0",
+	"version": "4.2.2",
 	"author": "quinton-ashley",
 	"license": "SEE LICENSE IN LICENSE.md",
 	"description": "A beginner friendly, web-based game engine that uses q5.js WebGPU for graphics and Box2D v3 WASM for physics.",

package/q5play.d.ts

@@ -84,26 +84,26 @@ declare global {
 		renderStats: boolean;
 
 		/**
-		 * "Made with q5play" [splash screen](https://en.wikipedia.org/wiki/Splash_screen) displayed during
-		 * initial page load by default.
+		 * "Made with q5play" [splash screen](https://en.wikipedia.org/wiki/Splash_screen)
+		 * displayed during initial page load by default.
 		 */
 		splashScreen(): Promise<void>;
 
 		/**
-		 * Runs automatically before each draw function call.
+		 * Runs automatically before each q5.draw function call.
 		 */
 		update(): void;
 
 		/**
-		 * Runs automatically after each draw function call.
+		 * Runs automatically after each q5.draw function call.
 		 */
-		postDraw(): void;
+		draw(): void;
 	}
 	const q5play: Q5Play;
 
 	/**
-	 * Box2D v3 ported to WASM is the physics engine that
-	 * q5play uses for its physics simulation.
+	 * Box2D v3 ported to WASM is used by
+	 * q5play to simulate physics.
 	 *
 	 * This variable enables direct access to the Box2D API for
 	 * advanced users who want to do things that aren't wrapped
@@ -1111,8 +1111,11 @@ declare global {
 
 		/**
 		 * Scales the the sprite.
-		 * @param x scaleX or uniform scale factor
-		 * @param y scaleY
+		 * 
+		 * Components can be negative to flip/mirror the sprite on an axis.
+		 * 
+		 * @param x horizontal scale factor or uniform scale factor for both axes
+		 * @param y vertical scale factor
 		 */
 		scaleBy(x: number, y?: number): void;
 
@@ -1154,6 +1157,7 @@ declare global {
 		/**
 		 * The sprite's speed along the surface of its collider(s),
 		 * like a conveyor belt.
+		 * Requires friction to be greater than 1 to have an effect.
 		 * @default 0
 		 */
 		get surfaceSpeed(): number;
@@ -3767,13 +3771,6 @@ declare global {
 		 */
 		y: number;
 
-		/**
-		 * The mouse's absolute position on the canvas.
-		 * @property {Number} x
-		 * @property {Number} y
-		 */
-		canvasPos: { x: number; y: number };
-
 		/**
 		 * The mouse's left button.
 		 */

package/q5play.js

@@ -19,14 +19,12 @@
 
 let q5play_version = '4.2';
 
-if (typeof globalThis.Q5 == 'undefined') {
+if (typeof globalThis.Q5 == 'undefined' && typeof globalThis.p5 == 'undefined') {
 	console.error('q5play requires q5.js to be loaded first. Visit https://q5js.org to learn more.');
-	if (typeof globalThis.p5 != 'undefined') {
-		console.error('p5.js is not compatible with q5play. https://github.com/processing/p5.js/issues/7737');
-	}
 }
 
-let box2dPromise;
+let box2dPromise,
+	using_p5 = false;
 
 // called when a new instance of Q5 is created
 async function q5playPreSetup(q) {
@@ -150,6 +148,7 @@ async function q5playPreSetup(q) {
 		b2CreateChain,
 		b2Chain_GetSegmentCount,
 		b2Chain_GetSegments,
+		b2DestroyChain,
 
 		/* Body */
 		b2BodyType,
@@ -249,7 +248,7 @@ async function q5playPreSetup(q) {
 			this.context = 'web';
 
 			this.update = () => q5playUpdate.call($, q);
-			this.postdraw = () => q5playPostDraw.call($, q);
+			this.draw = () => q5playPostDraw.call($, q);
 
 			if (window.matchMedia) {
 				this.hasMouse = window.matchMedia('(any-hover: none)').matches ? false : true;
@@ -327,7 +326,7 @@ async function q5playPreSetup(q) {
 
 		async splashScreen() {
 			if (document.getElementById('made-with-q5play')) return;
-			if (!using_p5v2) $._incrementPreload();
+			if (!using_p5) $._incrementPreload();
 			let d = document.createElement('div');
 			d.id = 'made-with-q5play';
 			d.style =
@@ -359,27 +358,30 @@ async function q5playPreSetup(q) {
 			d.style.display = 'none';
 			d.remove();
 			document.getElementById('made-with-q5play')?.remove();
-			if (!using_p5v2) $._decrementPreload();
+			if (!using_p5) $._decrementPreload();
 		}
 	};
 
 	$.q5play = new $.Q5Play();
 	delete $.Q5Play;
 
-	let using_p5v1 = !$._q5 && p5.VERSION[0] == 1;
-	let using_p5v2 = !$._q5 && p5.VERSION[0] == 2;
+	using_p5 = !$._q5;
+	if (using_p5 && p5.VERSION[0] != 2) {
+		throw new Error(`q5play requires q5.js or p5.js v2. Detected version: ${p5.VERSION}. Please upgrade.`);
+	}
 
-	// in q5play the default angle mode is degrees
 	const DEGREES = $.DEGREES,
 		DEGTORAD = Math.PI / 180,
 		RADTODEG = 180 / Math.PI;
+
+	// in q5play the default angle mode is degrees
 	$.angleMode(DEGREES);
 
 	// in q5play the default color mode is float RGB
-	$.colorMode($.RGB, 1);
+	if (!using_p5) $.colorMode($.RGB, 1);
 
 	// in q5play the default image mode is center
-	$.imageMode($.CENTER);
+	if (!using_p5) $.imageMode($.CENTER);
 
 	const ZERO_VEC = new b2Vec2(0, 0),
 		ZERO_ROT = b2MakeRot(0),
@@ -492,13 +494,13 @@ async function q5playPreSetup(q) {
 				geom = this.geom;
 
 			if (type == 0) {
-				let hw = geom._hw * scaleX,
-					hh = geom._hh * scaleY,
+				let hw = geom._hw * Math.abs(scaleX),
+					hh = geom._hh * Math.abs(scaleY),
 					rr;
 
 				if (!geom._rr) geom = b2MakeBox(hw, hh);
 				else {
-					rr = geom._rr * Math.min(scaleX, scaleY);
+					rr = geom._rr * Math.min(Math.abs(scaleX), Math.abs(scaleY));
 					geom = b2MakeRoundedBox(hw, hh, rr);
 				}
 				b2Shape_SetPolygon(id, geom);
@@ -506,11 +508,44 @@ async function q5playPreSetup(q) {
 				geom._hh = hh;
 				geom._rr = rr;
 				this.geom = geom;
+			} else if (type == 1) {
+				// convex polygon
+				geom = b2Shape_GetPolygon(id);
+				let verts = [];
+				for (let i = 0; i < geom.count; i++) {
+					const v = geom.GetVertex(i);
+					verts.push({ x: v.x * scaleX, y: v.y * scaleY });
+				}
+				let hull = b2ComputeHull(verts);
+				let rr = geom.radius * Math.min(scaleX, scaleY);
+				geom = rr ? b2MakeOffsetRoundedPolygon(hull, ZERO_VEC, ZERO_ROT, rr) : b2MakePolygon(hull, 0);
+				b2Shape_SetPolygon(id, geom);
+				this.geom = geom;
 			} else if (type == 3) {
-				geom.radius *= scaleX;
+				geom.radius *= Math.abs(scaleX);
 				b2Shape_SetCircle(id, geom);
 				this.geom = geom;
+			} else if (type == 4 || type == 7) {
+				// capsule (single or capsule chain segment)
+				geom = b2Shape_GetCapsule(id);
+				geom.center1.x *= scaleX;
+				geom.center1.y *= scaleY;
+				geom.center2.x *= scaleX;
+				geom.center2.y *= scaleY;
+				geom.radius *= Math.min(scaleX, scaleY);
+				b2Shape_SetCapsule(id, geom);
+				this.geom = geom;
+			} else if (type == 5) {
+				// segment
+				geom = b2Shape_GetSegment(id);
+				geom.point1.x *= scaleX;
+				geom.point1.y *= scaleY;
+				geom.point2.x *= scaleX;
+				geom.point2.y *= scaleY;
+				b2Shape_SetSegment(id, geom);
+				this.geom = geom;
 			}
+			// type 6 (chain) - handled by sprite's scaleBy, which rescales and sets all segments
 		}
 
 		_enableContactEvents(val = true) {
@@ -837,7 +872,13 @@ async function q5playPreSetup(q) {
 				if (flipY) ani.scale.y = -ani.scale.y;
 
 				if (start < 0) start = ani.length + start;
-				if (start !== undefined) ani._frame = start;
+				if (start !== undefined) {
+					ani._frame = start;
+				} else {
+					// reset so recycled animations don't immediately resolve
+					ani._frame = 0;
+					ani.playing = true;
+				}
 
 				if (end !== undefined) ani.goToFrame(end);
 				else if (ani._frame == ani.lastFrame) resolve();
@@ -954,7 +995,7 @@ async function q5playPreSetup(q) {
 
 			this._posX = x;
 			this._posY = y;
-			this._pos = $.createVector.call($);
+			this._pos = $.createVector.call($, 0, 0);
 
 			let _this = this;
 			Object.defineProperties(this._pos, {
@@ -976,7 +1017,7 @@ async function q5playPreSetup(q) {
 				}
 			});
 
-			this._canvasPos = $.createVector.call($);
+			this._canvasPos = $.createVector.call($, 0, 0);
 
 			Object.defineProperties(this._canvasPos, {
 				x: {
@@ -996,16 +1037,16 @@ async function q5playPreSetup(q) {
 			});
 
 			this._direction = 0;
-			this._velX = 0;
-			this._velY = 0;
+			this.vx = 0;
+			this.vy = 0;
 			this._velSynced = true;
-			this._vel = $.createVector.call($);
+			this._vel = $.createVector.call($, 0, 0);
 			this._vel._useCache = true;
 
 			this._syncVel = () => {
 				let v = b2Body_GetLinearVelocity(this.bdID);
-				this._velX = v.x;
-				this._velY = v.y;
+				this.vx = v.x;
+				this.vy = v.y;
 				this._velSynced = true;
 			};
 
@@ -1015,13 +1056,13 @@ async function q5playPreSetup(q) {
 						if (!_this._velSynced && _this._physicsEnabled) {
 							_this._syncVel();
 						}
-						return _this._velX;
+						return _this.vx;
 					},
 					set(val) {
 						if (_this._physicsEnabled) {
 							b2Body_SetLinearVelocity(_this.bdID, new b2Vec2(val, this.y));
 						}
-						_this._velX = val;
+						_this.vx = val;
 						this._magCached = this._directionCached = false;
 					}
 				},
@@ -1030,13 +1071,13 @@ async function q5playPreSetup(q) {
 						if (!_this._velSynced && _this._physicsEnabled) {
 							_this._syncVel();
 						}
-						return _this._velY;
+						return _this.vy;
 					},
 					set(val) {
 						if (_this._physicsEnabled) {
 							b2Body_SetLinearVelocity(_this.bdID, new b2Vec2(this.x, val));
 						}
-						_this._velY = val;
+						_this.vy = val;
 						this._magCached = this._directionCached = false;
 					}
 				}
@@ -1155,8 +1196,7 @@ async function q5playPreSetup(q) {
 				set(val) {
 					if (!val || val == this._x) return;
 					if (_this.watch) _this.mod[26] = true;
-					let scaleX = Math.abs(val / this._x);
-					_this.scaleBy(scaleX, 1);
+					_this.scaleBy(val / this._x, 1);
 					this._x = val;
 					this._avg = (this._x + this._y) * 0.5;
 					_this._shouldScale = this._avg != 1;
@@ -1170,8 +1210,7 @@ async function q5playPreSetup(q) {
 				set(val) {
 					if (!val || val == this._y) return;
 					if (_this.watch) _this.mod[26] = true;
-					let scaleY = Math.abs(val / this._y);
-					_this.scaleBy(1, scaleY);
+					_this.scaleBy(1, val / this._y);
 					this._y = val;
 					this._avg = (this._x + this._y) * 0.5;
 					_this._shouldScale = this._avg != 1;
@@ -1514,10 +1553,10 @@ async function q5playPreSetup(q) {
 							geom.center2 = vecs[i];
 							geom.radius = rr ? rr / meterSize : 0.02;
 							id = b2CreateCapsuleShape(bdID, shape.def, geom);
-							let shapePart = new Collider(this);
-							shape._init(id, 7, geom);
-							shapes.push(shapePart);
-							shapeDict[id.index1] = shapePart;
+							let sh = new Collider(this);
+							sh._init(id, 7, geom);
+							shapes.push(sh);
+							shapeDict[id.index1] = sh;
 						}
 						shape = null;
 						this.isSuperFast = true;
@@ -1535,12 +1574,17 @@ async function q5playPreSetup(q) {
 
 						id = b2CreateChain(bdID, shape.def);
 						shape._init(id, 6);
+						shape.friction = 0.5;
+						shape._points = vecs.map((v) => ({ x: v.x, y: v.y }));
+						shape._isLoopChain = vecs.isLoop;
+						this._chain = shape;
 
 						let count = b2Chain_GetSegmentCount(id);
 						let segments = b2Chain_GetSegments(id, count);
 						for (let segID of segments) {
 							let sh = new Collider(this);
 							sh._init(segID, 6);
+							sh.friction = 0.5;
 							shapes.push(sh);
 							shapeDict[segID.index1] = sh;
 						}
@@ -2090,17 +2134,85 @@ async function q5playPreSetup(q) {
 		scaleBy(x, y) {
 			if (y === undefined) y = x;
 
+			const ax = Math.abs(x),
+				ay = Math.abs(y);
+
 			if (this._shapes) {
 				for (let shape of this._shapes) {
 					shape.scaleBy(x, y);
 				}
 			}
 
-			this._w *= x;
-			this._hw *= x;
+			if (this._hasChain) this._rebuildChain(x, y);
+
+			this._w *= ax;
+			this._hw *= ax;
 			if (this._h) {
-				this._h *= y;
-				this._hh *= y;
+				this._h *= ay;
+				this._hh *= ay;
+			}
+		}
+
+		_rebuildChain(scaleX, scaleY) {
+			const chain = this._chain;
+			const shapes = this._shapes;
+
+			// save properties from existing segments before removing them
+			const firstCollider = this.colliders[0];
+			const savedFriction = firstCollider?._friction ?? 0.5;
+			const savedSurfaceSpeed = firstCollider?._tangentSpeed ?? 0;
+			const savedBounciness = firstCollider?._restitution ?? 0.2;
+			// negate surfaceSpeed when the chain is flipped (odd number of axes negated)
+			const newSurfaceSpeed = scaleX * scaleY < 0 ? -savedSurfaceSpeed : savedSurfaceSpeed;
+
+			// scale the stored points (already in Box2D meter coordinates)
+			for (let p of chain._points) {
+				p.x *= scaleX;
+				p.y *= scaleY;
+			}
+
+			// when an odd number of axes are negated, the winding order reverses,
+			// flipping the collision normal; reverse the point order to compensate
+			if (scaleX * scaleY < 0) chain._points.reverse();
+
+			// clean up old chain segment JS references
+			for (let i = shapes.length - 1; i >= 0; i--) {
+				if (shapes[i].type === 6) {
+					delete shapeDict[shapes[i].id.index1];
+					this.colliders.splice(this.colliders.indexOf(shapes[i]), 1);
+					shapes.splice(i, 1);
+				}
+			}
+
+			// destroy old chain (Box2D frees all segment physics objects)
+			b2DestroyChain(chain.id);
+
+			// recompute packed material data
+			const packedData = ((chain._isFirstShape ? 1 : 0) << 26) | this._uid;
+
+			// create new chain with scaled points
+			const chainDef = new b2DefaultChainDef();
+			chainDef.SetPoints([chain._points[0], ...chain._points, chain._points.at(-1)]);
+			chainDef.isLoop = chain._isLoopChain;
+			chainDef.SetMaterials([{ customColor: packedData }]);
+
+			const newId = b2CreateChain(this.bdID, chainDef);
+			chain._init(newId, 6);
+			chain.friction = savedFriction;
+			chain._tangentSpeed = newSurfaceSpeed;
+
+			// register new chain segments with restored properties
+			const count = b2Chain_GetSegmentCount(newId);
+			const segments = b2Chain_GetSegments(newId, count);
+			for (let segID of segments) {
+				let sh = new Collider(this);
+				sh._init(segID, 6);
+				sh.friction = savedFriction;
+				sh.bounciness = savedBounciness;
+				if (newSurfaceSpeed) sh.surfaceSpeed = newSurfaceSpeed;
+				shapes.push(sh);
+				this.colliders.push(sh);
+				shapeDict[segID.index1] = sh;
 			}
 		}
 
@@ -2124,10 +2236,7 @@ async function q5playPreSetup(q) {
 
 			if (this.watch) this.mod[26] = true;
 
-			let scaleX = Math.abs(x / sc._x);
-			let scaleY = Math.abs(y / sc._y);
-
-			this.scaleBy(scaleX, scaleY);
+			this.scaleBy(x / sc._x, y / sc._y);
 
 			sc._x = x;
 			sc._y = y;
@@ -2181,6 +2290,10 @@ async function q5playPreSetup(q) {
 		}
 		set surfaceSpeed(val) {
 			if (this.watch) this.mod[21] = true;
+			if (this._hasCapsuleChain) {
+				return console.error('Can not set surfaceSpeed of a capsule chain.');
+			}
+			if (this._hasChain) this._chain.surfaceSpeed = val;
 			for (let collider of this.colliders) {
 				collider.surfaceSpeed = val;
 			}
@@ -2412,12 +2525,19 @@ async function q5playPreSetup(q) {
 			this._setVel(val[0] ?? val.x, val[1] ?? val.y);
 		}
 
+		get velocity() {
+			return this._vel;
+		}
+		set velocity(val) {
+			this.vel = val;
+		}
+
 		_setVel(x, y) {
 			if (this._physicsEnabled) {
 				b2Body_SetLinearVelocity(this.bdID, new b2Vec2(x, y));
 			}
-			this._velX = x;
-			this._velY = y;
+			this.vx = x;
+			this.vy = y;
 			this._velSynced = true;
 			this._vel._magCached = this._vel._directionCached = false;
 		}
@@ -2426,18 +2546,11 @@ async function q5playPreSetup(q) {
 			if (this._physicsEnabled) {
 				b2Body_SetLinearVelocity(this.bdID, new b2Vec2(x, y));
 			}
-			this._velX = x;
-			this._velY = y;
+			this.vx = x;
+			this.vy = y;
 			this._velSynced = true;
 		}
 
-		get velocity() {
-			return this._vel;
-		}
-		set velocity(val) {
-			this.vel = val;
-		}
-
 		get grabbable() {
 			return this._grabbable;
 		}
@@ -2468,8 +2581,8 @@ async function q5playPreSetup(q) {
 			if (this._life <= 0) {
 				this.delete();
 			} else if (!this._physicsEnabled || !usePhysics) {
-				this._posX += this._velX * timeScale;
-				this._posY += this._velY * timeScale;
+				this._posX += this.vx * timeScale;
+				this._posY += this.vy * timeScale;
 				this._rotation += this._rotationSpeed * timeScale;
 			}
 
@@ -2776,8 +2889,9 @@ async function q5playPreSetup(q) {
 				args[2] = args[1];
 				args[1] = undefined;
 			}
-			let o = {};
-			o.forceVector = new b2Vec2(args[0], args[1]);
+			const v = this._args2Vec(args[0], args[1]),
+				o = {};
+			o.forceVector = new b2Vec2(v.x, v.y);
 			if (args[2] !== undefined) {
 				o.poa = this._args2Vec(args[2], args[3]);
 				o.poa = scaleTo(o.poa.x, o.poa.y);
@@ -2853,34 +2967,19 @@ async function q5playPreSetup(q) {
 			wind.delete();
 		}
 
-		moveTowards(x, y, tracking) {
-			if (x === undefined) return;
+		move(distance, direction, speed) {
+			if (!distance) return;
 
-			if (typeof x != 'number' && x !== null) {
-				let pos = x;
-				if (pos == $.mouse && !$.mouse.isActive) return;
-				tracking = y;
-				y = pos.y;
-				x = pos.x;
+			if (typeof direction == 'string') {
+				directionNamed = true;
+				this._heading = direction;
+				direction = this._getDirectionAngle(direction);
 			}
-			tracking ??= 0.1;
+			direction ??= this.direction;
 
-			let velX, velY;
-
-			if (x !== null && x !== undefined) {
-				let diffX = x - this.x;
-				if (!isSlop(diffX)) {
-					velX = diffX * tracking;
-				} else velX = 0;
-			} else velX = this._velX;
-			if (y !== null && y !== undefined) {
-				let diffY = y - this.y;
-				if (!isSlop(diffY)) {
-					velY = diffY * tracking;
-				} else velY = 0;
-			} else velY = this._velY;
-
-			this._setVel(velX, velY);
+			const x = $.cos(direction) * distance + this.x,
+				y = $.sin(direction) * distance + this.y;
+			return this.moveTo(x, y, speed);
 		}
 
 		moveTo(x, y, speed) {
@@ -2919,12 +3018,14 @@ async function q5playPreSetup(q) {
 				if (moveX && moveY) {
 					this.setSpeedAndDirection(speed, $.atan2(y - this.y, x - this.x));
 				} else if (moveX) {
-					this._setVel(x > this._posX ? speed : -speed, this._velY);
+					this._setVel(x > this._posX ? speed : -speed, this.vy);
 				} else {
-					this._setVel(this._velX, y > this._posY ? speed : -speed);
+					this._setVel(this.vx, y > this._posY ? speed : -speed);
 				}
 			}
 
+			if ($._py) return new Promise((resolve) => (this._destResolve = resolve));
+
 			return {
 				then: (onFulfilled) => {
 					this._destResolve = onFulfilled;
@@ -2932,6 +3033,36 @@ async function q5playPreSetup(q) {
 			};
 		}
 
+		moveTowards(x, y, tracking) {
+			if (x === undefined) return;
+
+			if (typeof x != 'number' && x !== null) {
+				let pos = x;
+				if (pos == $.mouse && !$.mouse.isActive) return;
+				tracking = y;
+				y = pos.y;
+				x = pos.x;
+			}
+			tracking ??= 0.1;
+
+			let velX, velY;
+
+			if (x !== null && x !== undefined) {
+				let diffX = x - this.x;
+				if (!isSlop(diffX)) {
+					velX = diffX * tracking;
+				} else velX = 0;
+			} else velX = this.vx;
+			if (y !== null && y !== undefined) {
+				let diffY = y - this.y;
+				if (!isSlop(diffY)) {
+					velY = diffY * tracking;
+				} else velY = 0;
+			} else velY = this.vy;
+
+			this._setVel(velX, velY);
+		}
+
 		angleTo(x, y, facing = 0) {
 			if (typeof x == 'object') {
 				facing = y || 0;
@@ -3023,7 +3154,7 @@ async function q5playPreSetup(q) {
 
 			this.rotationSpeed = speed;
 
-			log(this.rotation, this._destRot, angleDist, speed, this._destRotArrivalTime);
+			if ($._py) return new Promise((resolve) => (this._destRotationResolve = resolve));
 
 			return {
 				then: (onFulfilled) => {
@@ -4295,7 +4426,7 @@ async function q5playPreSetup(q) {
 			for (let vecProp of vecProps) {
 				vecProp = '_' + vecProp;
 				if (vecProp != 'vel') this[vecProp] = {};
-				else this[vecProp] = $.createVector.call($);
+				else this[vecProp] = $.createVector.call($, 0, 0);
 				this[vecProp]._x = undefined;
 				this[vecProp]._y = undefined;
 				for (let prop of ['x', 'y']) {
@@ -4755,6 +4886,21 @@ async function q5playPreSetup(q) {
 			for (let s of this) {
 				thenables.push(s.rotateTo(...arguments));
 			}
+
+			if ($._py) {
+				return new Promise((resolve) => {
+					let pending = thenables.length;
+					if (!pending) return resolve(true);
+					let allReached = true;
+					for (let t of thenables) {
+						t.then((reached) => {
+							if (!reached) allReached = false;
+							if (--pending === 0) resolve(allReached);
+						});
+					}
+				});
+			}
+
 			return {
 				then: (onFulfilled) => {
 					let pending = thenables.length;
@@ -4775,6 +4921,21 @@ async function q5playPreSetup(q) {
 			for (let s of this) {
 				thenables.push(s.rotate(...arguments));
 			}
+
+			if ($._py) {
+				return new Promise((resolve) => {
+					let pending = thenables.length;
+					if (!pending) return resolve(true);
+					let allReached = true;
+					for (let t of thenables) {
+						t.then((reached) => {
+							if (!reached) allReached = false;
+							if (--pending === 0) resolve(allReached);
+						});
+					}
+				});
+			}
+
 			return {
 				then: (onFulfilled) => {
 					let pending = thenables.length;
@@ -4795,6 +4956,21 @@ async function q5playPreSetup(q) {
 			for (let s of this) {
 				thenables.push(s.rotateMinTo(...arguments));
 			}
+
+			if ($._py) {
+				return new Promise((resolve) => {
+					let pending = thenables.length;
+					if (!pending) return resolve(true);
+					let allReached = true;
+					for (let t of thenables) {
+						t.then((reached) => {
+							if (!reached) allReached = false;
+							if (--pending === 0) resolve(allReached);
+						});
+					}
+				});
+			}
+
 			return {
 				then: (onFulfilled) => {
 					let pending = thenables.length;
@@ -4857,6 +5033,20 @@ async function q5playPreSetup(q) {
 				thenables.push(s.moveTo(tx, ty, speed));
 			}
 
+			if ($._py) {
+				return new Promise((resolve) => {
+					let pending = thenables.length;
+					if (!pending) return resolve(true);
+					let allReached = true;
+					for (let t of thenables) {
+						t.then((reached) => {
+							if (!reached) allReached = false;
+							if (--pending === 0) resolve(allReached);
+						});
+					}
+				});
+			}
+
 			return {
 				then: (onFulfilled) => {
 					let pending = thenables.length;
@@ -5686,7 +5876,7 @@ async function q5playPreSetup(q) {
 	$.Camera = class {
 		constructor() {
 			// camera position
-			this._pos = $.createVector.call($);
+			this._pos = $.createVector.call($, 0, 0);
 
 			// camera translation
 			this.__pos = { x: 0, y: 0, rounded: {} };
@@ -6956,10 +7146,18 @@ async function q5playPreSetup(q) {
 	};
 
 	$.delay = (milliseconds) => {
-		if (!milliseconds) return new Promise(requestAnimationFrame);
+		if (!milliseconds) {
+			return new Promise((resolve) => {
+				requestAnimationFrame(() => {
+					if (!$._removed) resolve();
+				});
+			});
+		}
 		// else it wraps setTimeout in a Promise
 		return new Promise((resolve) => {
-			setTimeout(resolve, milliseconds);
+			setTimeout(() => {
+				if (!$._removed) resolve();
+			}, milliseconds);
 		});
 	};
 
@@ -7009,6 +7207,8 @@ async function q5playPreSetup(q) {
 	$.Canvas = $.createCanvas = function (w, h) {
 		let args = [...arguments];
 
+		if (using_p5 && !didCreateCanvas && w == 100 && h == 100) return _createCanvas.call($, ...args);
+
 		// prevent p5 v1 overriding the user's canvas with a new default canvas
 		if (didCreateCanvas && w == 100 && h == 100) return;
 
@@ -7039,7 +7239,7 @@ async function q5playPreSetup(q) {
 		let rend = _createCanvas.call($, ...args);
 		$.ctx = $.drawingContext;
 		let c = rend.canvas || rend;
-		window.canvas = c; // for p5 v2
+		if (using_p5) window.canvas = c;
 		if (rend.GL) {
 			c.renderer = 'webgl';
 			$._webgl = true;
@@ -7106,7 +7306,7 @@ async function q5playPreSetup(q) {
 		return rend;
 	};
 
-	$.canvas = $.canvas;
+	$.canvas = $.canvas; // for brython
 
 	const _resizeCanvas = $.resizeCanvas;
 
@@ -7234,7 +7434,7 @@ async function q5playPreSetup(q) {
 
 	$.allSprites = new $.Group();
 	$.world = new $.World();
-	$.camera = new $.Camera();
+	$.camera = $._camera = new $.Camera();
 
 	$.InputDevice = class {
 		constructor() {
@@ -7309,7 +7509,6 @@ async function q5playPreSetup(q) {
 
 			this.x = 0;
 			this.y = 0;
-			this.canvasPos = {};
 			this.isOnCanvas = false;
 			this.isActive = false;
 			this.left = 0;
@@ -7321,7 +7520,7 @@ async function q5playPreSetup(q) {
 			let _this = this;
 
 			// this.x and this.y store the actual position values of the mouse
-			this._pos = $.createVector.call($);
+			this._pos = $.createVector.call($, 0, 0);
 
 			Object.defineProperty(this._pos, 'x', {
 				get() {
@@ -7362,10 +7561,20 @@ async function q5playPreSetup(q) {
 		}
 
 		_update() {
-			let cam = $.camera;
-			let m = this;
-			m.x = $.mouseX / cam.zoom + cam.x;
-			m.y = $.mouseY / cam.zoom + cam.y;
+			let cam = $.camera,
+				m = this,
+				mx = $.mouseX,
+				my = $.mouseY;
+
+			if (using_p5) {
+				if ($._webgpuFallback) {
+					mx -= $.halfWidth;
+					my -= $.halfHeight;
+				}
+			}
+
+			m.x = mx / cam.zoom + cam.x;
+			m.y = my / cam.zoom + cam.y;
 
 			if (m.scroll < 0) m.scroll = 0;
 			if (m.scrollDelta.x == 0 && m.scrollDelta.y == 0) {
@@ -8099,7 +8308,7 @@ async function q5playPreSetup(q) {
 			this[indexB] = tmp;
 			if (indexA == 0 || indexB == 0) {
 				$.contro = this[0];
-				if (!$._q5 && $._isGlobal) {
+				if (using_p5 && $._isGlobal) {
 					window.contro = this[0];
 				}
 			}
@@ -8186,7 +8395,7 @@ async function q5playPreSetup(q) {
 		fpsPos = 0,
 		fpsMin = 60,
 		fpsMax = 240;
-	let statsColor = $.color('lime');
+	let statsColor = $._q5 ? $.color('lime') : 'lime';
 
 	$.renderStats = () => {
 		let rs = $.q5play._renderStats;
@@ -8288,12 +8497,22 @@ async function q5playPreSetup(q) {
 		shapeStack = [];
 
 	const colorMax = $._colorFormat,
-		debugGreen = $.color(0, colorMax, 0, colorMax * 0.9),
-		debugGreenFill = $.color(0, colorMax, 0, colorMax * 0.1),
-		debugYellow = $.color(colorMax, colorMax, 0, colorMax * 0.9),
-		debugYellowFill = $.color(colorMax, colorMax, 0, colorMax * 0.1);
-
-	if ($.canvas.c2d) {
+		debugGreen = $._q5 ? $.color(0, colorMax, 0, colorMax * 0.9) : 'lime',
+		debugGreenFill = $._q5 ? $.color(0, colorMax, 0, colorMax * 0.1) : 'lime',
+		debugYellow = $._q5 ? $.color(colorMax, colorMax, 0, colorMax * 0.9) : 'yellow',
+		debugYellowFill = $._q5 ? $.color(colorMax, colorMax, 0, colorMax * 0.1) : 'yellow';
+
+	if (using_p5) {
+		$._getFillIdx = () => $._renderer.states.fillColor;
+		$._setFillIdx = (v) => $.fill(v);
+		$._getStrokeIdx = () => $._renderer.states.strokeColor;
+		$._setStrokeIdx = (v) => {
+			if ($._renderer.states.strokeSet) $.stroke(v);
+		};
+		$._getStrokeWeight = () => [$._renderer.states.strokeWeight];
+		$._setStrokeWeight = (v) => $.strokeWeight(...v);
+		$._getImageMode = () => $._renderer.states.imageMode;
+	} else if ($.canvas.c2d) {
 		// polyfill for q5 WebGPU high efficiency functions
 		$._getFillIdx = () => $._fill;
 		$._setFillIdx = (v) => ($._fill = v);
@@ -8479,12 +8698,17 @@ async function q5playPreSetup(q) {
 	};
 
 	// prettier-ignore
-	let q5playGlobals = ['q5play','Box2D','DYN','DYNAMIC','STA','STATIC','KIN','KINEMATIC','Sprite','Group','allSprites','Ani','Anis','Visual','Visuals','camera','Joint','GlueJoint','DistanceJoint','WheelJoint','HingeJoint','SliderJoint','GrabberJoint','world','kb','keyboard','mouse','contro','contros','controllers','pointer','pointers','spriteArt','EmojiImage','getFPS','animation','parseTextureAtlas','delay'];
+	let q5playGlobals = ['q5play','Box2D','DYN','DYNAMIC','STA','STATIC','KIN','KINEMATIC','Sprite','Group','allSprites','Ani','Anis','Visual','Visuals','Joint','GlueJoint','DistanceJoint','WheelJoint','HingeJoint','SliderJoint','GrabberJoint','world','kb','keyboard','mouse','contro','contros','controllers','pointer','pointers','spriteArt','EmojiImage','getFPS','animation','parseTextureAtlas','delay'];
 
 	// manually propagate q5play stuff to the global window object
 	if ($._isGlobal) {
 		for (let p of q5playGlobals) {
-			window[p] = $[p];
+			Object.defineProperty(window, p, {
+				value: $[p],
+				configurable: true,
+				writable: false,
+				enumerable: true
+			});
 		}
 	}
 
@@ -8495,10 +8719,31 @@ async function q5playPreSetup(q) {
 function q5playPostSetup() {
 	const $ = this;
 
-	if ($._isGlobal && window.update) {
-		$.update = window.update;
+	if ($._isGlobal && window.update) $.update = window.update;
+
+	if (using_p5) {
 		// p5 won't run the draw loop without a draw function defined
-		if (!$._q5) window.draw = () => {};
+		window.draw = () => {};
+
+		$.loge = $.log;
+		$.log = console.log;
+		$.camera = $._camera;
+
+		if ($._isGlobal) {
+			Object.defineProperty(window, 'log', {
+				value: console.log
+			});
+			Object.defineProperty(window, 'loge', {
+				value: $.loge
+			});
+			$.camera3D = window.camera;
+			Object.defineProperty(window, 'camera3D', {
+				value: $.camera3D
+			});
+			Object.defineProperty(window, 'camera', {
+				value: $.camera
+			});
+		}
 	}
 
 	$.update ??= $.clear;
@@ -8510,9 +8755,11 @@ function q5playPostSetup() {
 function q5playUpdate() {
 	const $ = this;
 
-	if (!$._q5) {
+	if (using_p5) {
 		$.q5play._preDrawFrameTime = performance.now();
+		$.resetMatrix();
 	}
+
 	$.q5play.spritesDrawn = 0;
 
 	$.contros._update();
@@ -8655,7 +8902,7 @@ function q5playPostDraw() {
 		else if ($.kb[k] > 0) $.kb[k]++;
 	}
 
-	if (!$._q5) {
+	if (using_p5) {
 		$.q5play._postDrawFrameTime = performance.now();
 		$.q5play._fps = Math.round(1000 / ($.q5play._postDrawFrameTime - $.q5play._preDrawFrameTime)) || 1;
 	}
@@ -8663,6 +8910,7 @@ function q5playPostDraw() {
 }
 
 function q5playRemove() {
+	this._removed = true;
 	this.world?.delete();
 }
 
@@ -8747,15 +8995,19 @@ addAnis -> es:añadirAnis
 changeAni -> es:cambiarAni
 playAni -> es:reproducirAni
 playAnis -> es:reproducirAnis
+moveTo -> es:moverA
 moveTowards -> es:moverHacia
+rotateTo -> es:rotarA
 rotateTowards -> es:rotarHacia
+transformTowards -> es:transformarHacia
 applyForce -> es:aplicarFuerza
 applyForceScaled -> es:aplicarFuerzaEscalada
 attractTo -> es:atraerA
 repelFrom -> es:repelerDe
 applyTorque -> es:aplicarTorque
-angleTo -> es:ánguloHacia
-angleDistTo -> es:distÁnguloHacia
+applyWind -> es:aplicarViento
+angleTo -> es:ánguloA
+angleDistTo -> es:distÁnguloA
 setSpeedAndDirection -> es:establecerVelocidadYDirección
 scaleBy -> es:escalarPor
 resetMass -> es:reiniciarMasa
@@ -8859,6 +9111,56 @@ pressure -> es:presión
 };
 q5playClassLangs.Group += q5playClassLangs.Sprite;
 
+if (typeof globalThis.Q5 == 'undefined') {
+	console.warn('p5.js v2 is not fully compatible with q5play. Consider using q5 instead: https://q5js.org');
+
+	p5.addHook = (hook, fn) => {
+		p5.registerAddon((p5, proto, lifecycles) => {
+			lifecycles[hook] = fn;
+		});
+	};
+
+	// p5.js v2 compatibility layer
+	globalThis.Canvas = (...args) => {
+		return new Promise((resolve) => {
+			window.setup = async function () {
+				const $ = p5.instance;
+				$._webgpu = $._webgpuFallback = true;
+
+				$.Canvas(...args);
+
+				// q5play defaults
+				colorMode(RGB, 1);
+				imageMode(CENTER);
+
+				$.halfWidth = width / 2;
+				$.halfHeight = height / 2;
+
+				let _resetMatrix = $.resetMatrix;
+
+				$.resetMatrix = () => {
+					_resetMatrix.call($);
+					$.translate($.halfWidth, $.halfHeight);
+				};
+
+				Object.defineProperty(p5, 'update', {
+					set(fn) {
+						$.update = fn;
+					},
+					get() {
+						return $.update;
+					},
+					configurable: true
+				});
+
+				resolve();
+			};
+		});
+	};
+
+	globalThis.Q5 = globalThis.q5 = p5;
+}
+
 Q5.addHook('presetup', q5playPreSetup);
 Q5.addHook('postsetup', q5playPostSetup);
 Q5.addHook('predraw', q5playUpdate);

package/q5play.pyi

@@ -86,25 +86,25 @@ class Q5Play:
 
     def splashScreen(self) -> Awaitable[None]:
         """
-        "Made with q5play" [splash screen](https://en.wikipedia.org/wiki/Splash_screen) displayed during
-        initial page load by default.
+        "Made with q5play" [splash screen](https://en.wikipedia.org/wiki/Splash_screen)
+        displayed during initial page load by default.
         """
         ...
 
     def update(self) -> None:
-        """Runs automatically before each draw function call."""
+        """Runs automatically before each q5.draw function call."""
         ...
 
-    def postDraw(self) -> None:
-        """Runs automatically after each draw function call."""
+    def draw(self) -> None:
+        """Runs automatically after each q5.draw function call."""
         ...
 
 q5play: Q5Play
 
 Box2D: Any
 """
-Box2D v3 ported to WASM is the physics engine that
-q5play uses for its physics simulation.
+Box2D v3 ported to WASM is used by
+q5play to simulate physics.
 
 This variable enables direct access to the Box2D API for
 advanced users who want to do things that aren't wrapped
@@ -1271,9 +1271,11 @@ class Sprite(Visual):
         """
         Scales the the sprite.
 
+        Components can be negative to flip/mirror the sprite on an axis.
+
         Args:
-            x: scaleX or uniform scale factor
-            y: scaleY
+            x: horizontal scale factor or uniform scale factor for both axes
+            y: vertical scale factor
         """
         ...
 
@@ -1328,6 +1330,7 @@ class Sprite(Visual):
         """
         The sprite's speed along the surface of its collider(s),
         like a conveyor belt.
+        Requires friction to be greater than 1 to have an effect.
 
         Default: `0`
         """
@@ -4398,9 +4401,6 @@ class _Mouse(InputDevice):
     y: float
     """The mouse's y position in the world."""
 
-    canvasPos: dict
-    """The mouse's absolute position on the canvas."""
-
     left: float
     """The mouse's left button."""