littlejsengine 1.24.2 → 1.25.0

package/CHANGELOG.md

@@ -7,6 +7,61 @@ What changed in each release, newest first. Releases before 1.20.0 are on the
 
 Nothing yet.
 
+## 1.25.0 - 2026-10-04
+
+### New Changes
+
+- glTF skinned animation: a rigged character plays its animations, its mesh bent by its joints each frame, the four strongest of up to eight a vertex, on the CPU, so shadows, picking and custom shaders work with it; `object.play(name, loop, speed, blend)` cross-fades from the pose it is in over `blend` seconds, and `object.getJointMatrix(name)` gives a joint's place to hang a sword on a hand
+- Tilt shift and depth of field post effects: `postProcessTiltShift(focus, size, blur)` keeps a band across the screen sharp, in 2D or 3D, and `postProcessDepthOfField(focus, range, blur)` keeps what is at a distance sharp, reading the 3D depth, with the edges of what is in focus kept crisp; the new 3D Focus Blur example focuses either with the mouse
+- `postProcess.values`: a game's own values for the post process shader, set every frame, and any effect setting may name one in place of a number, to change it live without making the shader again, all but glow's size; the shader is made at the first render, so values set right after the plugin is made are in it
+- The 3D Mesh example steps through a dropped model's animations with two buttons or the arrow keys, each cross-faded from the one before
+
+### Breaking Changes
+
+- The names deprecated in 1.20 are gone: `collideTiles` is `collideLevel`, the weld joint's `setSpringDampingRatio` and `getSpringDampingRatio` are `setDampingRatio` and `getDampingRatio` (the wheel joint keeps its own), and `NewgroundsPlugin.logView()`, which did nothing, is removed
+- `drawNineSliceScreen` and `drawThreeSliceScreen` take only the order since 1.20, a color after the tile and then the border size; a number in the color's place asserts in a debug build
+
+### Fixes
+
+- REFERENCE says where the draw functions' parameter orders differ, and has a section on what functions give back: what each raycast returns, overlaps and collide helpers, not found, how a failed load is reported and how each kind of thing is ended; the FAQ lists the global names a game's own top level declarations clash with in a script build
+- REFERENCE has a section on units and directions (angles in radians, clockwise in 2D, what is per frame and what is in seconds), says which vector and color methods give a copy, and names parameters as the code does; the Box2D shape methods, the vector helpers and a few others say what they return
+- In a browser with no audio, a zzfx sound and the page hiding do nothing, where they threw
+- A resume of the audio the browser refuses is caught, where it showed as an uncaught error in the console
+- `debug`, `debugOverlay` and `debugWatermark` are `false` in a release build, as their types say, where they were 0
+- `Box2dPinJoint`'s docs say its point defaults to objectA's position, which the d.ts showed as objectB's
+- TypeScript: `tileLayersLoad` and `objectLayersLoad` take a `TiledMap`, `level3DLoad` a `Level3D`, the types' defaults and properties are records, a tool's `pos` and `ray` and `onPlayFrom`'s position are typed, `levelEditor.open` and `close` return nothing, `Sound` takes a zzfx array as numbers, and `fetchJSON` gives `any`, as JSON is, so its result goes straight into any of them
+- A JSON, glTF or particle effect file that fails to read names the file, and says when it is a web page, as a dev server sends for a mistyped path, where it gave only "Unexpected token '<'"; an OBJ file with no faces warns, naming the file
+- In a release build `levelEditor.edit2D` is there and changes nothing, where it was undefined and a call on it threw, so a game needs no guard around it
+- A shader that fails to build on a device says why in the console in a release build too, where the screen stayed blank with no message: when the engine's own fails, the game draws with Canvas2D, a game's `Shader` that fails draws as if it had none, and a post process that fails leaves the frame as it is
+- The post process depth is read at full precision, where phones with Mali and Adreno GPUs read it at 11 bits and the outline drew false lines on flat ground; the outline draws nothing with no depth texture, and nothing wrong at the sky of a camera with no far plane, where both gave NaN pixels; a value or a setting may not be named as a GLSL word or a name the shader uses, which was a compile error or a value silently hidden; a setting below .01 keeps its digits
+- The 3D shader gives a mesh flattened to nothing on an axis no normal, where it was NaN, keeps the reflection's Fresnel term from NaN specks where a surface is seen head on, and treats fog that starts where it ends, and a shininess of 0, as defined
+- `lineTest`, and the tile raycasts on it, from a whole x or y heading down the grid start in the cell they head into, where they tested the cell behind first and could hit at the start
+- A particle whose `gravityScale` makes it rise lands on a ceiling, where its ground was the way the world's gravity points
+- `readSaveData` takes only an object from storage, where a stored string was spread into its letters
+- Faster where a game grows: path smoothing on a winding path checks lines from each corner, not each cell, a tween stopped among many no longer searches the list, a CSG cut leaves what is far from it alone, so a mesh cut many times does not grow slower to cut, and a paint stroke in the level editor draws the cells it changed, the whole layer only for a game's `onTile` or its own `onRedraw`
+- Examples: the breakout tutorial runs at every step, the platformer's debug explosion is on B, not the dodge key, the Box2D example's smoke rises and its explosion falls off, the raycaster has no fisheye, the 3D Mesh viewer's normals leave a rigged model alone, positions are copied where they were shared, and a list of smaller fixes across the shorts
+- An object whose child's update throws leaves the engine's list of children being updated as it was, where each throw kept them on it for good
+- Level editor: a turned or mirrored stamp turns or mirrors its objects too, each object's rotation with it, a box placed from the corner that becomes its own, a polygon's points and a tile object's image mirrored
+
+## 1.24.3 - 2026-10-03
+
+### Fixes
+
+- TypeScript: the d.ts keeps `undefined` where a value may be missing, so a game in strict mode can write `render3D.shader = undefined` and is told `light.flare`, `levelEditor.edit3D` or `uiSystem.keyInputObject` may be undefined; a game not in strict mode reads the same types as before
+- `box2d.boxCast` and `boxCastAll` say that they test each shape's bounding box, which can find an object near the corner of a turned box or a circle that the box does not touch
+- An image that failed to load gives tiles of no size, which draw nothing, where `tile()` gave NaN places in release builds and stopped debug builds at an assert; a texture slot never given an image still asserts in debug
+- A release build says when a sound, a `loadSprite` or a `loadAtlas` fails to load, as it did for textures and tile sets
+- A `Box2dObject` keeps one `pos` for life, moved in place each step as an EngineObject's is, so a camera holding it follows the body
+- `drawRectGradient` takes no size, as its docs say
+- A release build going on past an error logs each new error, not only the first, and an error every tick no longer runs the game at the screen's refresh rate
+- Under pointer lock a click is a press wherever the locked mouse was left, a letterbox bar too
+- A gamepad with no sticks keeps the one its d-pad stands in for, where its stick count flickered
+- A zzfx `Sound` made in a browser with no audio counts as loaded and plays nothing, where it threw
+- `glCompileShader`, `glCreateProgram` and `glCreateTexture` are typed as giving undefined with no WebGL
+- A release build going on past an error clears that frame's input, where a key press whose action threw was pressed again every frame
+- `loadSprite`, `loadTiles` and `loadAtlas` forget a load whose file failed, so loading it again tries again, where a failure once was kept for the session
+- glTF: a file the model names in subfolders is found when what is in its folder was dropped, not the folder, and a file found by its name alone may have capitals in it, where both said the file was not among those given; the 3D Mesh short keeps a dropped folder's name when other files come with it
+
 ## 1.24.2 - 2026-10-03
 
 ### New Changes

package/EDITOR.md

@@ -22,8 +22,8 @@ is run by `test/editorCustom.test.mjs` straight from this file, so it works as w
    and release are ended for you.
 5. **A type is named by a string**, never by its class, because minified builds rename classes.
 6. **Use `levelEditor.edit3D` and `levelEditor.edit2D` only inside what the editor calls**: a key's action, a
-   button's click, a tool's callbacks, `onUpdate`, `onDraw`. In a release build they are undefined, and none of
-   those are ever called.
+   button's click, a tool's callbacks, `onUpdate`, `onDraw`. In a release build none of those are ever called;
+   `edit2D` is there and changes nothing, and `edit3D` is undefined, as it is in a game without the 3D plugins.
 7. **`levelEditor.is3D`** says which editor is in use, for a game that has both kinds of level.
 
 ## The hooks

package/FAQ.md

@@ -196,6 +196,12 @@ This will show you any errors that occur and allows stepping through code to hel
 A common issue is the image data failing to load with a message like "The image element contains cross-origin data, and may not be loaded."
 This is probably because the game was loaded directly without using a web server!
 
+### Why does my game say a name "has already been declared"?
+
+In a script tag build the engine's names are globals, so a top-level `let`, `const` or `class` in your game with the same name is an error, as is any declaration of a name the engine declares with `let` or `const`, like `time`. A `function` or `var` named like an engine function replaces it instead, which breaks the engine wherever it calls that function. The names most likely to clash are the short ones: `time`, `frame`, `paused`, `debug`, `gravity`, `tile`, `rand`, `percent`, `lerp`, `clamp`, `mod`, `sign`, `min`, `max`, `abs`, `floor`, `round`, `ceil`, `sin`, `cos`, `tan`, `PI`, the colors (`RED`, `GREEN`, `BLUE`, `GRAY`, `WHITE`, `BLACK` and the rest), `mousePos`, `cameraPos`, `medals`, `speak`, `vibrate`, `tweak`, the classes `Timer`, `Sound`, `Color`, `Light`, `Mesh`, `Particle` and `Shader`, and the plugin objects `box2d`, `render3D`, `uiSystem`, `postProcess` and `levelEditor`. [REFERENCE.md](REFERENCE.md) lists every name.
+
+Rename yours, keep your game's state inside an object or class, or use the ES module build, where nothing is global and you import only the names you use (`import * as LJS from 'littlejsengine'` keeps them all under `LJS`).
+
 ### Do I need a local server to run LittleJS games, and how do I set one up?
 
 Yes, this is a necessary step because web browsers just have protection from loading local files which includes images.

package/REFERENCE.md

@@ -82,6 +82,36 @@ let remaining = 36000;
 })();
 ```
 
+## Units and directions
+- **Space:** world units, y up. Draws and objects take full sizes (a circle's diameter); only the math helpers and
+  lights take a radius, and their parameter says so
+- **2D angles:** radians, clockwise: `EngineObject.angle`, `cameraAngle`, the `angle` of every draw and of a
+  `ParticleEmitter`; `Vector2.angle()` is 0 up
+- **3D angles:** radians, `rotation3D` is pitch, yaw and roll, turning as three.js does, counter clockwise seen
+  down an axis; `Camera3D.fov` is radians; a 3D level file and the 3D editor's `setTransform` take degrees, as
+  does `ThreeJSPlugin.cameraFOV`
+- **Per frame:** speeds and spins, `velocity`, `angleVelocity`, a particle's `speed` and `angleSpeed`, damping and
+  gravity, at the fixed 60 updates a second
+- **Seconds:** `Timer`, `Tween`, `time`, a particle emitter's `emitTime` and `particleTime` and its `emitRate` (per
+  second) and `lifeTime`; a particle's `fadeRate` is a part of its life, not seconds
+- **Milliseconds:** `gamepadVibrate`'s duration, `vibrate` patterns and `saveDataURL`'s `revokeTime`
+
+## What functions give back
+- **Raycasts:** where the ray hits, a Vector2: `tileCollisionRaycast`, `lineTest`; how far along the ray, a number:
+  `raycastBox`, `raycastSphere`, `raycastPlane`, `HeightMap.raycast`; a record of the hit: `VoxelMap.raycast` (a
+  `VoxelHit`), `render3D.pick` (`{object, distance}`), `box2d.raycast` (a `Box2dRaycastResult`); every object
+  hit, a list: `engineObjectsRaycast`; nothing hit is `undefined`, or an empty list
+- **Overlaps:** `isOverlapping` and `isIntersecting` say whether, a boolean, as does a layer's `collisionTest`;
+  `tileCollisionTest` gives the layer hit; the collide helpers (`collideCircleBox`, `collideSphereBox` and the rest)
+  give the push that moves the first shape out, each `undefined` for none
+- **Not found:** `undefined`, but `PathFinder.getNode` and `getNearestClearNode`, which give `null`
+- **Loading:** an image that fails, from `engineInit` or `loadTexture`, and a `Sound` made from a file that fails,
+  warn in the console and the game goes on without them; `fetchJSON`, `loadGLTF`, `loadOBJ` and `Sound.loadSound`
+  reject with an error naming the file, for the game to catch
+- **Ending things:** objects, particles, UI, Box2D objects and joints are ended with `destroy`; a `Mesh` or a
+  `GLTFModel` frees its GPU buffers with `dispose`, a `TextureInfo` its texture with `destroyWebGLTexture`; a
+  playing sound, a `Tween` and an animation `stop`
+
 ## LittleJS Utilities Classes and Functions
 - General purpose math library
 - Vector2 - Fast, simple, easy 2D vector class
@@ -116,7 +146,7 @@ lerpAngle(angleA, angleB, percent)            // Linearly interpolates with wrap
 smoothStep(percent)                           // Applies smoothstep function, percent clamped to 0-1
 isPowerOfTwo(value)                           // Checks if the value is a power of two
 nearestPowerOfTwo(value)                      // Smallest power of two not less than the value
-isOverlapping(pointA, sizeA, pointB, sizeB)   // Checks if bounding boxes overlap
+isOverlapping(posA, sizeA, posB, sizeB)       // Checks if bounding boxes overlap
 isIntersecting(start, end, pos, size)         // Checks if ray intersects box
 // the collide helpers answer how far out, where isOverlapping answers whether; boxes are axis aligned and centered
 // with a full size, and each returns undefined when the shapes are not touching
@@ -169,13 +199,13 @@ Vector2.length()                          // Get length
 Vector2.lengthSquared()                   // Get length squared
 Vector2.distance(v)                       // Get distance to vector
 Vector2.distanceSquared(v)                // Get distance to vector squared
-Vector2.normalize(length=1)               // Normalize this vector to length
-Vector2.clampLength(length=1)             // Clamp this vector to length
+Vector2.normalize(length=1)               // Copy of this vector at a length, its direction kept
+Vector2.clampLength(length=1)             // Copy of this vector no longer than a length
 Vector2.dot(v)                            // Dot product with vector
 Vector2.cross(v)                          // Cross product with vector
 Vector2.reflect(normal, restitution=1)    // Reflect off a surface normal
-Vector2.floor()                           // Floor this vector
-Vector2.round()                           // Round this vector
+Vector2.floor()                           // Copy with each component floored
+Vector2.round()                           // Copy with each component rounded
 Vector2.abs()                             // Get copy with absolute value components
 Vector2.snap(grid)                        // Snap down to the grid, grid is steps per unit
 Vector2.mod(divisor=1)                    // Get modulo of each component
@@ -188,6 +218,8 @@ Vector2.rotate(angle)                     // Rotate by angle
 Vector2.setDirection(direction, length=1) // Set integer direction (0-3) and length
 Vector2.direction()                       // Get integer direction (0-3)
 Vector2.toString(digits=3)                // Get string representation
+// every Vector2 and Color method gives a new one and leaves it as it is, but set, setFrom, setAngle and
+// setDirection, and Color's set, setFrom, setAlpha, setHSLA and setHex, which change it in place
 
 // RGBA color object
 Color(r=1, g=1, b=1, a=1)                 // Create an RGBA color
@@ -199,11 +231,11 @@ Color.subtract(c)                         // Subtract a color
 Color.multiply(c)                         // Multiply by a color
 Color.divide(c)                           // Divide by a color
 Color.scale(scale, alphaScale=scale)      // Scale by a float
-Color.clamp()                             // Clamp this color
+Color.clamp()                             // Copy with each component clamped to 0 to 1
 Color.lerp(c, percent)                    // Interpolate between colors
 Color.setHSLA(h=0, s=0, l=1, a=1)         // Set the color from HSLA values
 Color.HSLA()                              // Get the color in HSLA format
-Color.mutate(amount=.05, alphaAmount=0)   // Randomly diverge from this color
+Color.mutate(amount=.05, alphaAmount=0)   // Copy randomly diverged from this color
 Color.setHex(hex)                         // Set this color from a hex code
 Color.setAlpha(a=1)                       // Set the alpha of this color
 Color.withAlpha(a=1)                      // Get a copy of this color with the alpha set
@@ -267,6 +299,14 @@ drawEllipseGradient(pos, size=(1,1), colorInner=WHITE, colorOuter=CLEAR_WHITE, a
 drawCircleGradient(pos, size=1, colorInner=WHITE, colorOuter=CLEAR_WHITE)
 drawCanvas2D(pos, size, angle=0, mirror=false, drawFunction, screenSpace=drawScreenSpace, context)
 
+// Where the orders differ, worth a look when changing one draw for another:
+// - angle is after the colors in drawTile, drawRect, drawEllipse and the gradients, after size in drawCanvas2D,
+//   after lineColor in drawRegularPoly and after pos in drawLine, drawLineList and drawPoly; drawCircle has none
+// - a line's width is before its color in drawLine and drawLineList, the outline's after the fill color, with
+//   lineColor, in drawPoly, drawRegularPoly, drawEllipse, drawCircle and the text
+// - pos comes first in most draws, but is an offset near the end in drawLine, drawLineList and drawPoly
+// - drawText and drawTextScreen draw with Canvas2D and take no useWebGL or screenSpace
+
 // Text functions
 drawText(text, pos, size=1, color=WHITE, lineWidth=0, lineColor=BLACK, textAlign='center', font, fontStyle, maxWidth, angle=0)
 drawTextScreen(text, pos, size, color=WHITE, lineWidth=0, lineColor=BLACK, textAlign='center', font, fontStyle, maxWidth, angle=0)
@@ -487,12 +527,12 @@ AudioFilter.node, AudioReverb.node, ...           // Each effect's wrapped Web A
 
 ```javascript
 // Keyboard, keys are KeyboardEvent.code names like 'KeyW', 'Space' or 'ArrowUp', not characters
-keyIsDown(key)                        // Is key down?
-keyWasPressed(key)                    // Was key pressed this frame?
-keyWasReleased(key)                   // Was key released this frame?
+keyIsDown(key, device=0)              // Is key down? device 0 is the keyboard and mouse, 1 on the gamepads
+keyWasPressed(key, device=0)          // Was key pressed this frame?
+keyWasReleased(key, device=0)         // Was key released this frame?
 keyDirection(up, down, left, right)   // Get input vector from arrow keys or wasd
 inputClear()                          // Clear all input state
-inputClearKey(key)                    // Clear input state for a specific key
+inputClearKey(key, device=0, clearDown=true, clearPressed=true, clearReleased=true) // Clear input state for a key
 
 // Mouse / Touch
 mousePos                              // World space mouse position
@@ -713,9 +753,9 @@ TileCollisionLayer.collisionTest(pos, size=(0,0), object) // Like tileCollisionT
 TileCollisionLayer.collisionRaycast(posStart, posEnd, object, normal) // Like tileCollisionRaycast for this layer only
 TileCollisionLayer.isSolid = true                   // Solid layers block objects and particles, the solidOnly tests
                                                     // skip the others
-tileCollisionGetData(pos)                           // Get tile collision data at pos
+tileCollisionGetData(pos, solidOnly=true)           // Get tile collision data at pos
 tileCollisionTest(pos, size=(0,0), object)          // Check if collision should occur
-tileCollisionRaycast(posStart, posEnd, object, normal, solidOnly=true) // Where the ray meets the first tile hit,
+tileCollisionRaycast(posStart, posEnd, callbackObject, normal, solidOnly=true) // Where the ray meets the first tile hit,
                                                     // or undefined; a normal vec2 passed in is set to the surface's
 tileCollisionLayers                                 // List of all tile collision layers
 tileLayersLoad(tileMapData, tileInfo=tile(), renderOrder=0, collisionLayer, draw=true) // collisionLayer is the index
@@ -783,7 +823,7 @@ particleEffectsBuiltIn                  // the built-in names: fire, torch, smok
 // itself, a continuous one goes until destroyed
 'fire'       // hue .08, continuous
 'torch'      // hue .09, continuous
-'smoke'      // no hue, grey, continuous
+'smoke'      // no hue, gray, continuous
 'steam'      // no hue, white, continuous
 'explosion'  // hue .12, one-shot
 'sparks'     // hue .17, continuous
@@ -806,9 +846,10 @@ particleEffectsBuiltIn                  // the built-in names: fire, torch, smok
 'confetti'   // hue 0 and .6, mixed, one-shot
 'splash'     // hue .58, one-shot
 particleEffectApply(emitter, effect)    // set a live 2D emitter to an effect
-particleEffectApply3D(emitter3D, effect) // the same for a ParticleEmitter3D, its particles, place and scale kept
-particleEffectFromEmitter(emitter)      // a 2D emitter's settings as an effect, to save or build in 3D
-particleEffectsAddBehavior(name, update, update3D) // add a behavior effects can name, with 2D and 3D pushes
+particleEffectApply3D(emitter, effect)  // the same for a ParticleEmitter3D, its particles, place and scale kept
+particleEffectFromEmitter(emitter, name='Effect') // a 2D emitter's settings as an effect, to save or build in 3D
+particleEffectsAddBehavior(name, update, update3D, min=-2, max=2, value=1, description='') // add a behavior effects
+                                        // can name, with 2D and 3D pushes; min, max and value for the designer
 particleEffectsAdd(effects)             // add effects to play by name, one of the same name replaces it
 particleEffectsGet(name)                // an effect's data, any case, to change or build by hand
 await particleEffectsLoad(url)          // load the file the particle designer's Save Library wrote, and add its effects
@@ -973,7 +1014,7 @@ uiSystem.drawSlice(slice, pos, size, color=WHITE) // Draw a TileSlice to the UI
 uiSystem.nativeHeight                  // If set, UI coords are normalized to this height
 uiSystem.destroyObjects()              // Remove all UI elements
 uiSystem.isMouseOverUI()               // True if the mouse is over a visible hoverable UI object, or a confirm dialog is open
-uiSetDebug(enable)                     // Toggle uiDebug rendering of widget bounds
+uiSetDebug(debugMode)                  // Toggle uiDebug rendering of widget bounds
 
 // Confirm dialog
 uiSystem.showConfirmDialog(text='Are you sure?', yes, no, size, exitKey='Escape') // the exit key or gamepad B answers no, the title and buttons scale with size
@@ -1129,6 +1170,16 @@ postProcessChromatic(strength=.005)          // red and blue split apart toward
 postProcessGlow(threshold=.6, strength=1, size=6) // the bloom as a piece
 postProcessOutline(color=BLACK, thickness=1, threshold=.02) // lines where the 3D depth jumps, needs
                                              // render3D.depthTexture
+postProcessTiltShift(focus=.5, size=.25, blur=8) // a sharp band across the screen at focus, 0 bottom to 1 top,
+                                             // size its height, blurred above and below, 2D or 3D
+postProcessDepthOfField(focus=10, range=4, blur=8) // sharp at focus world units from the camera, range deep,
+                                             // blurred nearer and farther; needs render3D.depthTexture
+postProcess.values = {focus: .5}             // the game's own values for the shader, a uniform each, set every
+                                             // frame; any effect setting but glow's size, which sets its sample
+                                             // count, may be such a name, to change it live; set them after the
+                                             // plugin is made, as the shader is made at the first render;
+                                             // not named _x, iX, gl_x, c, uv or p, which the shader uses:
+new PostProcessPlugin(postProcessEffects(postProcessTiltShift('focus'))); postProcess.values.focus = .6; // live
 ```
 
 ## LittleJS 3D Math
@@ -1164,7 +1215,7 @@ m.invert() m.transpose()       // in place, return self
 m.copy() m.transformPoint(v) m.transformDirection(v) m.getTranslation() // or v.transform(m), v.transformDirection(m)
 m.getScale() m.getRotation()   // the scale and the vec3(pitch, yaw, roll) back out of a transform, a mirror is a negative x
 m.determinant()                 // of the rotation and scale part: negative when it mirrors, 0 when it flattens
-buildMatrix(pos, rotation, scale, out)         // translate * rotate * scale, any arg optional; out is written into
+buildMatrix(pos, rotation, scale, matrix)      // translate * rotate * scale, any arg optional; matrix is written into
                                                // instead of a new matrix, for a loop that builds many each frame
 
 // Collision - boxes are centered with full size, upright unless given a rotation, an Euler vec3 like rotation3D;
@@ -1687,8 +1738,9 @@ await loadOBJ(url, smooth) // fetch then parse, in an async gameInit; chain .cen
                            // units
 
 // glTF models - the glTF plugin, .gltf with its files beside it or .glb in one file; meshes with their node placement,
-// vertex colors, material colors and base color textures, and node animations; no skins or morph targets, and no
-// Draco or meshopt compressed geometry, which throws saying so
+// vertex colors, material colors and base color textures, node animations and skinned characters, four joints a
+// vertex, bent on the CPU each frame; no morph targets, and no Draco or meshopt compressed geometry, which throws
+// saying so
 const model = await loadGLTF(url)   // a GLTFModel, in an async gameInit; or await parseGLTF(data, baseUrl, files) on
                                      // bytes or JSON you already have; files, a Map of the .bin and image files a
                                      // .gltf names by their paths, like the files of a drop, in place of fetching,
@@ -1709,15 +1761,20 @@ model.createObject(pos3D)            // a GLTFObject, an EngineObject3D with a c
                                      // emissive 1 for an unlit one; move and turn the root and the parts follow
 model.animations                     // one GLTFAnimation each: name, duration in seconds, and the channels that
                                      // move, turn and scale nodes; model.getAnimation(nameOrNumber) finds one
-object.play(animation=0, loop=true, speed=1) // play one on a GLTFObject by name or number, its parts move with it;
-                                     // speed below 0 plays it backward, and one that does not loop holds its end
+object.play(animation=0, loop=true, speed=1, blend=0) // play one on a GLTFObject by name or number, its parts move
+                                     // and a skinned mesh bends with it; speed below 0 plays it backward, one that
+                                     // does not loop holds its end, and blend is seconds to cross-fade from the pose
+                                     // it is in, the animation it leaves going on through the fade
+object.getJointMatrix(name)          // a node's world Matrix4 as posed now, by its name in the file, to hang a sword
+                                     // on a hand; undefined for a name the model does not have
 object.stop()                        // hold the pose where it is; object.setAnimationTime(t) poses it at a time
 object.animation .animationTime .animationSpeed .animationLoop .animationPlaying
 model.getPose(animation, time)       // one Matrix4 per part, how far it moved from its resting place
 model.dispose()                      // free the part meshes, the combined mesh and the textures of a model that
                                      // is done with; destroy the objects createObject made first
 // colors come in converted from glTF's linear values, a NEAREST sampler makes a part pixelated, sparse accessors
-// are read, and object.parts is what an animation poses
+// are read, and object.parts is what an animation poses; a skinned part's object bends a mesh of its own, so
+// characters of one model hold their own poses, and part.skin is what bends it
 model.center().fit(size)             // move the model's bounds onto the origin and scale its largest extent to
                                      // size, every part together, like Mesh.center and fit; getBounds and
                                      // transform(matrix) as well
@@ -1840,8 +1897,8 @@ new THREE.Raycaster()                     // render3D.screenToRay, pick and engi
 OBJLoader                                 // loadOBJ(url) or parseOBJ(text)
 GLTFLoader                                // loadGLTF(url): model.createObject(pos) is the scene as objects, model.mesh
                                           // is everything as one Mesh
-mixer.clipAction(clip).play()             // object.play(name) on the object createObject made, node animation only,
-                                          // no skinned characters
+mixer.clipAction(clip).play()             // object.play(name) on the object createObject made, skinned characters
+crossFadeTo(next, seconds)                // object.play(next, true, 1, seconds); bone.getWorldPosition: getJointMatrix
 EffectComposer and UnrealBloomPass        // postProcessBloom()
 renderer.render(scene, camera)            // nothing to do, the engine draws every frame and handles resizing
 position.setUsage(THREE.DynamicDrawUsage) // mesh.dynamicDraw = true once, then mesh.dirty = true when the points
@@ -2048,7 +2105,8 @@ box2d.raycast(start, end, includeSensors=false)    // Returns the closest Box2dR
                                                    // are passed through unless includeSensors
 box2d.raycastAll(start, end, includeSensors=false) // Every Box2dRaycastResult along the ray, nearest first
 box2d.boxCast(pos, size, includeSensors=false) / boxCastAll(pos, size, includeSensors=false) // An object, or all
-                               // of them, whose shapes overlap the box; sensors are passed through unless included
+                               // of them, whose shapes' bounding boxes overlap the box, so near the corner of a turned
+                               // box or a circle it can find one the box misses; sensors are passed through unless included
 box2d.circleCast(pos, diameter, includeSensors=false) / circleCastAll(pos, diameter, includeSensors=false) // The
                                // nearest object, or all of them, whose position is in the circle, wherever its shapes
                                // are; objects of only sensors are passed over unless included
@@ -2300,7 +2358,7 @@ debugPoint(pos, color, time, angle)                         // Draw debug point
 debugLine(posA, posB, color, width=.1, time)                // Draw debug line
 debugPoly(pos, points, color=WHITE, time=0, angle=0, fill)  // Draw debug polygon
 debugText(text, pos, size=1, color=WHITE, time=0, angle=0)  // Draw debug text
-debugOverlap(pA, sA, pB, sB, color) // Draw a debug overlap between two boxes
+debugOverlap(posA, sizeA, posB, sizeB, color) // Draw a debug overlap between two boxes
 // each debug draw also takes screenSpace as its last parameter, defaulting to drawScreenSpace; debugText takes a
 // font before it
 debugClear()                     // Clear all debug primitives
@@ -2326,19 +2384,6 @@ debugTweakables = false // Is the tweakables panel shown? setDebugTweakables(sho
 debugWatermark       // Should watermark with FPS appear in debug mode?
 ```
 
-## Deprecated
-
-Old names and argument orders that still work, marked `@deprecated` in the types; use the new ones, the old are
-kept until 1.25 at least.
-
-```javascript
-obj.collideTiles                         // since 1.20, use obj.collideLevel, the same flag
-weldJoint.setSpringDampingRatio(ratio)   // since 1.20, use setDampingRatio, and getDampingRatio for the getter
-newgrounds.logView()                     // since 1.20, does nothing, the view is logged when the plugin starts
-drawNineSliceScreen(pos, size, startTile, borderSize, extraSpace, angle) // since 1.20, the order is now
-drawThreeSliceScreen(pos, size, startTile, borderSize, extraSpace, angle) // (pos, size, startTile, color, ...)
-```
-
 [LittleJS Engine](https://github.com/KilledByAPixel/LittleJS) Copyright 2021 Frank Force
 
 ![LittleJS Logo](examples/favicon.png)