@dice-o-rolla/dice-assets 0.2.0

package/dist/asset-registry.js

@@ -0,0 +1,203 @@
+const ASSET_ID_PATTERN = /^[a-z0-9][a-z0-9._:-]*$/i;
+function assertId(value) {
+    if (!ASSET_ID_PATTERN.test(value)) {
+        throw new RangeError('asset id must be a non-empty portable identifier');
+    }
+}
+function immutable(source) {
+    assertId(source.id);
+    return deepFreeze(structuredClone(source));
+}
+function deepFreeze(value) {
+    if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+        for (const child of Object.values(value))
+            deepFreeze(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+export class AssetRegistry {
+    #assets = new Map();
+    #validate;
+    #revision = 0;
+    constructor(validate = () => undefined) {
+        this.#validate = validate;
+    }
+    get revision() {
+        return this.#revision;
+    }
+    register(source, options = {}) {
+        const asset = immutable(source);
+        this.#validate(asset);
+        if (this.#assets.has(asset.id) && options.replace !== true) {
+            throw new Error(`Dice asset "${asset.id}" is already registered`);
+        }
+        this.#assets.set(asset.id, asset);
+        this.#revision += 1;
+        return asset;
+    }
+    unregister(id) {
+        const asset = this.#assets.get(id);
+        if (asset === undefined)
+            return undefined;
+        this.#assets.delete(id);
+        this.#revision += 1;
+        return asset;
+    }
+    get(id) {
+        return this.#assets.get(id);
+    }
+    has(id) {
+        return this.#assets.has(id);
+    }
+    list() {
+        return Object.freeze(Array.from(this.#assets.values()));
+    }
+}
+export class DiceAssetRegistry {
+    audio = new AssetRegistry(validateAudioSprite);
+    audioBanks = new AssetRegistry(validateAudioBank);
+    materials = new AssetRegistry(validateMaterial);
+    patterns = new AssetRegistry(validatePattern);
+    skins = new AssetRegistry(validateSkin);
+    faces = new AssetRegistry(validateFaceAtlas);
+    get revision() {
+        return (this.audio.revision +
+            this.audioBanks.revision +
+            this.materials.revision +
+            this.patterns.revision +
+            this.skins.revision +
+            this.faces.revision);
+    }
+    registerCatalog(catalog) {
+        if (catalog.schemaVersion !== 1)
+            throw new RangeError('unsupported asset catalog schema');
+        for (const asset of catalog.audioSprites ?? [])
+            this.audio.register(asset);
+        for (const asset of catalog.audioBanks ?? [])
+            this.audioBanks.register(asset);
+        for (const asset of catalog.materials ?? [])
+            this.materials.register(asset);
+        for (const asset of catalog.patterns ?? [])
+            this.patterns.register(asset);
+        for (const asset of catalog.faces ?? [])
+            this.faces.register(asset);
+        for (const asset of catalog.skins ?? [])
+            this.skins.register(asset);
+        this.validateReferences();
+    }
+    validateReferences() {
+        for (const bank of this.audioBanks.list()) {
+            const sprite = this.audio.get(bank.spriteId);
+            if (sprite === undefined)
+                throw new Error(`Audio bank "${bank.id}" references missing sprite`);
+            for (const clipId of bank.clipIds) {
+                if (sprite.clips[clipId] === undefined) {
+                    throw new Error(`Audio bank "${bank.id}" references missing clip "${clipId}"`);
+                }
+            }
+            assertRange(bank.forceRange, 'forceRange');
+            assertRange(bank.gainRange, 'gainRange');
+        }
+        for (const skin of this.skins.list()) {
+            if (!this.materials.has(skin.materialId)) {
+                throw new Error(`Skin "${skin.id}" references missing material`);
+            }
+            if (!this.patterns.has(skin.patternId)) {
+                throw new Error(`Skin "${skin.id}" references missing pattern`);
+            }
+            if (skin.faceAtlasId !== undefined && !this.faces.has(skin.faceAtlasId)) {
+                throw new Error(`Skin "${skin.id}" references missing face atlas`);
+            }
+        }
+    }
+    registerSkin(source, options) {
+        return this.skins.register(source, options);
+    }
+    unregisterSkin(id) {
+        return this.skins.unregister(id);
+    }
+    getSkin(id) {
+        return this.skins.get(id);
+    }
+    listSkins() {
+        return this.skins.list();
+    }
+}
+function assertRange(range, name) {
+    if (!range.every(Number.isFinite) || range[0] < 0 || range[1] <= range[0]) {
+        throw new RangeError(`${name} must be a finite ascending non-negative range`);
+    }
+}
+function validateReference(reference, name) {
+    if (reference.uri.trim().length === 0)
+        throw new RangeError(`${name} uri must not be empty`);
+}
+function validateTexture(texture, name) {
+    validateReference(texture, name);
+    if (texture.mediaType !== 'image/ktx2' || !texture.mipmaps) {
+        throw new RangeError(`${name} must be a mipmapped KTX2 texture`);
+    }
+}
+function validateAudioSprite(sprite) {
+    validateReference(sprite.audio, 'audio sprite');
+    if (sprite.channels !== 1)
+        throw new RangeError('runtime audio sprites must be mono');
+    if (Object.keys(sprite.clips).length === 0)
+        throw new RangeError('audio sprite must contain clips');
+    for (const [id, clip] of Object.entries(sprite.clips)) {
+        assertId(id);
+        if (!Number.isFinite(clip.offsetSeconds) ||
+            clip.offsetSeconds < 0 ||
+            !Number.isFinite(clip.durationSeconds) ||
+            clip.durationSeconds <= 0) {
+            throw new RangeError('audio sprite clip timing must be finite and non-negative');
+        }
+    }
+}
+function validateAudioBank(bank) {
+    assertId(bank.spriteId);
+    if (bank.clipIds.length === 0)
+        throw new RangeError('audio bank must contain clip ids');
+    for (const id of bank.clipIds)
+        assertId(id);
+    assertRange(bank.forceRange, 'forceRange');
+    assertRange(bank.gainRange, 'gainRange');
+    if ((bank.pitchVariationCents ?? 0) < 0 || (bank.gainVariation ?? 0) < 0) {
+        throw new RangeError('audio variation must not be negative');
+    }
+}
+function validateMaterial(material) {
+    for (const [name, value] of [
+        ['roughness', material.roughness],
+        ['metalness', material.metalness],
+    ]) {
+        if (!Number.isFinite(value) || value < 0 || value > 1)
+            throw new RangeError(`${name} must be within [0, 1]`);
+    }
+}
+function validatePattern(pattern) {
+    validateTexture(pattern.baseColor, 'baseColor');
+    if (pattern.normal !== undefined)
+        validateTexture(pattern.normal, 'normal');
+    if (pattern.orm !== undefined)
+        validateTexture(pattern.orm, 'orm');
+}
+function validateSkin(skin) {
+    assertId(skin.materialId);
+    assertId(skin.patternId);
+    if (skin.faceAtlasId !== undefined)
+        assertId(skin.faceAtlasId);
+    if (skin.saturation !== undefined && (!Number.isFinite(skin.saturation) || skin.saturation < 0)) {
+        throw new RangeError('skin saturation must be a non-negative finite number');
+    }
+}
+function validateFaceAtlas(atlas) {
+    validateTexture(atlas.texture, 'face atlas');
+    if (!Number.isSafeInteger(atlas.width) ||
+        atlas.width <= 0 ||
+        !Number.isSafeInteger(atlas.height) ||
+        atlas.height <= 0) {
+        throw new RangeError('face atlas dimensions must be positive integers');
+    }
+}

package/dist/catalog-loader.d.ts

@@ -0,0 +1,15 @@
+import type { DiceAssetRegistry } from './asset-registry.js';
+import type { DiceAssetCatalogManifest } from './types.js';
+export interface DiceAssetCatalogLoaderOptions {
+    readonly fetch?: (uri: string) => Promise<{
+        json(): Promise<unknown>;
+    }>;
+}
+export declare class DiceAssetCatalogLoader {
+    #private;
+    readonly registry: DiceAssetRegistry;
+    constructor(registry: DiceAssetRegistry, options?: DiceAssetCatalogLoaderOptions);
+    load(uri: string): Promise<DiceAssetCatalogManifest>;
+}
+export declare function resolveCatalogReferences(catalog: DiceAssetCatalogManifest, catalogUri: string): DiceAssetCatalogManifest;
+export declare function parseCatalog(source: unknown): DiceAssetCatalogManifest;

package/dist/catalog-loader.js

@@ -0,0 +1,80 @@
+export class DiceAssetCatalogLoader {
+    registry;
+    #fetch;
+    constructor(registry, options = {}) {
+        this.registry = registry;
+        this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    async load(uri) {
+        if (uri.trim().length === 0)
+            throw new RangeError('catalog uri must not be empty');
+        const source = await (await this.#fetch(uri)).json();
+        const catalog = resolveCatalogReferences(parseCatalog(source), uri);
+        this.registry.registerCatalog(catalog);
+        return catalog;
+    }
+}
+export function resolveCatalogReferences(catalog, catalogUri) {
+    const resolveReference = (reference) => ({
+        ...reference,
+        uri: resolveAssetUri(reference.uri, catalogUri),
+    });
+    return {
+        ...catalog,
+        ...(catalog.audioSprites === undefined
+            ? {}
+            : {
+                audioSprites: catalog.audioSprites.map((sprite) => ({
+                    ...sprite,
+                    audio: resolveReference(sprite.audio),
+                })),
+            }),
+        ...(catalog.patterns === undefined
+            ? {}
+            : {
+                patterns: catalog.patterns.map((pattern) => ({
+                    ...pattern,
+                    baseColor: resolveReference(pattern.baseColor),
+                    ...(pattern.normal === undefined ? {} : { normal: resolveReference(pattern.normal) }),
+                    ...(pattern.orm === undefined ? {} : { orm: resolveReference(pattern.orm) }),
+                })),
+            }),
+        ...(catalog.faces === undefined
+            ? {}
+            : {
+                faces: catalog.faces.map((atlas) => ({
+                    ...atlas,
+                    texture: resolveReference(atlas.texture),
+                })),
+            }),
+    };
+}
+function resolveAssetUri(assetUri, catalogUri) {
+    if (/^(?:[a-z][a-z\d+.-]*:|\/)/i.test(assetUri))
+        return assetUri;
+    const dummyOrigin = 'https://dice-assets.invalid';
+    const resolved = new URL(assetUri, new URL(catalogUri, `${dummyOrigin}/`));
+    return resolved.origin === dummyOrigin
+        ? `${resolved.pathname}${resolved.search}${resolved.hash}`
+        : resolved.href;
+}
+export function parseCatalog(source) {
+    if (!isCatalogManifest(source)) {
+        throw new TypeError('asset catalog must use schemaVersion 1');
+    }
+    return source;
+}
+function isCatalogManifest(source) {
+    if (!isRecord(source))
+        return false;
+    if (source.schemaVersion !== 1)
+        return false;
+    for (const key of ['audioSprites', 'audioBanks', 'materials', 'patterns', 'skins', 'faces']) {
+        if (source[key] !== undefined && !Array.isArray(source[key]))
+            return false;
+    }
+    return true;
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object';
+}

package/dist/impact-sound-gate.d.ts

@@ -0,0 +1,20 @@
+export interface SoundCollisionEvent {
+    readonly dieId: string;
+    readonly otherDieId?: string;
+    readonly started: boolean;
+}
+export interface SoundImpactEvent {
+    readonly dieId: string;
+    readonly otherDieId?: string;
+}
+/**
+ * Converts Rapier's persistent contact-force stream into one audible impact
+ * for each collision lifecycle. Collision-start events must be observed before
+ * their matching impact events, as emitted by DiceEngine.
+ */
+export declare class ImpactSoundGate {
+    #private;
+    observeCollision(event: SoundCollisionEvent): void;
+    consumeImpact(event: SoundImpactEvent): boolean;
+    clear(): void;
+}

package/dist/impact-sound-gate.js

@@ -0,0 +1,30 @@
+/**
+ * Converts Rapier's persistent contact-force stream into one audible impact
+ * for each collision lifecycle. Collision-start events must be observed before
+ * their matching impact events, as emitted by DiceEngine.
+ */
+export class ImpactSoundGate {
+    #armedContacts = new Set();
+    observeCollision(event) {
+        const key = contactKey(event);
+        if (event.started)
+            this.#armedContacts.add(key);
+        else
+            this.#armedContacts.delete(key);
+    }
+    consumeImpact(event) {
+        const key = contactKey(event);
+        if (!this.#armedContacts.has(key))
+            return false;
+        this.#armedContacts.delete(key);
+        return true;
+    }
+    clear() {
+        this.#armedContacts.clear();
+    }
+}
+function contactKey(event) {
+    if (event.otherDieId === undefined)
+        return JSON.stringify([event.dieId, 'surface']);
+    return JSON.stringify([event.dieId, event.otherDieId].toSorted());
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { AssetRegistry, DiceAssetRegistry, type RegisterDiceAssetOptions, } from './asset-registry.js';
+export { resolveImpactGain, WebAudioSpritePlayer, type AudioBufferSourceNodeLike, type AudioContextLike, type AudioParamLike, type GainNodeLike, type PlayImpactOptions, type WebAudioSpritePlayerOptions, } from './web-audio-player.js';
+export { ThreeAssetMaterialProvider, type ThreeAssetMaterialProviderOptions, } from './three-material-provider.js';
+export { DiceAssetCatalogLoader, parseCatalog, resolveCatalogReferences, type DiceAssetCatalogLoaderOptions, } from './catalog-loader.js';
+export { ImpactSoundGate, type SoundCollisionEvent, type SoundImpactEvent, } from './impact-sound-gate.js';
+export type { AudioBankDefinition, AudioBankKind, AudioSpriteClip, AudioSpriteManifest, DiceAssetCatalogManifest, DiceAssetMetadataValue, DiceAssetReference, DiceFaceAtlasDefinition, DiceFaceRegion, DiceMaterialDefinition, DicePatternDefinition, DiceSkinCompositeMode, DiceSkinDefinition, RuntimeTextureReference, } from './types.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { AssetRegistry, DiceAssetRegistry, } from './asset-registry.js';
+export { resolveImpactGain, WebAudioSpritePlayer, } from './web-audio-player.js';
+export { ThreeAssetMaterialProvider, } from './three-material-provider.js';
+export { DiceAssetCatalogLoader, parseCatalog, resolveCatalogReferences, } from './catalog-loader.js';
+export { ImpactSoundGate, } from './impact-sound-gate.js';

package/dist/three-material-provider.d.ts

@@ -0,0 +1,16 @@
+import { type FaceMaterialContext, type FaceMaterialResource, type ThreeFaceMaterialProvider } from '@dice-o-rolla/dice-renderer-three';
+import { type WebGLRenderer } from 'three';
+import type { DiceAssetRegistry } from './asset-registry.js';
+export interface ThreeAssetMaterialProviderOptions {
+    readonly renderer: WebGLRenderer;
+    readonly transcoderPath: string;
+}
+/** KTX2-backed PBR adapter; lower-level renderer packages remain asset-schema agnostic. */
+export declare class ThreeAssetMaterialProvider implements ThreeFaceMaterialProvider {
+    #private;
+    readonly registry: DiceAssetRegistry;
+    constructor(registry: DiceAssetRegistry, options: ThreeAssetMaterialProviderOptions);
+    prepareSkin(skinId: string): Promise<void>;
+    createFace(context: FaceMaterialContext): FaceMaterialResource;
+    dispose(): void;
+}

package/dist/three-material-provider.js

@@ -0,0 +1,132 @@
+import { ThreeMaterialFactory, } from '@dice-o-rolla/dice-renderer-three';
+import { Color, MeshPhysicalMaterial, RepeatWrapping, SRGBColorSpace, } from 'three';
+import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
+/** KTX2-backed PBR adapter; lower-level renderer packages remain asset-schema agnostic. */
+export class ThreeAssetMaterialProvider {
+    registry;
+    #loader;
+    #textures = new Map();
+    #skins = new Map();
+    #fallback = new ThreeMaterialFactory();
+    constructor(registry, options) {
+        this.registry = registry;
+        this.#loader = new KTX2Loader()
+            .setTranscoderPath(options.transcoderPath)
+            .detectSupport(options.renderer);
+    }
+    async prepareSkin(skinId) {
+        if (this.#skins.has(skinId))
+            return;
+        this.registry.validateReferences();
+        const skin = this.registry.skins.get(skinId);
+        if (skin === undefined)
+            throw new Error(`Unknown skin: ${skinId}`);
+        const pattern = this.registry.patterns.get(skin.patternId);
+        const atlas = skin.faceAtlasId === undefined ? undefined : this.registry.faces.get(skin.faceAtlasId);
+        const [baseColor, normal, orm, faces] = await Promise.all([
+            this.#load(pattern.baseColor),
+            pattern.normal === undefined ? undefined : this.#load(pattern.normal),
+            pattern.orm === undefined ? undefined : this.#load(pattern.orm),
+            atlas === undefined ? undefined : this.#load(atlas.texture),
+        ]);
+        baseColor.wrapS = baseColor.wrapT = RepeatWrapping;
+        if (normal !== undefined)
+            normal.wrapS = normal.wrapT = RepeatWrapping;
+        if (orm !== undefined)
+            orm.wrapS = orm.wrapT = RepeatWrapping;
+        this.#skins.set(skinId, {
+            skin,
+            baseColor,
+            ...(normal === undefined ? {} : { normal }),
+            ...(orm === undefined ? {} : { orm }),
+            ...(faces === undefined ? {} : { faces }),
+        });
+    }
+    createFace(context) {
+        const skinId = context.preset?.skinId;
+        const loaded = skinId === undefined ? undefined : this.#skins.get(skinId);
+        if (skinId !== undefined && loaded === undefined) {
+            throw new Error(`Skin "${skinId}" must be prepared before creating dice`);
+        }
+        if (loaded === undefined)
+            return this.#createFallback(context);
+        const definition = this.registry.materials.get(loaded.skin.materialId);
+        const atlas = loaded.skin.faceAtlasId === undefined
+            ? undefined
+            : this.registry.faces.get(loaded.skin.faceAtlasId);
+        const region = atlas?.faces[String(context.label)] ?? atlas?.faces[String(context.faceValue)];
+        const material = new MeshPhysicalMaterial({
+            color: loaded.skin.tint ?? '#ffffff',
+            map: loaded.baseColor,
+            normalMap: loaded.normal ?? null,
+            aoMap: loaded.orm ?? null,
+            roughnessMap: loaded.orm ?? null,
+            metalnessMap: loaded.orm ?? null,
+            roughness: definition.roughness,
+            metalness: definition.metalness,
+            clearcoat: definition.clearcoat ?? 0,
+            clearcoatRoughness: definition.clearcoatRoughness ?? 0,
+        });
+        if (definition.normalScale !== undefined)
+            material.normalScale.setScalar(definition.normalScale);
+        if (loaded.faces !== undefined && region !== undefined && atlas !== undefined) {
+            configureCompositingShader(material, loaded.faces, region, atlas.width, atlas.height, loaded.skin);
+        }
+        return {
+            material,
+            dispose() {
+                material.dispose();
+            },
+        };
+    }
+    dispose() {
+        for (const pending of this.#textures.values())
+            void pending.then((texture) => texture.dispose());
+        this.#textures.clear();
+        this.#skins.clear();
+        this.#loader.dispose();
+    }
+    #load(reference) {
+        const existing = this.#textures.get(reference.uri);
+        if (existing !== undefined)
+            return existing;
+        const pending = this.#loader.loadAsync(reference.uri).then((texture) => {
+            texture.colorSpace = reference.colorSpace === 'srgb' ? SRGBColorSpace : '';
+            texture.generateMipmaps = false;
+            texture.needsUpdate = true;
+            return texture;
+        });
+        this.#textures.set(reference.uri, pending);
+        return pending;
+    }
+    #createFallback(context) {
+        const material = this.#fallback.createFace(context.label, context.theme, context.labelScale === undefined ? {} : { labelScale: context.labelScale });
+        return {
+            material,
+            dispose() {
+                material.map?.dispose();
+                material.dispose();
+            },
+        };
+    }
+}
+function configureCompositingShader(material, atlas, region, width, height, skin) {
+    const labelColor = new Color(skin.labelColor ?? '#111111');
+    material.onBeforeCompile = (shader) => {
+        shader.uniforms.faceAtlas = { value: atlas };
+        shader.uniforms.faceRect = {
+            value: [region.x / width, region.y / height, region.width / width, region.height / height],
+        };
+        shader.uniforms.labelColor = { value: labelColor };
+        shader.uniforms.skinHue = { value: skin.hueRotation ?? 0 };
+        shader.uniforms.skinSaturation = { value: skin.saturation ?? 1 };
+        shader.uniforms.patternScale = { value: skin.patternScale ?? [1, 1] };
+        shader.uniforms.compositeMode = {
+            value: skin.composite === 'overlay' ? 2 : skin.composite === 'multiply' ? 1 : 0,
+        };
+        shader.fragmentShader = shader.fragmentShader
+            .replace('#include <map_pars_fragment>', `#include <map_pars_fragment>\nuniform sampler2D faceAtlas;\nuniform vec4 faceRect;\nuniform vec3 labelColor;\nuniform float skinHue;\nuniform float skinSaturation;\nuniform vec2 patternScale;\nuniform int compositeMode;`)
+            .replace('#include <map_fragment>', `#ifdef USE_MAP\nvec4 skinPattern = texture2D(map, fract(vMapUv * patternScale));\nvec3 skinTint = diffuseColor.rgb;\nif (compositeMode == 0) diffuseColor.rgb = mix(skinTint, skinPattern.rgb, skinPattern.a);\nelse if (compositeMode == 1) diffuseColor.rgb = skinTint * skinPattern.rgb;\nelse { vec3 low = 2.0 * skinTint * skinPattern.rgb; vec3 high = 1.0 - 2.0 * (1.0 - skinTint) * (1.0 - skinPattern.rgb); diffuseColor.rgb = mix(low, high, step(vec3(0.5), skinTint)); }\ndiffuseColor.a *= skinPattern.a;\n#endif\nvec3 skinGray = vec3(dot(diffuseColor.rgb, vec3(0.2126, 0.7152, 0.0722)));\ndiffuseColor.rgb = mix(skinGray, diffuseColor.rgb, skinSaturation);\nfloat skinAngle = skinHue * 6.28318530718;\nvec3 skinAxis = normalize(vec3(1.0));\ndiffuseColor.rgb = diffuseColor.rgb * cos(skinAngle) + cross(skinAxis, diffuseColor.rgb) * sin(skinAngle) + skinAxis * dot(skinAxis, diffuseColor.rgb) * (1.0 - cos(skinAngle));\nvec2 faceUv = faceRect.xy + vMapUv * faceRect.zw;\nfloat faceMask = texture2D(faceAtlas, faceUv).a;\ndiffuseColor.rgb = mix(diffuseColor.rgb, labelColor, faceMask);`);
+    };
+    material.customProgramCacheKey = () => `dice-skin:${skin.id}`;
+}

package/dist/types.d.ts

@@ -0,0 +1,94 @@
+export type DiceAssetMetadataValue = string | number | boolean;
+export interface DiceAssetReference {
+    readonly uri: string;
+    readonly mediaType?: string;
+    readonly integrity?: string;
+}
+export interface RuntimeTextureReference extends DiceAssetReference {
+    readonly mediaType: 'image/ktx2';
+    readonly colorSpace: 'srgb' | 'linear';
+    readonly mipmaps: true;
+}
+export interface AudioSpriteClip {
+    readonly offsetSeconds: number;
+    readonly durationSeconds: number;
+    readonly gain?: number;
+    readonly weight?: number;
+}
+export interface AudioSpriteManifest {
+    readonly id: string;
+    readonly audio: DiceAssetReference & {
+        readonly mediaType: 'audio/webm; codecs=opus';
+    };
+    readonly channels: 1;
+    readonly clips: Readonly<Record<string, AudioSpriteClip>>;
+}
+export type AudioBankKind = 'die-material' | 'surface-material';
+export interface AudioBankDefinition {
+    readonly id: string;
+    readonly kind: AudioBankKind;
+    readonly spriteId: string;
+    readonly clipIds: readonly string[];
+    readonly forceRange: readonly [minimum: number, maximum: number];
+    readonly gainRange: readonly [minimum: number, maximum: number];
+    readonly pitchVariationCents?: number;
+    readonly gainVariation?: number;
+    readonly maxVoices?: number;
+    readonly metadata?: Readonly<Record<string, DiceAssetMetadataValue>>;
+}
+export interface DiceMaterialDefinition {
+    readonly id: string;
+    readonly roughness: number;
+    readonly metalness: number;
+    readonly normalScale?: number;
+    readonly clearcoat?: number;
+    readonly clearcoatRoughness?: number;
+    readonly metadata?: Readonly<Record<string, DiceAssetMetadataValue>>;
+}
+export interface DicePatternDefinition {
+    readonly id: string;
+    readonly baseColor: RuntimeTextureReference;
+    readonly normal?: RuntimeTextureReference;
+    /** Occlusion, roughness and metalness packed into R, G and B channels. */
+    readonly orm?: RuntimeTextureReference;
+    readonly repeat?: readonly [u: number, v: number];
+    readonly metadata?: Readonly<Record<string, DiceAssetMetadataValue>>;
+}
+export interface DiceFaceRegion {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+export interface DiceFaceAtlasDefinition {
+    readonly id: string;
+    readonly texture: RuntimeTextureReference;
+    readonly width: number;
+    readonly height: number;
+    readonly faces: Readonly<Record<string, DiceFaceRegion>>;
+    readonly metadata?: Readonly<Record<string, DiceAssetMetadataValue>>;
+}
+export type DiceSkinCompositeMode = 'normal' | 'multiply' | 'overlay';
+export interface DiceSkinDefinition {
+    readonly id: string;
+    readonly name?: string;
+    readonly materialId: string;
+    readonly patternId: string;
+    readonly faceAtlasId?: string;
+    readonly tint?: string;
+    readonly labelColor?: string;
+    readonly hueRotation?: number;
+    readonly saturation?: number;
+    readonly patternScale?: readonly [u: number, v: number];
+    readonly composite?: DiceSkinCompositeMode;
+    readonly metadata?: Readonly<Record<string, DiceAssetMetadataValue>>;
+}
+export interface DiceAssetCatalogManifest {
+    readonly schemaVersion: 1;
+    readonly audioSprites?: readonly AudioSpriteManifest[];
+    readonly audioBanks?: readonly AudioBankDefinition[];
+    readonly materials?: readonly DiceMaterialDefinition[];
+    readonly patterns?: readonly DicePatternDefinition[];
+    readonly skins?: readonly DiceSkinDefinition[];
+    readonly faces?: readonly DiceFaceAtlasDefinition[];
+}

package/dist/web-audio-player.d.ts

@@ -0,0 +1,45 @@
+import type { DiceAssetRegistry } from './asset-registry.js';
+import type { AudioBankDefinition, AudioSpriteClip } from './types.js';
+export interface AudioParamLike {
+    value: number;
+}
+export interface AudioBufferSourceNodeLike {
+    buffer: unknown;
+    readonly playbackRate: AudioParamLike;
+    connect(destination: unknown): void;
+    start(when?: number, offset?: number, duration?: number): void;
+    addEventListener(type: 'ended', listener: () => void, options?: {
+        readonly once?: boolean;
+    }): void;
+}
+export interface GainNodeLike {
+    readonly gain: AudioParamLike;
+    connect(destination: unknown): void;
+}
+export interface AudioContextLike {
+    readonly destination: unknown;
+    decodeAudioData(data: ArrayBuffer): Promise<unknown>;
+    createBufferSource(): AudioBufferSourceNodeLike;
+    createGain(): GainNodeLike;
+}
+export interface WebAudioSpritePlayerOptions {
+    readonly context: AudioContextLike;
+    readonly fetch?: (uri: string) => Promise<{
+        arrayBuffer(): Promise<ArrayBuffer>;
+    }>;
+    readonly random?: () => number;
+}
+export interface PlayImpactOptions {
+    readonly force: number;
+    readonly dieMaterialBankId: string;
+    readonly surfaceMaterialBankId?: string;
+}
+export declare class WebAudioSpritePlayer {
+    #private;
+    readonly registry: DiceAssetRegistry;
+    constructor(registry: DiceAssetRegistry, options: WebAudioSpritePlayerOptions);
+    preloadBank(bankId: string): Promise<void>;
+    playImpact(options: PlayImpactOptions): Promise<void>;
+    playBank(bankId: string, force: number): Promise<boolean>;
+}
+export declare function resolveImpactGain(bank: AudioBankDefinition, clip: AudioSpriteClip, force: number, signedVariation?: number): number;