Skip to content

Code-first video & image, rendered natively on WebGPU.

6.8 KB
Raw Blame
/**
 * Schemas for procedural 3D content: terrain, SDF sculptures, surface
 * scattering and wind. A model node's `primitive3d` is checked against the
 * terrain / SDF schema when it names one of them.
 */
import { z } from "zod";

const Vec3Schema = z.tuple([z.number(), z.number(), z.number()]);
const RangeSchema = (min: number, max: number) =>
	z.tuple([z.number().min(min).max(max), z.number().min(min).max(max)]);
const ShadingSchema = z.enum(["lit", "unlit", "toon"]);

const PrimitiveSurfaceFields = {
	color: z.string().optional(),
	material: ShadingSchema.optional(),
	shininess: z.number().min(0).optional(),
	roughness: z.number().min(0).max(1).optional(),
	metallic: z.number().min(0).max(1).optional(),
};

export const TerrainNoiseSchema = z
	.object({
		seed: z.number().optional(),
		/** Size of the largest landforms, px. */
		scale: z.number().positive().optional(),
		octaves: z.number().int().min(1).max(10).optional(),
		persistence: z.number().min(0).max(1).optional(),
		lacunarity: z.number().min(1).max(4).optional(),
		ridgeMode: z.enum(["fbm", "ridged", "terrace"]).optional(),
		terraceSteps: z.number().int().min(2).max(32).optional(),
	})
	.strict();

export const TerrainColorByElevationSchema = z
	.object({
		lowColor: z.string(),
		midColor: z.string().optional(),
		highColor: z.string(),
		cliffColor: z.string().optional(),
		cliffThreshold: z.number().min(0).max(1).optional(),
		bands: RangeSchema(0, 1).optional(),
	})
	.strict();

export const TerrainGeometrySchema = z
	.object({
		type: z.literal("terrain"),
		width: z.number().positive(),
		depth: z.number().positive(),
		height: z.number().min(0).optional(),
		segments: z
			.union([
				z.number().int().min(1).max(512),
				z.tuple([
					z.number().int().min(1).max(512),
					z.number().int().min(1).max(512),
				]),
			])
			.optional(),
		noise: TerrainNoiseSchema.optional(),
		heights: z.array(z.number().min(0).max(1)).optional(),
		overhangWarp: z.number().min(0).optional(),
		colorByElevation: TerrainColorByElevationSchema.optional(),
		flatShaded: z.boolean().optional(),
		base: z.number().min(0).optional(),
		...PrimitiveSurfaceFields,
	})
	.strict();

const SdfBaseFields = {
	op: z.enum(["union", "subtract", "intersect"]).optional(),
	smoothness: z.number().min(0).optional(),
	center: Vec3Schema.optional(),
	rotation: Vec3Schema.optional(),
	color: z.string().optional(),
};

export const SdfPrimitiveSchema = z.discriminatedUnion("shape", [
	z
		.object({
			...SdfBaseFields,
			shape: z.literal("sphere"),
			radius: z.number().positive(),
		})
		.strict(),
	z
		.object({
			...SdfBaseFields,
			shape: z.literal("box"),
			size: z.tuple([
				z.number().positive(),
				z.number().positive(),
				z.number().positive(),
			]),
			radius: z.number().min(0).optional(),
		})
		.strict(),
	z
		.object({
			...SdfBaseFields,
			shape: z.literal("cylinder"),
			radius: z.number().positive(),
			height: z.number().positive(),
		})
		.strict(),
	z
		.object({
			...SdfBaseFields,
			shape: z.literal("capsule"),
			radius: z.number().positive(),
			height: z.number().positive(),
		})
		.strict(),
	z
		.object({
			...SdfBaseFields,
			shape: z.literal("torus"),
			radius: z.number().positive(),
			tube: z.number().positive(),
		})
		.strict(),
	z
		.object({
			...SdfBaseFields,
			shape: z.literal("gyroid"),
			scale: z.number().positive(),
			thickness: z.number().positive(),
		})
		.strict(),
]);

export const SdfGeometrySchema = z
	.object({
		type: z.literal("sdf"),
		primitives: z.array(SdfPrimitiveSchema).min(1),
		bounds: z.tuple([
			z.number().positive(),
			z.number().positive(),
			z.number().positive(),
		]),
		resolution: z.number().int().min(16).max(160).optional(),
		flatShaded: z.boolean().optional(),
		...PrimitiveSurfaceFields,
	})
	.strict();

/** `primitive3d`: free-form for the classic primitives, strict for terrain and SDF. */
export const Primitive3DSpecSchema = z.unknown().superRefine((value, ctx) => {
	const type = (value as { type?: unknown } | null)?.type;
	const schema =
		type === "terrain"
			? TerrainGeometrySchema
			: type === "sdf"
				? SdfGeometrySchema
				: undefined;
	if (!schema) return;
	const parsed = schema.safeParse(value);
	if (parsed.success) return;
	for (const issue of parsed.error.issues) {
		ctx.addIssue({ ...issue, code: "custom", message: issue.message });
	}
});

export const WindSchema = z
	.object({
		/** Peak lean, degrees. Default 8. */
		amplitudeDeg: z.number().min(0).max(90).optional(),
		/** Sways per second. Default 0.4. */
		frequency: z.number().min(0).max(20).optional(),
		/** Downwind on the ground plane [x, z]. Default [1, 0]. */
		direction: z.tuple([z.number(), z.number()]).optional(),
		/** Gust wavelength across the field, px. Default 600. */
		waveScale: z.number().positive().optional(),
	})
	.strict();
export type WindConfig = z.infer<typeof WindSchema>;

export const ScatterExclusionSchema = z
	.object({
		x: z.number(),
		z: z.number(),
		radius: z.number().min(0),
		falloff: z.number().min(0).optional(),
	})
	.strict();

export const Scatter3DSchema = z
	.object({
		/** The surface node (any model3d node: terrain, sdf, primitive, file). */
		surface: z.custom<Record<string, unknown>>(
			(v) => typeof v === "object" && v !== null,
		),
		count: z.number().int().min(0).max(200_000),
		minDistance: z.number().min(0).optional(),
		seed: z.number().optional(),
		slopeRange: RangeSchema(0, 180).optional(),
		elevationRange: RangeSchema(0, 1).optional(),
		alignToNormal: z.number().min(0).max(1).optional(),
		scaleRange: z
			.tuple([z.number().positive(), z.number().positive()])
			.optional(),
		randomYaw: z.boolean().optional(),
		exclude: z.array(ScatterExclusionSchema).optional(),
		/** Push each instance this far into the surface, px. */
		sink: z.number().optional(),
	})
	.strict();
export type Scatter3DSpec = z.infer<typeof Scatter3DSchema>;

/** A layer drawn offscreen every frame and wrapped onto a model's surface. */
export const TextureLayerSchema = z
	.object({
		node: z.custom<unknown>((v) => typeof v === "object" && v !== null),
	})
	.strict();

/**
 * Voronoi destruction (`world.fracture`): the model is cut into `cells`
 * pieces, drawn as one rigidly skinned mesh posed per frame from `track`.
 * Without a track the pieces rest in place and the model looks whole.
 */
export const Fracture3DSchema = z
	.object({
		/** Voronoi pieces, 2..256. Default 48. */
		cells: z.number().int().min(2).max(256).optional(),
		seed: z.number().optional(),
		/** Object-space point the pieces crowd around. */
		impactPoint: Vec3Schema.optional(),
		/** Exposed faces' color. Default "#d8d2c4". */
		interiorColor: z.string().optional(),
		interiorRoughness: z.number().min(0).max(1).optional(),
		/** Per composition frame, per piece: x, y, z (scene px), qx, qy, qz, qw. */
		track: z.array(z.number()).optional(),
	})
	.strict();
export type Fracture3DSpec = z.infer<typeof Fracture3DSchema>;