nexus-2d 0.0.6 → 0.0.8

package/dist/cjs/index.cjs

@@ -59876,6 +59876,963 @@ class SpriteAtlas {
     }
 }
 
+// tilemap-profiler.js
+// Instruments tilemap rendering to expose the waste
+
+class TilemapProfiler {
+    constructor() {
+        this.reset();
+    }
+
+    reset() {
+        this.frameCount = 0;
+        this.totalPixelsTouched = 0;
+        this.totalBlitCalls = 0;
+        this.totalChunksDrawn = 0;
+        this.cameraMovedFrames = 0;
+        this.cameraStaticFrames = 0;
+        this.lastCameraPos = { x: 0, y: 0 };
+    }
+
+    startFrame(camera) {
+        this.frameCount++;
+        
+        // Track if camera moved
+        const moved = camera.worldPosition.x !== this.lastCameraPos.x || 
+                     camera.worldPosition.y !== this.lastCameraPos.y;
+        
+        if (moved) {
+            this.cameraMovedFrames++;
+        } else {
+            this.cameraStaticFrames++;
+        }
+
+        this.lastCameraPos.x = camera.worldPosition.x;
+        this.lastCameraPos.y = camera.worldPosition.y;
+    }
+
+    recordBlit(width, height) {
+        this.totalBlitCalls++;
+        this.totalPixelsTouched += width * height;
+    }
+
+    recordChunk() {
+        this.totalChunksDrawn++;
+    }
+
+    getReport() {
+        if (this.frameCount === 0) return "No frames recorded";
+
+        const avgPixelsPerFrame = this.totalPixelsTouched / this.frameCount;
+        const avgBlitsPerFrame = this.totalBlitCalls / this.frameCount;
+        const avgChunksPerFrame = this.totalChunksDrawn / this.frameCount;
+        const wasteRatio = this.cameraStaticFrames / this.frameCount;
+
+        return {
+            totalFrames: this.frameCount,
+            cameraMovedFrames: this.cameraMovedFrames,
+            cameraStaticFrames: this.cameraStaticFrames,
+            wasteRatio: (wasteRatio * 100).toFixed(1) + '%',
+            avgPixelsPerFrame: avgPixelsPerFrame.toFixed(0),
+            avgBlitsPerFrame: avgBlitsPerFrame.toFixed(1),
+            avgChunksPerFrame: avgChunksPerFrame.toFixed(1),
+            totalPixelsTouched: this.totalPixelsTouched,
+            wastedPixels: (avgPixelsPerFrame * this.cameraStaticFrames).toFixed(0),
+            
+            // The smoking gun
+            redundantWork: `${this.cameraStaticFrames} frames redrew ${avgPixelsPerFrame.toFixed(0)} pixels each for ZERO camera movement`
+        };
+    }
+
+    printReport() {
+        const r = this.getReport();
+        console.log('\n=== TILEMAP RENDER WASTE REPORT ===');
+        console.log(`Total frames analyzed: ${r.totalFrames}`);
+        console.log(`Camera moved: ${r.cameraMovedFrames} frames`);
+        console.log(`Camera static: ${r.cameraStaticFrames} frames`);
+        console.log(`Waste ratio: ${r.wasteRatio} of frames were redundant`);
+        console.log(`\nPer-frame averages:`);
+        console.log(`  Pixels touched: ${r.avgPixelsPerFrame}`);
+        console.log(`  Blit calls: ${r.avgBlitsPerFrame}`);
+        console.log(`  Chunks drawn: ${r.avgChunksPerFrame}`);
+        console.log(`\nTotal waste:`);
+        console.log(`  Pixels touched: ${r.totalPixelsTouched.toLocaleString()}`);
+        console.log(`  Wasted pixels (static frames): ${r.wastedPixels.toLocaleString()}`);
+        console.log(`\n⚠️  ${r.redundantWork}`);
+        console.log('=====================================\n');
+    }
+}
+
+// Singleton instance
+const tilemapProfiler = new TilemapProfiler();
+
+CacheBuffer.prototype.markRegion = (...args) => { }; // trickc
+
+
+
+class CameraTracker {
+    constructor() {
+        this.lastPosition = { x: 0, y: 0 };
+        this.lastZoom = 1.0;
+        this.currentPosition = { x: 0, y: 0 };
+        this.currentZoom = 1.0;
+
+        // Movement stats
+        this.totalFrames = 0;
+        this.staticFrames = 0;
+        this.smallMoveFrames = 0;  // < threshold
+        this.largeMoveFrames = 0;  // >= threshold
+        this.teleportFrames = 0;   // way outside cache
+
+        // Thresholds (pixels)
+        this.smallMoveThreshold = 32;  // moves smaller than this are "small"
+        this.teleportThreshold = 256;  // moves larger than this are "teleports"
+    }
+
+    //  this at start of each frame
+    update(camera) {
+        this.totalFrames++;
+
+        this.currentPosition.x = camera.worldPosition.x;
+        this.currentPosition.y = camera.worldPosition.y;
+        this.currentZoom = camera.zoom || camera.worldZoom || 1.0;
+
+        const delta = this.getDelta();
+        const distance = Math.sqrt(delta.x * delta.x + delta.y * delta.y);
+
+        // Classify movement
+        if (delta.x === 0 && delta.y === 0 && delta.zoom === 0) {
+            this.staticFrames++;
+        } else if (distance < this.smallMoveThreshold) {
+            this.smallMoveFrames++;
+        } else if (distance < this.teleportThreshold) {
+            this.largeMoveFrames++;
+        } else {
+            this.teleportFrames++;
+        }
+    }
+
+    // Get movement delta since last frame
+    getDelta() {
+        return {
+            x: this.currentPosition.x - this.lastPosition.x,
+            y: this.currentPosition.y - this.lastPosition.y,
+            zoom: this.currentZoom - this.lastZoom,
+            magnitude: Math.sqrt(
+                Math.pow(this.currentPosition.x - this.lastPosition.x, 2) +
+                Math.pow(this.currentPosition.y - this.lastPosition.y, 2)
+            )
+        };
+    }
+
+    // Check if camera moved at all
+    hasMoved() {
+        const d = this.getDelta();
+        return d.x !== 0 || d.y !== 0 || d.zoom !== 0;
+    }
+
+    // Check if movement is small enough for incremental update
+    isSmallMove() {
+        return this.getDelta().magnitude < this.smallMoveThreshold;
+    }
+
+    // Check if this is a teleport (need full redraw)
+    isTeleport() {
+        return this.getDelta().magnitude >= this.teleportThreshold;
+    }
+
+    // Check if zoom changed
+    zoomChanged() {
+        return this.currentZoom !== this.lastZoom;
+    }
+
+    // Call at end of frame to commit current position as "last"
+    commit() {
+        this.lastPosition.x = this.currentPosition.x;
+        this.lastPosition.y = this.currentPosition.y;
+        this.lastZoom = this.currentZoom;
+    }
+
+    // Get movement direction (for determining which edge to update)
+    getDirection() {
+        const delta = this.getDelta();
+        const absX = Math.abs(delta.x);
+        const absY = Math.abs(delta.y);
+
+        // Primary direction is the larger component
+        if (absX > absY) {
+            return delta.x > 0 ? 'right' : 'left';
+        } else if (absY > absX) {
+            return delta.y > 0 ? 'down' : 'up';
+        } else if (absX === absY && absX > 0) {
+            // Diagonal - return both directions
+            const h = delta.x > 0 ? 'right' : 'left';
+            const v = delta.y > 0 ? 'down' : 'up';
+            return `${v}-${h}`; // e.g., "down-right"
+        }
+
+        return 'none';
+    }
+
+    // Get stats about camera movement patterns
+    getStats() {
+        if (this.totalFrames === 0) return null;
+
+        return {
+            totalFrames: this.totalFrames,
+            staticFrames: this.staticFrames,
+            smallMoveFrames: this.smallMoveFrames,
+            largeMoveFrames: this.largeMoveFrames,
+            teleportFrames: this.teleportFrames,
+            staticRatio: (this.staticFrames / this.totalFrames * 100).toFixed(1) + '%',
+            smallMoveRatio: (this.smallMoveFrames / this.totalFrames * 100).toFixed(1) + '%',
+            largeMoveRatio: (this.largeMoveFrames / this.totalFrames * 100).toFixed(1) + '%',
+            teleportRatio: (this.teleportFrames / this.totalFrames * 100).toFixed(1) + '%'
+        };
+    }
+
+    printStats() {
+        const s = this.getStats();
+        if (!s) {
+            console.log('No camera movement data yet');
+            return;
+        }
+
+        console.log('\n=== CAMERA MOVEMENT STATS ===');
+        console.log(`Total frames: ${s.totalFrames}`);
+        console.log(`Static (no movement): ${s.staticFrames} (${s.staticRatio})`);
+        console.log(`Small moves (<32px): ${s.smallMoveFrames} (${s.smallMoveRatio})`);
+        console.log(`Large moves (32-256px): ${s.largeMoveFrames} (${s.largeMoveRatio})`);
+        console.log(`Teleports (>256px): ${s.teleportFrames} (${s.teleportRatio})`);
+        console.log('============================\n');
+    }
+}
+
+
+class CacheUpdateStrategy {
+    static determine(delta, cacheMargin) {
+        const dist = delta.magnitude;
+
+        // Zoom change always requires full redraw
+        if (delta.zoom !== 0) {
+            return { type: 'FULL_REDRAW', reason: 'zoom changed' };
+        }
+
+        // No movement - no update needed
+        if (dist === 0) {
+            return { type: 'NONE', reason: 'camera static' };
+        }
+
+        // Teleport - full redraw
+        if (dist > cacheMargin * 0.8) {
+            return { type: 'FULL_REDRAW', reason: 'teleport (outside cache margin)' };
+        }
+
+        // Small move - incremental update
+        if (dist < cacheMargin * 0.5) {
+            return {
+                type: 'INCREMENTAL',
+                reason: 'small move (within cache margin)',
+                delta: delta
+            };
+        }
+
+        // Medium move - still incremental but closer to limit
+        return {
+            type: 'INCREMENTAL',
+            reason: 'medium move',
+            delta: delta
+        };
+    }
+}
+
+// shifting 
+
+class CacheShifter {
+
+    // Shift buffer content left by dx pixels
+    // This is called when camera moves RIGHT
+    static shiftLeft(buffer, dx) {
+        if (dx <= 0 || dx >= buffer.width) return;
+
+        const data = buffer.data;
+        const width = buffer.width;
+        const height = buffer.height;
+        const shiftPixels = Math.floor(dx);
+
+        // Process row by row
+        // Each row: copy pixels from [shiftPixels...width] to [0...width-shiftPixels]
+        for (let y = 0; y < height; y++) {
+            const rowStart = y * width * 4;
+            const srcStart = rowStart + shiftPixels * 4;
+            const copyWidth = (width - shiftPixels) * 4;
+
+            // Copy row content leftward
+            data.copyWithin(rowStart, srcStart, srcStart + copyWidth);
+        }
+    }
+
+    // Shift buffer content right by dx pixels
+    // Called when camera moves LEFT
+    static shiftRight(buffer, dx) {
+        if (dx <= 0 || dx >= buffer.width) return;
+
+        const data = buffer.data;
+        const width = buffer.width;
+        const height = buffer.height;
+        const shiftPixels = Math.floor(dx);
+
+        // Process row by row, BACKWARDS to avoid overwriting
+        for (let y = height - 1; y >= 0; y--) {
+            const rowStart = y * width * 4;
+            const dstStart = rowStart + shiftPixels * 4;
+            const copyWidth = (width - shiftPixels) * 4;
+
+            // Copy row content rightward
+            data.copyWithin(dstStart, rowStart, rowStart + copyWidth);
+        }
+    }
+
+    // Shift buffer content up by dy pixels
+    // Called when camera moves DOWN
+    static shiftUp(buffer, dy) {
+        if (dy <= 0 || dy >= buffer.height) return;
+
+        const data = buffer.data;
+        const width = buffer.width;
+        const height = buffer.height;
+        const shiftRows = Math.floor(dy);
+        const rowBytes = width * 4;
+
+        // Copy rows upward
+        // Move rows [shiftRows...height] to [0...height-shiftRows]
+        const srcStart = shiftRows * rowBytes;
+        const copyBytes = (height - shiftRows) * rowBytes;
+
+        data.copyWithin(0, srcStart, srcStart + copyBytes);
+    }
+
+    // Shift buffer content down by dy pixels
+    // Called when camera moves UP
+    static shiftDown(buffer, dy) {
+        if (dy <= 0 || dy >= buffer.height) return;
+
+        const data = buffer.data;
+        const width = buffer.width;
+        const height = buffer.height;
+        const shiftRows = Math.floor(dy);
+        const rowBytes = width * 4;
+
+        // Copy rows downward, process backwards to avoid overwrite
+        const srcBytes = (height - shiftRows) * rowBytes;
+        const dstStart = shiftRows * rowBytes;
+
+        data.copyWithin(dstStart, 0, srcBytes);
+    }
+
+    // Combined shift for diagonal movement
+    // Does horizontal first, then vertical
+    static shift(buffer, dx, dy) {
+        // Horizontal shift
+        if (dx > 0) {
+            this.shiftLeft(buffer, dx);
+        } else if (dx < 0) {
+            this.shiftRight(buffer, -dx);
+        }
+
+        // Vertical shift
+        if (dy > 0) {
+            this.shiftUp(buffer, dy);
+        } else if (dy < 0) {
+            this.shiftDown(buffer, -dy);
+        }
+    }
+}
+
+// ============= THE FIX =============
+// The key insight: we need to calculate world regions BEFORE updating worldX/worldY
+// because the regions represent what NEW content to draw, relative to the OLD cache position
+
+class ShiftRegionCalculator {
+    static calculateNewRegions(oldWorldX, oldWorldY, cacheWidth, cacheHeight, deltaX, deltaY) {
+        const regions = [];
+
+        // deltaX/Y represent camera movement in world space
+        // We calculate which regions of the NEW cache bounds need fresh rendering
+
+        if (deltaX > 0) {
+            // Camera moved right → old cache was at oldWorldX, now at oldWorldX + deltaX
+            // The NEW right edge shows world content that wasn't in the old cache
+            // World coordinates: from (oldWorldX + cacheWidth) to (oldWorldX + cacheWidth + deltaX)
+            regions.push({
+                cache: {
+                    x: cacheWidth - Math.floor(deltaX),
+                    y: 0,
+                    width: Math.floor(deltaX),
+                    height: cacheHeight
+                },
+                world: {
+                    x: oldWorldX + cacheWidth,  // Right edge of OLD cache
+                    y: oldWorldY,
+                    width: Math.floor(deltaX),
+                    height: cacheHeight
+                },
+                edge: 'right'
+            });
+        } else if (deltaX < 0) {
+            // Camera moved left → new left edge needs rendering
+            const absDx = Math.floor(-deltaX);
+            regions.push({
+                cache: {
+                    x: 0,
+                    y: 0,
+                    width: absDx,
+                    height: cacheHeight
+                },
+                world: {
+                    x: oldWorldX + deltaX,  // New left edge in world space
+                    y: oldWorldY,
+                    width: absDx,
+                    height: cacheHeight
+                },
+                edge: 'left'
+            });
+        }
+
+        if (deltaY > 0) {
+            // Camera moved down → new bottom edge
+            const absDy = Math.floor(deltaY);
+            regions.push({
+                cache: {
+                    x: 0,
+                    y: cacheHeight - absDy,
+                    width: cacheWidth,
+                    height: absDy
+                },
+                world: {
+                    x: oldWorldX,
+                    y: oldWorldY + cacheHeight,  // Bottom edge of OLD cache
+                    width: cacheWidth,
+                    height: absDy
+                },
+                edge: 'bottom'
+            });
+        } else if (deltaY < 0) {
+            // Camera moved up → new top edge
+            const absDy = Math.floor(-deltaY);
+            regions.push({
+                cache: {
+                    x: 0,
+                    y: 0,
+                    width: cacheWidth,
+                    height: absDy
+                },
+                world: {
+                    x: oldWorldX,
+                    y: oldWorldY + deltaY,  // New top edge in world space
+                    width: cacheWidth,
+                    height: absDy
+                },
+                edge: 'top'
+            });
+        }
+
+        return regions;
+    }
+}
+
+
+class FullMapPreRender {
+    constructor(mapWidth, mapHeight) {
+        this.mapWidth = mapWidth;
+        this.mapHeight = mapHeight;
+        this.buffer = new CacheBuffer(mapWidth, mapHeight);
+        this.rendered = false;
+        this.pixelsDrawn = 0;
+
+        console.log(`[FullMapPreRender] Created ${mapWidth}x${mapHeight} full-map buffer`);
+    }
+
+    render(renderCallback) {
+        if (this.rendered) return;
+
+        console.log(`[FullMapPreRender] Rendering full map...`);
+        this.buffer.clear(0, 0, 0, 0);
+        
+        renderCallback(this.buffer);
+        this.pixelsDrawn = this.mapWidth * this.mapHeight;
+        this.rendered = true;
+    }
+
+    copyToDisplay(displayCanvas, camera) {
+        const cameraWorldX = camera.worldPosition.x;
+        const cameraWorldY = camera.worldPosition.y;
+
+        // offset within full map buffer where camera is looking
+        const bufferOffsetX = cameraWorldX;
+        const bufferOffsetY = cameraWorldY;
+
+        this._blitRegion(
+            this.buffer,
+            bufferOffsetX,
+            bufferOffsetY,
+            displayCanvas.width,
+            displayCanvas.height,
+            displayCanvas,
+            0,
+            0
+        );
+    }
+
+    _blitRegion(srcBuffer, srcX, srcY, width, height, dstCanvas, dstX, dstY) {
+        const srcData = srcBuffer.data;
+        const dstData = dstCanvas.data;
+        const srcW = srcBuffer.width;
+        const srcH = srcBuffer.height;
+        const dstW = dstCanvas.width;
+        const dstH = dstCanvas.height;
+
+        // Clamp source bounds
+        const srcStartX = Math.max(0, Math.floor(srcX));
+        const srcStartY = Math.max(0, Math.floor(srcY));
+        const srcEndX = Math.min(srcW, Math.ceil(srcX + width));
+        const srcEndY = Math.min(srcH, Math.ceil(srcY + height));
+
+        // Clamp destination bounds
+        const dstStartX = Math.max(0, Math.floor(dstX));
+        const dstStartY = Math.max(0, Math.floor(dstY));
+        const dstEndX = Math.min(dstW, Math.floor(dstX + (srcEndX - srcStartX)));
+        const dstEndY = Math.min(dstH, Math.floor(dstY + (srcEndY - srcStartY)));
+
+        const copyWidth = dstEndX - dstStartX;
+        const copyHeight = dstEndY - dstStartY;
+
+        if (copyWidth <= 0 || copyHeight <= 0) return;
+
+        // Adjust source start if destination was clamped
+        const srcOffsetX = dstStartX - Math.floor(dstX);
+        const srcOffsetY = dstStartY - Math.floor(dstY);
+
+        // Fast row-by-row copy
+        for (let y = 0; y < copyHeight; y++) {
+            const srcRowStart = ((srcStartY + srcOffsetY + y) * srcW + srcStartX + srcOffsetX) * 4;
+            const dstRowStart = ((dstStartY + y) * dstW + dstStartX) * 4;
+
+            dstData.set(
+                srcData.subarray(srcRowStart, srcRowStart + copyWidth * 4),
+                dstRowStart
+            );
+        }
+
+        dstCanvas.markRegion(dstStartX, dstStartY, copyWidth, copyHeight);
+    }
+
+    getStats() {
+        return {
+            mapSize: `${this.mapWidth}x${this.mapHeight}`,
+            rendered: this.rendered,
+            pixelsDrawn: this.pixelsDrawn
+        };
+    }
+
+    printStats() {
+        const s = this.getStats();
+        console.log('FULL MAP PRE-RENDER STATS');
+        console.log(`Map size: ${s.mapSize}`);
+        console.log(`Rendered: ${s.rendered}`);
+        console.log(`Pixels drawn: ${s.pixelsDrawn}`);
+        console.log('=============================\n');
+    }
+}
+
+
+class OffscreenTilemapCache {
+    constructor(viewportWidth, viewportHeight, marginRatio = 0.25) {
+        this.viewportWidth = viewportWidth;
+        this.viewportHeight = viewportHeight;
+        this.marginRatio = marginRatio;
+        const marginX = Math.ceil(viewportWidth * marginRatio);
+        const marginY = Math.ceil(viewportHeight * marginRatio);
+
+        this.cacheWidth = viewportWidth + marginX * 2;
+        this.cacheHeight = viewportHeight + marginY * 2;
+        this.marginPixels = { x: marginX, y: marginY };
+
+        this.buffer = new CacheBuffer(this.cacheWidth, this.cacheHeight);
+
+        this.worldX = 0;
+        this.worldY = 0;
+
+
+        this.dirty = true;
+
+        this.tracker = new CameraTracker();
+
+        this.fullRedraws = 0;
+        this.incrementalUpdates = 0;
+        this.copies = 0;
+        this.skippedUpdates = 0;
+        this.pixelsShifted = 0;
+        this.pixelsDrawn = 0;
+
+        console.log(`[OffscreenCache] Created ${this.cacheWidth}x${this.cacheHeight} cache for ${viewportWidth}x${viewportHeight} viewport`);
+    }
+
+    needsUpdate(camera) {
+        this.tracker.update(camera);
+        const delta = this.tracker.getDelta();
+
+        // Use margin size as threshold for determining update type
+        const marginSize = Math.min(this.marginPixels.x, this.marginPixels.y);
+        return CacheUpdateStrategy.determine(delta, marginSize);
+
+    }
+
+    incrementalUpdate(delta, renderCallback) {
+        const dx = delta.x;
+        const dy = delta.y;
+
+        // STEP 1: Calculate regions BEFORE updating worldX/worldY
+        // This is the fix - we need the OLD cache position to know what's NEW
+        const oldWorldX = this.worldX;
+        const oldWorldY = this.worldY;
+
+        const newRegions = ShiftRegionCalculator.calculateNewRegions(
+            oldWorldX,
+            oldWorldY,
+            this.cacheWidth,
+            this.cacheHeight,
+            dx,
+            dy
+        );
+
+        // STEP 2: Shift buffer content
+        CacheShifter.shift(this.buffer, dx, dy);
+        this.pixelsShifted += this.cacheWidth * this.cacheHeight;
+
+        // STEP 3: Render new regions (BEFORE updating world bounds)
+        // Each region now has BOTH cache coords and world coords pre-calculated
+        for (const region of newRegions) {
+            this.pixelsDrawn += region.cache.width * region.cache.height;
+            renderCallback(region.cache, region.world);
+        }
+
+        // STEP 4: Update world bounds (NOW, after rendering)
+        this.worldX += dx;
+        this.worldY += dy;
+
+        this.incrementalUpdates++;
+    }
+
+    commitFrame() {
+        this.tracker.commit();
+    }
+
+    invalidate() {
+        this.dirty = true;
+    }
+
+    setWorldRegion(worldX, worldY) {
+        this.worldX = worldX;
+        this.worldY = worldY;
+    }
+
+    getWorldBounds() {
+        return {
+            left: this.worldX,
+            top: this.worldY,
+            right: this.worldX + this.cacheWidth,
+            bottom: this.worldY + this.cacheHeight,
+            width: this.cacheWidth,
+            height: this.cacheHeight
+        };
+    }
+
+    isCameraInBounds(camera) {
+        const bounds = this.getWorldBounds();
+        const camX = camera.worldPosition.x;
+        const camY = camera.worldPosition.y;
+
+        // Camera should stay within the inner viewport area, not near edges
+        const safeLeft = bounds.left + this.marginPixels.x;
+        const safeRight = bounds.right - this.marginPixels.x;
+        const safeTop = bounds.top + this.marginPixels.y;
+        const safeBottom = bounds.bottom - this.marginPixels.y;
+
+        return camX >= safeLeft && camX <= safeRight &&
+            camY >= safeTop && camY <= safeBottom;
+    }
+
+    clear() {
+        this.buffer.clear(0, 0, 0, 0);
+    }
+
+    copyToDisplay(displayCanvas, camera) {
+        this.copies++;
+
+
+        const cameraWorldX = camera.worldPosition.x;
+        const cameraWorldY = camera.worldPosition.y;
+
+        // offset within cache where camera is looking
+        const cacheOffsetX = cameraWorldX - this.worldX;
+        const cacheOffsetY = cameraWorldY - this.worldY;
+
+
+        this._blitRegion(
+            this.buffer,
+            cacheOffsetX,
+            cacheOffsetY,
+            this.viewportWidth,
+            this.viewportHeight,
+            displayCanvas,
+            0,
+            0
+        );
+    }
+
+    // Fast blit from cache to display - assumes opaque
+    _blitRegion(srcBuffer, srcX, srcY, width, height, dstCanvas, dstX, dstY) {
+        const srcData = srcBuffer.data;
+        const dstData = dstCanvas.data;
+        const srcW = srcBuffer.width;
+        const srcH = srcBuffer.height;
+        const dstW = dstCanvas.width;
+        const dstH = dstCanvas.height;
+
+        // Clamp source bounds
+        const srcStartX = Math.max(0, Math.floor(srcX));
+        const srcStartY = Math.max(0, Math.floor(srcY));
+        const srcEndX = Math.min(srcW, Math.ceil(srcX + width));
+        const srcEndY = Math.min(srcH, Math.ceil(srcY + height));
+
+        // Clamp destination bounds
+        const dstStartX = Math.max(0, Math.floor(dstX));
+        const dstStartY = Math.max(0, Math.floor(dstY));
+        const dstEndX = Math.min(dstW, Math.floor(dstX + (srcEndX - srcStartX)));
+        const dstEndY = Math.min(dstH, Math.floor(dstY + (srcEndY - srcStartY)));
+
+        const copyWidth = dstEndX - dstStartX;
+        const copyHeight = dstEndY - dstStartY;
+
+        if (copyWidth <= 0 || copyHeight <= 0) return;
+
+        // Adjust source start if destination was clamped
+        const srcOffsetX = dstStartX - Math.floor(dstX);
+        const srcOffsetY = dstStartY - Math.floor(dstY);
+
+        // Fast row-by-row copy
+        for (let y = 0; y < copyHeight; y++) {
+            const srcRowStart = ((srcStartY + srcOffsetY + y) * srcW + srcStartX + srcOffsetX) * 4;
+            const dstRowStart = ((dstStartY + y) * dstW + dstStartX) * 4;
+
+            dstData.set(
+                srcData.subarray(srcRowStart, srcRowStart + copyWidth * 4),
+                dstRowStart
+            );
+        }
+
+        dstCanvas.markRegion(dstStartX, dstStartY, copyWidth, copyHeight);
+    }
+
+    getStats() {
+        return {
+            cacheSize: `${this.cacheWidth}x${this.cacheHeight}`,
+            viewportSize: `${this.viewportWidth}x${this.viewportHeight}`,
+            marginRatio: this.marginRatio,
+            fullRedraws: this.fullRedraws,
+            copies: this.copies,
+            worldRegion: `(${this.worldX}, ${this.worldY}) to (${this.worldX + this.cacheWidth}, ${this.worldY + this.cacheHeight})`
+        };
+    }
+
+    printStats() {
+        const s = this.getStats();
+        console.log('OFFSCREEN CACHE STATS');
+        console.log(`Cache size: ${s.cacheSize}`);
+        console.log(`Viewport size: ${s.viewportSize}`);
+        console.log(`Margin: ${(this.marginRatio * 100).toFixed(0)}%`);
+        console.log(`Full redraws: ${s.fullRedraws}`);
+        console.log(`Cache copies: ${s.copies}`);
+        console.log(`World region: ${s.worldRegion}`);
+        console.log('=============================\n');
+    }
+}
+
+
+// ============= STRATEGY 3: CHUNKED PRE-RENDER =============
+// Divide world into fixed-size chunks, pre-render all layers into each chunk,
+// then just copy visible chunks to display. No shifting, no artifacts.
+
+class ChunkedPreRender {
+    constructor(mapWidth, mapHeight, chunkSize = 256) {
+        this.mapWidth = mapWidth;
+        this.mapHeight = mapHeight;
+        this.chunkSize = chunkSize;
+        
+        // Calculate grid dimensions
+        this.chunksX = Math.ceil(mapWidth / chunkSize);
+        this.chunksY = Math.ceil(mapHeight / chunkSize);
+        
+        // Store rendered chunk buffers in a 2D grid
+        this.chunks = new Array(this.chunksY);
+        for (let y = 0; y < this.chunksY; y++) {
+            this.chunks[y] = new Array(this.chunksX);
+        }
+        
+        this.renderCallbacks = [];
+        this.rendered = false;
+        this.pixelsDrawn = 0;
+        
+        console.log(`[ChunkedPreRender] Created ${this.chunksX}x${this.chunksY} chunk grid (${chunkSize}x${chunkSize}px chunks) for ${mapWidth}x${mapHeight} map`);
+    }
+    
+    // Register a callback that will render layers to a buffer
+    // Called during initialization and when chunks need updating
+    onRenderChunk(callback) {
+        this.renderCallbacks.push(callback);
+    }
+    
+    // Pre-render all chunks (call once during init)
+    renderAllChunks() {
+        if (this.rendered) return;
+        
+        console.log(`[ChunkedPreRender] Pre-rendering ${this.chunksX * this.chunksY} chunks...`);
+        
+        for (let cy = 0; cy < this.chunksY; cy++) {
+            for (let cx = 0; cx < this.chunksX; cx++) {
+                const chunk = this._renderChunk(cx, cy);
+                this.chunks[cy][cx] = chunk;
+                this.pixelsDrawn += chunk.buffer.width * chunk.buffer.height;
+            }
+        }
+        
+        this.rendered = true;
+        console.log(`[ChunkedPreRender] Pre-render complete. Total pixels: ${this.pixelsDrawn}`);
+    }
+    
+    // Render a single chunk
+    _renderChunk(chunkX, chunkY) {
+        // Calculate world bounds for this chunk
+        const worldX = chunkX * this.chunkSize;
+        const worldY = chunkY * this.chunkSize;
+        
+        // Calculate actual chunk size (may be smaller at map edges)
+        const chunkWidth = Math.min(this.chunkSize, this.mapWidth - worldX);
+        const chunkHeight = Math.min(this.chunkSize, this.mapHeight - worldY);
+        
+        // Create buffer for this chunk
+        const buffer = new CacheBuffer(chunkWidth, chunkHeight);
+        buffer.clear(0, 0, 0, 0);
+        
+        // Call all registered render callbacks with this chunk's world region
+        for (const callback of this.renderCallbacks) {
+            callback(buffer, {
+                x: worldX,
+                y: worldY,
+                width: chunkWidth,
+                height: chunkHeight
+            });
+        }
+        
+        return {
+            buffer,
+            worldX,
+            worldY,
+            width: chunkWidth,
+            height: chunkHeight
+        };
+    }
+    
+    // Copy visible chunks to display canvas based on camera position
+    copyToDisplay(displayCanvas, camera) {
+        const cameraX = camera.worldPosition.x;
+        const cameraY = camera.worldPosition.y;
+        const viewWidth = displayCanvas.width;
+        const viewHeight = displayCanvas.height;
+        
+        // Calculate which chunks are visible
+        // Camera position is top-left of viewport
+        const minChunkX = Math.max(0, Math.floor(cameraX / this.chunkSize));
+        const maxChunkX = Math.min(this.chunksX - 1, Math.floor((cameraX + viewWidth) / this.chunkSize));
+        const minChunkY = Math.max(0, Math.floor(cameraY / this.chunkSize));
+        const maxChunkY = Math.min(this.chunksY - 1, Math.floor((cameraY + viewHeight) / this.chunkSize));
+        
+        // Blit each visible chunk to canvas
+        for (let cy = minChunkY; cy <= maxChunkY; cy++) {
+            for (let cx = minChunkX; cx <= maxChunkX; cx++) {
+                const chunk = this.chunks[cy][cx];
+                if (!chunk) continue;
+                
+                // Calculate destination position on canvas
+                // chunk.worldX is in world space, convert to screen space (relative to camera)
+                const screenX = chunk.worldX - cameraX;
+                const screenY = chunk.worldY - cameraY;
+                
+                this._blitChunk(chunk.buffer, screenX, screenY, displayCanvas);
+            }
+        }
+    }
+    
+    // Blit a single chunk buffer to the display canvas
+    _blitChunk(srcBuffer, dstX, dstY, dstCanvas) {
+        const srcData = srcBuffer.data;
+        const dstData = dstCanvas.data;
+        const srcW = srcBuffer.width;
+        const srcH = srcBuffer.height;
+        const dstW = dstCanvas.width;
+        const dstH = dstCanvas.height;
+        
+        // Clamp destination bounds
+        const dstStartX = Math.max(0, Math.floor(dstX));
+        const dstStartY = Math.max(0, Math.floor(dstY));
+        const dstEndX = Math.min(dstW, Math.floor(dstX + srcW));
+        const dstEndY = Math.min(dstH, Math.floor(dstY + srcH));
+        
+        if (dstStartX >= dstEndX || dstStartY >= dstEndY) return;
+        
+        // Calculate corresponding source region (clipping)
+        const srcStartX = Math.max(0, Math.floor(-dstX));
+        const srcStartY = Math.max(0, Math.floor(-dstY));
+        const copyWidth = dstEndX - dstStartX;
+        const copyHeight = dstEndY - dstStartY;
+        
+        // Fast row-by-row copy
+        for (let y = 0; y < copyHeight; y++) {
+            const srcRowStart = ((srcStartY + y) * srcW + srcStartX) * 4;
+            const dstRowStart = ((dstStartY + y) * dstW + dstStartX) * 4;
+            
+            dstData.set(
+                srcData.subarray(srcRowStart, srcRowStart + copyWidth * 4),
+                dstRowStart
+            );
+        }
+        
+        dstCanvas.markRegion(dstStartX, dstStartY, copyWidth, copyHeight);
+    }
+    
+    getStats() {
+        return {
+            mapSize: `${this.mapWidth}x${this.mapHeight}`,
+            chunkSize: this.chunkSize,
+            chunkGrid: `${this.chunksX}x${this.chunksY}`,
+            rendered: this.rendered,
+            pixelsDrawn: this.pixelsDrawn
+        };
+    }
+    
+    printStats() {
+        const s = this.getStats();
+        console.log('=== CHUNKED PRE-RENDER STATS ===');
+        console.log(`Map size: ${s.mapSize}`);
+        console.log(`Chunk size: ${s.chunkSize}`);
+        console.log(`Chunk grid: ${s.chunkGrid}`);
+        console.log(`Rendered: ${s.rendered}`);
+        console.log(`Pixels drawn: ${s.pixelsDrawn}`);
+        console.log('==================================\n');
+    }
+}
+
 const tiledperf = globalPerf;
 
 function reshapeArray(arr, width, height) {
@@ -60009,6 +60966,7 @@ class TileLayer extends BaseLayer {
     }
 
     renderChunkToBuffer(chunkX, chunkY, buffer) {
+        tiledperf.start("renderChunkToBuffer");
         const startX = chunkX * this.chunkSize;
         const startY = chunkY * this.chunkSize;
         const endX = Math.min(startX + this.chunkSize, this.layerwidth);
@@ -60046,9 +61004,11 @@ class TileLayer extends BaseLayer {
                 });
             }
         }
+        tiledperf.end("renderChunkToBuffer");
     }
 
     blitBuffer(srcBuffer, dstCanvas, destX, destY) {
+        tiledperf.start("blitBufferPixels");
         const srcData = srcBuffer.data;
         const dstData = dstCanvas.data;
         const srcW = srcBuffer.width;
@@ -60061,7 +61021,10 @@ class TileLayer extends BaseLayer {
         const endX = Math.min(dstW, destX + srcW);
         const endY = Math.min(dstH, destY + srcH);
 
-        if (startX >= endX || startY >= endY) return;
+        if (startX >= endX || startY >= endY) {
+            tiledperf.end("blitBufferPixels");
+            return;
+        }
 
         if (this.assumeOpaque) {
             for (let y = startY; y < endY; y++) {
@@ -60106,12 +61069,136 @@ class TileLayer extends BaseLayer {
                 }
             }
         }
-
-        dstCanvas.markRegion(startX, startY, endX - startX, endY - startY);
+
+        dstCanvas.markRegion(startX, startY, endX - startX, endY - startY);
+        tiledperf.end("blitBufferPixels");
+    }
+
+
+
+
+    /**
+ * Draw only a specific region of the tilemap
+ * Used for incremental cache updates
+ * 
+ * @param {CacheBuffer} canvas - buffer to draw to
+ * @param {Object} camera - fake camera for coordinate conversion
+ * @param {Object} region - {x, y, width, height} in cache coordinates
+ * @param {Object} worldRegion - {x, y, width, height} in world coordinates
+ */
+
+    drawRegion(canvas, camera, region, worldRegion) {
+          tiledperf.start("tilelayer_drawRegion");
+    // Cache locals for faster access
+    const chunks = this.chunkspertiles[0];
+    const chunkSize = this.chunkSize;
+    const tileW = this.tileWidth;
+    const tileH = this.tileHeight;
+    const layerWorldX = this.worldPosition.x;
+    const layerWorldY = this.worldPosition.y;
+    const regionX = worldRegion.x;
+    const regionY = worldRegion.y;
+    const regionW = worldRegion.width;
+    const regionH = worldRegion.height;
+    
+    // Calculate chunk bounds - inline to avoid function call
+    const chunkPixelW = chunkSize * tileW;
+    const chunkPixelH = chunkSize * tileH;
+    
+    let startChunkX = Math.floor((regionX - layerWorldX) / chunkPixelW);
+    let endChunkX = Math.ceil((regionX + regionW - layerWorldX) / chunkPixelW);
+    let startChunkY = Math.floor((regionY - layerWorldY) / chunkPixelH);
+    let endChunkY = Math.ceil((regionY + regionH - layerWorldY) / chunkPixelH);
+    
+    // Clamp to valid chunk range
+    if (startChunkX < 0) startChunkX = 0;
+    if (startChunkY < 0) startChunkY = 0;
+    const maxChunkX = chunks[0].length - 1;
+    const maxChunkY = chunks.length - 1;
+    if (endChunkX > maxChunkX) endChunkX = maxChunkX;
+    if (endChunkY > maxChunkY) endChunkY = maxChunkY;
+    
+    // Blit chunks - tight loop, no allocations
+    for (let cy = startChunkY; cy <= endChunkY; cy++) {
+        const chunkRow = this.chunkBuffers[cy];
+        
+        for (let cx = startChunkX; cx <= endChunkX; cx++) {
+            const chunkBuffer = chunkRow[cx];
+            
+            // Calculate world position - inline
+            const chunkWorldX = layerWorldX + cx * chunkPixelW;
+            const chunkWorldY = layerWorldY + cy * chunkPixelH;
+            
+            // Convert to cache coords using the proper worldToScreen method
+            const screenPos = camera.worldToScreen(chunkWorldX, chunkWorldY);
+            const destX = Math.floor(screenPos.x);
+            const destY = Math.floor(screenPos.y);
+            
+            // Quick bounds check - inline
+            const chunkW = chunkBuffer.width;
+            const chunkH = chunkBuffer.height;
+            const regionLeft = region.x;
+            const regionRight = region.x + region.width;
+            const regionTop = region.y;
+            const regionBottom = region.y + region.height;
+            
+            if (destX + chunkW < regionLeft || destX > regionRight ||
+                destY + chunkH < regionTop || destY > regionBottom) {
+                continue;
+            }
+            
+            // Blit chunk
+            this.blitBuffer(chunkBuffer, canvas, destX, destY);
+        }
     }
+          tiledperf.end("tilelayer_drawRegion");
+}
+    // drawRegion(canvas, camera, region, worldRegion) {
+    //     tiledperf.start("drawRegion");
+    //     // Calculate which chunks intersect this region
+    //     const startChunkX = Math.floor((worldRegion.x - this.worldPosition.x) / (this.chunkSize * this.tileWidth));
+    //     const endChunkX = Math.ceil((worldRegion.x + worldRegion.width - this.worldPosition.x) / (this.chunkSize * this.tileWidth));
+    //     const startChunkY = Math.floor((worldRegion.y - this.worldPosition.y) / (this.chunkSize * this.tileHeight));
+    //     const endChunkY = Math.ceil((worldRegion.y + worldRegion.height - this.worldPosition.y) / (this.chunkSize * this.tileHeight));
+
+    //     const chunks = this.chunkspertiles[0];
+    //     const clampStartX = Math.max(0, startChunkX);
+    //     const clampEndX = Math.min(chunks[0].length - 1, endChunkX);
+    //     const clampStartY = Math.max(0, startChunkY);
+    //     const clampEndY = Math.min(chunks.length - 1, endChunkY);
+
+    //     // Blit only the chunks that intersect the region
+    //     for (let cy = clampStartY; cy <= clampEndY; cy++) {
+    //         for (let cx = clampStartX; cx <= clampEndX; cx++) {
+    //             const chunkBuffer = this.chunkBuffers[cy][cx];
+    //             const chunkWorldX = this.worldPosition.x + cx * this.chunkSize * this.tileWidth;
+    //             const chunkWorldY = this.worldPosition.y + cy * this.chunkSize * this.tileHeight;
+
+    //             // Convert world position to cache coordinates
+    //             const screenPos = camera.worldToScreen(chunkWorldX, chunkWorldY);
+    //             const destX = Math.floor(screenPos.x);
+    //             const destY = Math.floor(screenPos.y);
+
+    //             // Only blit if chunk intersects region
+    //             if (destX + chunkBuffer.width >= region.x &&
+    //                 destX < region.x + region.width &&
+    //                 destY + chunkBuffer.height >= region.y &&
+    //                 destY < region.y + region.height) {
+
+    //                 this.blitBuffer(chunkBuffer, canvas, destX, destY);
+    //             }
+    //         }
+    //     }
+    //     tiledperf.end("drawRegion");
+    // }
 
-    draw(canvas, camera) {
+    draw(canvas, camera, region = null, worldRegion = null) {
+        if (region && worldRegion) {
+            this.drawRegion(canvas, camera, region, worldRegion);
+            return;
+        }
         tiledperf.start("drawVisibleChunks");
+        tilemapProfiler.startFrame(camera);
         const visibleBounds = camera.getVisibleBounds();
         const chunks = this.chunkspertiles[0];
 
@@ -60129,6 +61216,8 @@ class TileLayer extends BaseLayer {
                 const screenPos = camera.worldToScreen(worldX, worldY);
                 const destX = Math.floor(screenPos.x);
                 const destY = Math.floor(screenPos.y);
+                tilemapProfiler.recordBlit(chunkBuffer.width, chunkBuffer.height);
+                tilemapProfiler.recordChunk();
                 this.blitBuffer(chunkBuffer, canvas, destX, destY);
             }
         }
@@ -60188,7 +61277,66 @@ class ObjectLayer extends BaseLayer {
         }
     }
 
-    draw(canvas, camera) {
+    /**
+ * Draw only objects that intersect the specified region
+ * For incremental cache updates
+ */
+    drawRegion(canvas, camera, cacheRegion, worldRegion) {
+        // Iterate through precomputed render cache
+        // Only draw objects that intersect worldRegion
+          tiledperf.start("objectlayer_drawregion");
+
+
+        const regionLeft = worldRegion.x;
+        const regionRight = worldRegion.x + worldRegion.width;
+        const regionTop = worldRegion.y;
+        const regionBottom = worldRegion.y + worldRegion.height;
+
+        for (let i = 0; i < this.objectRenderCache.length; i++) {
+            const cached = this.objectRenderCache[i];
+
+            // Quick AABB intersection test
+            const objLeft = cached.worldX;
+            const objRight = cached.worldX + cached.width;
+            const objTop = cached.worldY;
+            const objBottom = cached.worldY + cached.height;
+
+            // Skip if no intersection
+            if (objRight < regionLeft || objLeft > regionRight ||
+                objBottom < regionTop || objTop > regionBottom) {
+                continue;
+            }
+
+            // Object intersects region - draw it
+            const screenPos = camera.worldToScreen(cached.worldX, cached.worldY);
+
+            const destRect = {
+                x: Math.floor(screenPos.x),
+                y: Math.floor(screenPos.y),
+                width: Math.floor(cached.width * camera.zoom),
+                height: Math.floor(cached.height * camera.zoom)
+            };
+
+            // Draw to canvas
+            drawAtlasRegionToCanvas(cached.image, cached.srcRect, canvas, destRect, {
+                algorithm: "nn",
+                camera: camera
+            });
+        }
+
+          tiledperf.end("objectlayer_drawregion");
+
+    }
+
+
+    draw(canvas, camera, cacheRegion = null, worldRegion = null) {
+          tiledperf.start("objectlayer_draw");
+
+        if (cacheRegion && worldRegion) {
+            this.drawRegion(canvas, camera, cacheRegion, worldRegion);
+            return;
+        }
+
         for (const cached of this.objectRenderCache) {
             const screenPos = camera.worldToScreen(cached.worldX, cached.worldY);
 
@@ -60209,6 +61357,8 @@ class ObjectLayer extends BaseLayer {
                 camera: camera
             });
         }
+          tiledperf.end("objectlayer_draw");
+
     }
 
     printDebug() {
@@ -60408,9 +61558,124 @@ class CollisionLayer extends BaseLayer {
         return created;
     }
 
-    draw(canvas, camera) {
+    drawRegion(canvas, camera, cacheRegion, worldRegion) {
+        if (!this.debugCollisions) return;
+
+        const regionLeft = worldRegion.x;
+        const regionRight = worldRegion.x + worldRegion.width;
+        const regionTop = worldRegion.y;
+        const regionBottom = worldRegion.y + worldRegion.height;
+
+        const getColorForBody = (body) => {
+            switch ((body.type || '').toLowerCase()) {
+                case 'static': return { r: 120, g: 120, b: 120, a: 220 };
+                case 'kinematic': return { r: 0, g: 140, b: 255, a: 220 };
+                case 'dynamic':
+                default: return { r: 255, g: 60, b: 60, a: 220 };
+            }
+        };
+
+        // Inline AABB test - no function call overhead
+        const intersectsRegion = (left, top, right, bottom) => {
+            return !(right < regionLeft || left > regionRight ||
+                bottom < regionTop || top > regionBottom);
+        };
+
+        const strokeThickness = 1;
+
+        for (const [name, body] of this.bodies.entries()) {
+            if (!body) continue;
+
+            const color = getColorForBody(body);
+            const children = body.children || [];
+
+            if (!children.length) continue;
+
+            for (let s = 0; s < children.length; s++) {
+                const shape = children[s];
+                if (!shape || !shape.shapeType) continue;
+
+                const opts = shape.options || {};
+                const anchor = shape.anchorOffset || { x: 0, y: 0 };
+                const baseX = (opts.x || 0);
+                const baseY = (opts.y || 0);
+                const lx = baseX - anchor.x;
+                const ly = baseY - anchor.y;
+                const worldBaseX = (body.position && body.position.x !== undefined) ? body.position.x + lx : lx;
+                const worldBaseY = (body.position && body.position.y !== undefined) ? body.position.y + ly : ly;
+
+                // Quick reject based on shape type
+                let shouldDraw = false;
+
+                if (shape.shapeType === 'box') {
+                    const w = opts.width || 0;
+                    const h = opts.height || 0;
+                    const left = worldBaseX - w / 2;
+                    const top = worldBaseY - h / 2;
+                    shouldDraw = intersectsRegion(left, top, left + w, top + h);
+
+                    if (shouldDraw) {
+                        const screenPos = camera.worldToScreen(left, top);
+                        ShapeDrawer.strokeRect(canvas, screenPos.x, screenPos.y, w, h, strokeThickness, color.r, color.g, color.b, color.a);
+                    }
+                } else if (shape.shapeType === 'circle') {
+                    const rpx = opts.radius || 0;
+                    const left = worldBaseX - rpx;
+                    const top = worldBaseY - rpx;
+                    shouldDraw = intersectsRegion(left, top, worldBaseX + rpx, worldBaseY + rpx);
+
+                    if (shouldDraw) {
+                        const screenPos = camera.worldToScreen(worldBaseX, worldBaseY);
+                        ShapeDrawer.strokeCircle(canvas, screenPos.x, screenPos.y, rpx, strokeThickness, color.r, color.g, color.b, color.a);
+                    }
+                } else if (shape.shapeType === 'polygon' || shape.shapeType === 'poly') {
+                    const pts = opts.points || [];
+                    if (!pts.length) continue;
+
+                    // Calculate AABB for polygon
+                    let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+                    for (let p = 0; p < pts.length; p++) {
+                        const wx = worldBaseX + pts[p].x;
+                        const wy = worldBaseY + pts[p].y;
+                        if (wx < minX) minX = wx;
+                        if (wy < minY) minY = wy;
+                        if (wx > maxX) maxX = wx;
+                        if (wy > maxY) maxY = wy;
+                    }
+
+                    shouldDraw = intersectsRegion(minX, minY, maxX, maxY);
+
+                    if (shouldDraw) {
+                        const worldPts = pts.map(p => ({ x: worldBaseX + p.x, y: worldBaseY + p.y }));
+                        const screenPts = worldPts.map(p => camera.worldToScreen(p.x, p.y));
+
+                        if (shape.shapeType === 'polygon' || opts.closed === true) {
+                            PolygonDrawer.fillPolygon(canvas, screenPts, color.r, color.g, color.b, Math.floor(color.a * 0.2));
+                            PolygonDrawer.strokePolygon(canvas, screenPts, strokeThickness, color.r, color.g, color.b, color.a);
+                        } else {
+                            PolygonDrawer.strokePolygon(canvas, screenPts, strokeThickness, color.r, color.g, color.b, color.a);
+                        }
+                    }
+                } else if (shape.shapeType === 'point') {
+                    shouldDraw = intersectsRegion(worldBaseX - 3, worldBaseY - 3, worldBaseX + 3, worldBaseY + 3);
+
+                    if (shouldDraw) {
+                        const screenPos = camera.worldToScreen(worldBaseX, worldBaseY);
+                        ShapeDrawer.fillCircle(canvas, screenPos.x, screenPos.y, 3, color.r, color.g, color.b, color.a);
+                    }
+                }
+            }
+        }
+    }
+
+    draw(canvas, camera, cacheRegion = null, worldRegion = null) {
         if (!this.debugCollisions) return;
 
+        if (cacheRegion && worldRegion) {
+            this.drawRegion(canvas, camera, cacheRegion, worldRegion);
+            return;
+        }
+
         const getColorForBody = (body) => {
             switch ((body.type || '').toLowerCase()) {
                 case 'static': return { r: 120, g: 120, b: 120, a: 220 };
@@ -60625,6 +61890,19 @@ class Tiled extends Node {
         this.opaque = opaque;
         this.renderer = renderer;
 
+        this.useCache = opts.useCache !== false; // default true
+        this.cache = null;
+        this.cacheInitialized = false;
+
+        // Full map pre-render strategy (Strategy 2)
+        this.preRenderEntireMap = opts.preRenderEntireMap || false;
+        this.fullMapBuffer = null;
+
+        // Chunked pre-render strategy (Strategy 3)
+        this.useChunkedRender = opts.useChunkedRender || false;
+        this.chunkedBuffer = null;
+        this.chunkSize = opts.chunkSize || 256;
+
         if (path$1.extname(path) != ".json") {
             throw new Error("expected a json map");
         }
@@ -60645,6 +61923,20 @@ class Tiled extends Node {
         tiledperf.start("processLayers");
         this.processLayers(this.json.layers);
         tiledperf.end("processLayers");
+
+        this._drawMethods = [
+            function fallback(c, cam) {
+                for (let i = 0; i < this.layers.length; i++) {
+                    this.layers[i].draw(c, cam);
+                }
+            }.bind(this),
+            function fast(c, cam) {
+                const strategy = this.cache.needsUpdate(cam);
+                console.log("STRAT", strategy);
+                this.cache.copyToDisplay(c, cam);
+            }.bind(this)
+        ];
+
     }
 
     processTilesets(tilesets) {
@@ -60665,12 +61957,191 @@ class Tiled extends Node {
 
 
         this.collisionObjects = c;
-   
+
+    }
+
+
+    initializeFullMapBuffer(camera) {
+        if (!this.preRenderEntireMap) return;
+
+        console.log('[Tiled] Initializing full-map pre-render...');
+
+        // Calculate full map bounds in world space
+        let mapWidth = this.json.width * this.json.tilewidth;
+        let mapHeight = this.json.height * this.json.tileheight;
+
+        // Account for layer offsets
+        for (const layer of this.layers) {
+            if (layer.worldPosition) {
+                const layerRightEdge = layer.worldPosition.x + (layer.layer?.width || 0) * this.json.tilewidth;
+                const layerBottomEdge = layer.worldPosition.y + (layer.layer?.height || 0) * this.json.tileheight;
+                mapWidth = Math.max(mapWidth, layerRightEdge);
+                mapHeight = Math.max(mapHeight, layerBottomEdge);
+            }
+        }
+
+        this.fullMapBuffer = new FullMapPreRender(Math.ceil(mapWidth), Math.ceil(mapHeight));
+
+        // Render all layers to the full-map buffer
+        this.fullMapBuffer.render((buffer) => {
+            const fakeCamera = {
+                worldPosition: { x: 0, y: 0 },
+                zoom: 1,
+                worldToScreen: (wx, wy) => ({ x: wx, y: wy }),
+                getVisibleBounds: () => ({
+                    left: 0,
+                    top: 0,
+                    right: mapWidth,
+                    bottom: mapHeight,
+                    width: mapWidth,
+                    height: mapHeight
+                }),
+                cullingEnabled: true,
+                frustum: { left: 0, right: mapWidth, top: 0, bottom: mapHeight }
+            };
+
+            for (let i = 0; i < this.layers.length; i++) {
+                this.layers[i].draw(buffer, fakeCamera);
+            }
+        });
+
+        console.log(`[Tiled] Full-map buffer rendered: ${mapWidth}x${mapHeight}`);
+    }
+
+    initializeChunkedRender(camera) {
+        if (!this.useChunkedRender) return;
+
+        console.log('[Tiled] Initializing chunked pre-render...');
+
+        // Calculate full map bounds in world space
+        let mapWidth = this.json.width * this.json.tilewidth;
+        let mapHeight = this.json.height * this.json.tileheight;
+
+        // Account for layer offsets
+        for (const layer of this.layers) {
+            if (layer.worldPosition) {
+                const layerRightEdge = layer.worldPosition.x + (layer.layer?.width || 0) * this.json.tilewidth;
+                const layerBottomEdge = layer.worldPosition.y + (layer.layer?.height || 0) * this.json.tileheight;
+                mapWidth = Math.max(mapWidth, layerRightEdge);
+                mapHeight = Math.max(mapHeight, layerBottomEdge);
+            }
+        }
+
+        this.chunkedBuffer = new ChunkedPreRender(Math.ceil(mapWidth), Math.ceil(mapHeight), this.chunkSize);
+
+        // Register render callback for all layers
+        this.chunkedBuffer.onRenderChunk((buffer, region) => {
+            const fakeCamera = {
+                worldPosition: {
+                    x: region.x + region.width / 2,
+                    y: region.y + region.height / 2
+                },
+                zoom: 1,
+                worldToScreen: (wx, wy) => ({ 
+                    x: wx - region.x, 
+                    y: wy - region.y 
+                }),
+                getVisibleBounds: () => ({
+                    left: region.x,
+                    top: region.y,
+                    right: region.x + region.width,
+                    bottom: region.y + region.height,
+                    width: region.width,
+                    height: region.height
+                }),
+                cullingEnabled: true,
+                frustum: {
+                    left: region.x,
+                    right: region.x + region.width,
+                    top: region.y,
+                    bottom: region.y + region.height
+                }
+            };
+
+            for (let i = 0; i < this.layers.length; i++) {
+                this.layers[i].draw(buffer, fakeCamera);
+            }
+        });
+
+        // Pre-render all chunks
+        this.chunkedBuffer.renderAllChunks();
+        console.log(`[Tiled] Chunked render initialized: ${mapWidth}x${mapHeight} into ${this.chunkSize}x${this.chunkSize} chunks`);
+    }
+
+    initializeCache(viewportWidth, viewportHeight, camera) {
+        if (!this.useCache) return;
+
+        console.log('[Tiled] Initializing offscreen cache...');
+
+        // Create cache
+        this.cache = new OffscreenTilemapCache(viewportWidth, viewportHeight);
+
+        // Set cache to cover camera view with margin
+        const bounds = camera.getVisibleBounds();
+
+        // Center cache on camera
+        // this.cache.setWorldRegion(
+        //     camera.worldPosition.x - halfViewW - this.cache.marginPixels.x,
+        //     camera.worldPosition.y - halfViewH - this.cache.marginPixels.y
+        // );
+        this.cache.setWorldRegion(bounds.left, bounds.top);
+
+
+        // Render all layers to cache
+        this._renderToCache();
+
+        this.cacheInitialized = true;
+        this.cache.fullRedraws++;
+
+        console.log('[Tiled] Cache initialized and rendered');
+    }
+
+
+    _renderToCache() {
+        tiledperf.start("_renderToCache");
+        if (!this.cache) {
+            tiledperf.end("_renderToCache");
+            return;
+        }
+
+
+        this.cache.clear();
+
+        const fakeCamera = {
+            worldPosition: {
+                x: this.cache.worldX + this.cache.cacheWidth / 2,
+                y: this.cache.worldY + this.cache.cacheHeight / 2
+            },
+            zoom: 1,
+            worldToScreen: (wx, wy) => {
+                return {
+                    x: wx - this.cache.worldX,
+                    y: wy - this.cache.worldY
+                };
+            },
+            getVisibleBounds: () => this.cache.getWorldBounds(),
+            cullingEnabled: true,
+            frustum: {
+                left: this.cache.worldX,
+                right: this.cache.worldX + this.cache.cacheWidth,
+                top: this.cache.worldY,
+                bottom: this.cache.worldY + this.cache.cacheHeight
+            }
+        };
+
+        // draw all layers to cache buffer
+        for (let i = 0; i < this.layers.length; i++) {
+            this.layers[i].draw(this.cache.buffer, fakeCamera);
+        }
+        tiledperf.end("_renderToCache");
     }
+
+
+
     _ready() {
         for (let i = 0; i < this.collisionObjects.length; i++)
             this.parent.addChild(this.collisionObjects[i]);
-         console.log("added ", this.collisionObjects.length, " bodies");
+        console.log("added ", this.collisionObjects.length, " bodies");
     }
     processLayers(layers) {
         for (let i = 0; i < layers.length; i++) {
@@ -60701,11 +62172,203 @@ class Tiled extends Node {
         }
     }
 
-    _draw(canvas, camera) {
-        // polymorphic draw - each layer handles its own rendering
+
+
+    _renderRegionToCache(cacheRegion, worldRegion) {
+        tiledperf.start("_renderRegionToCache");
+        if (!this.cache) {
+            tiledperf.end("_renderRegionToCache");
+            return;
+        }
+
+        // Create fake camera for this region
+        const fakeCamera = {
+            worldPosition: {
+                x: this.cache.worldX + this.cache.cacheWidth / 2,
+                y: this.cache.worldY + this.cache.cacheHeight / 2
+            },
+            zoom: 1,
+            worldToScreen: (wx, wy) => {
+                return {
+                    x: wx - this.cache.worldX,
+                    y: wy - this.cache.worldY
+                };
+            },
+            getVisibleBounds: () => ({
+                left: worldRegion.x,
+                top: worldRegion.y,
+                right: worldRegion.x + worldRegion.width,
+                bottom: worldRegion.y + worldRegion.height,
+                width: worldRegion.width,
+                height: worldRegion.height
+            }),
+            cullingEnabled: true,
+            frustum: {
+                left: worldRegion.x,
+                right: worldRegion.x + worldRegion.width,
+                top: worldRegion.y,
+                bottom: worldRegion.y + worldRegion.height
+            }
+        };
+
+        // Draw each layer's region
         for (let i = 0; i < this.layers.length; i++) {
-            this.layers[i].draw(canvas, camera);
+            this.layers[i].draw(this.cache.buffer, fakeCamera, cacheRegion, worldRegion);
+        }
+        tiledperf.end("_renderRegionToCache");
+    }
+
+    _draw(canvas, camera) {
+        tiledperf.start("_draw");
+        
+        // Strategy 3: Chunked pre-render
+        if (this.useChunkedRender && !this.chunkedBuffer) {
+            this.initializeChunkedRender(camera);
+        }
+
+        if (this.useChunkedRender && this.chunkedBuffer) {
+            tiledperf.start("chunkedBuffer_copy");
+            this.chunkedBuffer.copyToDisplay(canvas, camera);
+            tiledperf.end("chunkedBuffer_copy");
+            tiledperf.end("_draw");
+            return;
+        }
+
+        // Strategy 2: Full-map pre-render
+        if (this.preRenderEntireMap && !this.fullMapBuffer) {
+            this.initializeFullMapBuffer(camera);
+        }
+
+        if (this.preRenderEntireMap && this.fullMapBuffer) {
+            tiledperf.start("fullMapBuffer_copy");
+            this.fullMapBuffer.copyToDisplay(canvas, camera);
+            tiledperf.end("fullMapBuffer_copy");
+            tiledperf.end("_draw");
+            return;
+        }
+
+        // Strategy 1: Incremental offscreen cache
+        // First frame: initialize
+        if (this.useCache && !this.cacheInitialized) {
+            this.initializeCache(canvas.width, canvas.height, camera);
+        }
+
+        if (this.useCache && this.cache) {
+            // Determine what kind of update we need
+            const strategy = this.cache.needsUpdate(camera);
+
+            switch (strategy.type) {
+                case 'NONE':
+                    tiledperf.start("cacheUpdate_NONE");
+                    // Camera didn't move - just copy from cache
+                    this.cache.skippedUpdates++;
+                    tiledperf.end("cacheUpdate_NONE");
+                    break;
+
+                case 'INCREMENTAL':
+                    tiledperf.start("cacheUpdate_INCREMENTAL");
+                    // Small move - incremental update (Chapter 4 will implement this)
+                    // For now, treat as full redraw
+                    // console.log(`[Tiled] Incremental update needed (${strategy.reason}), delta: ${strategy.delta.x.toFixed(1)}, ${strategy.delta.y.toFixed(1)}`);
+                    // this._fullCacheRedraw(camera);
+                    this.cache.incrementalUpdates++;
+                               this.cache.incrementalUpdate(
+                        strategy.delta,
+                        (cacheRegion, worldRegion) => {
+                            this._renderRegionToCache(cacheRegion, worldRegion);
+                        }
+                    );
+                    tiledperf.end("cacheUpdate_INCREMENTAL");
+                    break;
+
+                case 'FULL_REDRAW':
+                    tiledperf.start("cacheUpdate_FULL_REDRAW");
+                    // Teleport or zoom - need full redraw
+                    console.log(`[Tiled] Full redraw needed (${strategy.reason})`);
+                    this._fullCacheRedraw(camera);
+                    this.cache.fullRedraws++;
+                    tiledperf.end("cacheUpdate_FULL_REDRAW");
+                    break;
+            }
+
+            // Always copy cache to display
+            tiledperf.start("copyToDisplay");
+            this.cache.copyToDisplay(canvas, camera);
+            tiledperf.end("copyToDisplay");
+
+            // Commit frame
+            this.cache.commitFrame();
+
+        } else {
+            // Fallback: no cache
+            tiledperf.start("directLayerDraw");
+            for (let i = 0; i < this.layers.length; i++) {
+                this.layers[i].draw(canvas, camera);
+            }
+            tiledperf.end("directLayerDraw");
         }
+        tiledperf.end("_draw");
+    }
+
+    // Full cache redraw - recenter and render
+    _fullCacheRedraw(camera) {
+        tiledperf.start("_fullCacheRedraw");
+        this.cache.viewportWidth / 2;
+        this.cache.viewportHeight / 2;
+
+        const bounds = camera.getVisibleBounds();
+        // Recenter cache on camera
+        // this.cache.setWorldRegion(
+        //     camera.worldPosition.x - halfViewW - this.cache.marginPixels.x,
+        //     camera.worldPosition.y - halfViewH - this.cache.marginPixels.y
+        // );
+
+        this.cache.setWorldRegion(bounds.left, bounds.top);
+
+        this._renderToCache();
+        tiledperf.end("_fullCacheRedraw");
+    }
+
+
+    // _draw(canvas, camera) {
+    //     (this.useCache && !this.cacheInitialized) && (
+    //         this.initializeCache(canvas.width, canvas.height, camera),
+    //         this.cache.printStats(),
+    //         this._drawMethods[1] = function fast(c, cam) { this.cache.copyToDisplay(c, cam); }.bind(this) // update after init
+    //     );
+
+    //     const useFast = +(this.useCache && !!this.cache);
+    //     this._drawMethods[useFast](canvas, camera);
+    // }
+    // _draw(canvas, camera) {
+    //     if (this.useCache && !this.cacheInitialized) {
+    //         this.initializeCache(canvas.width, canvas.height, camera);
+    //         this.cache.printStats()
+    //     }
+
+    //     if (this.useCache && this.cache) {
+    //         // Fast path: copy from cache
+    //         this.cache.copyToDisplay(canvas, camera);
+    //     } else {
+    //         // Fallback: direct render (old way)
+    //         // polymorphic draw - each layer handles its own rendering
+    //         for (let i = 0; i < this.layers.length; i++) {
+    //             this.layers[i].draw(canvas, camera);
+    //         }
+    //     }
+
+    // }
+
+    needsCacheUpdate(camera) {
+        if (!this.cache) return false;
+
+        const bounds = this.cache.getWorldBounds();
+        const camX = camera.worldPosition.x;
+        const camY = camera.worldPosition.y;
+
+        // Simple check: is camera center still inside cache bounds?
+        return camX < bounds.left || camX > bounds.right ||
+            camY < bounds.top || camY > bounds.bottom;
     }
 
 }