littlejsengine 1.19.3 → 1.21.0

package/src/engineDraw.js

@@ -81,19 +81,23 @@ let textureInfos = [];
 /** Keeps track of how many draw calls there were each frame for debugging
  *  @type {number}
  *  @memberof Draw */
-let drawCount;
+let drawCount = 0;
 
 /** Keeps track of how many primitives were drawn each frame for debugging
  *  A single draw call can render many primitives (e.g. a WebGL sprite batch).
  *  @type {number}
  *  @memberof Draw */
-let primitiveCount;
+let primitiveCount = 0;
 
 // internal predicates for tint short-circuiting in canvas2D draw paths
 // isWhite ignores alpha because alpha is applied via globalAlpha, not multiply
 // isBlack includes alpha so additive colors that only contribute alpha are not skipped
-/** @param {Color} c */ function isWhite(c) { return c.r >= 1 && c.g >= 1 && c.b >= 1; }
-/** @param {Color} c */ function isBlack(c) { return c.r <= 0 && c.g <= 0 && c.b <= 0 && c.a <= 0; }
+/** @ignore
+ *  @param {Color} c */
+function isWhite(c) { return c.r >= 1 && c.g >= 1 && c.b >= 1; }
+/** @ignore
+ *  @param {Color} c */
+function isBlack(c) { return c.r <= 0 && c.g <= 0 && c.b <= 0 && c.a <= 0; }
 
 ///////////////////////////////////////////////////////////////////////////////
 
@@ -120,8 +124,6 @@ function tile(index=0, size=tileDefaultSize, texture=0, padding=tileDefaultPaddi
     ASSERT(isNumber(texture) || texture instanceof TextureInfo, 'texture must be a number or TextureInfo');
     ASSERT(isNumber(padding), 'padding must be a number');
 
-    if (headlessMode) return new TileInfo;
-
     if (typeof size === 'number')
     {
         // if size is a number, make it a vector
@@ -132,6 +134,8 @@ function tile(index=0, size=tileDefaultSize, texture=0, padding=tileDefaultPaddi
     // create tile info object
     const textureInfo = typeof texture === 'number' ?
         textureInfos[texture] : texture;
+    if (headlessMode && !textureInfo?.size.x)
+        return new TileInfo(new Vector2, size.copy(), textureInfo, padding, bleed); // no image loaded, no place in it
     ASSERT(textureInfo instanceof TextureInfo, 'tile texture is not loaded');
     ASSERT(textureInfo.size.x > 0, 'tile texture is not loaded');
 
@@ -203,8 +207,8 @@ class TileInfo
         const h = this.size.y + this.padding*2;
         const x = (this.columns ? frame % this.columns : frame) * w;
         const y = (this.columns ? frame / this.columns | 0 : 0) * h;
-        ASSERT(this.pos.x + x + this.size.x <= this.textureInfo.size.x, 'frame extends beyond texture width!');
-        ASSERT(this.pos.y + y + this.size.y <= this.textureInfo.size.y, 'frame extends beyond texture height!');
+        ASSERT(!this.textureInfo || this.pos.x + x + this.size.x <= this.textureInfo.size.x, 'frame extends beyond texture width!');
+        ASSERT(!this.textureInfo || this.pos.y + y + this.size.y <= this.textureInfo.size.y, 'frame extends beyond texture height!');
         return this.offset(new Vector2(x, y));
     }
 
@@ -220,7 +224,8 @@ class TileInfo
     }
 
     /**
-     * Returns a tile info for an index using this tile as reference
+     * Returns a tile info for an index using this tile's size, texture and padding as reference
+     * - the index counts from the texture's origin like tile(), for a sprite packed in a texture sheet use frame()
      * @param {Vector2|number} [index=0]
      * @return {TileInfo}
      */
@@ -243,20 +248,21 @@ class TileInfo
 }
 
 /**
- * Tile Info - Stores info about each texture
+ * Texture Info - Stores info about each texture
  * @memberof Draw
  */
 class TextureInfo
 {
     /**
      * Create a TextureInfo, called automatically by the engine
-     * @param {HTMLImageElement|OffscreenCanvas} image
+     * @param {HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap} image
      * @param {boolean} [useWebGL] - Should use WebGL if available?
-     * @param {boolean} [wrap] - Should the texture wrap (REPEAT) or clamp (CLAMP_TO_EDGE)?
+     * @param {boolean|Array<number>} [wrap] - Should the texture wrap (REPEAT) or clamp (CLAMP_TO_EDGE)? Or the WebGL
+     *   modes across and down, like [gl.CLAMP_TO_EDGE, gl.MIRRORED_REPEAT], as a glTF sampler gives them
      */
     constructor(image, useWebGL=true, wrap=false)
     {
-        /** @property {HTMLImageElement|OffscreenCanvas} - image source */
+        /** @property {HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap} - image source */
         this.image = image;
         /** @property {Vector2} - size of the image */
         this.size = image ? vec2(image.width, image.height) : vec2();
@@ -265,13 +271,24 @@ class TextureInfo
         /** @property {WebGLTexture|undefined} - WebGL texture
          *  @type {WebGLTexture|undefined} */
         this.glTexture = undefined;
-        /** @property {boolean} - true for REPEAT wrap mode, false for CLAMP_TO_EDGE */
+        /** @property {boolean|Array<number>} - true for REPEAT wrap mode, false for CLAMP_TO_EDGE, or the WebGL modes
+         *  across and down
+         *  @type {boolean|Array<number>} */
         this.wrap = wrap;
         useWebGL && this.createWebGLTexture();
     }
 
     /** Creates the WebGL texture, updates if already created */
-    createWebGLTexture() { glRegisterTextureInfo(this); }
+    createWebGLTexture()
+    {
+        const image = this.image;
+        if (image?.width) // the image may have been resized since
+        {
+            this.size = vec2(image.width, image.height);
+            this.sizeInverse = vec2(1/image.width, 1/image.height);
+        }
+        glRegisterTextureInfo(this);
+    }
 
     /** Destroys the WebGL texture */
     destroyWebGLTexture() { glUnregisterTextureInfo(this); }
@@ -281,7 +298,8 @@ class TextureInfo
     hasWebGL() { return !!this.glTexture; }
 
     /** Set the wrap mode for this texture
-     *  @param {boolean} [wrap] - true for REPEAT, false for CLAMP_TO_EDGE */
+     *  @param {boolean|Array<number>} [wrap] - true for REPEAT, false for CLAMP_TO_EDGE, or the WebGL modes across
+     *    and down */
     setWrap(wrap=true)
     {
         this.wrap = wrap;
@@ -290,12 +308,20 @@ class TextureInfo
 }
 
 ///////////////////////////////////////////////////////////////////////////////
+/**
+ * @callback SpriteAnimationEndCallback - Called once when a SpriteAnimation's play ends
+ * @return {void}
+ * @memberof Draw
+ */
+
 /**
  * SpriteAnimation - Steps a tile through its frames over time: looping, once, or there and back
  * - Driven by the engine time like a Timer, so it pauses with the game and needs no update call
  * - Read tileInfo each frame for the frame to draw, from an object's update or before a drawTile
  * - loop, play and pingPong each start over from the first frame; stop holds the current one
+ * - play(onEnd) calls onEnd once the play ends, on the first read after it, since there is no update to call it
  * - Frames follow each other along the row, as tileInfo.frame counts them
+ * - SpriteAnimator switches between a character's animations by name
  * @example
  * const walk = new SpriteAnimation(tile(0, 16), 4, .1); // four frames, a tenth of a second each
  * const attack = new SpriteAnimation(tile(4, 16), 3, .05).play(); // once, then holds the last frame
@@ -327,15 +353,24 @@ class SpriteAnimation
         /** @property {number|undefined} - The frame held by stop, undefined while running
          *  @type {number|undefined} */
         this.heldFrame = undefined;
+        /** @property {SpriteAnimationEndCallback|undefined} - Called once when a play ends, on the first read after it
+         *  @type {SpriteAnimationEndCallback|undefined} */
+        this.onEnd = undefined;
     }
 
     /** Start over from the first frame and repeat forever
      *  @return {SpriteAnimation} */
     loop() { return this.restart('loop'); }
 
-    /** Start over from the first frame, run through once and hold the last frame
+    /** Start over from the first frame, run through once and hold the last frame, last to first at a negative speed
+     *  @param {function():void} [onEnd] - Called once when it ends, on the first read of it after that
      *  @return {SpriteAnimation} */
-    play() { return this.restart('once'); }
+    play(onEnd)
+    {
+        this.restart('once');
+        this.onEnd = onEnd;
+        return this;
+    }
 
     /** Start over from the first frame and run there and back forever
      *  @return {SpriteAnimation} */
@@ -345,7 +380,7 @@ class SpriteAnimation
      *  @return {SpriteAnimation} */
     stop() { this.heldFrame = this.frame; return this; }
 
-    /** Start over from the first frame in a mode
+    /** Start over from the first frame in a mode, with no end callback
      *  @param {string} [mode] - 'loop', 'once' or 'pingPong', the current mode when left out
      *  @return {SpriteAnimation} */
     restart(mode=this.mode)
@@ -353,6 +388,7 @@ class SpriteAnimation
         this.mode = mode;
         this.startTime = time;
         this.heldFrame = undefined;
+        this.onEnd = undefined;
         return this;
     }
 
@@ -364,14 +400,15 @@ class SpriteAnimation
      *  @return {number} */
     get frame()
     {
+        this.isDone; // a read after a play ends calls onEnd, which may start it over
         if (this.heldFrame !== undefined)
             return this.heldFrame;
         const n = this.frameCount, f = floor(this.elapsedFrames);
-        if (this.mode == 'once')
-            return min(f, n - 1);
+        if (this.mode == 'once') // backward it counts down from the last frame, showing it from the start
+            return clamp(this.speed < 0 ? n - 1 + ceil(this.elapsedFrames) : f, 0, n - 1);
         if (this.mode == 'loop')
-            return f % n;
-        const period = max(2 * n - 2, 1), k = f % period; // there and back, the ends once each
+            return mod(f, n);
+        const period = max(2 * n - 2, 1), k = mod(f, period); // there and back, the ends once each
         return k < n ? k : period - k;
     }
 
@@ -379,9 +416,81 @@ class SpriteAnimation
      *  @return {TileInfo} */
     get tileInfo() { return this.firstTile.frame(this.frame); }
 
-    /** True once a play has shown its last frame for its time
+    /** True once a play has shown its last frame for its time, the first read after that calls onEnd
      *  @return {boolean} */
-    get isDone() { return this.mode == 'once' && this.heldFrame === undefined && this.elapsedFrames >= this.frameCount; }
+    get isDone()
+    {
+        const done = this.mode == 'once' && this.heldFrame === undefined && abs(this.elapsedFrames) >= this.frameCount;
+        if (done && this.onEnd)
+        {
+            const onEnd = this.onEnd;
+            this.onEnd = undefined; // once, and it can start a new play with a callback of its own
+            onEnd();
+        }
+        return done;
+    }
+}
+
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * SpriteAnimator - A character's animations by name, like idle, walk and attack, and the one showing now
+ * - Each clip is a SpriteAnimation and keeps its own mode, loop, play or pingPong
+ * - set starts a clip over only when it changes or a play of it has ended, so it can be called every update
+ * - Read tileInfo each frame for the frame to draw, as with a SpriteAnimation
+ * @example
+ * const hero = new SpriteAnimator({
+ *     idle:   new SpriteAnimation(tile(0, 16), 2, .4),
+ *     walk:   new SpriteAnimation(tile(2, 16), 4, .1),
+ *     attack: new SpriteAnimation(tile(6, 16), 3, .05).play(),
+ * });
+ * hero.set('attack', ()=> hero.set('idle')); // back to idle when the attack ends
+ * // in update: this.tileInfo = hero.tileInfo;
+ * @memberof Draw
+ */
+class SpriteAnimator
+{
+    /** Create an animator from its clips, showing the first one
+     *  @param {Object<string, SpriteAnimation>} clips - The clips by name */
+    constructor(clips)
+    {
+        const names = Object.keys(clips);
+        ASSERT(names.length > 0, 'an animator needs at least one clip');
+        /** @property {Object<string, SpriteAnimation>} - The clips by name */
+        this.clips = clips;
+        /** @property {string} - The name of the clip showing now */
+        this.name = names[0];
+    }
+
+    /** Show a clip, starting it over in its own mode unless it is showing and has not ended
+     *  @param {string} name - The clip's name
+     *  @param {function():void} [onEnd] - Called once when a play clip ends, as with SpriteAnimation.play
+     *  @return {SpriteAnimator} */
+    set(name, onEnd)
+    {
+        ASSERT(this.clips[name], 'no clip named ' + name);
+        if (name == this.name && !this.clip.isDone)
+            return this;
+        this.name = name;
+        this.clip.restart();
+        this.clip.onEnd = onEnd;
+        return this;
+    }
+
+    /** The clip showing now
+     *  @return {SpriteAnimation} */
+    get clip() { return this.clips[this.name]; }
+
+    /** The tile of the frame showing now
+     *  @return {TileInfo} */
+    get tileInfo() { return this.clip.tileInfo; }
+
+    /** The frame of the clip showing now
+     *  @return {number} */
+    get frame() { return this.clip.frame; }
+
+    /** True once the clip showing now is a play that has ended
+     *  @return {boolean} */
+    get isDone() { return this.clip.isDone; }
 }
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -393,18 +502,26 @@ class SpriteAnimation
  * - Set it as obj.shader, or use setShader for 2D draws and render3D.shader for 3D draws
  * - Draws that share a Shader share a batch; with no Shader set nothing changes
  * - In 2D it shades textured draws, untextured ones like drawRect draw as they are
+ * - A render target, like a tile layer drawn in WebGL, holds premultiplied color, and so does every image when
+ *   tilesPixelated is false; there iChannel0 reads premultiplied texels and the snippet's color is taken as
+ *   premultiplied too. premultipliedTexture is true there, so a snippet that changes the alpha, or makes a see
+ *   through color of its own, scales the rgb with it: `if (premultipliedTexture) c.rgb *= k;`
  * - Compiled once per renderer by the first draw that needs it; a bad snippet throws with the GLSL log in debug
  * - Make each Shader once, at init, and share it; every one made lives for the session with its programs
- * - Names in both renderers: iChannel0 the texture, iTime, iResolution, and localUV, 0 to 1 across the sprite
- *   or the mesh's own uv
- * - Names in 3D only: worldPos, worldNormal, cameraPos, sunDirection, sunColor, ambientColor, lightCount,
- *   lights[i], lightColors[i] and shadow()
+ * - Names in both renderers: iChannel0 the texture, iTime, iResolution, premultipliedTexture, and localUV, 0 to 1
+ *   across the sprite or the mesh's own uv
+ * - Names in 3D only: worldPos, worldNormal, cameraPos, sunDirection, sunColor, ambientColor, ambientGroundColor,
+ *   lightCount, lights[i], lightColors[i] and shadow()
+ * - In 3D the shadow map is drawn without the Shader, cut only by the texture's alpha, so a snippet that removes
+ *   parts of a surface still shadows with the whole of it
  * @example
  * const fade = new Shader(`
  * void mainImage(out vec4 c, vec2 uv)
  * {
  *     c = texture(iChannel0, uv);
- *     c.a *= .5 + .5*sin(iTime);
+ *     float fade = .5 + .5*sin(iTime);
+ *     c.a *= fade;
+ *     if (premultipliedTexture) c.rgb *= fade; // a tile layer, or any image with tilesPixelated false
  * }`);
  * obj.shader = fade;
  * @memberof Draw
@@ -440,11 +557,11 @@ class Shader
  *  @param {boolean}  [mirror] - Is image flipped along the Y axis?
  *  @param {Color}    [additiveColor] - Additive color to be applied if any
  *  @param {boolean}  [useWebGL=glEnable] - Use accelerated WebGL rendering?
- *  @param {boolean}  [screenSpace=false] - Are the pos and size are in screen space?
+ *  @param {boolean}  [screenSpace=drawScreenSpace] - Are the pos and size are in screen space?
  *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context] - Canvas 2D context to draw to
  *  @memberof Draw */
 function drawTile(pos, size=vec2(1), tileInfo, color=WHITE,
-    angle=0, mirror, additiveColor, useWebGL=glEnable, screenSpace=false, context)
+    angle=0, mirror, additiveColor, useWebGL=glEnable, screenSpace=drawScreenSpace, context)
 {
     ASSERT(isVector2(pos), 'pos must be a vec2');
     ASSERT(isVector2(size), 'size must be a vec2');
@@ -453,15 +570,23 @@ function drawTile(pos, size=vec2(1), tileInfo, color=WHITE,
     ASSERT(!additiveColor || isColor(additiveColor), 'additiveColor must be a color');
     ASSERT(!context || !useWebGL, 'context only supported in canvas 2D mode');
 
+    if (headlessMode && !context) return; // headless has no canvas, only a context passed in is drawn to
+
     const textureInfo = tileInfo?.textureInfo;
+    if (textureInfo && !(tileInfo.size.x && tileInfo.size.y))
+        return; // a tile with no area draws nothing, like a sprite still loading
     const bleed = tileInfo?.bleed ?? 0;
     if (useWebGL && glEnable)
     {
         ASSERT(!!glContext, 'WebGL is not enabled!');
         if (screenSpace)
+        {
+            if (glSkipScreenSpace) return;
             [pos, size, angle] = screenToWorldTransform(pos, size, angle);
+        }
         if (textureInfo)
         {
+            ASSERT(!!textureInfo.glTexture, 'texture has no WebGL texture, draw it with useWebGL false');
             // calculate uvs and render
             const sizeInverse = textureInfo.sizeInverse;
             const x = tileInfo.pos.x * sizeInverse.x;
@@ -487,8 +612,7 @@ function drawTile(pos, size=vec2(1), tileInfo, color=WHITE,
         }
         else
         {
-            // untextured: fold color+additive to match the Canvas2D path's
-            // color.add(additiveColor) on line ~337.
+            // untextured: color plus additive in one color, as the Canvas2D path below does
             const combined = additiveColor ? color.add(additiveColor) : color;
             glDrawUntextured(pos.x, pos.y, size.x, size.y, angle, combined.rgbaInt());
         }
@@ -526,7 +650,7 @@ function drawTile(pos, size=vec2(1), tileInfo, color=WHITE,
  *  @param {Color}   [color=WHITE]
  *  @param {number}  [angle]
  *  @param {boolean} [useWebGL=glEnable]
- *  @param {boolean} [screenSpace]
+ *  @param {boolean} [screenSpace=drawScreenSpace]
  *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context]
  *  @memberof Draw */
 function drawRect(pos, size, color, angle, useWebGL, screenSpace, context)
@@ -541,10 +665,10 @@ function drawRect(pos, size, color, angle, useWebGL, screenSpace, context)
  *  @param {Color}   [colorBottom=CLEAR_WHITE]
  *  @param {number}  [angle]
  *  @param {boolean} [useWebGL=glEnable]
- *  @param {boolean} [screenSpace]
+ *  @param {boolean} [screenSpace=drawScreenSpace]
  *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context]
  *  @memberof Draw */
-function drawRectGradient(pos, size, colorTop=WHITE, colorBottom=CLEAR_WHITE, angle=0, useWebGL=glEnable, screenSpace=false, context)
+function drawRectGradient(pos, size, colorTop=WHITE, colorBottom=CLEAR_WHITE, angle=0, useWebGL=glEnable, screenSpace=drawScreenSpace, context)
 {
     ASSERT(isVector2(pos), 'pos must be a vec2');
     ASSERT(isVector2(size), 'size must be a vec2');
@@ -552,15 +676,15 @@ function drawRectGradient(pos, size, colorTop=WHITE, colorBottom=CLEAR_WHITE, an
     ASSERT(isNumber(angle), 'angle must be a number');
     ASSERT(!context || !useWebGL, 'context only supported in canvas 2D mode');
 
+    if (headlessMode && !context) return; // headless has no canvas, only a context passed in is drawn to
+
     if (useWebGL && glEnable)
     {
         ASSERT(!!glContext, 'WebGL is not enabled!');
         if (screenSpace)
         {
-            // convert to world space
-            pos = screenToWorld(pos);
-            size = size.scale(1/cameraScale);
-            angle += cameraAngle;
+            if (glSkipScreenSpace) return;
+            [pos, size, angle] = screenToWorldTransform(pos, size, angle);
         }
         // build 4 corner points for the rectangle
         const points = [], colors = [];
@@ -608,11 +732,11 @@ function drawRectGradient(pos, size, colorTop=WHITE, colorBottom=CLEAR_WHITE, an
  *  @param {number}   [angle=0] - Angle to rotate by
  *  @param {Color}    [additiveColor] - Additive color to be applied if any
  *  @param {boolean}  [useWebGL=glEnable] - Use accelerated WebGL rendering?
- *  @param {boolean}  [screenSpace=false] - Are pos and size in screen space?
+ *  @param {boolean}  [screenSpace=drawScreenSpace] - Are pos and size in screen space?
  *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context] - Canvas 2D context to draw to
  *  @memberof Draw */
 function drawTextureWrapped(pos, size, wrapCount, texture=0, color=WHITE,
-    angle=0, additiveColor, useWebGL=glEnable, screenSpace=false, context)
+    angle=0, additiveColor, useWebGL=glEnable, screenSpace=drawScreenSpace, context)
 {
     ASSERT(isVector2(pos), 'pos must be a vec2');
     ASSERT(isVector2(size), 'size must be a vec2');
@@ -624,8 +748,8 @@ function drawTextureWrapped(pos, size, wrapCount, texture=0, color=WHITE,
     ASSERT(!(texture instanceof TileInfo),
         'pass a TextureInfo or texture index, not a TileInfo — use tileInfo.textureInfo');
 
-    // short-circuit before texture lookup — textureInfos[0] is undefined in headless mode
-    if (headlessMode) return;
+    // only a context passed in is drawn to in headless mode, before the texture lookup, textureInfos is empty there
+    if (headlessMode && !context) return;
 
     // resolve texture argument: TextureInfo or index
     const textureInfo = typeof texture === 'number' ? textureInfos[texture] : texture;
@@ -638,7 +762,10 @@ function drawTextureWrapped(pos, size, wrapCount, texture=0, color=WHITE,
     {
         ASSERT(!!glContext, 'WebGL is not enabled!');
         if (screenSpace)
+        {
+            if (glSkipScreenSpace) return;
             [pos, size, angle] = screenToWorldTransform(pos, size, angle);
+        }
         glSetTexture(textureInfo.glTexture);
         glDraw(pos.x, pos.y, size.x, size.y, angle,
             0, 0, wrapCount.x, wrapCount.y,
@@ -660,9 +787,7 @@ function drawTextureWrapped(pos, size, wrapCount, texture=0, color=WHITE,
     // pick image source: raw, or tinted bake. Match drawImageColor's
     // "no tint needed" predicate so behavior stays consistent.
     const noTint = !canvasColorTiles ||
-        (additiveColor
-            ? isWhite(color.add(additiveColor)) && additiveColor.a <= 0
-            : isWhite(color));
+        isWhite(color) && (!additiveColor || isBlack(additiveColor));
     // alpha is baked into pixels by bakeTintedImage's additive branch;
     // in that case globalAlpha must NOT also apply color.a
     const alphaBaked = !noTint && additiveColor && !isBlack(additiveColor);
@@ -698,10 +823,10 @@ function drawTextureWrapped(pos, size, wrapCount, texture=0, color=WHITE,
  *  @param {Vector2} [pos=vec2()] - Offset to apply
  *  @param {number}  [angle] - Angle to rotate by
  *  @param {boolean} [useWebGL=glEnable]
- *  @param {boolean} [screenSpace]
+ *  @param {boolean} [screenSpace=drawScreenSpace]
  *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context]
  *  @memberof Draw */
-function drawLineList(points, width=.1, color=WHITE, wrap=false, pos=vec2(), angle=0, useWebGL=glEnable, screenSpace=false, context)
+function drawLineList(points, width=.1, color=WHITE, wrap=false, pos=vec2(), angle=0, useWebGL=glEnable, screenSpace=drawScreenSpace, context)
 {
     ASSERT(isArray(points), 'points must be an array');
     ASSERT(isNumber(width), 'width must be a number');
@@ -710,12 +835,17 @@ function drawLineList(points, width=.1, color=WHITE, wrap=false, pos=vec2(), ang
     ASSERT(isNumber(angle), 'angle must be a number');
     ASSERT(!context || !useWebGL, 'context only supported in canvas 2D mode');
 
+    if (headlessMode && !context) return; // headless has no canvas, only a context passed in is drawn to
+
     if (useWebGL && glEnable)
     {
         ASSERT(!!glContext, 'WebGL is not enabled!');
         let size = vec2(1);
         if (screenSpace)
+        {
+            if (glSkipScreenSpace) return;
             [pos, size, angle] = screenToWorldTransform(pos, size, angle);
+        }
         glDrawOutlineTransform(points, color.rgbaInt(), width, pos.x, pos.y, size.x, size.y, angle, wrap);
     }
     else
@@ -725,8 +855,11 @@ function drawLineList(points, width=.1, color=WHITE, wrap=false, pos=vec2(), ang
         ++primitiveCount;
         drawCanvas2D(pos, vec2(1), angle, false, (context)=>
         {
+            // Canvas2D ignores a width of 0 or below and keeps the last one, WebGL draws none for 0
+            // and a negative width as its size, the outline turned inside out
+            if (!width) return;
             context.strokeStyle = color.toString();
-            context.lineWidth = width;
+            context.lineWidth = abs(width);
             context.beginPath();
             for (let i=0; i<points.length; ++i)
             {
@@ -747,14 +880,15 @@ function drawLineList(points, width=.1, color=WHITE, wrap=false, pos=vec2(), ang
  *  @param {Vector2} [pos=vec2()] - Offset to apply
  *  @param {number}  [angle] - Angle to rotate by
  *  @param {boolean} [useWebGL=glEnable]
- *  @param {boolean} [screenSpace]
+ *  @param {boolean} [screenSpace=drawScreenSpace]
  *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context]
  *  @memberof Draw */
-function drawLine(posA, posB, width=.1, color=WHITE, pos=vec2(), angle=0, useWebGL=glEnable, screenSpace=false, context)
+function drawLine(posA, posB, width=.1, color=WHITE, pos=vec2(), angle=0, useWebGL=glEnable, screenSpace=drawScreenSpace, context)
 {
     const halfDelta = vec2((posB.x - posA.x)/2, (posB.y - posA.y)/2);
     const size = vec2(width, halfDelta.length()*2);
-    pos = pos.add(posA.add(halfDelta));
+    const middle = posA.add(halfDelta);
+    pos = pos.add(angle ? middle.rotate(screenSpace ? -angle : angle) : middle); // screen y is down, so it turns back
     if (screenSpace)
         halfDelta.y *= -1;  // flip angle Y if screen space
     angle += halfDelta.angle();
@@ -770,10 +904,10 @@ function drawLine(posA, posB, width=.1, color=WHITE, pos=vec2(), angle=0, useWeb
  *  @param {Color}   [lineColor=BLACK]
  *  @param {number}  [angle]
  *  @param {boolean} [useWebGL=glEnable]
- *  @param {boolean} [screenSpace]
+ *  @param {boolean} [screenSpace=drawScreenSpace]
  *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context]
  *  @memberof Draw */
-function drawRegularPoly(pos, size=vec2(1), sides=3, color=WHITE, lineWidth=0, lineColor=BLACK, angle=0, useWebGL=glEnable, screenSpace=false, context)
+function drawRegularPoly(pos, size=vec2(1), sides=3, color=WHITE, lineWidth=0, lineColor=BLACK, angle=0, useWebGL=glEnable, screenSpace=drawScreenSpace, context)
 {
     ASSERT(isVector2(size), 'size must be a vec2');
     ASSERT(isNumber(sides), 'sides must be a number');
@@ -790,6 +924,8 @@ function drawRegularPoly(pos, size=vec2(1), sides=3, color=WHITE, lineWidth=0, l
 }
 
 /** Draw colored polygon using passed in points
+ *  - WebGL fills a polygon whose edges do not cross, concave or not; a self crossing one, like a star through its
+ *    outer points, fills wrong there, so draw it as its simple outline or in parts
  *  @param {Array<Vector2>} points - Array of Vector2 points
  *  @param {Color}   [color=WHITE]
  *  @param {number}  [lineWidth]
@@ -797,10 +933,10 @@ function drawRegularPoly(pos, size=vec2(1), sides=3, color=WHITE, lineWidth=0, l
  *  @param {Vector2} [pos=vec2()] - Offset to apply
  *  @param {number}  [angle] - Angle to rotate by
  *  @param {boolean} [useWebGL=glEnable]
- *  @param {boolean} [screenSpace]
+ *  @param {boolean} [screenSpace=drawScreenSpace]
  *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context]
  *  @memberof Draw */
-function drawPoly(points, color=WHITE, lineWidth=0, lineColor=BLACK, pos=vec2(), angle=0, useWebGL=glEnable, screenSpace=false, context=undefined)
+function drawPoly(points, color=WHITE, lineWidth=0, lineColor=BLACK, pos=vec2(), angle=0, useWebGL=glEnable, screenSpace=drawScreenSpace, context=undefined)
 {
     ASSERT(isVector2(pos), 'pos must be a vec2');
     ASSERT(isArray(points), 'points must be an array');
@@ -809,18 +945,25 @@ function drawPoly(points, color=WHITE, lineWidth=0, lineColor=BLACK, pos=vec2(),
     ASSERT(isNumber(angle), 'angle must be a number');
     ASSERT(!context || !useWebGL, 'context only supported in canvas 2D mode');
 
+    if (headlessMode && !context) return; // headless has no canvas, only a context passed in is drawn to
+
     if (useWebGL && glEnable)
     {
         ASSERT(!!glContext, 'WebGL is not enabled!');
         let size = vec2(1);
         if (screenSpace)
+        {
+            if (glSkipScreenSpace) return;
             [pos, size, angle] = screenToWorldTransform(pos, size, angle);
+        }
         glDrawPointsTransform(points, color.rgbaInt(), pos.x, pos.y, size.x, size.y, angle);
         if (lineWidth > 0)
             glDrawOutlineTransform(points, lineColor.rgbaInt(), lineWidth, pos.x, pos.y, size.x, size.y, angle);
     }
     else
     {
+        ++drawCount;
+        ++primitiveCount;
         drawCanvas2D(pos, vec2(1), angle, false, context=>
         {
             context.fillStyle = color.toString();
@@ -829,7 +972,7 @@ function drawPoly(points, color=WHITE, lineWidth=0, lineColor=BLACK, pos=vec2(),
                 context.lineTo(point.x, point.y);
             context.closePath();
             context.fill();
-            if (lineWidth)
+            if (lineWidth > 0) // as in WebGL, Canvas2D would stroke a width below 0 with the last one
             {
                 context.strokeStyle = lineColor.toString();
                 context.lineWidth = lineWidth;
@@ -839,6 +982,9 @@ function drawPoly(points, color=WHITE, lineWidth=0, lineColor=BLACK, pos=vec2(),
     }
 }
 
+// the unit rings drawEllipse fills with in WebGL, one for each side count
+const drawEllipseRings = new Map;
+
 /** Draw colored ellipse using passed in point
  *  @param {Vector2} pos
  *  @param {Vector2} [size=vec2(1)] - Width and height diameter
@@ -847,10 +993,10 @@ function drawPoly(points, color=WHITE, lineWidth=0, lineColor=BLACK, pos=vec2(),
  *  @param {number}  [lineWidth]
  *  @param {Color}   [lineColor=BLACK]
  *  @param {boolean} [useWebGL=glEnable]
- *  @param {boolean} [screenSpace]
+ *  @param {boolean} [screenSpace=drawScreenSpace]
  *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context]
  *  @memberof Draw */
-function drawEllipse(pos, size=vec2(1), color=WHITE, angle=0, lineWidth=0, lineColor=BLACK, useWebGL=glEnable, screenSpace=false, context)
+function drawEllipse(pos, size=vec2(1), color=WHITE, angle=0, lineWidth=0, lineColor=BLACK, useWebGL=glEnable, screenSpace=drawScreenSpace, context)
 {
     ASSERT(isVector2(pos), 'pos must be a vec2');
     ASSERT(isVector2(size), 'size must be a vec2');
@@ -860,24 +1006,51 @@ function drawEllipse(pos, size=vec2(1), color=WHITE, angle=0, lineWidth=0, lineC
     ASSERT(lineWidth >= 0, 'lineWidth must be a positive value or 0');
     ASSERT(!context || !useWebGL, 'context only supported in canvas 2D mode');
 
-    // clamp line width to prevent artifacts
-    lineWidth = clamp(lineWidth, 0, min(size.x, size.y));
+    if (headlessMode && !context) return; // headless has no canvas, only a context passed in is drawn to
+
+    // clamp line width to prevent artifacts, a negative size draws mirrored
+    lineWidth = clamp(lineWidth, 0, min(abs(size.x), abs(size.y)));
 
     if (useWebGL && glEnable)
     {
-        // draw as a regular polygon
         const sides = glCircleSides;
-        drawRegularPoly(pos, size, sides, color, lineWidth, lineColor, angle, useWebGL, screenSpace, context);
+        if (lineWidth > 0)
+        {
+            // draw as a regular polygon, the outline is made from the points at their size
+            drawRegularPoly(pos, size, sides, color, lineWidth, lineColor, angle, useWebGL, screenSpace, context);
+            return;
+        }
+
+        // a fill is a unit ring scaled, made once for each side count and already in strip order
+        let ring = drawEllipseRings.get(sides);
+        if (!ring)
+        {
+            const points = [];
+            for (let i=sides; i--;)
+            {
+                const a = (i/sides)*PI*2;
+                points.push(vec2(sin(a), cos(a)));
+            }
+            drawEllipseRings.set(sides, ring = glPolyStrip(points));
+        }
+        if (screenSpace)
+        {
+            if (glSkipScreenSpace) return;
+            [pos, size, angle] = screenToWorldTransform(pos, size, angle);
+        }
+        glDrawPointsTransform(ring, color.rgbaInt(), pos.x, pos.y, size.x/2, size.y/2, angle, false);
     }
     else
     {
+        ++drawCount;
+        ++primitiveCount;
         drawCanvas2D(pos, vec2(1), angle, false, context=>
         {
             context.fillStyle = color.toString();
             context.beginPath();
-            context.ellipse(0, 0, size.x/2, size.y/2, 0, 0, 9);
+            context.ellipse(0, 0, abs(size.x)/2, abs(size.y)/2, 0, 0, 9); // it throws on a negative radius
             context.fill();
-            if (lineWidth)
+            if (lineWidth > 0)
             {
                 context.strokeStyle = lineColor.toString();
                 context.lineWidth = lineWidth;
@@ -894,15 +1067,16 @@ function drawEllipse(pos, size=vec2(1), color=WHITE, angle=0, lineWidth=0, lineC
  *  @param {number}  [lineWidth=0]
  *  @param {Color}   [lineColor=BLACK]
  *  @param {boolean} [useWebGL=glEnable]
- *  @param {boolean} [screenSpace]
+ *  @param {boolean} [screenSpace=drawScreenSpace]
  *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context]
  *  @memberof Draw */
-function drawCircle(pos, size=1, color=WHITE, lineWidth=0, lineColor=BLACK, useWebGL=glEnable, screenSpace=false, context)
+function drawCircle(pos, size=1, color=WHITE, lineWidth=0, lineColor=BLACK, useWebGL=glEnable, screenSpace=drawScreenSpace, context)
 {
     ASSERT(isNumber(size), 'size must be a number');
     drawEllipse(pos, vec2(size), color, 0, lineWidth, lineColor, useWebGL, screenSpace, context);
 }
 
+let drawEllipseGradientOffset = 0;
 /** Draw an ellipse filled with a radial gradient from the center to the rim
  *  - Best when batched with other untextured polys
  *  - If drawing mostly textured sprites, bake the gradient into a texture and use drawTile instead
@@ -913,11 +1087,10 @@ function drawCircle(pos, size=1, color=WHITE, lineWidth=0, lineColor=BLACK, useW
  *  @param {Color}   [colorOuter=CLEAR_WHITE]
  *  @param {number}  [angle]
  *  @param {boolean} [useWebGL=glEnable]
- *  @param {boolean} [screenSpace]
+ *  @param {boolean} [screenSpace=drawScreenSpace]
  *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context]
  *  @memberof Draw */
-let drawEllipseGradientOffset = 0;
-function drawEllipseGradient(pos, size=vec2(1), colorInner=WHITE, colorOuter=CLEAR_WHITE, angle=0, useWebGL=glEnable, screenSpace=false, context)
+function drawEllipseGradient(pos, size=vec2(1), colorInner=WHITE, colorOuter=CLEAR_WHITE, angle=0, useWebGL=glEnable, screenSpace=drawScreenSpace, context)
 {
     ASSERT(isVector2(pos), 'pos must be a vec2');
     ASSERT(isVector2(size), 'size must be a vec2');
@@ -925,17 +1098,15 @@ function drawEllipseGradient(pos, size=vec2(1), colorInner=WHITE, colorOuter=CLE
     ASSERT(isNumber(angle), 'angle must be a number');
     ASSERT(!context || !useWebGL, 'context only supported in canvas 2D mode');
 
-    if (headlessMode) return;
+    if (headlessMode && !context) return; // headless has no canvas, only a context passed in is drawn to
 
     if (useWebGL && glEnable)
     {
         ASSERT(!!glContext, 'WebGL is not enabled!');
         if (screenSpace)
         {
-            // convert to world space
-            pos = screenToWorld(pos);
-            size = size.scale(1/cameraScale);
-            angle += cameraAngle;
+            if (glSkipScreenSpace) return;
+            [pos, size, angle] = screenToWorldTransform(pos, size, angle);
         }
         // fan as tristrip; rotate the boundary vertex by one slice per call
         // so back-to-back gradients at the same position have their hole
@@ -992,10 +1163,10 @@ function drawEllipseGradient(pos, size=vec2(1), colorInner=WHITE, colorOuter=CLE
  *  @param {Color}   [colorInner=WHITE]
  *  @param {Color}   [colorOuter=CLEAR_WHITE]
  *  @param {boolean} [useWebGL=glEnable]
- *  @param {boolean} [screenSpace]
+ *  @param {boolean} [screenSpace=drawScreenSpace]
  *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context]
  *  @memberof Draw */
-function drawCircleGradient(pos, size=1, colorInner=WHITE, colorOuter=CLEAR_WHITE, useWebGL=glEnable, screenSpace=false, context)
+function drawCircleGradient(pos, size=1, colorInner=WHITE, colorOuter=CLEAR_WHITE, useWebGL=glEnable, screenSpace=drawScreenSpace, context)
 {
     ASSERT(isNumber(size), 'size must be a number');
     drawEllipseGradient(pos, vec2(size), colorInner, colorOuter, 0, useWebGL, screenSpace, context);
@@ -1013,19 +1184,21 @@ function drawCircleGradient(pos, size=1, colorInner=WHITE, colorOuter=CLEAR_WHIT
  *  (e.g. linear gradients) should flip their own Y endpoints accordingly.
  *  @param {Vector2}  pos
  *  @param {Vector2}  size
- *  @param {number}   angle
+ *  @param {number}   [angle]
  *  @param {boolean}  [mirror]
- *  @param {Canvas2DDrawFunction} [drawFunction]
- *  @param {boolean}  [screenSpace=false]
+ *  @param {Canvas2DDrawFunction} [drawFunction] - Needed, marked optional only because the ones before it are
+ *  @param {boolean}  [screenSpace=drawScreenSpace]
  *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context=drawContext]
  *  @memberof Draw */
-function drawCanvas2D(pos, size, angle=0, mirror=false, drawFunction, screenSpace=false, context=drawContext)
+function drawCanvas2D(pos, size, angle=0, mirror=false, drawFunction, screenSpace=drawScreenSpace, context=drawContext)
 {
     ASSERT(isVector2(pos), 'pos must be a vec2');
     ASSERT(isVector2(size), 'size must be a vec2');
     ASSERT(isNumber(angle), 'angle must be a number');
     ASSERT(typeof drawFunction === 'function', 'drawFunction must be a function');
 
+    if (headlessMode && !context) return; // headless has no canvas, only a context passed in is drawn to
+
     if (!screenSpace)
     {
         pos = worldToScreen(pos);
@@ -1051,7 +1224,7 @@ function drawCanvas2D(pos, size, angle=0, mirror=false, drawFunction, screenSpac
  *  @param {Color}   [color=WHITE]
  *  @param {number}  [lineWidth]
  *  @param {Color}   [lineColor=BLACK]
- *  @param {CanvasTextAlign}  [textAlign='center']
+ *  @param {'left'|'center'|'right'} [textAlign='center']
  *  @param {string}  [font=fontDefault]
  *  @param {string}  [fontStyle]
  *  @param {number}  [maxWidth]
@@ -1064,8 +1237,9 @@ function drawText(text, pos, size=1, color=WHITE, lineWidth=0, lineColor=BLACK,
     pos = worldToScreen(pos);
     size *= cameraScale;
     lineWidth *= cameraScale;
+    if (maxWidth !== undefined)
+        maxWidth *= cameraScale;
     angle -= cameraAngle;
-    angle *= -1;
 
     drawTextScreen(text, pos, size, color, lineWidth, lineColor, textAlign, font, fontStyle, maxWidth, angle, context);
 }
@@ -1078,11 +1252,11 @@ function drawText(text, pos, size=1, color=WHITE, lineWidth=0, lineColor=BLACK,
  *  @param {Color}   [color=WHITE]
  *  @param {number}  [lineWidth]
  *  @param {Color}   [lineColor=BLACK]
- *  @param {CanvasTextAlign}  [textAlign]
+ *  @param {'left'|'center'|'right'} [textAlign]
  *  @param {string}  [font=fontDefault]
  *  @param {string}  [fontStyle]
  *  @param {number}  [maxWidth]
- *  @param {number}  [angle]
+ *  @param {number}  [angle] - Clockwise, like the other screen space draws
  *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context=drawContext]
  *  @memberof Draw */
 function drawTextScreen(text, pos, size, color=WHITE, lineWidth=0, lineColor=BLACK, textAlign='center', font=fontDefault, fontStyle='', maxWidth, angle=0, context=drawContext)
@@ -1097,9 +1271,10 @@ function drawTextScreen(text, pos, size, color=WHITE, lineWidth=0, lineColor=BLA
     ASSERT(isStringLike(font), 'font must be a string');
     ASSERT(isStringLike(fontStyle), 'fontStyle must be a string');
     ASSERT(isNumber(angle), 'angle must be a number');
+
+    if (headlessMode && !context) return; // headless has no canvas, only a context passed in is drawn to
     
     const lines = (text+'').split('\n');
-    const posY = pos.y - (lines.length-1) * size/2; // center vertically
     // save before style mutations so caller's context state is preserved
     context.save();
     context.fillStyle = color.toString();
@@ -1108,9 +1283,9 @@ function drawTextScreen(text, pos, size, color=WHITE, lineWidth=0, lineColor=BLA
     context.textAlign = textAlign;
     context.font = fontStyle + ' ' + size + 'px '+ font;
     context.textBaseline = 'middle';
-    context.translate(pos.x, posY);
-    context.rotate(-angle);
-    let yOffset = 0;
+    context.translate(pos.x + .5, pos.y + .5); // a screen position is the center of a pixel, as for every other draw
+    context.rotate(angle);
+    let yOffset = -(lines.length-1) * size/2; // center vertically
     lines.forEach(line=>
     {
         lineWidth && context.strokeText(line, 0, yOffset, maxWidth);
@@ -1123,29 +1298,37 @@ function drawTextScreen(text, pos, size, color=WHITE, lineWidth=0, lineColor=BLA
 ///////////////////////////////////////////////////////////////////////////////
 // Drawing utilities
 
-/** Load a texture at a specific index
- *  @param {number} textureIndex - Index to store the texture at
+/** Load a texture at a specific index after engineInit, the images passed to engineInit load this way
+ *  @param {number} textureIndex - Index to store the texture at, an unused one
  *  @param {string} [src] - Image source path
- *  @return {Promise} Promise that resolves when texture is loaded
+ *  @return {Promise<TextureInfo>} Resolves to the texture info once the image loads, or fails to with a warning
  *  @memberof Draw */
 async function loadTexture(textureIndex, src)
 {
     ASSERT(isNumber(textureIndex), 'textureIndex must be a number');
-    ASSERT(!textureInfos[textureIndex], 'textureIndex is already loaded!');
+    // engineInit's empty placeholder in slot 0, when it was given no images, or a load that failed can be replaced
+    const old = textureInfos[textureIndex];
+    ASSERT(!old?.size.x, 'textureIndex is already loaded!');
+    old?.destroyWebGLTexture();
     ASSERT(!src || isStringLike(src), 'image src must be a string');
     
     const image = new Image;
     if (src)
     {
-        await new Promise(resolve =>
+        await engineAddLoad(new Promise(resolve => // startup waits for it
         {
-            image.onerror = image.onload = resolve;
+            image.onload = resolve;
+            image.onerror = ()=>
+            {
+                console.warn('failed to load image: ' + src); // in release too, like the WebGL warning
+                resolve();
+            };
             image.crossOrigin = 'anonymous';
             image.src = src;
-        });
+        }));
     }
     
-    textureInfos[textureIndex] = new TextureInfo(image);
+    return textureInfos[textureIndex] = new TextureInfo(image);
 }
 
 /** Convert from screen to world space coordinates
@@ -1212,7 +1395,7 @@ function screenToWorldDelta(screenDelta)
     return new Vector2(x, y);
 }
 
-/** Convert from screen to world space coordinates for a directional vector (no translation)
+/** Convert from world to screen space coordinates for a directional vector (no translation)
  *  @param {Vector2} worldDelta
  *  @return {Vector2}
  *  @memberof Draw */
@@ -1256,6 +1439,14 @@ function screenToWorldTransform(screenPos, screenSize, screenAngle=0)
  *  @memberof Draw */
 function getCameraSize() { return mainCanvasSize.scale(1/cameraScale); }
 
+/** Padding for each side of a rectangle, the sides left out are 0
+ *  @typedef {Object} CameraFitSides
+ *  @property {number} [top]
+ *  @property {number} [right]
+ *  @property {number} [bottom]
+ *  @property {number} [left]
+ *  @memberof Draw */
+
 /** Fit the camera to a rectangle in world space by setting cameraPos and cameraScale
  *  - worldMargin pads the content rectangle in world units, so the gap scales with the content on resize
  *  - screenInset reserves space in screen pixels on each viewport edge (for example a HUD band) and
@@ -1264,8 +1455,8 @@ function getCameraSize() { return mainCanvasSize.scale(1/cameraScale); }
  *    or an object with any of {top, right, bottom, left}
  *  @param {Vector2} center - Center of the rectangle in world space
  *  @param {Vector2} size - Size of the rectangle in world space
- *  @param {number|Vector2|Object} [worldMargin] - World space padding added around the content rectangle
- *  @param {number|Vector2|Object} [screenInset] - Screen space padding in pixels reserved on each viewport edge
+ *  @param {number|Vector2|CameraFitSides} [worldMargin] - World space padding added around the content rectangle
+ *  @param {number|Vector2|CameraFitSides} [screenInset] - Screen space padding in pixels reserved on each viewport edge
  *  @return {number} - The new camera scale
  *  @memberof Draw */
 function cameraFit(center, size, worldMargin, screenInset)
@@ -1285,12 +1476,15 @@ function cameraFit(center, size, worldMargin, screenInset)
     if (!(worldW > 0 && worldH > 0 && viewW > 0 && viewH > 0))
         return cameraScale;
 
-    // scale to fit the padded content
-    cameraScale = min(viewW / worldW, viewH / worldH);
+    // scale to fit the padded content, measured along the camera's axes when it is turned
+    const c = cos(cameraAngle), s = sin(cameraAngle);
+    const fitW = abs(c) * worldW + abs(s) * worldH, fitH = abs(s) * worldW + abs(c) * worldH;
+    cameraScale = min(viewW / fitW, viewH / fitH);
 
-    // calculate offset vectors
+    // calculate offset vectors, the inset is on the screen, so it turns back into the world with the camera
     const marginVector = vec2(margin.right - margin.left, margin.top - margin.bottom).scale(.5);
-    const insetVector = vec2(inset.right - inset.left, inset.top - inset.bottom).scale(.5 / cameraScale);
+    const ix = (inset.right - inset.left) * .5 / cameraScale, iy = (inset.top - inset.bottom) * .5 / cameraScale;
+    const insetVector = vec2(ix * c + iy * s, iy * c - ix * s);
 
     // apply the offsets and return camera scale
     cameraPos = center.add(marginVector).add(insetVector);
@@ -1316,7 +1510,7 @@ function cameraFit(center, size, worldMargin, screenInset)
  *  If size is a Vector2, uses the length as diameter
  *  This can be used to cull offscreen objects from render or update
  *  @param {Vector2} pos - world space position
- *  @param {Vector2|number} size - world space size or diameter
+ *  @param {Vector2|number} [size] - world space size or diameter
  *  @return {boolean}
  *  @memberof Draw */
 function isOnScreen(pos, size=0)
@@ -1327,8 +1521,7 @@ function isOnScreen(pos, size=0)
     // cameraScale of 0 collapses world coords; nothing is visible
     if (!cameraScale) return false;
 
-    // optimized circle on screen test
-    // pos = worldToScreen(pos);
+    // circle on screen test, worldToScreen inlined in doubled screen units so it compares against the full canvas size
     let x = pos.x - cameraPos.x;
     let y = pos.y - cameraPos.y;
     if (cameraAngle)
@@ -1402,6 +1595,31 @@ function combineCanvases()
     mainContext.restore();
 }
 
+// tint straight color pixels in place, rgb times color, plus additiveColor with alpha when it adds anything;
+// returns true when color.a went into the alpha, so it is not applied again as globalAlpha
+function tintImageData(data, color, additiveColor)
+{
+    if (additiveColor && !isBlack(additiveColor))
+    {
+        // multiply + additive (slower), color.a is baked into the alpha channel here
+        const colorMultiply = [color.r, color.g, color.b, color.a];
+        const colorAdd = [additiveColor.r * 255, additiveColor.g * 255,
+                          additiveColor.b * 255, additiveColor.a * 255];
+        for (let i = 0; i < data.length; ++i)
+            data[i] = data[i] * colorMultiply[i&3] + colorAdd[i&3] |0;
+        return true;
+    }
+
+    // RGB only, faster — alpha left intact for the caller
+    for (let i = 0; i < data.length; i+=4)
+    {
+        data[i  ] *= color.r;
+        data[i+1] *= color.g;
+        data[i+2] *= color.b;
+    }
+    return false;
+}
+
 // Internal: bake a color/additive-color tint into workReadCanvas at the
 // image's native resolution. Returns the work canvas, suitable for
 // passing to context.createPattern. Used by drawTextureWrapped's
@@ -1415,45 +1633,27 @@ function bakeTintedImage(image, color, additiveColor)
     workReadContext.drawImage(image, 0, 0);
 
     const imageData = workReadContext.getImageData(0, 0, w, h);
-    const data = imageData.data;
-    if (additiveColor && !isBlack(additiveColor))
-    {
-        // multiply + additive (slower)
-        const colorMultiply = [color.r, color.g, color.b, color.a];
-        const colorAdd = [additiveColor.r * 255, additiveColor.g * 255,
-                          additiveColor.b * 255, additiveColor.a * 255];
-        for (let i = 0; i < data.length; ++i)
-            data[i] = data[i] * colorMultiply[i&3] + colorAdd[i&3] |0;
-    }
-    else
-    {
-        // RGB only, faster — alpha left intact for the caller
-        for (let i = 0; i < data.length; i+=4)
-        {
-            data[i  ] *= color.r;
-            data[i+1] *= color.g;
-            data[i+2] *= color.b;
-        }
-    }
+    tintImageData(imageData.data, color, additiveColor);
     workReadContext.putImageData(imageData, 0, 0);
     return workReadCanvas;
 }
 
-/** Helper function to draw an image with color and additive color applied
- *  This is slower then normal drawImage when color is applied
-    *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} context
-    *  @param {HTMLImageElement|OffscreenCanvas} image
-    *  @param {number} sx
-    *  @param {number} sy
-    *  @param {number} sWidth
-    *  @param {number} sHeight
-    *  @param {number} dx
-    *  @param {number} dy
-    *  @param {number} dWidth
-    *  @param {number} dHeight
-    *  @param {Color} color
-    *  @param {Color} [additiveColor]
-    *  @param {number} [bleed] - How many pixels to shrink the source, used to fix bleeding
+/** Internal: draw an image with color and additive color applied in Canvas2D, drawTile calls it
+ *  This is slower than normal drawImage when color is applied
+ *  @ignore
+ *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} context
+ *  @param {HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap} image
+ *  @param {number} sx
+ *  @param {number} sy
+ *  @param {number} sWidth
+ *  @param {number} sHeight
+ *  @param {number} dx
+ *  @param {number} dy
+ *  @param {number} dWidth
+ *  @param {number} dHeight
+ *  @param {Color} color
+ *  @param {Color} [additiveColor]
+ *  @param {number} [bleed] - How many pixels to shrink the source, used to fix bleeding
  *  @memberof Draw */
 function drawImageColor(context, image, sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight, color, additiveColor, bleed=0)
 {
@@ -1463,9 +1663,9 @@ function drawImageColor(context, image, sx, sy, sWidth, sHeight, dx, dy, dWidth,
     sHeight = max(1,sHeight|0);
     const sWidth2  = sWidth  - 2*bleed;
     const sHeight2 = sHeight - 2*bleed;
-    if (!canvasColorTiles || (additiveColor ? isWhite(color.add(additiveColor)) && additiveColor.a <= 0 : isWhite(color)))
+    if (!canvasColorTiles || isWhite(color) && (!additiveColor || isBlack(additiveColor)))
     {
-        // white texture with no additive alpha, no need to tint
+        // white tint and nothing added, the texels are drawn as they are
         context.globalAlpha = color.a;
         context.drawImage(image, sx+sx2, sy+sy2, sWidth2, sHeight2, dx, dy, dWidth, dHeight);
         context.globalAlpha = 1;
@@ -1479,31 +1679,11 @@ function drawImageColor(context, image, sx, sy, sWidth, sHeight, dx, dy, dWidth,
 
         // tint image using offscreen work context
         const imageData = workReadContext.getImageData(0, 0, sWidth, sHeight);
-        const data = imageData.data;
-        if (additiveColor && !isBlack(additiveColor))
-        {
-            // slower path with additive color
-            const colorMultiply = [color.r, color.g, color.b, color.a];
-            const colorAdd = [additiveColor.r * 255, additiveColor.g * 255, additiveColor.b * 255, additiveColor.a * 255];
-            for (let i = 0; i < data.length; ++i)
-                data[i] = data[i] * colorMultiply[i&3] + colorAdd[i&3] |0;
-            workReadContext.putImageData(imageData, 0, 0);
-            context.drawImage(workReadCanvas, sx2, sy2, sWidth2, sHeight2, dx, dy, dWidth, dHeight);
-        }
-        else
-        {
-            // faster path with no additive color
-            for (let i = 0; i < data.length; i+=4)
-            {
-                data[i  ] *= color.r;
-                data[i+1] *= color.g;
-                data[i+2] *= color.b;
-            }
-            workReadContext.putImageData(imageData, 0, 0);
-            context.globalAlpha = color.a;
-            context.drawImage(workReadCanvas, sx2, sy2, sWidth2, sHeight2, dx, dy, dWidth, dHeight);
-            context.globalAlpha = 1;
-        }
+        const alphaBaked = tintImageData(imageData.data, color, additiveColor);
+        workReadContext.putImageData(imageData, 0, 0);
+        if (!alphaBaked) context.globalAlpha = color.a;
+        context.drawImage(workReadCanvas, sx2, sy2, sWidth2, sHeight2, dx, dy, dWidth, dHeight);
+        if (!alphaBaked) context.globalAlpha = 1;
     }
 }
 
@@ -1556,7 +1736,7 @@ let engineImageFont;
  * const font = engineImageFont;
  *
  * // draw text
- * font.drawTextScreen('LittleJS\nHello World!', vec2(200, 50));
+ * font.drawTextScreen('LittleJS\nHello World!', vec2(200, 50), 16);
  */
 class ImageFont
 {
@@ -1568,14 +1748,15 @@ class ImageFont
         ASSERT(!!tileInfo, 'tileInfo is required for ImageFont');
         
         /** @property {TileInfo} - Tile info for the font */
-        this.tileInfo = tileInfo.frame(0);
+        this.tileInfo = tileInfo; // kept, not copied, so a loadSprite tile filled in once it loads is seen
     }
 
     /** Draw text in world space using the image font
+     *  - The text stays upright and ignores cameraAngle, each glyph is snapped to whole screen pixels to keep it crisp
      *  @param {string|number} text
      *  @param {Vector2} pos
      *  @param {Vector2|number} [size]
-     *  @param {boolean} [center=true]
+     *  @param {boolean} [center=true] - center each line on pos, and the lines of multi-line text around it
      *  @param {Color} [color=WHITE]
      *  @param {boolean} [useWebGL=glEnable]
      *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context] 
@@ -1593,14 +1774,18 @@ class ImageFont
         }
         else
             size = size.scale(cameraScale);
+        // world text, only drawn through screen space, so it still casts in a pass that skips screen space draws
+        const skip = glSkipScreenSpace;
+        glSkipScreenSpace = false;
         this.drawTextScreen(text, worldToScreen(pos), size, center, color, useWebGL, context);
+        glSkipScreenSpace = skip;
     }
 
     /** Draw text in screen space using the image font
      *  @param {string|number} text
      *  @param {Vector2} pos
      *  @param {Vector2|number} size
-     *  @param {boolean} [center]
+     *  @param {boolean} [center] - center each line on pos, and the lines of multi-line text around it
      *  @param {Color} [color=WHITE]
      *  @param {boolean} [useWebGL=glEnable]
      *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context]
@@ -1610,35 +1795,27 @@ class ImageFont
         ASSERT(isStringLike(text), 'text must be a string');
         ASSERT(isVector2(pos), 'pos must be a vec2');
         ASSERT(isVector2(size) || typeof size === 'number', 'size must be a vec2 or number');
+        ASSERT(typeof center === 'boolean', 'center must be a boolean, the color comes after it, unlike drawText');
         ASSERT(isColor(color), 'color must be a color');
 
         // if size is a number, make it a vector
-        size = typeof size === 'number' ? new Vector2(size, size) : size;
+        const glyphSize = typeof size === 'number' ? new Vector2(size, size) : size;
 
-        // precache objects for drawing
+        // precache objects for drawing, a copy of the tile info each glyph moves, the font's own stays put
         const drawPos = new Vector2;
-        const tileInfo = this.tileInfo;
-        const padding = tileInfo.padding;
-        const sizePaddedX = tileInfo.size.x + padding*2;
-        const sizePaddedY = tileInfo.size.y + padding*2;
-        const cols = tileInfo.textureInfo.size.x / sizePaddedX |0;
-
-        // draw each line of text
-        (text+'').split('\n').forEach((line, j)=>
+        const tileInfo = this.tileInfo.frame(0);
+
+        // draw each line of text, centered vertically like drawTextScreen when center is set
+        const lines = (text+'').split('\n');
+        const centerOffsetY = center ? (lines.length-1) * glyphSize.y / 2 : 0;
+        lines.forEach((line, j)=>
         {
-            const centerOffset = center ? (line.length-1) * size.x / 2 : 0;
+            const centerOffset = center ? (line.length-1) * glyphSize.x / 2 : 0;
             for (let i=line.length; i--;)
             {
-                // get the character index
+                // get the glyph, out of range characters use the last one
                 const charCode = line.charCodeAt(i);
-                const index = charCode < 32 || charCode > 127 ?
-                    95 : charCode - 32; // handle out of range characters
-
-                // get the position of the tile
-                const x = index % cols;
-                const y = index / cols |0;
-                tileInfo.pos.x = x*sizePaddedX + padding;
-                tileInfo.pos.y = y*sizePaddedY + padding;
+                this.getGlyphPos(charCode < 32 || charCode > 127 ? 95 : charCode - 32, tileInfo.pos);
 
                 // snap the glyph edges to whole pixels
                 // tiles are drawn from their center, so snapping the center
@@ -1647,12 +1824,28 @@ class ImageFont
                 // no pixel center inside it and is not rasterized at all
                 // ceil picks the nearest aligned position, breaking ties
                 // downward to match how this used to truncate
-                drawPos.x = ceil(pos.x + i * size.x - centerOffset - size.x/2) + size.x/2 - .5;
-                drawPos.y = ceil(pos.y + j * size.y - size.y/2) + size.y/2 - .5;
-                drawTile(drawPos, size, tileInfo, color, 0, false, undefined, useWebGL, true, context);
+                drawPos.x = ceil(pos.x + i * glyphSize.x - centerOffset - glyphSize.x/2) + glyphSize.x/2 - .5;
+                drawPos.y = ceil(pos.y + j * glyphSize.y - centerOffsetY - glyphSize.y/2) + glyphSize.y/2 - .5;
+                drawTile(drawPos, glyphSize, tileInfo, color, 0, false, undefined, useWebGL, true, context);
             }
         });
     }
+
+    /** Get where a glyph sits in the texture: counted in the font's own columns when its tile has them, like a font
+     *  packed by loadSprite, otherwise along the texture's grid from the font's first tile, the way tile() lays it out
+     *  @param {number} index - Glyph number, 0 is the space and the characters follow in ASCII order
+     *  @param {Vector2} [pos] - Written into and returned, for a loop that places many
+     *  @return {Vector2} */
+    getGlyphPos(index, pos=new Vector2)
+    {
+        const t = this.tileInfo, padding = t.padding;
+        const w = t.size.x + padding*2, h = t.size.y + padding*2;
+        if (t.columns)
+            return pos.set(t.pos.x + index % t.columns * w, t.pos.y + (index / t.columns |0) * h);
+        const columns = t.textureInfo.size.x / w |0;
+        const glyph = ((t.pos.y - padding) / h |0) * columns + ((t.pos.x - padding) / w |0) + index;
+        return pos.set(glyph % columns * w + padding, (glyph / columns |0) * h + padding);
+    }
 }
 
 // load engine font, called automatically on startup