effect-motion
Guides

Use images

Image assets as typed resources, drawn on a plane that tweens like any shape

An Image entity draws a bitmap on a flat extent — position, width, height, opacity, all animatable like any other shape. The bitmap itself is a typed resource, declared and provided exactly like a font:

import * as Image from "effect-motion/Image";

const Rocket = Image.Image("rocket");

Yield the constant to get the handle (adding ImageLoader<"rocket"> to the scene's requirements), then instantiate:

const rocketImage = yield* Rocket;
const rocket = yield* Scene.instantiate("Image", {
	image: rocketImage,
	width: 260,
	height: 260,
});

Provide the bytes with a layer — renderLayers on the Player, Effect.provide in an export program:

export const renderLayers = Image.layer(
	Rocket,
	Resource.fetchBytes("https://…/rocket.png"),
);

The bytes load once at mount and decode once per render session; every frame reuses the decoded picture. Since width and height are plain numeric fields, scaling an image is just a tweenTo.

Use PNG or JPEG. The browser decodes whatever it supports, but Node (motion frames, motion render) decodes only those two, and fails loudly with the image's id on anything else. See What the renderer draws.

Load files from your project

Resource.fetchBytes needs a URL, and Node has no web server for your project files. One loader works in both places if it resolves the file against import.meta.url and branches on the result: in the browser (motion studio, the Player) the URL is http:, so fetch it; in Node it is a file: URL, so read it from disk.

// src/assets.ts, next to src/assets/
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as Font from "effect-motion/Font";
import * as Image from "effect-motion/Image";
import { EffectMotionError, Resource } from "effect-motion";

const asset = (file: string) => {
	const url = new URL(`./assets/${file}`, import.meta.url);
	return url.protocol === "file:"
		? Effect.tryPromise({
				try: async () => {
					const fs = await import("node:fs/promises");
					return new Uint8Array(await fs.readFile(url));
				},
				catch: (cause) => EffectMotionError.of(`could not read ${file}`, cause),
			})
		: Resource.fetchBytes(url.href);
};

export const Logo = Image.Image("logo");
export const Inter = Font.Font("Inter");

export const layers = Layer.mergeAll(
	Image.layer(Logo, asset("logo.png")),
	Font.layer(Inter, asset("Inter-Bold.ttf")),
);

Pass layers to studioConfig({ scenes, layers }) for the studio and motion frames, and Effect.provide(layers) in render.ts. The node:fs/promises import is dynamic, so the browser never loads it.

0:00
import * as Color from "effect-motion/Color";import * as Entity from "effect-motion/Entity";import * as Image from "effect-motion/Image";import * as Motion from "effect-motion/Motion";import * as Resource from "effect-motion/Resource";import * as Scene from "effect-motion/Scene";// Images are typed scene dependencies like fonts: the layer loads the bytes// once at mount, the render session decodes them once, and every frame// reuses the decoded picture. width/height are plain numeric fields, so// scaling an image is just a tween.const Rocket = Image.Image("rocket");export const scene = Scene.make(	"images",	function* () {		const rocketImage = yield* Rocket;		const rocket = yield* Scene.instantiate("Image", {			position: Entity.vec3({ y: -130 }),			image: rocketImage,			width: 260,			height: 260,			opacity: 0,		});		const caption = yield* Scene.instantiate("Text", {			position: Entity.vec3({ y: -400 }),			text: "images tween like any shape",			fontSize: 64,			fillColor: Color.hex("#94a3b8"),			textAnchor: "middle",			baseline: "middle",			opacity: 0,		});		yield* rocket.pipe(Motion.fadeTo(1, "500 millis"));		yield* caption.pipe(Motion.fadeTo(1, "400 millis"));		// lift off: move up while growing — size is data, so it tweens		yield* Scene.all([			rocket.pipe(Motion.moveTo({ y: 180 }, "1200 millis", "easeInOutCubic")),			rocket.pipe(				Motion.tweenTo(					{ width: 430, height: 430 },					"1200 millis",					"easeInOutCubic",				),			),		]);		yield* Motion.wait("800 millis");	},	{ width: 1920, height: 1080, backgroundColor: Color.rgba(22, 22, 29) },);// a CORS-open, version-pinned PNG (512×512 — comfortably above the largest// size the scene scales it to)export const renderLayers = Image.layer(	Rocket,	Resource.fetchBytes(		"https://cdn.jsdelivr.net/gh/googlefonts/noto-emoji@v2.042/png/512/emoji_u1f680.png",	),);

On this page