@sw-file-lib/three 0.1.0

package/dist/index.mjs

@@ -0,0 +1,1280 @@
+import * as THREE from "three";
+import { BufferAttribute, BufferGeometry } from "three";
+import { WHITE, parseColor } from "@sw-file-lib/core/color";
+import { parseMesh } from "@sw-file-lib/core";
+import { parseComponentDefinitionXml } from "@sw-file-lib/xml";
+import { Orientation, addVec3, mulMat3, mulMat3Vec3, parseMat3, transposeMat3, vec3 } from "@sw-file-lib/core/math";
+import { buildSurfacesGeometry, getSurfaceOrientation, isValidSurfaceOrientation, isValidSurfaceRotation } from "@sw-file-lib/geometry";
+//#region src/geometry.ts
+/**
+* Transfers the contents of a {@link GeometryBuilder} into a `THREE.BufferGeometry`.
+*
+* This function clears the existing attributes and groups of the buffer geometry,
+* then copies the position, normal, color, index, and group data from the builder.
+*
+* @param builder The source geometry builder.
+* @param buffer The target buffer geometry.
+*/
+function applyBuilderOnBufferGeometry(builder, buffer) {
+	buffer.clearGroups();
+	const { position, normal, color, index, groups } = builder.toBufferGeometryAttributes();
+	buffer.setAttribute("position", new BufferAttribute(position, 3));
+	buffer.setAttribute("normal", new BufferAttribute(normal, 3));
+	buffer.setAttribute("color", new BufferAttribute(color.map((v) => v / 255), 4));
+	buffer.setIndex(new BufferAttribute(new Uint32Array(index), 1));
+	for (const { start, length, materialIndex } of groups) buffer.addGroup(start, length, materialIndex);
+}
+/**
+* Creates a new `THREE.BufferGeometry` from a {@link GeometryBuilder}.
+*/
+function bufferGeometryFromBuilder(builder) {
+	const buffer = new BufferGeometry();
+	applyBuilderOnBufferGeometry(builder, buffer);
+	return buffer;
+}
+//#endregion
+//#region src/lights.ts
+const AMBIENT_COLOR_HIGH = new THREE.Color(118 / 255, 142 / 255, 190 / 255);
+const AMBIENT_COLOR_LOW = new THREE.Color(11 / 255, 16 / 255, 44 / 255);
+/**
+* Create the default Stormworks-style light objects.
+*
+* The returned array contains a hemisphere light and a directional light.
+*/
+function createSwLights(options = {}) {
+	const hemi = new THREE.HemisphereLight(AMBIENT_COLOR_HIGH, AMBIENT_COLOR_LOW, options.hemisphereIntensity ?? 1.6);
+	const sun = new THREE.DirectionalLight(new THREE.Color(.95, .95, 1), options.directionalIntensity ?? 1.6);
+	sun.position.set(0, 1, -.5);
+	return [hemi, sun];
+}
+/** Create a group containing the default Stormworks-style lights. */
+function createSwLightGroup(options = {}) {
+	const group = new THREE.Group();
+	createSwLights(options).forEach((light) => {
+		group.add(light);
+	});
+	return group;
+}
+//#endregion
+//#region src/material/uniformController.ts
+const CREATE = Symbol("create");
+const ATTACH = Symbol("attach");
+const boolTransformer = {
+	toUniform: (v) => v ? 1 : 0,
+	fromUniform: (v) => v === 1
+};
+const colorVec3Transformer = {
+	toUniform: (v) => [
+		v.r / 255,
+		v.g / 255,
+		v.b / 255
+	],
+	fromUniform: (v) => Array.isArray(v) && v.length === 3 && v.every((v) => typeof v === "number") ? {
+		r: Math.round(v[0] * 255),
+		g: Math.round(v[1] * 255),
+		b: Math.round(v[2] * 255)
+	} : void 0
+};
+const colorVec4Transformer = {
+	toUniform: (v) => [
+		v.r / 255,
+		v.g / 255,
+		v.b / 255,
+		v.a !== void 0 ? v.a / 255 : 1
+	],
+	fromUniform: (v) => Array.isArray(v) && v.length === 4 && v.every((v) => typeof v === "number") ? {
+		r: Math.round(v[0] * 255),
+		g: Math.round(v[1] * 255),
+		b: Math.round(v[2] * 255),
+		a: Math.round(v[3] * 255)
+	} : void 0
+};
+/**
+* Manages shader uniforms for a material.
+*/
+var UniformController = class UniformController {
+	transformers;
+	pending = {};
+	shaderUniforms;
+	/** @hidden */
+	static [CREATE](transformers) {
+		return new UniformController(transformers);
+	}
+	constructor(transformers) {
+		this.transformers = transformers;
+	}
+	/** @hidden */
+	[ATTACH](shader) {
+		this.shaderUniforms = shader;
+		for (const key in this.pending) this.set(key, this.pending[key]);
+		this.pending = {};
+	}
+	/** Gets the value of a uniform. */
+	get(key) {
+		if (this.shaderUniforms) {
+			const entry = this.shaderUniforms[key];
+			if (entry === void 0) return;
+			return this.transformers[key].fromUniform(entry.value);
+		} else return this.pending[key];
+	}
+	/** Sets the value of a uniform. */
+	set(key, value) {
+		if (!this.shaderUniforms) {
+			this.pending[key] = value;
+			return;
+		}
+		const raw = this.transformers[key].toUniform(value);
+		const name = key;
+		if (this.shaderUniforms[name]) this.shaderUniforms[name].value = raw;
+		else this.shaderUniforms[name] = { value: raw };
+	}
+	/** Patches multiple uniforms at once. */
+	patch(values) {
+		for (const key in values) this.set(key, values[key]);
+	}
+};
+//#endregion
+//#region src/material/additive.ts
+/**
+* Create the default uniforms used for additive materials.
+*
+* An additive material can be created using {@link createAdditiveMaterial}.
+*
+* The default uniforms are:
+* - `overrideColorEnabled`: true
+* - `overrideColor`: white
+*
+* @example
+* ```ts
+* const additiveUniforms = createAdditiveUniforms({
+*  overrideColorEnabled: false
+* });
+*
+* const additiveMaterial = createAdditiveMaterial(additiveUniforms);
+* ```
+*/
+function createAdditiveUniforms(defaults = {}) {
+	const controller = UniformController[CREATE]({
+		overrideColorEnabled: boolTransformer,
+		overrideColor: colorVec4Transformer
+	});
+	controller.patch({
+		overrideColorEnabled: true,
+		overrideColor: WHITE,
+		...defaults
+	});
+	return controller;
+}
+/**
+* Create an additive material used for materialIndex 2 groups.
+*
+* If you want to use custom uniforms, you can create them using {@link createAdditiveUniforms} and pass them to this function.
+*
+* You can override the material parameters by passing a `THREE.MeshBasicMaterialParameters` object as the second argument.
+*
+* @returns A new `THREE.MeshBasicMaterial` with the specified uniforms, or a default one if not provided.
+*/
+function createAdditiveMaterial(uniforms, materialParameters) {
+	uniforms ??= createAdditiveUniforms();
+	const material = new THREE.MeshBasicMaterial({
+		vertexColors: true,
+		transparent: true,
+		blending: THREE.AdditiveBlending,
+		depthWrite: false,
+		...materialParameters
+	});
+	material.onBeforeCompile = (shader) => {
+		uniforms[ATTACH](shader.uniforms);
+		shader.vertexShader = shader.vertexShader.replace("#include <common>", `#include <common>
+uniform vec4 overrideColor;
+uniform int overrideColorEnabled;`).replace("#include <color_vertex>", `#include <color_vertex>
+if (overrideColorEnabled == 1)
+{
+  vColor.r = pow(overrideColor.r, 2.2);
+  vColor.g = pow(overrideColor.g, 2.2);
+  vColor.b = pow(overrideColor.b, 2.2);
+}`);
+	};
+	return material;
+}
+//#endregion
+//#region src/material/glass.ts
+const SKY_COLOR_UP = {
+	r: 0,
+	g: 61,
+	b: 182
+};
+const SKY_COLOR_DOWN = {
+	r: 139,
+	g: 210,
+	b: 207
+};
+const GLASS_VERTEX_SHADER = `
+out vec3 vWorldPosition;
+out vec3 vWorldNormal;
+
+void main() {
+  vec4 worldPosition = modelMatrix * vec4(position, 1.0);
+  vWorldPosition = worldPosition.xyz;
+  vWorldNormal = normalize(mat3(modelMatrix) * normal);
+
+  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+}
+`;
+const GLASS_FRAGMENT_SHADER = `
+uniform vec3 skyColorUp;
+uniform vec3 skyColorDown;
+
+in vec3 vWorldPosition;
+in vec3 vWorldNormal;
+
+void main() {
+  vec3 cameraToFragment = normalize(vWorldPosition - cameraPosition);
+  vec3 reflectedDir = reflect(cameraToFragment, normalize(vWorldNormal));
+
+  float reflectionFactor = max(0.0, -dot(vWorldNormal, cameraToFragment));
+  reflectionFactor = pow(1.0 - reflectionFactor, 5.0);
+  reflectionFactor = clamp(reflectionFactor, 0.0, 1.0);
+
+  float angleFactor = reflectedDir.y * 0.5 + 0.5;
+  vec3 skyColor = mix(skyColorDown.rgb, skyColorUp.rgb, angleFactor);
+
+  gl_FragColor = vec4(skyColor * reflectionFactor * 0.823, 0.0);
+}
+`;
+/**
+* Create the default uniforms used for glass materials.
+*
+* A glass material can be created using {@link createGlassMaterial}.
+*
+* The default uniforms are:
+* - `skyColorUp`: { r: 0, g: 61, b: 182 }
+* - `skyColorDown`: { r: 139, g: 210, b: 207 }
+*
+* @example
+* ```ts
+* const glassUniforms = createGlassUniforms({
+*  skyColorUp: { r: 0, g: 61, b: 182 },
+*  skyColorDown: { r: 139, g: 210, b: 207 }
+* });
+*
+* const glassMaterial = createGlassMaterial(glassUniforms);
+* ```
+*/
+function createGlassUniforms(defaults = {}) {
+	const controller = UniformController[CREATE]({
+		skyColorUp: colorVec3Transformer,
+		skyColorDown: colorVec3Transformer
+	});
+	controller.patch({
+		skyColorUp: SKY_COLOR_UP,
+		skyColorDown: SKY_COLOR_DOWN,
+		...defaults
+	});
+	return controller;
+}
+/**
+* Create the default glass material used for materialIndex 1 groups.
+*
+* If you want to use custom uniforms, you can create them using {@link createGlassUniforms} and pass them to this function.
+*
+* You can override the material parameters by passing a `THREE.ShaderMaterialParameters` object as the second argument.
+*
+* @returns A new `THREE.ShaderMaterial` with the specified uniforms, or a default one if not provided.
+*/
+function createGlassMaterial(uniforms, materialParameters) {
+	uniforms ??= createGlassUniforms();
+	const shaderUniforms = {};
+	uniforms[ATTACH](shaderUniforms);
+	return new THREE.ShaderMaterial({
+		vertexShader: GLASS_VERTEX_SHADER,
+		fragmentShader: GLASS_FRAGMENT_SHADER,
+		uniforms: shaderUniforms,
+		transparent: true,
+		depthWrite: false,
+		blending: THREE.CustomBlending,
+		blendSrc: THREE.OneFactor,
+		blendDst: THREE.OneMinusSrcAlphaFactor,
+		blendEquation: THREE.AddEquation,
+		...materialParameters
+	});
+}
+//#endregion
+//#region src/material/opaque.ts
+/**
+* Create the default uniforms used for opaque materials.
+*
+* An opaque material can be created using {@link createOpaqueMaterial}.
+*
+* The default uniforms are:
+* - `overrideColorEnabled`: true
+* - `overrideColor1`: white
+* - `overrideColor2`: white
+* - `overrideColor3`: white
+*
+* @example
+* ```ts
+* const opaqueUniforms = createOpaqueUniforms({
+*  overrideColorEnabled: false
+* });
+*
+* const opaqueMaterial = createOpaqueMaterial(opaqueUniforms);
+* ```
+*/
+function createOpaqueUniforms(defaults = {}) {
+	const controller = UniformController[CREATE]({
+		overrideColorEnabled: boolTransformer,
+		overrideColor1: colorVec4Transformer,
+		overrideColor2: colorVec4Transformer,
+		overrideColor3: colorVec4Transformer
+	});
+	controller.patch({
+		overrideColorEnabled: true,
+		overrideColor1: WHITE,
+		overrideColor2: WHITE,
+		overrideColor3: WHITE,
+		...defaults
+	});
+	return controller;
+}
+/**
+* Create the default opaque material used for materialIndex 0 groups.
+*
+* If you want to use custom uniforms, you can create them using {@link createOpaqueUniforms} and pass them to this function.
+*
+* You can override the material parameters by passing a `THREE.MeshStandardMaterialParameters` object as the second argument.
+*
+* @returns A new `THREE.MeshStandardMaterial` with the specified uniforms, or a default one if not provided.
+*/
+function createOpaqueMaterial(uniforms, materialParameters) {
+	uniforms ??= createOpaqueUniforms();
+	const material = new THREE.MeshStandardMaterial({
+		vertexColors: true,
+		roughness: 1,
+		metalness: 0,
+		...materialParameters
+	});
+	material.onBeforeCompile = (shader) => {
+		uniforms[ATTACH](shader.uniforms);
+		shader.vertexShader = shader.vertexShader.replace("#include <common>", `#include <common>
+uniform vec4 overrideColor1;
+uniform vec4 overrideColor2;
+uniform vec4 overrideColor3;
+uniform int overrideColorEnabled;`).replace("#include <color_vertex>", `#ifdef USE_COLOR
+vColor.xyz = color.xyz;
+if (overrideColorEnabled == 1) {
+  if (distance(color.rgb, vec3(1.0, 0.494, 0.0)) < 0.01) vColor = overrideColor1;
+  else if (distance(color.rgb, vec3(0.608, 0.494, 0.0)) < 0.01) vColor = overrideColor2;
+  else if (distance(color.rgb, vec3(0.216, 0.494, 0.0)) < 0.01) vColor = overrideColor3;
+}
+vColor.rgb = pow(vColor.rgb, vec3(2.2));
+#endif`);
+		shader.fragmentShader = shader.fragmentShader.replace("#include <aomap_fragment>", `#include <aomap_fragment>
+float dist = length(vViewPosition);
+float incidence = max(dot(geometryNormal, geometryViewDir), 0.0);
+float distanceFactor = 0.05 * (1.0 / max(0.01, dist) - 1.0 / 100.0);
+reflectedLight.directDiffuse += diffuseColor.rgb * incidence * distanceFactor * 16.0;`);
+	};
+	return material;
+}
+//#endregion
+//#region src/material/materials.ts
+/**
+* Create the default materials used by Stormworks object helpers.
+*
+* A new material set has independent uniform stores, making it suitable for
+* object-local color and shader state. Share the returned set only when objects
+* should intentionally share uniform updates.
+*/
+function createSwMaterials(options = {}) {
+	const opaqueUniforms = createOpaqueUniforms(options.uniforms?.opaque);
+	const glassUniforms = createGlassUniforms(options.uniforms?.glass);
+	const additiveUniforms = createAdditiveUniforms(options.uniforms?.additive);
+	return {
+		opaque: createOpaqueMaterial(opaqueUniforms),
+		glass: createGlassMaterial(glassUniforms),
+		additive: createAdditiveMaterial(additiveUniforms),
+		uniforms: {
+			opaque: opaqueUniforms,
+			glass: glassUniforms,
+			additive: additiveUniforms
+		}
+	};
+}
+//#endregion
+//#region src/mesh.ts
+/**
+* Create a renderable Three.js mesh from parsed Stormworks `mesh` data.
+*
+* The returned mesh owns its geometry. It uses material groups mapped from the
+* file's group shader ids: opaque, glass, and additive.
+*/
+function createSwMesh(mesh, options = {}) {
+	const geometry = createSwMeshGeometry(mesh);
+	const materials = options.materials ?? createSwMaterials();
+	const object = new THREE.Mesh(geometry, [
+		materials.opaque,
+		materials.glass,
+		materials.additive
+	]);
+	object.name = options.name ?? "";
+	return object;
+}
+/**
+* Create a Three.js group from parsed Stormworks `phys` data.
+*
+* Each physics section becomes a child mesh using the `phys` material from the
+* supplied material set.
+*/
+function createSwPhysMeshGroup(mesh, material, options = {}) {
+	const group = new THREE.Group();
+	mesh.groups.forEach((g) => {
+		const geometry = createSwPhysGroupGeometry(g);
+		group.add(new THREE.Mesh(geometry, material));
+	});
+	group.name = options.name ?? "";
+	return group;
+}
+/**
+* Create buffer geometry for parsed Stormworks render mesh data.
+*
+* The geometry includes `position`, `normal`, and `color` attributes, and material groups derived from group shader ids.
+*/
+function createSwMeshGeometry(mesh) {
+	const geometry = new THREE.BufferGeometry();
+	const positions = new Float32Array(mesh.vertices.length * 3);
+	const normals = new Float32Array(mesh.vertices.length * 3);
+	const colors = new Float32Array(mesh.vertices.length * 4);
+	mesh.vertices.forEach((vertex, index) => {
+		const offset3 = index * 3;
+		const offset4 = index * 4;
+		positions[offset3] = vertex.position.x;
+		positions[offset3 + 1] = vertex.position.y;
+		positions[offset3 + 2] = -vertex.position.z;
+		normals[offset3] = vertex.normal.x;
+		normals[offset3 + 1] = vertex.normal.y;
+		normals[offset3 + 2] = -vertex.normal.z;
+		colors[offset4] = vertex.color.r / 255;
+		colors[offset4 + 1] = vertex.color.g / 255;
+		colors[offset4 + 2] = vertex.color.b / 255;
+		colors[offset4 + 3] = vertex.color.a !== void 0 ? vertex.color.a / 255 : 1;
+	});
+	geometry.setAttribute("position", new THREE.BufferAttribute(positions, 3));
+	geometry.setAttribute("normal", new THREE.BufferAttribute(normals, 3));
+	geometry.setAttribute("color", new THREE.BufferAttribute(colors, 4));
+	geometry.setIndex(mesh.indices);
+	setGroups(geometry, mesh);
+	geometry.computeBoundingSphere();
+	return geometry;
+}
+/**
+* Create buffer geometry for parsed Stormworks phys group.
+*
+* The geometry includes `position` attributes.
+*/
+function createSwPhysGroupGeometry(physGroup) {
+	const geometry = new THREE.BufferGeometry();
+	const positions = new Float32Array(physGroup.vertices.length * 3);
+	physGroup.vertices.forEach((vertex, index) => {
+		const offset = index * 3;
+		positions[offset] = vertex.x;
+		positions[offset + 1] = vertex.y;
+		positions[offset + 2] = -vertex.z;
+	});
+	geometry.setAttribute("position", new THREE.BufferAttribute(positions, 3));
+	geometry.setIndex(physGroup.indices.length > 0 ? physGroup.indices : createFallbackTriangleIndices(physGroup.vertices.length));
+	geometry.computeVertexNormals();
+	geometry.computeBoundingSphere();
+	return geometry;
+}
+function createFallbackTriangleIndices(vertexCount) {
+	return Array.from({ length: vertexCount }, (_, index) => index);
+}
+function setGroups(geometry, mesh) {
+	geometry.clearGroups();
+	if (mesh.groups.length === 0) {
+		geometry.addGroup(0, mesh.indices.length, 0);
+		return;
+	}
+	mesh.groups.forEach((g) => {
+		geometry.addGroup(g.indexBufferStart, g.indexBufferLength, g.materialIndex);
+	});
+}
+//#endregion
+//#region src/vehicleAssembler/assetResolver.ts
+/**
+* Creates a {@link VehicleAssetResolver} from raw asset providers.
+*
+* The returned resolver automatically parses XML component definitions,
+* converts Stormworks mesh files into `THREE.BufferGeometry`, and
+* caches the results so each asset is loaded and parsed at most once.
+*
+* This is the recommended way to construct a resolver for {@link VehicleBodyAssembler}.
+*
+* @param getComponentDefinitionFile Returns the XML source of a component
+* definition.
+* @param getMeshFile Returns the binary contents of a Stormworks mesh file.
+* @returns A cached asset resolver.
+*/
+function createVehicleAssetResolver(getComponentDefinitionFile, getMeshFile) {
+	return {
+		resolveComponentDefinition: withCache(async (componentId) => {
+			const data = await getComponentDefinitionFile(componentId ?? "01_block");
+			if (!data) return void 0;
+			return parseComponentDefinitionXml(data);
+		}),
+		resolveMesh: withCache(async (meshPath) => {
+			const data = await getMeshFile(meshPath);
+			if (!data) return void 0;
+			return createSwMeshGeometry(parseMesh(data));
+		})
+	};
+}
+/**
+* Wraps an asynchronous resolver with memoization.
+*
+* The returned function caches both completed results and in-flight promises,
+* ensuring that concurrent requests for the same key share a single operation.
+*
+* @param resolver The resolver to memoize.
+* @returns A cached resolver.
+*/
+function withCache(resolver) {
+	const cache = /* @__PURE__ */ new Map();
+	return (key) => {
+		let value = cache.get(key);
+		if (!value) {
+			value = Promise.resolve(resolver(key));
+			cache.set(key, value);
+		}
+		return value;
+	};
+}
+//#endregion
+//#region src/internal/index.ts
+function stormworksToThreeMatrix4(rot, pos, posScale = 1) {
+	return new THREE.Matrix4().set(rot[0], rot[1], -rot[2], pos.x * posScale, rot[3], rot[4], -rot[5], pos.y * posScale, -rot[6], -rot[7], rot[8], -pos.z * posScale, 0, 0, 0, 1);
+}
+//#endregion
+//#region src/vehicleAssembler/utils.ts
+const ADDITIVE_LUT = new Uint8Array([
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	13,
+	25,
+	35,
+	47,
+	57,
+	66,
+	75,
+	85,
+	93,
+	99,
+	106,
+	113,
+	119,
+	126,
+	130,
+	136,
+	141,
+	145,
+	150,
+	154,
+	158,
+	161,
+	164,
+	168,
+	171,
+	174,
+	177,
+	179,
+	182,
+	184,
+	186,
+	188,
+	191,
+	193,
+	194,
+	196,
+	198,
+	200,
+	201,
+	202,
+	203,
+	204,
+	207,
+	208,
+	209,
+	210,
+	211,
+	211,
+	212,
+	214,
+	215,
+	216,
+	217,
+	217,
+	218,
+	219,
+	219,
+	220,
+	220,
+	222,
+	223,
+	223,
+	224,
+	224,
+	225,
+	225,
+	226,
+	226,
+	227,
+	227,
+	228,
+	228,
+	228,
+	230,
+	230,
+	230,
+	231,
+	231,
+	231,
+	232,
+	232,
+	232,
+	233,
+	233,
+	233,
+	234,
+	234,
+	234,
+	234,
+	235,
+	235,
+	235,
+	235,
+	236,
+	236,
+	236,
+	236,
+	236,
+	238,
+	238,
+	238,
+	238,
+	238,
+	239,
+	239,
+	239,
+	239,
+	239,
+	240,
+	240,
+	240,
+	240,
+	240,
+	240,
+	240,
+	241,
+	241,
+	241,
+	241,
+	241,
+	241,
+	241,
+	242,
+	242,
+	242,
+	242,
+	242,
+	242,
+	242,
+	242,
+	243,
+	243,
+	243,
+	243,
+	243,
+	243,
+	243,
+	243,
+	243,
+	244,
+	244,
+	244,
+	244,
+	244,
+	244,
+	244,
+	244,
+	244,
+	244,
+	244,
+	244,
+	246,
+	246,
+	246,
+	246,
+	246,
+	246,
+	246,
+	246,
+	246,
+	246,
+	246,
+	246,
+	246,
+	247,
+	247,
+	247,
+	247,
+	247,
+	247,
+	247,
+	247,
+	247,
+	247,
+	247,
+	247,
+	247,
+	247,
+	247,
+	247,
+	248,
+	248,
+	248,
+	248,
+	248,
+	248,
+	248,
+	248,
+	248,
+	248,
+	248,
+	248,
+	248,
+	248,
+	248,
+	248,
+	248,
+	248,
+	248,
+	248,
+	249,
+	249,
+	249,
+	249,
+	249,
+	249,
+	249,
+	249,
+	249,
+	249,
+	249,
+	249,
+	249,
+	249,
+	249,
+	249,
+	249,
+	249,
+	249,
+	249,
+	249,
+	249,
+	249
+]);
+function createMaterialsForComponent(component) {
+	const materials = createSwMaterials();
+	const bc = component.o?.bc ? parseColor(component.o.bc) : void 0;
+	const bc2 = component.o?.bc2 ? parseColor(component.o.bc2) : bc;
+	const bc3 = component.o?.bc3 ? parseColor(component.o.bc3) : bc;
+	if (bc) materials.uniforms.opaque.set("overrideColor1", bc);
+	if (bc2) materials.uniforms.opaque.set("overrideColor2", bc2);
+	if (bc3) materials.uniforms.opaque.set("overrideColor3", bc3);
+	materials.uniforms.opaque.set("overrideColorEnabled", true);
+	const ac = component.o?.ac ? parseColor(component.o.ac) : void 0;
+	if (ac) materials.uniforms.additive.set("overrideColor", ac);
+	materials.uniforms.additive.set("overrideColorEnabled", true);
+	return {
+		materials,
+		materialArr: [
+			materials.opaque,
+			materials.glass,
+			materials.additive
+		]
+	};
+}
+function combineGeometries(geometries, material) {
+	const group = new THREE.Group();
+	for (const geometry of geometries) if (geometry) group.add(new THREE.Mesh(geometry, material));
+	return group;
+}
+//#endregion
+//#region src/vehicleAssembler/specialComponents/microcontroller.ts
+const MICROCONTROLLER_CORNER_MESH = "meshes/component_microprocessor_corner.mesh";
+const MICROCONTROLLER_EDGE_MESH = "meshes/component_microprocessor_edge.mesh";
+const MICROCONTROLLER_TOP_MESH = "meshes/component_microprocessor_top.mesh";
+const MICROCONTROLLER_TOP_CORNER_MESH = "meshes/component_microprocessor_top_corner.mesh";
+const MICROCONTROLLER_TOP_EDGE_MESH = "meshes/component_microprocessor_top_edge.mesh";
+async function assembleMicrocontroller(componentInstance, assets) {
+	const microcontroller = componentInstance.o?.microprocessor_definition;
+	if (!microcontroller) return;
+	const width = microcontroller.width ?? 0;
+	const length = microcontroller.length ?? 0;
+	if (width <= 0 || length <= 0) return;
+	const cornerX = .25 * (width - 1);
+	const cornerZ = -.25 * (length - 1);
+	const surfaces = [];
+	for (let x = 0; x < width; x++) for (let z = 0; z < length; z++) {
+		surfaces.push({
+			orientation: 3,
+			shape: 1,
+			position: {
+				x,
+				y: 0,
+				z
+			}
+		});
+		surfaces.push({
+			orientation: 2,
+			shape: 0,
+			position: {
+				x,
+				y: 0,
+				z
+			}
+		});
+	}
+	for (let x = 0; x < width; x++) {
+		surfaces.push({
+			orientation: 5,
+			shape: 0,
+			position: {
+				x,
+				y: 0,
+				z: 0
+			}
+		});
+		surfaces.push({
+			orientation: 4,
+			shape: 0,
+			position: {
+				x,
+				y: 0,
+				z: length - 1
+			}
+		});
+	}
+	for (let z = 0; z < length; z++) {
+		surfaces.push({
+			orientation: 1,
+			shape: 0,
+			position: {
+				x: 0,
+				y: 0,
+				z
+			}
+		});
+		surfaces.push({
+			orientation: 0,
+			shape: 0,
+			position: {
+				x: width - 1,
+				y: 0,
+				z
+			}
+		});
+	}
+	const { materialArr } = createMaterialsForComponent(componentInstance);
+	const group = new THREE.Group();
+	const cornerMesh = await assets.resolveMesh(MICROCONTROLLER_CORNER_MESH);
+	const topCornerMesh = await assets.resolveMesh(MICROCONTROLLER_TOP_CORNER_MESH);
+	if (cornerMesh || topCornerMesh) {
+		const corner1 = combineGeometries([cornerMesh, topCornerMesh], materialArr);
+		const corner2 = corner1.clone();
+		const corner3 = corner1.clone();
+		const corner4 = corner1.clone();
+		corner2.rotation.y = Math.PI / 2;
+		corner3.rotation.y = -Math.PI / 2;
+		corner4.rotation.y = Math.PI;
+		corner2.position.x = cornerX;
+		corner3.position.z = cornerZ;
+		corner4.position.x = cornerX;
+		corner4.position.z = cornerZ;
+		group.add(corner1);
+		group.add(corner2);
+		group.add(corner3);
+		group.add(corner4);
+	}
+	const edgeMesh = await assets.resolveMesh(MICROCONTROLLER_EDGE_MESH);
+	const topEdgeMesh = await assets.resolveMesh(MICROCONTROLLER_TOP_EDGE_MESH);
+	if (edgeMesh || topEdgeMesh) {
+		const edge = combineGeometries([edgeMesh, topEdgeMesh], materialArr);
+		for (let x = 0; x < width - 1; x++) {
+			const edge1 = edge.clone();
+			const edge2 = edge.clone();
+			edge2.rotation.y = Math.PI;
+			edge1.position.x = .25 * x + .125;
+			edge2.position.x = .25 * x + .125;
+			edge2.position.z = cornerZ;
+			group.add(edge1);
+			group.add(edge2);
+		}
+		for (let z = 0; z < length - 1; z++) {
+			const edge1 = edge.clone();
+			const edge2 = edge.clone();
+			edge1.rotation.y = -Math.PI / 2;
+			edge2.rotation.y = Math.PI / 2;
+			edge1.position.z = -(.25 * z + .125);
+			edge2.position.z = -(.25 * z + .125);
+			edge2.position.x = cornerX;
+			group.add(edge1);
+			group.add(edge2);
+		}
+	}
+	const topMesh = await assets.resolveMesh(MICROCONTROLLER_TOP_MESH);
+	if (topMesh) for (let x = 0; x < width - 1; x++) for (let z = 0; z < length - 1; z++) {
+		const top = new THREE.Mesh(topMesh, materialArr);
+		top.position.x = .25 * x + .125;
+		top.position.z = -(.25 * z + .125);
+		group.add(top);
+	}
+	return {
+		surfaces,
+		objects: [group]
+	};
+}
+//#endregion
+//#region src/vehicleAssembler/specialComponents/paintableSign.ts
+async function assemblePaintableSign(componentInstance, definition) {
+	const isNoAdditive = ((definition.flags ?? 0) >> 22 & 1) !== 0;
+	let paintableSurface = false;
+	const surfaces = definition.surfaces?.map((surface) => {
+		if (surface.orientation === 2 && (surface.position?.x ?? 0) === 0 && (surface.position?.y ?? 0) === 0 && (surface.position?.z ?? 0) === 0) {
+			paintableSurface = true;
+			return {
+				...surface,
+				shape: 0
+			};
+		}
+		return surface;
+	});
+	if (!paintableSurface) return surfaces ? { surfaces } : {};
+	const objects = [];
+	const geom1 = createPixelGeometry(componentInstance.o?.gc?.split(",").map((c) => parseColor(c)) ?? [], .125);
+	const opaqueMaterial = createOpaqueMaterial(createOpaqueUniforms({ overrideColorEnabled: false }));
+	objects.push(new THREE.Mesh(geom1, opaqueMaterial));
+	if (!isNoAdditive) {
+		const geom2 = createPixelGeometry(componentInstance.o?.gca?.split(",").map((c) => parseColor(c)) ?? [], .125, true);
+		const additiveMaterial = createAdditiveMaterial(createAdditiveUniforms({ overrideColorEnabled: false }));
+		objects.push(new THREE.Mesh(geom2, additiveMaterial));
+	}
+	return {
+		surfaces,
+		objects
+	};
+}
+function createPixelGeometry(data, y = 0, isAdditive = false) {
+	const positions = [];
+	const normals = [];
+	const colors = [];
+	const indices = [];
+	for (let z = 0; z < 9; z++) for (let x = 0; x < 9; x++) {
+		const intColor = data[z * 9 + x] ?? {
+			r: 255,
+			g: 255,
+			b: 255
+		};
+		const x1 = .25 * (x / 9) - .125;
+		const x2 = .25 * ((x + 1) / 9) - .125;
+		const z1 = -.25 * (z / 9) + .125;
+		const z2 = -.25 * ((z + 1) / 9) + .125;
+		positions.push(x1, y, z1);
+		positions.push(x2, y, z1);
+		positions.push(x2, y, z2);
+		positions.push(x1, y, z2);
+		for (let i = 0; i < 4; i++) {
+			normals.push(0, 1, 0);
+			colors.push(convertSignColor(intColor.r, isAdditive), convertSignColor(intColor.g, isAdditive), convertSignColor(intColor.b, isAdditive));
+		}
+		const i0 = (z * 9 + x) * 4;
+		const i1 = i0 + 1;
+		const i2 = i0 + 2;
+		const i3 = i0 + 3;
+		indices.push(i0, i1, i2);
+		indices.push(i0, i2, i3);
+	}
+	const geometry = new THREE.BufferGeometry();
+	geometry.setAttribute("position", new THREE.Float32BufferAttribute(positions, 3));
+	geometry.setAttribute("normal", new THREE.Float32BufferAttribute(normals, 3));
+	geometry.setAttribute("color", new THREE.Float32BufferAttribute(colors, 3));
+	geometry.setIndex(indices);
+	return geometry;
+}
+function convertSignColor(value, isAdditive) {
+	value = Math.min(Math.max(Math.round(value), 0), 255);
+	if (isAdditive) return Math.pow((ADDITIVE_LUT[value] ?? 0) / 255, 2.2);
+	else return value / 255;
+}
+//#endregion
+//#region src/vehicleAssembler/bodyAssembler.ts
+/** The names of the mesh reference attributes in the component definition XML. */
+const MESH_ATTRIBUTE_NAMES = [
+	"mesh_data_name",
+	"mesh_0_name",
+	"mesh_1_name",
+	"mesh_2_name"
+];
+/**
+* Assembles a single Stormworks vehicle body into Three.js objects.
+*
+* The assembler collects component geometry and meshes, then produces one
+* `THREE.Group` containing a culled surface mesh and any additional meshes.
+*
+* A single instance should be used for one vehicle body.
+*
+* The primary methods most applications should call are {@link appendComponent} and {@link build}.
+*
+* @example
+* ```ts
+* import * as THREE from "three";
+* import { parseVehicleXml } from "@sw-file-lib/xml";
+* import { createVehicleAssetResolver, VehicleBodyAssembler } from "@sw-file-lib/three";
+*
+* const assetResolver = createVehicleAssetResolver(
+*   (componentId) =>
+*     fetch(`/rom/data/definitions/${componentId}.xml`)
+*     .then((res) => res.ok ? res.text() : undefined),
+*   (meshPath) =>
+*     fetch(`/rom/${meshPath}`)
+*     .then((res) => res.ok ? res.arrayBuffer() : undefined)
+* );
+*
+* const vehicle = parseVehicleXml(text);
+* const vehicleGroup = new THREE.Group();
+*
+* for (const body of vehicle.bodies ?? []) {
+*   const assembler = new VehicleBodyAssembler(assetResolver);
+*   for (const component of body.components ?? []) {
+*     await assembler.appendComponent(component);
+*   }
+*
+*   const obj = assembler.build();
+*   vehicleGroup.add(obj);
+* }
+*
+* scene.add(vehicleGroup);
+* ```
+*/
+var VehicleBodyAssembler = class {
+	assets;
+	surfaces = [];
+	groups = [];
+	/**
+	* Creates a new body assembler.
+	*
+	* @param assets Callbacks used to resolve component definitions and mesh assets.
+	* Create a resolver with {@link createVehicleAssetResolver}, or make your own.
+	* Wrapping them with a cache is recommended when loading from disk or over the network.
+	*/
+	constructor(assets) {
+		this.assets = assets;
+	}
+	/**
+	* Appends a component to the body.
+	*
+	* The component type is detected automatically, and the appropriate builder
+	* is used internally. This is the primary method most applications should call.
+	*
+	* @param componentInstance The component instance from the vehicle body.
+	* Represented by a `<c>` element in the vehicle XML.
+	*/
+	async appendComponent(componentInstance) {
+		const definition = await this.assets.resolveComponentDefinition(componentInstance.d);
+		if (!definition) return;
+		switch (definition.type) {
+			case 28: return await this.appendPaintableSign(componentInstance, definition);
+			case 37: return await this.appendMicrocontroller(componentInstance);
+		}
+		return await this.appendStandardComponent(componentInstance, definition);
+	}
+	/**
+	* Appends surfaces and prebuilt objects to the body.
+	*
+	* This is a low-level API intended for custom or unsupported components.
+	* All surfaces and objects must be provided in the component's local
+	* coordinate system; they will be transformed into body space automatically.
+	*
+	* @param componentInstance The component instance from the vehicle body.
+	* Represented by a `<c>` element in the vehicle XML.
+	* @param surfaceDefinitions Surface definitions in local space.
+	* @param objects Additional Three.js objects in local space.
+	*/
+	appendRawComponent(componentInstance, surfaceDefinitions, objects) {
+		const componentPosition = vec3(componentInstance.o?.vp);
+		let componentMatrix = [
+			0,
+			0,
+			1,
+			-1,
+			0,
+			0,
+			0,
+			-1,
+			0
+		];
+		if (componentInstance.o?.r !== void 0) componentMatrix = parseMat3(componentInstance.o.r) ?? componentMatrix;
+		componentMatrix = transposeMat3(componentMatrix);
+		if (componentInstance.t !== void 0) {
+			if ((componentInstance.t & 1) !== 0) componentMatrix = mulMat3(componentMatrix, Orientation.FlipX.toMat3());
+			if ((componentInstance.t & 2) !== 0) componentMatrix = mulMat3(componentMatrix, Orientation.FlipY.toMat3());
+			if ((componentInstance.t & 4) !== 0) componentMatrix = mulMat3(componentMatrix, Orientation.FlipZ.toMat3());
+		}
+		const blockColor = parseColor(componentInstance.o?.bc ?? "x", {
+			r: 255,
+			g: 255,
+			b: 255
+		});
+		const surfaceColors = componentInstance.o?.sc?.split(",").slice(1).map((c) => parseColor(c)) ?? [];
+		for (const [index, surface] of (surfaceDefinitions ?? []).entries()) {
+			const orientation = surface.orientation ?? 0;
+			const rotation = surface.rotation ?? 0;
+			const shape = surface.shape ?? 0;
+			if (!isValidSurfaceOrientation(orientation)) continue;
+			if (!isValidSurfaceRotation(rotation)) continue;
+			const localPosition = vec3(surface.position);
+			const position = addVec3(componentMatrix ? mulMat3Vec3(componentMatrix, localPosition) : localPosition, componentPosition);
+			let matrix = getSurfaceOrientation(orientation, rotation).toMat3();
+			if (componentMatrix) matrix = mulMat3(componentMatrix, matrix);
+			this.surfaces.push({
+				position,
+				matrix,
+				shape,
+				color: surfaceColors[index] ?? blockColor
+			});
+		}
+		if (objects && objects.length > 0) {
+			const group = new THREE.Group();
+			for (const meshObject of objects) group.add(meshObject);
+			group.matrixAutoUpdate = false;
+			group.matrix.copy(stormworksToThreeMatrix4(componentMatrix, componentPosition, .25));
+			this.groups.push(group);
+		}
+	}
+	/**
+	* Appends a standard component using its component definition.
+	*
+	* This resolves surface definitions and any required mesh assets, transforms
+	* them into world space, and adds them to the current body.
+	*
+	* Most users should prefer {@link appendComponent}, which performs type
+	* detection automatically.
+	*
+	* @param componentInstance The component instance from the vehicle body.
+	* Represented by a `<c>` element in the vehicle XML.
+	* @param definition The component definition for the component instance.
+	* @param meshesToExclude Optional list of mesh attributes to ignore.
+	*/
+	async appendStandardComponent(componentInstance, definition, meshesToExclude) {
+		const { materialArr } = createMaterialsForComponent(componentInstance);
+		const meshes = [];
+		for (const meshAttributeName of MESH_ATTRIBUTE_NAMES) {
+			if (meshesToExclude?.includes(meshAttributeName) || !definition?.[meshAttributeName]) continue;
+			const geometry = await this.assets.resolveMesh(definition[meshAttributeName]);
+			if (!geometry) continue;
+			meshes.push(new THREE.Mesh(geometry, materialArr));
+		}
+		this.appendRawComponent(componentInstance, definition?.surfaces, meshes);
+	}
+	/**
+	* Appends a paintable sign component.
+	*
+	* Paintable signs generate their geometry dynamically from the component
+	* properties and do not use a predefined mesh asset.
+	*
+	* @param componentInstance The component instance from the vehicle body.
+	* Represented by a `<c>` element in the vehicle XML.
+	* @param definition The component definition for the component instance.
+	*/
+	async appendPaintableSign(componentInstance, definition) {
+		const result = await assemblePaintableSign(componentInstance, definition);
+		if (!result) return;
+		this.appendRawComponent(componentInstance, result.surfaces, result.objects);
+	}
+	/**
+	* Appends a microcontroller component.
+	*
+	* Microcontrollers have variable dimensions and therefore generate their
+	* surfaces and meshes procedurally instead of using a fixed definition.
+	*
+	* @param componentInstance The component instance from the vehicle body.
+	* Represented by a `<c>` element in the vehicle XML.
+	*/
+	async appendMicrocontroller(componentInstance) {
+		const result = await assembleMicrocontroller(componentInstance, this.assets);
+		if (!result) return;
+		this.appendRawComponent(componentInstance, result.surfaces, result.objects);
+	}
+	/**
+	* Builds the merged surface mesh for this body using {@link GeometryBuilder}.
+	*
+	* Surface culling is performed before constructing geometry unless explicitly disabled by the options.
+	* The returned geometry does not include any additional meshes.
+	*
+	* @see {@link build} for the complete object including additional meshes.
+	*/
+	buildSurfaceMesh(options) {
+		return buildSurfacesGeometry(this.surfaces, options);
+	}
+	/**
+	* Builds the final Three.js object representing this vehicle body.
+	*
+	* The returned group contains the merged surface mesh together with every
+	* additional mesh appended during assembly.
+	*
+	* @returns A complete Three.js group for the body.
+	*/
+	build(surfaceOptions) {
+		const group = new THREE.Group();
+		const surfaceGeometry = bufferGeometryFromBuilder(this.buildSurfaceMesh(surfaceOptions));
+		const surfaceMaterial = createOpaqueMaterial(createOpaqueUniforms({ overrideColorEnabled: false }));
+		const surfaceMesh = new THREE.Mesh(surfaceGeometry, surfaceMaterial);
+		group.add(surfaceMesh);
+		for (const childGroup of this.groups) group.add(childGroup);
+		return group;
+	}
+};
+//#endregion
+export { MESH_ATTRIBUTE_NAMES, UniformController, VehicleBodyAssembler, applyBuilderOnBufferGeometry, bufferGeometryFromBuilder, createAdditiveMaterial, createAdditiveUniforms, createGlassMaterial, createGlassUniforms, createOpaqueMaterial, createOpaqueUniforms, createSwLightGroup, createSwLights, createSwMaterials, createSwMesh, createSwMeshGeometry, createSwPhysGroupGeometry, createSwPhysMeshGroup, createVehicleAssetResolver, withCache };