q5play 4.2.0 → 4.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "q5play",
-	"version": "4.2.0",
+	"version": "4.2.3",
 	"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) {
@@ -667,6 +702,8 @@ async function q5playPreSetup(q) {
 			if (typeof val == 'string') {
 				if (!val.includes('.')) {
 					val = new $.EmojiImage(val, this.w);
+				} else if (using_p5) {
+					return this._setP5Img(val);
 				} else val = $.loadImage(val);
 			}
 			this._img = this._extendImage(val);
@@ -695,6 +732,13 @@ async function q5playPreSetup(q) {
 			return img;
 		}
 
+		async _setP5Img(val) {
+			// for p5 v2 compatibility
+			let img = await $.loadImage(val);
+			this._img = this._extendImage(img);
+			this._hasImagery = true;
+		}
+
 		addAni() {
 			let args = [...arguments];
 			let ani, name;
@@ -837,7 +881,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 +1004,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 +1026,7 @@ async function q5playPreSetup(q) {
 				}
 			});
 
-			this._canvasPos = $.createVector.call($);
+			this._canvasPos = $.createVector.call($, 0, 0);
 
 			Object.defineProperties(this._canvasPos, {
 				x: {
@@ -996,16 +1046,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 +1065,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,18 +1080,42 @@ 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;
 					}
 				}
 			});
 
+			if (using_p5) {
+				this._vel.direction = function () {
+					if (!this._directionCached) {
+						const x = this.x,
+							y = this.y;
+						if (x || y) this._direction = $.atan2(this.y, this.x);
+						else this._direction = 0;
+						this._directionCached = this._useCache;
+					}
+					return this._direction;
+				};
+
+				this._vel.setDirection = function (ang) {
+					let mag = this.mag();
+					if (mag) {
+						this.x = mag * $.cos(ang);
+						this.y = mag * $.sin(ang);
+					}
+					this._direction = ang;
+					this._directionCached = this._useCache;
+					return this;
+				};
+			}
+
 			this._heading = 'right';
 
 			if (group._layer) this.layer = group._layer;
@@ -1155,8 +1229,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 +1243,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 +1586,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 +1607,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 +2167,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 +2269,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 +2323,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 +2558,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 +2579,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 +2614,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 +2922,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 +3000,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;
-
-			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;
+			direction ??= this.direction;
 
-			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 +3051,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 +3066,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 +3187,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) => {
@@ -3480,6 +3644,12 @@ async function q5playPreSetup(q) {
 
 			// image sequence format
 			if (args.length == 2 && typeof args[0] == 'string' && typeof args[1] == 'string' && !args[1].includes('.')) {
+				if (using_p5) {
+					throw new Error(
+						'p5.js v2 does not support preloading or lazy loading images. Convert the image sequence to a sprite sheet.'
+					);
+				}
+
 				let file = args[0],
 					extIndex = file.lastIndexOf('.'),
 					digits = 0;
@@ -3634,7 +3804,9 @@ async function q5playPreSetup(q) {
 					if (typeof sheet == 'string') {
 						sheet = $.loadImage(sheet);
 					}
-					sheet.promise.then(() => {
+					let promise = !using_p5 ? sheet.promise : sheet;
+					promise.then((img) => {
+						if (using_p5) this.spriteSheet = sheet = img;
 						if (!this.length) findFrames();
 
 						if (this._clones) {
@@ -3656,7 +3828,11 @@ async function q5playPreSetup(q) {
 			else {
 				for (let i = 0; i < args.length; i++) {
 					if (args[i] instanceof Q5.Image) this.push(args[i]);
-					else this.push($.loadImage(args[i]));
+					else if (using_p5) {
+						throw new Error(
+							'p5.js v2 does not support preloading or lazy loading images. You need to use `await load(url)`.'
+						);
+					} else this.push($.loadImage(args[i]));
 				}
 			}
 
@@ -4025,6 +4201,8 @@ async function q5playPreSetup(q) {
 			if (typeof val == 'string') {
 				if (!val.includes('.')) {
 					val = new $.EmojiImage(val, this.w || this.width || this.d || this.diameter);
+				} else if (using_p5) {
+					return $.Visual.prototype._setP5Img(val);
 				} else val = $.loadImage(val);
 			}
 			this._img = $.Visual.prototype._extendImage(val);
@@ -4295,7 +4473,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 +4933,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 +4968,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 +5003,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 +5080,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 +5923,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 +7193,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 +7254,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,11 +7286,18 @@ async function q5playPreSetup(q) {
 		let rend = _createCanvas.call($, ...args);
 		$.ctx = $.drawingContext;
 		let c = rend.canvas || rend;
-		window.canvas = c; // for p5 v2
-		if (rend.GL) {
-			c.renderer = 'webgl';
-			$._webgl = true;
-		} else if (!$._webgpu) $._c2d = true;
+		if (using_p5) {
+			window.canvas = c;
+			if (rend.GPU) {
+				c.renderer = 'webgpu';
+				$._webgpu = true;
+			} else if (rend.GL) {
+				c.renderer = 'webgl';
+				$._webgl = true;
+			} else {
+				$._webgpu = $._webgpuFallback = true;
+			}
+		}
 		c.tabIndex = 0;
 		c.w = args[0];
 		c.h = args[1];
@@ -7106,7 +7360,7 @@ async function q5playPreSetup(q) {
 		return rend;
 	};
 
-	$.canvas = $.canvas;
+	$.canvas = $.canvas; // for brython
 
 	const _resizeCanvas = $.resizeCanvas;
 
@@ -7234,7 +7488,7 @@ async function q5playPreSetup(q) {
 
 	$.allSprites = new $.Group();
 	$.world = new $.World();
-	$.camera = new $.Camera();
+	$.camera = $._camera = new $.Camera();
 
 	$.InputDevice = class {
 		constructor() {
@@ -7309,7 +7563,6 @@ async function q5playPreSetup(q) {
 
 			this.x = 0;
 			this.y = 0;
-			this.canvasPos = {};
 			this.isOnCanvas = false;
 			this.isActive = false;
 			this.left = 0;
@@ -7321,7 +7574,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 +7615,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 +8362,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 +8449,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 +8551,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) : '#0f0e',
+		debugGreenFill = $._q5 ? $.color(0, colorMax, 0, colorMax * 0.1) : '#0f02',
+		debugYellow = $._q5 ? $.color(colorMax, colorMax, 0, colorMax * 0.9) : '#ff0e',
+		debugYellowFill = $._q5 ? $.color(colorMax, colorMax, 0, colorMax * 0.1) : '#ff02';
+
+	if (using_p5) {
+		$._getFillIdx = () => $._renderer.states.fillColor;
+		$._setFillIdx = (v) => ($._renderer.states.fillColor = v);
+		$._getStrokeIdx = () => $._renderer.states.strokeColor;
+		$._setStrokeIdx = (v) => ($._renderer.states.strokeColor = v);
+		$._getStrokeWeight = () => [$._renderer.states.strokeWeight];
+		$._setStrokeWeight = (v) => $.strokeWeight(...v);
+		$._getImageMode = () => $._renderer.states.imageMode;
+		$._doFill = () => {};
+		$._doStroke = () => {};
+	} else if ($.canvas.c2d) {
 		// polyfill for q5 WebGPU high efficiency functions
 		$._getFillIdx = () => $._fill;
 		$._setFillIdx = (v) => ($._fill = v);
@@ -8394,7 +8667,7 @@ async function q5playPreSetup(q) {
 					transformPoint(xf, v);
 					$.vertex(v.x, v.y);
 				}
-				$.endShape(true);
+				$.endShape($.CLOSE);
 				if (rr > 0) {
 					$._setStrokeWeight(swData);
 					$._setStrokeIdx(ogStroke);
@@ -8440,7 +8713,7 @@ async function q5playPreSetup(q) {
 							transformPoint(xf, v);
 							$.vertex(v.x, v.y);
 						}
-						$.endShape(true);
+						$.endShape($.CLOSE);
 					} else {
 						let x = (cmd.data[0] + cmd.data[2]) / 2,
 							y = (cmd.data[1] + cmd.data[3]) / 2;
@@ -8479,12 +8752,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','camera','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 +8773,24 @@ 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) {
+			$.camera3D = window.camera;
+			for (let prop of ['log', 'loge', 'camera', 'camera3D']) {
+				Object.defineProperty(window, prop, {
+					value: $[prop]
+				});
+			}
+		}
 	}
 
 	$.update ??= $.clear;
@@ -8510,9 +8802,11 @@ function q5playPostSetup() {
 function q5playUpdate() {
 	const $ = this;
 
-	if (!$._q5) {
+	if (using_p5) {
 		$.q5play._preDrawFrameTime = performance.now();
+		$.resetMatrix();
 	}
+
 	$.q5play.spritesDrawn = 0;
 
 	$.contros._update();
@@ -8655,7 +8949,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 +8957,7 @@ function q5playPostDraw() {
 }
 
 function q5playRemove() {
+	this._removed = true;
 	this.world?.delete();
 }
 
@@ -8747,15 +9042,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 +9158,178 @@ pressure -> es:presión
 };
 q5playClassLangs.Group += q5playClassLangs.Sprite;
 
+if (typeof globalThis.Q5 == 'undefined') {
+	let upgrade = ' Consider upgrading to q5: https://q5js.org';
+	console.warn('p5.js v2 is not fully compatible with q5play.' + upgrade);
+
+	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;
+
+				$.Canvas(...args);
+
+				// q5play defaults
+				$.angleMode($.DEGREES);
+				$.colorMode($.RGB, 1);
+				$.imageMode($.CENTER);
+
+				$.halfWidth = width / 2;
+				$.halfHeight = height / 2;
+				$.jit = (v) => $.random(-v, v);
+
+				$._loaders = [];
+				$._colorFormat = 1;
+
+				const imgRegex = /(jpe?g|png|gif|webp|avif|svg)/i,
+					fontRegex = /(ttf|otf|woff2?|eot|json)/i,
+					fontCategoryRegex = /(serif|sans-serif|monospace|cursive|fantasy)/i,
+					audioRegex = /(wav|flac|mp3|ogg|m4a|aac|aiff|weba)/i;
+
+				$.load = function (...urls) {
+					if (Array.isArray(urls[0])) urls = urls[0];
+
+					let promises = [];
+
+					for (let url of urls) {
+						let ext = url.split('.').pop().toLowerCase();
+
+						let obj;
+						if (ext == 'json') {
+							if (url.includes('-msdf.')) {
+								throw new Error('p5.js v2 can not load MSDF fonts.' + upgrade);
+							}
+							obj = $.loadJSON(url);
+						} else if (ext == 'csv') {
+							obj = $.loadCSV(url);
+						} else if (imgRegex.test(ext)) {
+							obj = $.loadImage(url);
+						} else if (fontRegex.test(ext) || fontCategoryRegex.test(url)) {
+							obj = $.loadFont(url);
+						} else if (audioRegex.test(ext)) {
+							obj = $.loadSound(url);
+						} else if (ext == 'xml') {
+							obj = $.loadXML(url);
+						} else {
+							obj = $.loadText(url);
+						}
+						promises.push(obj);
+					}
+
+					if (urls.length == 1) return promises[0];
+					return Promise.all(promises);
+				};
+
+				if ($._webgpuFallback) {
+					$.opacity = function (v) {
+						$.ctx.globalAlpha = v;
+					};
+				}
+
+				$.pushMatrix = $.push;
+				$.popMatrix = $.pop;
+
+				$.loadAll = function () {
+					console.error('p5.js v2 does not have loadAll().' + upgrade);
+				};
+
+				$.displayMode = () => {
+					console.error('p5.js v2 does not have displayMode().' + upgrade);
+				};
+
+				$.MAXED = 'maxed';
+				$.SMOOTH = 'smooth';
+				$.PIXELATED = 'pixelated';
+
+				if ($._isGlobal) {
+					let props = [
+						'halfWidth',
+						'halfHeight',
+						'jit',
+						'load',
+						'opacity',
+						'pushMatrix',
+						'popMatrix',
+						'loadAll',
+						'displayMode',
+						'MAXED',
+						'PIXELATED'
+					];
+					for (let p of props) {
+						window[p] = $[p];
+					}
+				}
+
+				if ($._webgpuFallback) {
+					const _resetMatrix = $.resetMatrix;
+					$.resetMatrix = () => {
+						_resetMatrix.call($);
+						// sets origin to the center of the canvas
+						$.translate($.halfWidth, $.halfHeight);
+					};
+				}
+
+				Object.defineProperty(p5, 'lang', {
+					set() {
+						console.error('p5.js v2 does not support changing language.' + upgrade);
+					},
+					get() {
+						return 'en';
+					},
+					configurable: true
+				});
+
+				const entryPoints = [
+					'setup',
+					'update',
+					'draw',
+					'deviceMoved',
+					'deviceTurned',
+					'deviceShaken',
+					'doubleClicked',
+					'mousePressed',
+					'mouseReleased',
+					'mouseMoved',
+					'mouseDragged',
+					'mouseClicked',
+					'mouseWheel',
+					'touchStarted',
+					'touchMoved',
+					'touchEnded',
+					'keyPressed',
+					'keyReleased',
+					'keyTyped',
+					'windowResized'
+				];
+
+				for (let ep of entryPoints) {
+					Object.defineProperty(p5, ep, {
+						set(fn) {
+							$[ep] = fn;
+							if ($._isGlobal) window[ep] = fn;
+						},
+						get() {
+							return $[ep];
+						},
+						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."""