@arcadekit/render-three 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,855 @@
+import * as THREE from "three";
+import { Data, Effect, Result, Schema } from "effect";
+// src/camera.ts
+/** Keeps the camera at a fixed offset from a target on the ground plane, looking at it. Top-down and isometric games. */
+const followTarget = (camera, target, offset) => {
+	camera.position.set(target.x + offset.x, offset.y, target.z + offset.z);
+	camera.lookAt(target.x, 0, target.z);
+};
+/**
+* Circles the camera around a point on the ground plane at a fixed height, looking at it.
+* `angle` is in radians; 0 puts the camera on the point's +z side. Menu backdrops and
+* showcase views.
+*/
+const orbitAround = (camera, center, options) => {
+	camera.position.set(center.x + Math.sin(options.angle) * options.radius, options.height, center.z + Math.cos(options.angle) * options.radius);
+	camera.lookAt(center.x, 0, center.z);
+};
+/**
+* Places a camera above a rectangle on the ground plane, looking at its center, so that all of
+* it shows at the camera's current aspect ratio. Board, puzzle and arena games. Call it every
+* frame (it allocates nothing), or at least after each resize.
+*
+* A perspective camera keeps its field of view and moves back far enough. An orthographic
+* camera (`Stage` with `camera: "orthographic"`) changes its frustum to fit instead.
+* With a tilt, the fit is still worked out as if looking straight down. That leaves an
+* orthographic camera a little extra room. It does not hold for a perspective camera: a small
+* tilt (below the tangent of half its field of view) can push the near edge of the bounds off
+* the screen, so give it more margin.
+*/
+const fitCamera = (camera, bounds, options = {}) => {
+	const margin = options.margin ?? 0;
+	const tilt = options.tilt ?? 0;
+	const centerX = (bounds.minX + bounds.maxX) / 2;
+	const centerZ = (bounds.minZ + bounds.maxZ) / 2;
+	const halfWidth = (bounds.maxX - bounds.minX) / 2 + margin;
+	const halfDepth = (bounds.maxZ - bounds.minZ) / 2 + margin;
+	let height;
+	if (isPerspective(camera)) {
+		const halfTan = Math.tan(camera.fov * Math.PI / 360);
+		height = Math.max(halfDepth / halfTan, halfWidth / (halfTan * camera.aspect));
+	} else {
+		const aspect = (camera.right - camera.left) / (camera.top - camera.bottom);
+		const halfHeight = Math.max(halfDepth, halfWidth / aspect);
+		camera.top = halfHeight;
+		camera.bottom = -halfHeight;
+		camera.left = -halfHeight * aspect;
+		camera.right = halfHeight * aspect;
+		camera.updateProjectionMatrix();
+		height = 4 * Math.max(halfWidth, halfDepth, 1);
+	}
+	camera.position.set(centerX, height, centerZ + height * tilt);
+	camera.lookAt(centerX, 0, centerZ);
+};
+const isPerspective = (camera) => camera.isPerspectiveCamera === true;
+// src/instanced-sprites.ts
+/** Frames per row of the frame table texture; each frame takes 2 texels in a column. */
+const TABLE_COLUMNS = 256;
+/** How far a layer's depth band reaches either side of its middle. Bands are 1 apart. */
+const BAND = .45;
+const VERTEX = `
+// x, z, lift, layer
+attribute vec4 aPlace;
+// frame, flipX, flash
+attribute vec3 aFrame;
+// r, g, b, alpha
+attribute vec4 aTint;
+uniform sampler2D uFrames;
+uniform vec2 uSheetSize;
+uniform vec2 uAnchor;
+uniform float uUnitsPerPixel;
+uniform float uSnap;
+uniform float uLayer;
+uniform float uDepthScale;
+varying vec2 vUv;
+varying vec4 vTint;
+varying float vFlash;
+
+ivec2 tableCell(int frame, int row) {
+  return ivec2(frame % ${TABLE_COLUMNS}, (frame / ${TABLE_COLUMNS}) * 2 + row);
+}
+
+void main() {
+  int frame = int(aFrame.x + 0.5);
+  // x, y, width, height in the image
+  vec4 rect = texelFetch(uFrames, tableCell(frame, 0), 0);
+  // offset x, y in the untrimmed frame; its width, height
+  vec4 source = texelFetch(uFrames, tableCell(frame, 1), 0);
+  // uv.y is 1 at the top of the quad; pixel rows count down from the top.
+  vec2 corner = vec2(uv.x, 1.0 - uv.y);
+  vec2 pixel = source.xy + corner * rect.zw;
+  if (aFrame.y > 0.5) {
+    pixel.x = source.z - pixel.x;
+  }
+  vec2 anchor = floor(uAnchor * source.zw + 0.5);
+  vec2 local = (pixel - anchor) * uUnitsPerPixel;
+  // Up the screen is -z, so a lifted sprite moves toward -z; its depth stays at its feet.
+  vec2 base = vec2(aPlace.x, aPlace.y - aPlace.z);
+  if (uSnap > 0.5) {
+    base = floor(base / uUnitsPerPixel + 0.5) * uUnitsPerPixel;
+  }
+  float depth = uLayer + aPlace.w + 0.5 + clamp(aPlace.y * uDepthScale, -${BAND}, ${BAND});
+  vUv = (rect.xy + corner * rect.zw) / uSheetSize;
+  vTint = aTint;
+  vFlash = aFrame.z;
+  gl_Position = projectionMatrix * viewMatrix * modelMatrix * vec4(base.x + local.x, depth, base.y + local.y, 1.0);
+}`;
+const FRAGMENT = `
+uniform sampler2D uMap;
+uniform float uAlphaTest;
+uniform float uBlend;
+varying vec2 vUv;
+varying vec4 vTint;
+varying float vFlash;
+
+void main() {
+  vec4 texel = texture2D(uMap, vUv);
+  float alpha = texel.a * vTint.a;
+  if (alpha < uAlphaTest) discard;
+  vec3 color = mix(texel.rgb * vTint.rgb, vec3(1.0), vFlash);
+  gl_FragColor = vec4(color, uBlend > 0.5 ? alpha : 1.0);
+  #include <colorspace_fragment>
+}`;
+/**
+* Draws up to `capacity` sprites from one sheet in a single draw call, as quads on the ground
+* plane facing a straight-down camera (`PixelCamera`). Each sprite has a position, a frame,
+* a horizontal flip, a tint, a flash toward white, an alpha, a lift and a layer. Within a layer
+* a sprite lower on screen (larger z) draws in front.
+*
+* Each frame, call `set` for every sprite to draw (it resets that sprite's look), then the
+* other setters for those that need them, then `commit(count)`. Nothing allocates per frame.
+* Add `mesh` to the scene. `dispose` (or `disposeObject`) frees its own geometry, material and
+* frame table, never the sheet's texture: the sheet's owner frees that.
+*/
+var InstancedSprites = class {
+	mesh;
+	capacity;
+	sheet;
+	frameCount;
+	place;
+	frame;
+	tint;
+	frameTable;
+	constructor(sheet, options) {
+		this.sheet = sheet;
+		this.capacity = options.capacity;
+		this.frameCount = sheet.data.frames.length;
+		const transparent = options.transparent ?? false;
+		const quad = new THREE.PlaneGeometry(1, 1);
+		const geometry = new THREE.InstancedBufferGeometry();
+		geometry.index = quad.index;
+		geometry.setAttribute("position", quad.getAttribute("position"));
+		geometry.setAttribute("uv", quad.getAttribute("uv"));
+		quad.dispose();
+		this.place = dynamicAttribute(geometry, "aPlace", this.capacity, 4);
+		this.frame = dynamicAttribute(geometry, "aFrame", this.capacity, 3);
+		this.tint = dynamicAttribute(geometry, "aTint", this.capacity, 4);
+		geometry.instanceCount = 0;
+		this.frameTable = frameTable(sheet.data);
+		const anchor = options.anchor ?? {
+			x: .5,
+			y: .5
+		};
+		const material = new THREE.ShaderMaterial({
+			vertexShader: VERTEX,
+			fragmentShader: FRAGMENT,
+			uniforms: {
+				uMap: { value: sheet.texture },
+				uFrames: { value: this.frameTable },
+				uSheetSize: { value: new THREE.Vector2(sheet.data.width, sheet.data.height) },
+				uAnchor: { value: new THREE.Vector2(anchor.x, anchor.y) },
+				uUnitsPerPixel: { value: options.unitsPerPixel ?? 1 / 16 },
+				uSnap: { value: options.snap ?? true ? 1 : 0 },
+				uLayer: { value: options.layer ?? 0 },
+				uDepthScale: { value: BAND / (options.sortRange ?? 256) },
+				uAlphaTest: { value: options.alphaTest ?? (transparent ? .01 : .5) },
+				uBlend: { value: transparent ? 1 : 0 }
+			},
+			transparent,
+			depthWrite: !transparent,
+			side: THREE.DoubleSide
+		});
+		this.mesh = new THREE.Mesh(geometry, material);
+		this.mesh.frustumCulled = false;
+	}
+	/**
+	* Places sprite `index` with its feet (its anchor) at (x, z) on the ground, showing frame
+	* `frame` (an index into `sheet.data.frames`, as `frameAt` gives), mirrored if `flipX`.
+	* Resets its tint, alpha, flash, lift and layer. A frame outside the sheet draws frame 0.
+	*/
+	set(index, x, z, frame, flipX = false) {
+		const shown = frame >= 0 && frame < this.frameCount ? frame : 0;
+		write4(this.place, index, x, z, 0, 0);
+		write3(this.frame, index, shown, flipX ? 1 : 0, 0);
+		write4(this.tint, index, 1, 1, 1, 1);
+	}
+	/** Multiplies sprite `index`'s colors by `color` (white leaves them), and sets its alpha. */
+	setTint(index, color, alpha = 1) {
+		write4(this.tint, index, color.r, color.g, color.b, alpha);
+	}
+	/** Sets sprite `index`'s alpha (0 to 1) and keeps its tint. Opaque sprites hide below `alphaTest`. */
+	setAlpha(index, alpha) {
+		this.tint.array[index * 4 + 3] = alpha;
+	}
+	/** Blends sprite `index` toward white: 0 is its own colors, 1 a white silhouette. A hit flash. */
+	setFlash(index, amount) {
+		this.frame.array[index * 3 + 2] = amount;
+	}
+	/**
+	* Draws sprite `index` `lift` world units up the screen, as if floating: a bat. Its depth
+	* stays where its feet are, so it sorts with the things standing near it.
+	*/
+	setLift(index, lift) {
+		this.place.array[index * 4 + 2] = lift;
+	}
+	/** Puts sprite `index` in another layer, added to the batch's own. See `InstancedSpritesOptions.layer`. */
+	setLayer(index, layer) {
+		this.place.array[index * 4 + 3] = layer;
+	}
+	/** Shows the first `count` sprites and uploads them. */
+	commit(count) {
+		const shown = Math.max(0, Math.min(count, this.capacity));
+		this.mesh.geometry.instanceCount = shown;
+		for (const attribute of [
+			this.place,
+			this.frame,
+			this.tint
+		]) {
+			attribute.clearUpdateRanges();
+			attribute.addUpdateRange(0, Math.max(1, shown) * attribute.itemSize);
+			attribute.needsUpdate = true;
+		}
+	}
+	/** Removes the mesh and frees its geometry, material and frame table. Never the sheet. */
+	dispose() {
+		this.mesh.removeFromParent();
+		this.mesh.geometry.dispose();
+		this.mesh.material.dispose();
+		this.frameTable.dispose();
+	}
+};
+const dynamicAttribute = (geometry, name, capacity, size) => {
+	const attribute = new THREE.InstancedBufferAttribute(new Float32Array(Math.max(1, capacity) * size), size);
+	attribute.setUsage(THREE.DynamicDrawUsage);
+	geometry.setAttribute(name, attribute);
+	return attribute;
+};
+const write4 = (attribute, index, a, b, c, d) => {
+	const array = attribute.array;
+	const at = index * 4;
+	array[at] = a;
+	array[at + 1] = b;
+	array[at + 2] = c;
+	array[at + 3] = d;
+};
+const write3 = (attribute, index, a, b, c) => {
+	const array = attribute.array;
+	const at = index * 3;
+	array[at] = a;
+	array[at + 1] = b;
+	array[at + 2] = c;
+};
+/**
+* The frame table the vertex shader reads: frame i at column i % TABLE_COLUMNS, rows
+* 2 * floor(i / TABLE_COLUMNS) (its rect in the image) and the row after (its offset in the
+* untrimmed frame, and that frame's size).
+*/
+const frameTableData = (sheet) => {
+	const count = sheet.frames.length;
+	const width = Math.min(Math.max(1, count), TABLE_COLUMNS);
+	const height = 2 * Math.max(1, Math.ceil(count / TABLE_COLUMNS));
+	const data = new Float32Array(width * height * 4);
+	for (const [index, frame] of sheet.frames.entries()) {
+		const column = index % TABLE_COLUMNS;
+		const row = 2 * Math.floor(index / TABLE_COLUMNS);
+		data.set([
+			frame.x,
+			frame.y,
+			frame.width,
+			frame.height
+		], (row * width + column) * 4);
+		data.set([
+			frame.offsetX,
+			frame.offsetY,
+			frame.sourceWidth,
+			frame.sourceHeight
+		], ((row + 1) * width + column) * 4);
+	}
+	return {
+		data,
+		width,
+		height
+	};
+};
+const frameTable = (sheet) => {
+	const { data, width, height } = frameTableData(sheet);
+	const texture = new THREE.DataTexture(data, width, height, THREE.RGBAFormat, THREE.FloatType);
+	texture.needsUpdate = true;
+	return texture;
+};
+// src/mesh-instances.ts
+const DEFAULT_COLOR = new THREE.Color("#ffffff");
+/**
+* Draws up to `capacity` copies of one mesh in a single draw call.
+* Call `set` (and optionally `setColor`) for the instances that changed, then `commit(count)`
+* to show the first `count` instances and upload the changes.
+*/
+var MeshInstances = class {
+	mesh;
+	capacity;
+	matrix = new THREE.Matrix4();
+	constructor(geometry, material, capacity) {
+		this.capacity = capacity;
+		this.mesh = new THREE.InstancedMesh(geometry, material, capacity);
+		this.mesh.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
+		this.mesh.setColorAt(0, DEFAULT_COLOR);
+		this.mesh.count = 0;
+		this.mesh.frustumCulled = false;
+	}
+	/**
+	* Places instance `index` at (x, y, z) with a uniform `scale` and a rotation around the vertical axis.
+	* For a fixed tilt every instance shares (a flat ring lying on the floor), rotate the geometry once instead.
+	*/
+	set(index, x, y, z, scale = 1, rotationY = 0) {
+		if (rotationY === 0) this.matrix.makeScale(scale, scale, scale);
+		else {
+			this.matrix.makeRotationY(rotationY);
+			if (scale !== 1) this.matrix.scale(SCALE.set(scale, scale, scale));
+		}
+		this.matrix.setPosition(x, y, z);
+		this.mesh.setMatrixAt(index, this.matrix);
+	}
+	setColor(index, color) {
+		this.mesh.setColorAt(index, color);
+	}
+	/** Shows the first `count` instances and uploads this frame's changes. */
+	commit(count) {
+		this.mesh.count = Math.min(count, this.capacity);
+		this.mesh.instanceMatrix.needsUpdate = true;
+		if (this.mesh.instanceColor) this.mesh.instanceColor.needsUpdate = true;
+	}
+	dispose() {
+		this.mesh.removeFromParent();
+		this.mesh.geometry.dispose();
+		const materials = Array.isArray(this.mesh.material) ? this.mesh.material : [this.mesh.material];
+		for (const material of materials) material.dispose();
+	}
+};
+const SCALE = new THREE.Vector3();
+// src/pixel-camera.ts
+/** How high above the ground the camera sits. Anything from y = -HEIGHT to just below it is drawn. */
+const HEIGHT = 100;
+/**
+* Screen pixels per sprite pixel that best shows `viewHeight` world units on a drawing buffer
+* `bufferHeight` pixels tall: the nearest whole number, at least 1.
+*/
+const pixelScale = (bufferHeight, viewHeight, pixelsPerUnit) => Math.max(1, Math.round(bufferHeight / (viewHeight * pixelsPerUnit)));
+/**
+* The largest whole number of screen pixels per sprite pixel at which a `width` x `depth` world
+* unit area fits a `bufferWidth` x `bufferHeight` drawing buffer, at least 1 (a buffer too
+* small for the area at 1 crops it).
+*/
+const fitPixelScale = (bufferWidth, bufferHeight, width, depth, pixelsPerUnit) => Math.max(1, Math.floor(Math.min(bufferWidth / (width * pixelsPerUnit), bufferHeight / (depth * pixelsPerUnit))));
+/**
+* Rounds a world position to the nearest pixel edge, at `pixelsPerUnit` pixels per world unit:
+* sprite pixels with the sheet's density, or screen pixels with the camera's.
+*/
+const snapToPixel = (value, pixelsPerUnit) => Math.round(value * pixelsPerUnit) / pixelsPerUnit;
+/**
+* The frustum for a `bufferWidth` x `bufferHeight` drawing buffer at `pixelsPerWorldUnit`
+* screen pixels per world unit, around a camera at the origin. An odd size gets its spare
+* pixel on the right or bottom, so the camera's position stays on a screen pixel's corner.
+*/
+const pixelFrustum = (bufferWidth, bufferHeight, pixelsPerWorldUnit) => {
+	const halfWidth = Math.floor(bufferWidth / 2);
+	const halfHeight = Math.floor(bufferHeight / 2);
+	return {
+		left: -halfWidth / pixelsPerWorldUnit,
+		right: (bufferWidth - halfWidth) / pixelsPerWorldUnit,
+		top: halfHeight / pixelsPerWorldUnit,
+		bottom: -(bufferHeight - halfHeight) / pixelsPerWorldUnit
+	};
+};
+/**
+* An orthographic camera looking straight down at the ground plane (y = 0), with +x to the
+* right and +z down the screen, so a larger z is lower on screen. It keeps sprite pixels whole:
+* `pixelScale` screen pixels per sprite pixel, a whole number, and a position on whole screen
+* pixels. Give it the drawing buffer's size with `setBufferSize` (a `Stage` made with
+* `camera: "pixel"` does, on every resize), then `follow` a point or `fit` an area each frame.
+* Don't move it with `fitCamera` or `lookAt`: they undo the snapping.
+*/
+var PixelCamera = class extends THREE.OrthographicCamera {
+	isPixelCamera = true;
+	pixelsPerUnitValue;
+	viewHeightValue;
+	screenScale = 1;
+	bufferWidth = 1;
+	bufferHeight = 1;
+	targetX = 0;
+	targetZ = 0;
+	/** Set by `fit`, cleared by `follow`. */
+	fitted = null;
+	constructor(options = {}) {
+		super(-1, 1, 1, -1, 1, 200);
+		this.pixelsPerUnitValue = options.pixelsPerUnit ?? 16;
+		this.viewHeightValue = options.viewHeight ?? 20;
+		this.rotation.set(-Math.PI / 2, 0, 0);
+		this.update();
+	}
+	/** Sprite pixels per world unit. */
+	get pixelsPerUnit() {
+		return this.pixelsPerUnitValue;
+	}
+	/** Screen pixels per sprite pixel: a whole number, at least 1. */
+	get pixelScale() {
+		return this.screenScale;
+	}
+	/** Screen (drawing buffer) pixels per world unit. */
+	get screenPixelsPerUnit() {
+		return this.pixelsPerUnitValue * this.screenScale;
+	}
+	/** The ground height to aim for, in world units. Takes effect at once. */
+	setViewHeight(viewHeight) {
+		this.viewHeightValue = viewHeight;
+		this.update();
+	}
+	/** The drawing buffer's size in pixels (`renderer.getDrawingBufferSize`), not CSS pixels. */
+	setBufferSize(width, height) {
+		this.bufferWidth = Math.max(1, Math.round(width));
+		this.bufferHeight = Math.max(1, Math.round(height));
+		this.update();
+	}
+	/** Centres the view on a ground point, snapped to the nearest screen pixel. Survivors' hero. */
+	follow(x, z) {
+		this.fitted = null;
+		this.targetX = x;
+		this.targetZ = z;
+		this.update();
+	}
+	/**
+	* Shows all of an area plus `margin` world units around it, at the largest whole pixel scale
+	* that fits, centred on it. It keeps fitting on resize until the next `follow`. A puzzle board.
+	*/
+	fit(bounds, margin = 0) {
+		this.fitted = {
+			minX: bounds.minX - margin,
+			maxX: bounds.maxX + margin,
+			minZ: bounds.minZ - margin,
+			maxZ: bounds.maxZ + margin
+		};
+		this.targetX = (bounds.minX + bounds.maxX) / 2;
+		this.targetZ = (bounds.minZ + bounds.maxZ) / 2;
+		this.update();
+	}
+	update() {
+		const perUnit = this.pixelsPerUnitValue;
+		this.screenScale = this.fitted ? fitPixelScale(this.bufferWidth, this.bufferHeight, this.fitted.maxX - this.fitted.minX, this.fitted.maxZ - this.fitted.minZ, perUnit) : pixelScale(this.bufferHeight, this.viewHeightValue, perUnit);
+		const screenPerUnit = perUnit * this.screenScale;
+		const frustum = pixelFrustum(this.bufferWidth, this.bufferHeight, screenPerUnit);
+		this.left = frustum.left;
+		this.right = frustum.right;
+		this.top = frustum.top;
+		this.bottom = frustum.bottom;
+		this.updateProjectionMatrix();
+		this.position.set(snapToPixel(this.targetX, screenPerUnit), HEIGHT, snapToPixel(this.targetZ, screenPerUnit));
+		this.updateMatrixWorld();
+	}
+};
+// src/sprite-sheet.ts
+const SpriteSheetErrorBase = Data.TaggedError("SpriteSheetError");
+/** A sprite sheet that couldn't be fetched, decoded or checked. `file` is the JSON or image that failed. */
+var SpriteSheetError = class extends SpriteSheetErrorBase {};
+const Count = Schema.Int;
+const Rect = Schema.Struct({
+	x: Count,
+	y: Count,
+	w: Count,
+	h: Count
+});
+const Size = Schema.Struct({
+	w: Count,
+	h: Count
+});
+const AsepriteFrame = Schema.Struct({
+	filename: Schema.optional(Schema.String),
+	frame: Rect,
+	rotated: Schema.optional(Schema.Boolean),
+	spriteSourceSize: Schema.optional(Rect),
+	sourceSize: Schema.optional(Size),
+	duration: Schema.optional(Schema.Finite)
+});
+const AsepriteSheet = Schema.Struct({
+	frames: Schema.Union([Schema.Array(AsepriteFrame), Schema.Record(Schema.String, AsepriteFrame)]),
+	meta: Schema.Struct({
+		image: Schema.String,
+		size: Size,
+		frameTags: Schema.optional(Schema.Array(Schema.Struct({
+			name: Schema.String,
+			from: Count,
+			to: Count,
+			direction: Schema.optional(Schema.Literals([
+				"forward",
+				"reverse",
+				"pingpong",
+				"pingpong_reverse"
+			]))
+		})))
+	})
+});
+const decodeAseprite = Schema.decodeUnknownResult(AsepriteSheet);
+/** Aseprite's default frame duration, in ms, for exports that leave it out. */
+const DEFAULT_DURATION_MS = 100;
+/**
+* Parses an Aseprite JSON export (frames as an array or a hash) and checks it: every frame
+* inside the image, every tag inside the frames, no two tags with one name. `file` names the
+* JSON in the error. Rotated frames (a TexturePacker option) aren't supported. A tag's
+* `repeat` is ignored: animations loop.
+*/
+const decodeSpriteSheet = (file, json) => {
+	const fail = (message) => Effect.fail(new SpriteSheetError({
+		file,
+		message: `The sprite sheet ${file} is invalid: ${message}`
+	}));
+	const decoded = decodeAseprite(json);
+	if (Result.isFailure(decoded)) return fail(decoded.failure.message);
+	const { meta } = decoded.success;
+	if (meta.size.w < 1 || meta.size.h < 1) return fail(`meta.size is ${meta.size.w}x${meta.size.h}`);
+	const entries = Array.isArray(decoded.success.frames) ? decoded.success.frames.map((frame, index) => [frame.filename ?? String(index), frame]) : Object.entries(decoded.success.frames);
+	if (entries.length === 0) return fail("it has no frames");
+	const frames = [];
+	const frameByName = /* @__PURE__ */ new Map();
+	for (const [name, frame] of entries) {
+		const problem = frameProblem(frame, meta.size);
+		if (problem !== void 0) return fail(`frame ${frames.length} (${name}) ${problem}`);
+		const { x, y, w, h } = frame.frame;
+		const placed = frame.spriteSourceSize ?? {
+			x: 0,
+			y: 0,
+			w,
+			h
+		};
+		const source = frame.sourceSize ?? {
+			w,
+			h
+		};
+		if (!frameByName.has(name)) frameByName.set(name, frames.length);
+		frames.push({
+			name,
+			x,
+			y,
+			width: w,
+			height: h,
+			offsetX: placed.x,
+			offsetY: placed.y,
+			sourceWidth: source.w,
+			sourceHeight: source.h,
+			duration: (frame.duration ?? DEFAULT_DURATION_MS) / 1e3
+		});
+	}
+	const tags = readTags(meta.frameTags ?? [], frames);
+	if (typeof tags === "string") return fail(tags);
+	return Effect.succeed({
+		image: meta.image,
+		width: meta.size.w,
+		height: meta.size.h,
+		frames,
+		frameByName,
+		tags
+	});
+};
+/** The tags by name, or what's wrong with them. */
+const readTags = (frameTags, frames) => {
+	const tags = /* @__PURE__ */ new Map();
+	for (const tag of frameTags) {
+		if (tags.has(tag.name)) return `two tags are named "${tag.name}"`;
+		if (tag.from < 0 || tag.from > tag.to || tag.to >= frames.length) return `tag "${tag.name}" runs from frame ${tag.from} to ${tag.to}, but the sheet has frames 0 to ${frames.length - 1}`;
+		const shape = {
+			from: tag.from,
+			to: tag.to,
+			direction: tag.direction ?? "forward"
+		};
+		let duration = 0;
+		for (let step = 0; step < loopLength(shape); step += 1) duration += frames[frameOfStep(shape, step)]?.duration ?? 0;
+		tags.set(tag.name, {
+			name: tag.name,
+			...shape,
+			duration
+		});
+	}
+	return tags;
+};
+/** What's wrong with one frame, or undefined. */
+const frameProblem = (frame, image) => {
+	const { x, y, w, h } = frame.frame;
+	if (frame.rotated === true) return "is rotated, which isn't supported";
+	if (w < 1 || h < 1) return `is ${w}x${h}`;
+	if (x < 0 || y < 0 || x + w > image.w || y + h > image.h) return `at ${x},${y} size ${w}x${h} lies outside the ${image.w}x${image.h} image`;
+	if (frame.duration !== void 0 && frame.duration <= 0) return `lasts ${frame.duration} ms`;
+	const placed = frame.spriteSourceSize;
+	const source = frame.sourceSize ?? {
+		w,
+		h
+	};
+	if (placed !== void 0 && (placed.x < 0 || placed.y < 0 || placed.x + w > source.w || placed.y + h > source.h)) return `is placed at ${placed.x},${placed.y} outside its ${source.w}x${source.h} source size`;
+};
+const isPingpong = (tag) => tag.direction === "pingpong" || tag.direction === "pingpong_reverse";
+/** Frames in one loop: a pingpong over 0..3 plays 0 1 2 3 2 1. */
+const loopLength = (tag) => {
+	const count = tag.to - tag.from + 1;
+	return isPingpong(tag) && count > 1 ? 2 * count - 2 : count;
+};
+/** The frame index shown at `step` of a loop. */
+const frameOfStep = (tag, step) => {
+	const count = tag.to - tag.from + 1;
+	const back = step - count + 1;
+	switch (tag.direction) {
+		case "forward": return tag.from + step;
+		case "reverse": return tag.to - step;
+		case "pingpong": return step < count ? tag.from + step : tag.to - back;
+		case "pingpong_reverse": return step < count ? tag.to - step : tag.from + back;
+	}
+};
+/**
+* The frame index (into `sheet.frames`) a tag shows `seconds` into its animation, looping,
+* from each frame's duration and the tag's direction. Allocates nothing: call it per sprite
+* per frame. Negative times count back from the end of a loop.
+*/
+const frameAt = (sheet, tag, seconds) => {
+	if (tag.from === tag.to || !(tag.duration > 0)) return tag.from;
+	let left = seconds % tag.duration;
+	if (left < 0) left += tag.duration;
+	const steps = loopLength(tag);
+	for (let step = 0; step < steps; step += 1) {
+		const index = frameOfStep(tag, step);
+		left -= sheet.frames[index]?.duration ?? 0;
+		if (left < 0) return index;
+	}
+	return frameOfStep(tag, steps - 1);
+};
+// src/stage.ts
+/** A perspective camera's field of view, in degrees. Set `stage.camera.fov` to change it. */
+const FOV = 50;
+/** The near and far planes of a perspective or orthographic camera. */
+const NEAR = .1;
+const FAR = 400;
+/**
+* Caps devicePixelRatio for a perspective or orthographic stage; 2 keeps phones sharp without
+* rendering 9x the pixels. A pixel stage isn't capped: see `drawingBuffer`.
+*/
+const MAX_PIXEL_RATIO = 2;
+/**
+* A renderer, scene and camera that fill a container element and resize with it.
+* The camera is perspective unless `camera: "orthographic"` or `"pixel"` is passed; on resize, an
+* orthographic camera keeps its view height and widens or narrows to the new aspect ratio, and a
+* pixel camera picks its pixel scale again. The pixel ratio is read again on every resize, and
+* a pixel stage sizes its drawing buffer to the canvas's exact device pixels, where the others
+* cap the ratio at 2 (see `drawingBuffer`). The camera is public: change its fields (a
+* perspective camera's `fov`, `near` and `far`) and call `updateProjectionMatrix()`. So is the
+* scene: set `stage.scene.fog` for fog.
+* `dispose()` frees every GPU resource in the scene, except kept textures (see `keepTexture`),
+* and removes the canvas.
+*/
+var Stage = class {
+	renderer;
+	scene = new THREE.Scene();
+	camera;
+	container;
+	resizeObserver;
+	constructor(container, options = {}) {
+		this.container = container;
+		const pixel = options.camera === "pixel";
+		this.renderer = new THREE.WebGLRenderer({
+			antialias: !pixel,
+			powerPreference: "high-performance"
+		});
+		const canvas = this.renderer.domElement;
+		canvas.style.display = "block";
+		canvas.style.width = "100%";
+		canvas.style.height = "100%";
+		if (pixel) canvas.style.imageRendering = "pixelated";
+		container.append(canvas);
+		if (pixel) this.camera = new PixelCamera({
+			...options.pixelsPerUnit === void 0 ? {} : { pixelsPerUnit: options.pixelsPerUnit },
+			...options.viewHeight === void 0 ? {} : { viewHeight: options.viewHeight }
+		});
+		else if (options.camera === "orthographic") {
+			const half = (options.viewHeight ?? 10) / 2;
+			this.camera = new THREE.OrthographicCamera(-half, half, half, -half, NEAR, FAR);
+		} else this.camera = new THREE.PerspectiveCamera(FOV, 1, NEAR, FAR);
+		if (options.background !== void 0) this.scene.background = new THREE.Color(options.background);
+		this.resizeObserver = new ResizeObserver((entries) => this.resize(entries.at(-1)));
+		try {
+			this.resizeObserver.observe(container, { box: "device-pixel-content-box" });
+		} catch {
+			this.resizeObserver.observe(container);
+		}
+		this.resize(void 0);
+	}
+	render() {
+		this.renderer.render(this.scene, this.camera);
+	}
+	dispose() {
+		this.resizeObserver.disconnect();
+		disposeObject(this.scene);
+		this.renderer.dispose();
+		this.renderer.domElement.remove();
+	}
+	resize(entry) {
+		const width = Math.max(1, this.container.clientWidth);
+		const height = Math.max(1, this.container.clientHeight);
+		const camera = this.camera;
+		const target = drawingBuffer(camera instanceof PixelCamera, width, height, window.devicePixelRatio, MAX_PIXEL_RATIO, entry?.devicePixelContentBoxSize?.[0]);
+		this.renderer.setPixelRatio(target.pixelRatio);
+		this.renderer.setSize(target.width, target.height, false);
+		const aspect = width / height;
+		if (camera instanceof PixelCamera) {
+			const buffer = this.renderer.getDrawingBufferSize(BUFFER_SIZE);
+			camera.setBufferSize(buffer.x, buffer.y);
+		} else if (camera instanceof THREE.OrthographicCamera) {
+			const centerX = (camera.left + camera.right) / 2;
+			const halfWidth = (camera.top - camera.bottom) / 2 * aspect;
+			camera.left = centerX - halfWidth;
+			camera.right = centerX + halfWidth;
+		} else camera.aspect = aspect;
+		camera.updateProjectionMatrix();
+	}
+};
+const BUFFER_SIZE = new THREE.Vector2();
+/**
+* The drawing buffer for a canvas `width` x `height` CSS pixels: the pixel ratio and size to
+* give `renderer.setSize`. A pixel stage never caps the ratio, since a smaller buffer is
+* stretched onto the screen by a fraction and sprite pixels would cover uneven numbers of
+* screen pixels; where the browser reports the canvas's device pixels (`device`), it uses
+* those, as width * ratio can round a pixel off from the browser's size at a fractional ratio.
+*/
+const drawingBuffer = (pixel, width, height, devicePixelRatio, maxPixelRatio, device) => {
+	if (!pixel) return {
+		pixelRatio: Math.min(devicePixelRatio, maxPixelRatio),
+		width,
+		height
+	};
+	if (device === void 0) return {
+		pixelRatio: devicePixelRatio,
+		width,
+		height
+	};
+	return {
+		pixelRatio: 1,
+		width: Math.max(1, device.inlineSize),
+		height: Math.max(1, device.blockSize)
+	};
+};
+const KEEP = "arcadekitKeep";
+/**
+* Marks a texture that something outside the scene owns, such as a sprite sheet the app
+* loaded: `disposeObject` and `Stage.dispose` leave it alone, and its owner disposes it.
+* Returns the texture.
+*/
+const keepTexture = (texture) => {
+	texture.userData[KEEP] = true;
+	return texture;
+};
+/** Whether `keepTexture` marked this texture. */
+const isKeptTexture = (texture) => texture.userData[KEEP] === true;
+/**
+* Frees the geometries, materials and textures of `root` and everything under it: the textures
+* a material holds (its maps, and a shader material's texture uniforms) and, for a scene, its
+* background and environment. Textures marked with `keepTexture` are skipped.
+* `Stage.dispose` calls it on the whole scene. A view that removes an object from the
+* scene calls it on that object, which `Stage.dispose` no longer reaches.
+*/
+const disposeObject = (root) => {
+	const textures = /* @__PURE__ */ new Set();
+	if (root instanceof THREE.Scene) {
+		addTexture(textures, root.background);
+		addTexture(textures, root.environment);
+	}
+	root.traverse((object) => {
+		if (object instanceof THREE.Mesh || object instanceof THREE.Line || object instanceof THREE.Points) {
+			object.geometry.dispose();
+			const materials = Array.isArray(object.material) ? object.material : [object.material];
+			for (const material of materials) {
+				for (const value of Object.values(material)) addTexture(textures, value);
+				if (material instanceof THREE.ShaderMaterial) for (const uniform of Object.values(material.uniforms)) addTexture(textures, uniform.value);
+				material.dispose();
+			}
+		}
+	});
+	for (const texture of textures) texture.dispose();
+};
+const addTexture = (textures, value) => {
+	if (value instanceof THREE.Texture && !isKeptTexture(value)) textures.add(value);
+};
+// src/sprite-loader.ts
+/**
+* Makes a sheet from parsed data and an image that's already in memory, such as a canvas the
+* art was painted on. `loadSpriteSheet` uses it after fetching both files.
+*/
+const makeSpriteSheet = (data, image) => {
+	const texture = new THREE.Texture(image);
+	texture.magFilter = THREE.NearestFilter;
+	texture.minFilter = THREE.NearestFilter;
+	texture.generateMipmaps = false;
+	texture.colorSpace = THREE.SRGBColorSpace;
+	texture.flipY = false;
+	texture.premultiplyAlpha = false;
+	texture.name = data.image;
+	texture.needsUpdate = true;
+	keepTexture(texture);
+	return {
+		data,
+		texture,
+		dispose: () => {
+			texture.dispose();
+			if (typeof ImageBitmap !== "undefined" && image instanceof ImageBitmap) image.close();
+		}
+	};
+};
+/**
+* Loads an Aseprite sheet: fetches the JSON at `jsonUrl`, then the image its `meta.image`
+* names, relative to the JSON. Fails with a `SpriteSheetError` naming the file when either
+* can't be fetched, the JSON is invalid, or the image's size isn't `meta.size`.
+*/
+const loadSpriteSheet = (jsonUrl) => Effect.gen(function* () {
+	const json = yield* fetchFile(jsonUrl, (response) => response.json());
+	const data = yield* decodeSpriteSheet(jsonUrl, json);
+	const imageUrl = new URL(data.image, new URL(jsonUrl, globalThis.location.href)).href;
+	const image = yield* fetchFile(imageUrl, async (response) => createImageBitmap(await response.blob(), {
+		premultiplyAlpha: "none",
+		colorSpaceConversion: "none"
+	}));
+	const { width, height } = image;
+	if (width !== data.width || height !== data.height) {
+		image.close();
+		return yield* new SpriteSheetError({
+			file: imageUrl,
+			message: `The sprite sheet image ${imageUrl} is ${width}x${height}, but ${jsonUrl} says ${data.width}x${data.height}`
+		});
+	}
+	return makeSpriteSheet(data, image);
+});
+const fetchFile = (file, read) => Effect.tryPromise({
+	try: async (signal) => {
+		const response = await fetch(file, { signal });
+		if (!response.ok) throw new Error(`HTTP ${response.status}`);
+		return await read(response);
+	},
+	catch: (cause) => new SpriteSheetError({
+		file,
+		message: `The sprite sheet file ${file} can't be loaded: ${cause instanceof Error ? cause.message : String(cause)}`,
+		cause
+	})
+});
+export { InstancedSprites, MeshInstances, PixelCamera, SpriteSheetError, Stage, decodeSpriteSheet, disposeObject, fitCamera, fitPixelScale, followTarget, frameAt, isKeptTexture, keepTexture, loadSpriteSheet, makeSpriteSheet, orbitAround, pixelFrustum, pixelScale, snapToPixel };
+
+//# sourceMappingURL=index.js.map