@forgeax/engine-render 0.1.2

package/src/components/__tests__/atmosphere-red.test.ts

@@ -0,0 +1,51 @@
+import { World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import * as render from '../../index';
+
+type RenderSurface = Record<string, unknown>;
+
+const atmosphereToken = (render as RenderSurface).Atmosphere as
+  | {
+      readonly fields?: Record<string, { readonly default?: number }>;
+    }
+  | undefined;
+const selectEnvironmentSource = (render as RenderSurface).selectEnvironmentSource as
+  | ((input: { readonly resourceOwner: World }) => {
+      readonly ok: boolean;
+      readonly error?: { readonly code: string };
+    })
+  | undefined;
+
+describe('Atmosphere authoring contract (red gate)', () => {
+  it('requires the five-field schema; cardinality is renderer-owned', () => {
+    expect(atmosphereToken).toBeDefined();
+    expect(Object.keys(atmosphereToken?.fields ?? {})).toEqual([
+      'turbidity',
+      'rayleigh',
+      'mieCoefficient',
+      'mieDirectionalG',
+      'sunAngularRadius',
+    ]);
+  });
+
+  it('requires an Atmosphere source to be co-located with DirectionalLight', () => {
+    expect(atmosphereToken).toBeDefined();
+    expect(selectEnvironmentSource).toBeDefined();
+    const world = new World();
+    world.spawn({ component: atmosphereToken as never, data: {} }).unwrap();
+    const result = selectEnvironmentSource?.({ resourceOwner: world });
+    expect(result?.ok).toBe(false);
+    if (result && !result.ok) expect(result.error?.code).toBe('atmosphere-sun-missing');
+  });
+
+  it('rejects multiple Atmosphere sources in the resource World', () => {
+    expect(atmosphereToken).toBeDefined();
+    expect(selectEnvironmentSource).toBeDefined();
+    const world = new World();
+    world.spawn({ component: atmosphereToken as never, data: {} }).unwrap();
+    world.spawn({ component: atmosphereToken as never, data: {} }).unwrap();
+    const result = selectEnvironmentSource?.({ resourceOwner: world });
+    expect(result?.ok).toBe(false);
+    if (result && !result.ok) expect(result.error?.code).toBe('atmosphere-cardinality-invalid');
+  });
+});

package/src/components/__tests__/atmosphere.test.ts

@@ -0,0 +1,79 @@
+import { World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import { Atmosphere, validateAtmosphereData } from '../atmosphere';
+
+describe('Atmosphere schema', () => {
+  it('exposes exactly five finite medium fields with canonical defaults', () => {
+    expect(Object.keys(Atmosphere.fields)).toEqual([
+      'turbidity',
+      'rayleigh',
+      'mieCoefficient',
+      'mieDirectionalG',
+      'sunAngularRadius',
+    ]);
+    expect(
+      Object.fromEntries(
+        Object.entries(Atmosphere.fields).map(([name, field]) => [name, field.default]),
+      ),
+    ).toEqual({
+      turbidity: 2,
+      rayleigh: 1,
+      mieCoefficient: 0.005,
+      mieDirectionalG: 0.8,
+      sunAngularRadius: 0.004675,
+    });
+  });
+
+  it('accepts every inclusive boundary and the open sun radius lower bound', () => {
+    const cases = [
+      ['turbidity', 1],
+      ['turbidity', 20],
+      ['rayleigh', 0],
+      ['rayleigh', 4],
+      ['mieCoefficient', 0],
+      ['mieCoefficient', 0.1],
+      ['mieDirectionalG', 0],
+      ['mieDirectionalG', 0.999],
+      ['sunAngularRadius', 0.000001],
+      ['sunAngularRadius', 0.02],
+    ] as const;
+    for (const [field, value] of cases) {
+      const result = validateAtmosphereData({ [field]: value });
+      expect(result.ok, `${field}=${value}`).toBe(true);
+    }
+  });
+
+  it('rejects non-finite and out-of-range values with structured detail', () => {
+    const cases = [
+      ['turbidity', Number.NaN],
+      ['turbidity', Number.POSITIVE_INFINITY],
+      ['rayleigh', Number.NEGATIVE_INFINITY],
+      ['rayleigh', -0.001],
+      ['mieCoefficient', 0.101],
+      ['mieDirectionalG', 1],
+      ['sunAngularRadius', 0],
+      ['sunAngularRadius', 0.020001],
+    ] as const;
+    for (const [field, value] of cases) {
+      const result = validateAtmosphereData({ [field]: value });
+      expect(result.ok, `${field}=${value}`).toBe(false);
+      if (!result.ok) {
+        const error = result.error as unknown as {
+          readonly code: string;
+          readonly detail: { readonly field: string; readonly value: number };
+        };
+        expect(error.code).toBe('atmosphere-parameter-invalid');
+        expect(error.detail.field).toBe(field);
+        expect(Object.is(error.detail.value, value)).toBe(true);
+      }
+    }
+  });
+
+  it('keeps component storage independent across Worlds', () => {
+    const worldA = new World();
+    const worldB = new World();
+    expect(worldA.spawn({ component: Atmosphere, data: {} }).ok).toBe(true);
+    expect(worldA.spawn({ component: Atmosphere, data: {} }).ok).toBe(true);
+    expect(worldB.spawn({ component: Atmosphere, data: {} }).ok).toBe(true);
+  });
+});

package/src/components/__tests__/fog.test-d.ts

@@ -0,0 +1,49 @@
+import { World } from '@forgeax/engine-ecs';
+import { componentSchema } from '@forgeax/engine-ecs/internal';
+import { expectTypeOf } from 'vitest';
+import { Fog } from '../environment';
+
+const world = new World();
+
+world.spawn({
+  component: Fog,
+  data: {
+    color: [0.18, 0.22, 0.28],
+    density: 0.035,
+    heightFalloff: 0.28,
+    maxOpacity: 0.92,
+  },
+});
+
+// Legacy profile and split-range concepts are intentionally not part of the
+// single Fog authoring surface.
+world.spawn({
+  component: Fog,
+  // @ts-expect-error Fog has no mode discriminator.
+  data: { mode: 'height' },
+});
+world.spawn({
+  component: Fog,
+  // @ts-expect-error Fog has no baseHeight field.
+  data: { baseHeight: 0 },
+});
+world.spawn({
+  component: Fog,
+  // @ts-expect-error Fog has no start field.
+  data: { start: 1 },
+});
+world.spawn({
+  component: Fog,
+  // @ts-expect-error Fog has no end field.
+  data: { end: 10 },
+});
+world.spawn({
+  component: Fog,
+  // @ts-expect-error color must be a three-component numeric array.
+  data: { color: 'gray' },
+});
+
+expectTypeOf(componentSchema(Fog).color).toEqualTypeOf<'array<f32, 3>'>();
+expectTypeOf(componentSchema(Fog).density).toEqualTypeOf<'f32'>();
+expectTypeOf(componentSchema(Fog).heightFalloff).toEqualTypeOf<'f32'>();
+expectTypeOf(componentSchema(Fog).maxOpacity).toEqualTypeOf<'f32'>();

package/src/components/__tests__/fog.test.ts

@@ -0,0 +1,60 @@
+import { World } from '@forgeax/engine-ecs';
+import { componentSchema } from '@forgeax/engine-ecs/internal';
+import { describe, expect, it } from 'vitest';
+import { Fog } from '../environment';
+
+const DEFAULT_COLOR = [0.5, 0.5, 0.5];
+
+describe('Fog schema contract', () => {
+  it('exposes one environment token with exactly four reflected fields', () => {
+    expect(Object.keys(Fog.fields)).toEqual(['color', 'density', 'heightFalloff', 'maxOpacity']);
+    expect(Fog.fields.color.type).toBe('array<f32, 3>');
+    expect(Fog.fields.density.type).toBe('f32');
+    expect(Fog.fields.heightFalloff.type).toBe('f32');
+    expect(Fog.fields.maxOpacity.type).toBe('f32');
+    expect(componentSchema(Fog)).toEqual({
+      color: 'array<f32, 3>',
+      density: 'f32',
+      heightFalloff: 'f32',
+      maxOpacity: 'f32',
+    });
+    expect('mode' in componentSchema(Fog)).toBe(false);
+    expect('baseHeight' in componentSchema(Fog)).toBe(false);
+    expect('start' in componentSchema(Fog)).toBe(false);
+    expect('end' in componentSchema(Fog)).toBe(false);
+    expect('profile' in componentSchema(Fog)).toBe(false);
+  });
+
+  it('uses the canonical defaults and gives each entity an independent color array', () => {
+    expect(Fog.fields.color.default).toEqual(new Float32Array(DEFAULT_COLOR));
+    expect(Fog.fields.density.default).toBe(0.01);
+    expect(Fog.fields.heightFalloff.default).toBe(0);
+    expect(Fog.fields.maxOpacity.default).toBe(1);
+
+    const world = new World();
+    const first = world.spawn({ component: Fog, data: {} }).unwrap();
+    const second = world.spawn({ component: Fog, data: {} }).unwrap();
+    const firstColor = world.get(first, Fog).unwrap().color;
+    const secondColor = world.get(second, Fog).unwrap().color;
+
+    expect(firstColor).toEqual(new Float32Array(DEFAULT_COLOR));
+    expect(secondColor).toEqual(new Float32Array(DEFAULT_COLOR));
+    expect(firstColor).not.toBe(secondColor);
+    firstColor[0] = 9;
+    expect(secondColor[0]).toBe(DEFAULT_COLOR[0]);
+    expect((Fog.fields.color.default as Float32Array)[0]).toBe(DEFAULT_COLOR[0]);
+  });
+
+  it('stores authoring values for render-owner validation', () => {
+    const result = new World().spawn({
+      component: Fog,
+      data: {
+        color: [2, 0.25, 0],
+        density: 0,
+        heightFalloff: 0.75,
+        maxOpacity: 1,
+      },
+    });
+    expect(result.ok).toBe(true);
+  });
+});

package/src/components/__tests__/schema-parity.unit.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+import {
+  Camera,
+  DirectionalLight,
+  MeshFilter,
+  MeshRenderer,
+  orthographic,
+  perspective,
+} from '../index';
+
+describe('render schema parity', () => {
+  it('keeps branded mesh and merged light fields in the canonical schema', () => {
+    expect(MeshFilter.fields.assetHandle.type).toBe('shared<MeshAsset>');
+    expect(DirectionalLight.fields.direction.type).toBe('array<f32, 3>');
+    expect(DirectionalLight.fields.castShadow.default).toBe(true);
+    expect(MeshRenderer.fields.materials.type).toBe('array<shared<MaterialAsset>>');
+  });
+
+  it('exposes both camera projection variants and helpers', () => {
+    expect(Camera.fields.projection.default).toBe(0);
+    expect(Camera.fields.left.default).toBe(-1);
+    expect(perspective({ fov: 1, aspect: 2 }).projection).toBe(0);
+    expect(orthographic({ left: -2, right: 2, bottom: -1, top: 1 }).projection).toBe(1);
+  });
+});

package/src/components/__tests__/visibility-schema.unit.test.ts

@@ -0,0 +1,35 @@
+import { World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import { Visibility, VisibilityStateValue, visibilityStateFromU32 } from '../visibility';
+
+describe('M1 Visibility schema', () => {
+  it('uses inherited as the default and decodes the closed three-state set', () => {
+    const world = new World();
+    const entity = world.spawn({ component: Visibility, data: {} }).unwrap();
+
+    expect(world.get(entity, Visibility).unwrap().state).toBe(VisibilityStateValue.inherited);
+    expect(Visibility.fields.state.labels).toEqual(VisibilityStateValue);
+    expect(Object.isFrozen(Visibility.fields.state.labels)).toBe(true);
+    expect(JSON.parse(JSON.stringify(Visibility.fields.state.labels))).toEqual(
+      VisibilityStateValue,
+    );
+    expect(Visibility.fields.state.default).toBe(VisibilityStateValue.inherited);
+    expect(visibilityStateFromU32(VisibilityStateValue.inherited)).toBe('inherited');
+    expect(visibilityStateFromU32(VisibilityStateValue.hidden)).toBe('hidden');
+    expect(visibilityStateFromU32(VisibilityStateValue.visible)).toBe('visible');
+    expect(visibilityStateFromU32(3)).toBeUndefined();
+  });
+
+  it('supports real World.set and Query consumption without a cast', () => {
+    const world = new World();
+    const entity = world.spawn({ component: Visibility, data: {} }).unwrap();
+
+    expect(world.set(entity, Visibility, { state: VisibilityStateValue.hidden }).ok).toBe(true);
+
+    const query = world.query({ read: [Visibility] }).unwrap();
+    let stateFromQuery: number | undefined;
+    for (const row of query) stateFromQuery = row.get(Visibility).state;
+
+    expect(stateFromQuery).toBe(VisibilityStateValue.hidden);
+  });
+});

package/src/components/atmosphere.ts

@@ -0,0 +1,64 @@
+import { defineComponent } from '@forgeax/engine-ecs';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { type AtmosphereField, AtmosphereParameterInvalidError } from '../errors/render';
+
+/**
+ * Analytic atmosphere medium parameters. Sun direction, color, and
+ * illuminance belong to a co-located DirectionalLight, never to this token.
+ * The renderer-owned environment selector enforces one Atmosphere source per
+ * resource World; ECS component schemas do not carry cardinality policy.
+ */
+export const Atmosphere = defineComponent('Atmosphere', {
+  turbidity: { type: 'f32', default: 2 },
+  rayleigh: { type: 'f32', default: 1 },
+  mieCoefficient: { type: 'f32', default: 0.005 },
+  mieDirectionalG: { type: 'f32', default: 0.8 },
+  sunAngularRadius: { type: 'f32', default: 0.004675 },
+});
+
+const ATMOSPHERE_CHECKS: readonly {
+  readonly field: AtmosphereField;
+  readonly min: number;
+  readonly max: number;
+  readonly minExclusive?: boolean;
+}[] = [
+  { field: 'turbidity', min: 1, max: 20 },
+  { field: 'rayleigh', min: 0, max: 4 },
+  { field: 'mieCoefficient', min: 0, max: 0.1 },
+  { field: 'mieDirectionalG', min: 0, max: 0.999 },
+  { field: 'sunAngularRadius', min: 0, max: 0.02, minExclusive: true },
+];
+
+/** Validate Atmosphere payloads at the renderer owner boundary. */
+export function validateAtmosphereData(
+  data: Readonly<Record<string, unknown>>,
+): Result<void, AtmosphereParameterInvalidError> {
+  for (const check of ATMOSPHERE_CHECKS) {
+    const reflectedDefault = Atmosphere.fields[check.field]?.default;
+    const rawValue = data[check.field] ?? reflectedDefault;
+    const value = typeof rawValue === 'number' ? rawValue : Number.NaN;
+    if (!Number.isFinite(value)) {
+      return err(
+        new AtmosphereParameterInvalidError(
+          check.field,
+          value,
+          check.min,
+          check.max,
+          check.minExclusive ?? false,
+        ),
+      );
+    }
+    if ((check.minExclusive ? value <= check.min : value < check.min) || value > check.max) {
+      return err(
+        new AtmosphereParameterInvalidError(
+          check.field,
+          value,
+          check.min,
+          check.max,
+          check.minExclusive ?? false,
+        ),
+      );
+    }
+  }
+  return ok(undefined);
+}