@laplace.live/persona-sdk 0.12.0 → 0.14.0

package/dist/values/effect-schema.js

@@ -21,6 +21,9 @@ export const EFFECT_SPECS = {
         saturation: { default: 0, min: -1, max: 1, step: 0.01 },
         brightness: { default: 0, min: -1, max: 1, step: 0.01 },
         contrast: { default: 0, min: -1, max: 1, step: 0.01 },
+        // Unity PPv2's white-balance range, so a Unity-authored grade arrives as-is.
+        temperature: { default: 0, min: -100, max: 100, step: 1 },
+        tint: { default: 0, min: -100, max: 100, step: 1 },
     },
     bloom: {
         // Past ×3 the halo overwhelms the source pixels and everything reads as haze.

package/dist/values/limits.d.ts

@@ -1,4 +1,4 @@
-import type { Attach, ModelFormat, MToonTuning, ObjectContent, ObjectSpace, SceneLight, SceneLightType, ScreenPlacement, VrmPlacement } from '../wire/types.ts';
+import type { AssetRef, Attach, EnvironmentLook, ModelFormat, MToonTuning, ObjectContent, ObjectSpace, SceneEnvironment, SceneLight, SceneLightType, ScreenPlacement, VrmPlacement } from '../wire/types.ts';
 export declare function clamp(v: number, min: number, max: number): number;
 /** Clamp to the unit interval. */
 export declare function clamp01(v: number): number;
@@ -37,15 +37,69 @@ export declare function sceneLightShadowRadiusMax(type: SceneLightType): number;
 export declare const SCENE_FOG_DENSITY_MAX = 0.5;
 /** ×4 is +2 stops — enough to rescue an AgX-dimmed avatar without turning the slider to mush. */
 export declare const SCENE_EXPOSURE_MAX = 4;
+export declare const MTOON_NORMAL_SCALE_MAX = 2;
 export declare const MTOON_RIM_MAX = 2;
+/** ×0 flattens the Fresnel to a flood fill, ×4 tightens a default power-5 rim to a hairline. */
+export declare const MTOON_RIM_FRESNEL_POWER_MAX = 4;
+/** ×4 carries a quarter-strength authored `matcapFactor` back to the spec's full 1.0. */
+export declare const MTOON_MATCAP_MAX = 4;
 export declare const MTOON_OUTLINE_WIDTH_MAX = 2;
 /** HDR headroom: past ×1 the point is pushing emissive parts over the bloom threshold. */
 export declare const MTOON_EMISSIVE_MAX = 4;
+export declare const MTOON_UV_ANIMATION_MAX = 4;
 export declare function defaultMToonTuning(): MToonTuning;
 export declare const DEFAULT_LIGHT_AZIMUTH_DEG = 45;
 export declare const DEFAULT_LIGHT_ELEVATION_DEG: number;
 /** A fresh light of `type`, at the defaults that read sensibly for that type. */
 export declare function defaultSceneLightOf(type: SceneLightType): SceneLight;
+/**
+ * Where a scene's own lights drop once a set lights the stage — Warudo's
+ * `CalculateIdealDirectionalLightIntensity`; past it the two light sets clip MToon to white.
+ */
+export declare const ENVIRONMENT_IDEAL_LIGHT_INTENSITY = 0.25;
+/**
+ * Warudo's Apply Environment Lighting: route the set's lights at everything and cap each
+ * shading light at {@link ENVIRONMENT_IDEAL_LIGHT_INTENSITY}; ambient, a flat floor, stays.
+ * @returns New `environment` and `lights` values; the inputs are untouched.
+ */
+export declare function applyEnvironmentLighting(env: SceneEnvironment, lights: readonly SceneLight[]): {
+    environment: SceneEnvironment;
+    lights: SceneLight[];
+};
+/**
+ * Fold a set's {@link EnvironmentLook} into a scene's environment: its fog, its
+ * ambient level and the four post settings it names, leaving every other effect —
+ * and the user's lights, map and placement — untouched.
+ *
+ * Enabling an effect here is enough for it to render: `effectLayers` is re-derived
+ * from what the result switches on, so a look lands on the live stage rather than
+ * waiting for main's healing pass to come back around.
+ * @returns A new environment; the input is untouched.
+ */
+export declare function applyEnvironmentLook(env: SceneEnvironment, look: EnvironmentLook): SceneEnvironment;
+/**
+ * Whether `env` still holds `reference`'s values in every field an
+ * {@link EnvironmentLook} would overwrite — so applying one takes nothing away.
+ *
+ * The guard on adopting a set's look unasked. Applying it is otherwise deliberate
+ * because it overwrites fog and post the user may have tuned; when none of it has
+ * been touched, there is nothing to protect and a room that ships a look should
+ * simply arrive wearing it.
+ */
+export declare function environmentLookIsUntouched(env: SceneEnvironment, reference: SceneEnvironment): boolean;
+/**
+ * Point an environment at one asset, or at none.
+ *
+ * {@link SceneEnvironment.iblAssetId} and {@link SceneEnvironment.modelAssetId} are a
+ * single slot — a scene wears an equirect map or a 3D set — so this clears whichever
+ * the pick is not. `bakeFromModel` goes with the set: it outlives the id it names, and
+ * it wins over a picked map, so a stale one would leave a fresh map lighting nothing.
+ * Light overrides index the set's own lamps, so a different set — or none — drops them.
+ * `modelLook` stays put: the stage replaces it as the next set parses, and the desktop
+ * reads the outgoing one as what the scene wears now when deciding to adopt the next.
+ * @returns A new environment; the input is untouched.
+ */
+export declare function environmentWithAsset(env: SceneEnvironment, asset: Pick<AssetRef, 'id' | 'kind'> | null): SceneEnvironment;
 export declare const PLACE_2D_SCALE_MIN = 0.01;
 export declare const PLACE_2D_SCALE_MAX = 50;
 export declare const PLACE_3D_SCALE_MIN = 0.01;

package/dist/values/limits.js

@@ -1,3 +1,4 @@
+import { effectLayerKeys } from "./effect-schema.js";
 export function clamp(v, min, max) {
     return Math.min(max, Math.max(min, v));
 }
@@ -51,12 +52,33 @@ export function sceneLightShadowRadiusMax(type) {
 export const SCENE_FOG_DENSITY_MAX = 0.5;
 /** ×4 is +2 stops — enough to rescue an AgX-dimmed avatar without turning the slider to mush. */
 export const SCENE_EXPOSURE_MAX = 4;
+export const MTOON_NORMAL_SCALE_MAX = 2;
 export const MTOON_RIM_MAX = 2;
+/** ×0 flattens the Fresnel to a flood fill, ×4 tightens a default power-5 rim to a hairline. */
+export const MTOON_RIM_FRESNEL_POWER_MAX = 4;
+/** ×4 carries a quarter-strength authored `matcapFactor` back to the spec's full 1.0. */
+export const MTOON_MATCAP_MAX = 4;
 export const MTOON_OUTLINE_WIDTH_MAX = 2;
 /** HDR headroom: past ×1 the point is pushing emissive parts over the bloom threshold. */
 export const MTOON_EMISSIVE_MAX = 4;
+export const MTOON_UV_ANIMATION_MAX = 4;
 export function defaultMToonTuning() {
-    return { shade: 1, shadingShift: 0, shadingToony: 0, giEqualization: 0, rim: 1, outlineWidth: 1, emissive: 1 };
+    return {
+        shade: 1,
+        shadingShift: 0,
+        shadingToony: 0,
+        giEqualization: 0,
+        normalScale: 1,
+        rim: 1,
+        rimLift: 0,
+        rimFresnelPower: 1,
+        rimLightingMix: 0,
+        matcap: 1,
+        outlineWidth: 1,
+        outlineLightingMix: 0,
+        emissive: 1,
+        uvAnimation: 1,
+    };
 }
 // Ranges for toggle-style effect params live in effect-schema.ts (EFFECT_SPECS).
 // Angles at which lightDirection reproduces (1,1,1).normalize() — the app's original hardcoded light.
@@ -82,6 +104,86 @@ export function defaultSceneLightOf(type) {
         shadowRadius: 6,
     };
 }
+/**
+ * Where a scene's own lights drop once a set lights the stage — Warudo's
+ * `CalculateIdealDirectionalLightIntensity`; past it the two light sets clip MToon to white.
+ */
+export const ENVIRONMENT_IDEAL_LIGHT_INTENSITY = 0.25;
+/**
+ * Warudo's Apply Environment Lighting: route the set's lights at everything and cap each
+ * shading light at {@link ENVIRONMENT_IDEAL_LIGHT_INTENSITY}; ambient, a flat floor, stays.
+ * @returns New `environment` and `lights` values; the inputs are untouched.
+ */
+export function applyEnvironmentLighting(env, lights) {
+    return {
+        environment: { ...env, modelLightsEnabled: true, lightsAffectCharacters: true, lightsAffectProps: true },
+        lights: lights.map(l => l.type === 'ambient' ? { ...l } : { ...l, intensity: Math.min(l.intensity, ENVIRONMENT_IDEAL_LIGHT_INTENSITY) }),
+    };
+}
+/**
+ * Fold a set's {@link EnvironmentLook} into a scene's environment: its fog, its
+ * ambient level and the four post settings it names, leaving every other effect —
+ * and the user's lights, map and placement — untouched.
+ *
+ * Enabling an effect here is enough for it to render: `effectLayers` is re-derived
+ * from what the result switches on, so a look lands on the live stage rather than
+ * waiting for main's healing pass to come back around.
+ * @returns A new environment; the input is untouched.
+ */
+export function applyEnvironmentLook(env, look) {
+    const effects = {
+        ...env.effects,
+        toneMapping: look.toneMapping,
+        exposure: look.exposure,
+        bloom: { ...look.bloom },
+        color: { ...look.color },
+    };
+    return {
+        ...env,
+        iblIntensity: look.iblIntensity,
+        fog: { ...look.fog },
+        effects,
+        effectLayers: effectLayerKeys(env.effectLayers, effects),
+    };
+}
+/**
+ * Whether `env` still holds `reference`'s values in every field an
+ * {@link EnvironmentLook} would overwrite — so applying one takes nothing away.
+ *
+ * The guard on adopting a set's look unasked. Applying it is otherwise deliberate
+ * because it overwrites fog and post the user may have tuned; when none of it has
+ * been touched, there is nothing to protect and a room that ships a look should
+ * simply arrive wearing it.
+ */
+export function environmentLookIsUntouched(env, reference) {
+    // Compared through the same shape `applyEnvironmentLook` writes, so a field
+    // added to the look is covered here without a second edit.
+    const looked = (e) => JSON.stringify([e.fog, e.iblIntensity, e.effects.toneMapping, e.effects.exposure, e.effects.bloom, e.effects.color]);
+    return looked(env) === looked(reference);
+}
+/**
+ * Point an environment at one asset, or at none.
+ *
+ * {@link SceneEnvironment.iblAssetId} and {@link SceneEnvironment.modelAssetId} are a
+ * single slot — a scene wears an equirect map or a 3D set — so this clears whichever
+ * the pick is not. `bakeFromModel` goes with the set: it outlives the id it names, and
+ * it wins over a picked map, so a stale one would leave a fresh map lighting nothing.
+ * Light overrides index the set's own lamps, so a different set — or none — drops them.
+ * `modelLook` stays put: the stage replaces it as the next set parses, and the desktop
+ * reads the outgoing one as what the scene wears now when deciding to adopt the next.
+ * @returns A new environment; the input is untouched.
+ */
+export function environmentWithAsset(env, asset) {
+    const isSet = asset?.kind === 'prop';
+    const modelAssetId = isSet ? asset.id : null;
+    return {
+        ...env,
+        iblAssetId: asset !== null && !isSet ? asset.id : null,
+        modelAssetId,
+        bakeFromModel: isSet && env.bakeFromModel,
+        modelLightOverrides: modelAssetId === env.modelAssetId ? env.modelLightOverrides : {},
+    };
+}
 export const PLACE_2D_SCALE_MIN = 0.01;
 export const PLACE_2D_SCALE_MAX = 50;
 export const PLACE_3D_SCALE_MIN = 0.01;

package/dist/wire/types.d.ts

@@ -92,7 +92,8 @@ export interface Place3D extends VrmPlacement {
 /**
  * Per-instance MToon fine-tuning, layered over each material's authored values —
  * offsets add, multipliers scale, so materials keep their relative differences.
- * All-neutral values (1, 0, 0, 0, 1, 1, 1) render the model exactly as authored.
+ * Neutral values — every multiplier 1, every offset 0 — render the model exactly
+ * as authored; `defaultMToonTuning()` is that neutral set.
  */
 export interface MToonTuning {
     /** 0..1 strength of the authored shading: 1 keeps it, 0 lifts every shade color to its lit color. */
@@ -103,12 +104,26 @@ export interface MToonTuning {
     shadingToony: number;
     /** -1..1 added to authored GI equalization: how evenly ambient/IBL light wraps the model. */
     giEqualization: number;
+    /** Multiplier on normal-map strength; 0 flattens the surface detail away. */
+    normalScale: number;
     /** Multiplier on the parametric rim color. */
     rim: number;
+    /** -1..1 added to authored rim lift: how far the rim wraps in off the silhouette. */
+    rimLift: number;
+    /** Multiplier on the rim's Fresnel power; higher pulls the band tighter to the edge. */
+    rimFresnelPower: number;
+    /** -1..1 added to authored rim lighting mix: 0 renders rim and matcap flat, 1 ties them to the scene lights. */
+    rimLightingMix: number;
+    /** Multiplier on the matcap factor — the sphere-add reflection. No-op on materials without a matcap. */
+    matcap: number;
     /** Multiplier on outline width. */
     outlineWidth: number;
+    /** -1..1 added to authored outline lighting mix: 0 keeps the outline its own color, 1 tints it with lighting. */
+    outlineLightingMix: number;
     /** Multiplier on emissive intensity; >1 pairs with bloom. */
     emissive: number;
+    /** Multiplier on UV scroll and rotation speeds; 0 freezes an animated texture. */
+    uvAnimation: number;
 }
 export interface SceneModelItem {
     kind: 'model';
@@ -242,8 +257,10 @@ export interface OrbitTransform {
     azimuth: number;
     elevation: number;
     distance: number;
+    /** Pivot the camera orbits and looks at. Panning moves it along the camera's own axes, so it leaves the XY plane. */
     targetX: number;
     targetY: number;
+    targetZ: number;
 }
 /** Scene-level VRM camera. `orbit: null` = never framed — the first VRM load frames it from model height. */
 export interface SceneCamera {
@@ -339,6 +356,10 @@ export interface SceneColorGrade {
     saturation: number;
     brightness: number;
     contrast: number;
+    /** White balance along blue↔amber, −100..100. Positive is warmer. */
+    temperature: number;
+    /** White balance along green↔magenta, −100..100 — the axis `temperature` leaves alone. */
+    tint: number;
 }
 /** Lens fringing that grows toward frame edges (Unity PPv2's curve, the one VTube Studio wraps). */
 export interface SceneChromaticAberration {
@@ -573,14 +594,59 @@ export interface SceneCustomEffect {
     params: Record<string, number | boolean | string>;
 }
 /**
- * Image-based lighting for the 3D stage: an environment map, whether to show it
- * behind the scene, the scene-global fog, and post-processing.
+ * A 3D set's own suggested look — the fog and post settings it was authored against,
+ * read from its root `LAPLACE_environment` extension and held on the scene for every client.
+ */
+export interface EnvironmentLook {
+    fog: SceneFog;
+    /**
+     * How strong the room's own ambient should be, in {@link SceneEnvironment.iblIntensity}'s
+     * units — the magnitude its environment map was calibrated against.
+     */
+    iblIntensity: number;
+    toneMapping: SceneToneMapping;
+    /** Scene exposure, in {@link SceneEffects.exposure}'s units. */
+    exposure: number;
+    bloom: SceneBloom;
+    color: SceneColorGrade;
+}
+/**
+ * The world the 3D stage sits in: one environment — a map, or a 3D set the avatar
+ * stands inside — the scene-global fog, and post-processing.
+ *
+ * The two asset ids are a single slot the editors write through
+ * {@link environmentWithAsset}: at most one is ever set.
  */
 export interface SceneEnvironment {
     /** Equirectangular `.hdr` or image driving the environment lighting, or null. */
     iblAssetId: string | null;
     iblIntensity: number;
+    /**
+     * How much of the environment's diffuse light reaches MToon avatars, 0..1. PBR
+     * meshes always take it in full; this is the toon-side dial, since MToon 1.0
+     * has no IBL term of its own and the app adds one.
+     */
+    iblAvatarAmount: number;
     showSkybox: boolean;
+    /** A `prop` asset (glb/gltf) rendered as the set the scene sits in, or null. */
+    modelAssetId: string | null;
+    /** Where that set sits, in the same units as an object's `place3d`. */
+    modelPlace: Place3D;
+    /**
+     * Bake the set's geometry into the environment lighting. It wins over
+     * {@link SceneEnvironment.iblAssetId}, so it only means anything with a set.
+     */
+    bakeFromModel: boolean;
+    /** Whether lights baked into the set render at all. */
+    modelLightsEnabled: boolean;
+    /** Whether the set's own lights reach avatars. Off means avatars keep only the scene's lights. */
+    lightsAffectCharacters: boolean;
+    /** Whether the set's own lights reach props. */
+    lightsAffectProps: boolean;
+    /** Overrides for the set's baked lights, keyed by traversal index — same shape as an object's. */
+    modelLightOverrides: Record<string, ObjectLightOverride>;
+    /** The set's suggested look, captured when the model was picked; null when it carries none. */
+    modelLook: EnvironmentLook | null;
     fog: SceneFog;
     effects: SceneEffects;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laplace.live/persona-sdk",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "TypeScript SDK and wire schema for the LAPLACE Persona plugin API",
   "license": "MIT",
   "type": "module",