Fog.defs.ts

Fog — definitions.

Holds the FogComponent class and the shapes its data and events travel in. No System lives here, which is the point: another component can name Fog in a query, or type an event it listens for, without pulling Fog's behaviour into its own bundle. Import from here, not from Fog.ts.

Fog.defs.ts

import { Component } from '@babylonjsmarket/ecs';
import type { Color, FogSpec } from '@babylonjsmarket/ecs/renderer-types';
export { FogEvents } from './Fog.events';

/** Falloff curve — see the notes on each in {@link FogInput.mode}. */
export type FogMode = 'linear' | 'exp' | 'exp2';

export interface FogInput {
  /**
   * `linear` fades between `start` and `end`; `exp` fades by e^-(d·density);
   * `exp2` by e^-(d·density)² — clear up close, then a faster roll-off, which
   * is the usual pick for an interior. Default 'exp2'.
   */
  mode?: FogMode;
  /**
   * What distant surfaces fade toward. Match the scene's clear colour and the
   * horizon dissolves instead of drawing a hard edge. Default black.
   */
  color?: Color;
  /** Thickness for the exp modes. Default 0.05; a 24 m room reads well near 0.1. */
  density?: number;
  /** Where `linear` fog begins. Default 10. */
  start?: number;
  /** Where `linear` fog is fully opaque. Default 100. */
  end?: number;
  /** Off switch that keeps the settings — a menu toggle. Default true. */
  enabled?: boolean;
}

function cloneColor(c: Color): Color {
  return [c[0], c[1], c[2]];
}

export class FogComponent extends Component {
  // Declared, not read off the class name: a minified build renames classes,
  // and the scene file still has to find this class by name.
  static componentType = 'Fog';

  mode: FogMode;
  color: Color;
  density: number;
  start: number;
  end: number;

  constructor(data: FogInput = {}) {
    super();
    this.mode = data.mode ?? 'exp2';
    this.color = data.color ? cloneColor(data.color) : [0, 0, 0];
    this.density = data.density ?? 0.05;
    this.start = data.start ?? 10;
    this.end = data.end ?? 100;
    // `enabled` is the base Component accessor; setting it here (no bus yet) is silent.
    this.enabled = data.enabled ?? true;
  }

  /** The adapter's shape, detached so a later edit here doesn't alias it. */
  toSpec(): FogSpec {
    return {
      mode: this.mode,
      color: cloneColor(this.color),
      density: this.density,
      start: this.start,
      end: this.end,
    };
  }

  serialize(): FogInput {
    return {
      mode: this.mode,
      color: cloneColor(this.color),
      density: this.density,
      start: this.start,
      end: this.end,
      enabled: this.enabled,
    };
  }
}

Fog.events.ts

Fog — event names.

The EventBus contract for Fog: what it emits and what it listens for. A listener imports these names from here, never from Fog.ts, so it can hear Fog without carrying Fog's System. bjs download hands this file out free with any component that imports it, and it does not make Fog a dependency to buy.

Fog.events.ts

// FogEvents — from Fog
export const FogEvents = {
  /** Fog is on with the component's current settings. `{ entityId, mode, density }`. */
  APPLIED: 'fog.applied',
  /** Fog was switched off (component removed or `enabled` false). `{ entityId }`. */
  CLEARED: 'fog.cleared',
} as const;

Fog.ts

Fog.ts — renderer-agnostic System for scene-wide distance fog.

Scene-global, like EnvironmentTexture: there is one fog per scene, and this System pushes the component's settings to renderer.setFog when the component attaches and clears them (setFog(null)) when it goes away. Unlike EnvironmentTexture it is NOT one-shot: every field is diffed each frame, so a settings slider that drives density live, or a menu toggle that flips enabled, reaches the adapter without anyone calling us.

Fog.ts

import { FogEvents } from './Fog.events';
import { System } from '@babylonjsmarket/ecs';
import type { EventBus, Entity } from '@babylonjsmarket/ecs';
import { FogComponent, type FogInput, type FogMode } from './Fog.defs';

export { FogComponent, type FogInput, type FogMode };

/** What we last sent the adapter, so a frame with no change sends nothing. */
interface FogSnapshot {
  mode: FogMode;
  r: number;
  g: number;
  b: number;
  density: number;
  start: number;
  end: number;
  enabled: boolean;
}

interface FogRuntime {
  /** True while the adapter has this component's fog on. */
  applied: boolean;
  last?: FogSnapshot;
}

function snapshot(comp: FogComponent): FogSnapshot {
  return {
    mode: comp.mode,
    r: comp.color[0],
    g: comp.color[1],
    b: comp.color[2],
    density: comp.density,
    start: comp.start,
    end: comp.end,
    enabled: comp.enabled,
  };
}

function same(a: FogSnapshot | undefined, b: FogSnapshot): boolean {
  return (
    !!a &&
    a.mode === b.mode &&
    a.r === b.r &&
    a.g === b.g &&
    a.b === b.b &&
    a.density === b.density &&
    a.start === b.start &&
    a.end === b.end &&
    a.enabled === b.enabled
  );
}

export class FogSystem extends System {
  protected query = { required: [FogComponent] };
  private runtime = new WeakMap<FogComponent, FogRuntime>();

  constructor(eventBus: EventBus) {
    super(eventBus);
  }

  private getRuntime(comp: FogComponent): FogRuntime {
    let rt = this.runtime.get(comp);
    if (!rt) {
      rt = { applied: false };
      this.runtime.set(comp, rt);
    }
    return rt;
  }

  protected onInitialize(): void {
    for (const entity of this.entities) this.sync(entity);
  }

  protected onEntityAdded(entity: Entity): void {
    this.sync(entity);
  }

  protected onEntityRemoved(entity: Entity): void {
    const comp = entity.get(FogComponent);
    if (!comp) return;
    const rt = this.getRuntime(comp);
    if (rt.applied) {
      this.world?.renderer?.setFog(null);
      this.eventBus.emit(FogEvents.CLEARED, { entityId: entity.id });
    }
    rt.applied = false;
    rt.last = undefined;
  }

  protected onUpdate(_dt: number): void {
    for (const entity of this.entities) this.sync(entity);
  }

  /** Push the component to the adapter if anything about it changed. */
  private sync(entity: Entity): void {
    const comp = entity.get(FogComponent);
    if (!comp) return;
    const r = this.world?.renderer;
    if (!r) return;
    const rt = this.getRuntime(comp);
    const now = snapshot(comp);
    if (same(rt.last, now)) return;
    rt.last = now;

    if (comp.enabled) {
      r.setFog(comp.toSpec());
      rt.applied = true;
      this.eventBus.emit(FogEvents.APPLIED, {
        entityId: entity.id,
        mode: comp.mode,
        density: comp.density,
      });
    } else if (rt.applied) {
      // Disabled after being on: switch it off, and say so once.
      r.setFog(null);
      rt.applied = false;
      this.eventBus.emit(FogEvents.CLEARED, { entityId: entity.id });
    }
  }
}
export { FogEvents } from './Fog.events';

Fog.contract.test.ts

12 ✓

ArcadeECS contract: Fog

Component() with no args constructs and applies defaults
Component merges sample input on top of defaults
Component.serialize() round-trips into a constructor input
System constructor signature is exactly (eventBus)
System declares a non-empty query.required
world.addSystem + initialize + update runs clean with no entity
adding the Component attaches the entity to the System
world.update(dt) does not throw with the entity attached
Adapter handles: create/dispose balance across entity lifecycle
EventBus has no lingering listeners after world.destroy()
Declared event names follow the "{domain}.{action}" convention
Emits at least one declared output event during an update

Last run 2026-10-08

Fog.contract.test.ts

import { FogEvents } from './Fog.events';
import { runMechanicContract } from '@babylonjsmarket/ecs/testing';
import { FogComponent, FogSystem } from './Fog';

runMechanicContract({
  name: 'Fog',
  componentClass: FogComponent,
  systemClass: FogSystem,
  sampleInput: { mode: 'exp2', color: [0.01, 0.01, 0.02], density: 0.11 },
  events: {
    output: [FogEvents.APPLIED],
  },
});

Fog.test.ts

14 ✓

FogComponent

defaults to thin black exp2 fog, enabled
copies the colour rather than aliasing the caller’s
serialize round-trips through the constructor
toSpec hands the adapter a detached copy without the enabled flag

FogSystem

applies the fog through the adapter when the component attaches
stays quiet while nothing changes
re-applies when a slider drives density live
re-applies on a colour, mode or range edit
switches fog off when enabled flips false, and back on when it flips true
a component that starts disabled never touches the adapter
clears the fog when the entity is removed
removing a disabled component does not clear (nothing was applied)
applies to entities that already exist when the system initializes
no-ops on a renderer-less world

Last run 2026-10-08

Fog.test.ts

import { beforeEach, describe, expect, it, vi } from 'vitest';
import { EventBus, MockRendererAdapter, World } from '@babylonjsmarket/ecs';
import { FogEvents } from './Fog.events';
import { FogComponent, FogSystem } from './Fog';

describe('FogComponent', () => {
  it('defaults to thin black exp2 fog, enabled', () => {
    const c = new FogComponent();
    expect(c.mode).toBe('exp2');
    expect(c.color).toEqual([0, 0, 0]);
    expect(c.density).toBe(0.05);
    expect(c.start).toBe(10);
    expect(c.end).toBe(100);
    expect(c.enabled).toBe(true);
  });

  it('copies the colour rather than aliasing the caller’s', () => {
    const color: [number, number, number] = [0.1, 0.2, 0.3];
    const c = new FogComponent({ color });
    color[0] = 99;
    expect(c.color).toEqual([0.1, 0.2, 0.3]);
  });

  it('serialize round-trips through the constructor', () => {
    const c = new FogComponent({
      mode: 'linear',
      color: [0.01, 0.01, 0.02],
      density: 0.11,
      start: 4,
      end: 30,
      enabled: false,
    });
    expect(new FogComponent(c.serialize()).serialize()).toEqual(c.serialize());
  });

  it('toSpec hands the adapter a detached copy without the enabled flag', () => {
    const c = new FogComponent({ color: [0.5, 0.5, 0.5] });
    const spec = c.toSpec();
    spec.color[0] = 99;
    expect(c.color[0]).toBe(0.5);
    expect(spec).toEqual({ mode: 'exp2', color: [99, 0.5, 0.5], density: 0.05, start: 10, end: 100 });
  });
});

describe('FogSystem', () => {
  let eventBus: EventBus;
  let world: World;
  let renderer: MockRendererAdapter;

  beforeEach(() => {
    eventBus = new EventBus();
    renderer = new MockRendererAdapter();
    world = new World({ eventBus, renderer, detectRaces: false });
    world.addSystem(new FogSystem(eventBus));
    world.initialize();
  });

  const fogCalls = () => renderer.calls.filter((c) => c.method === 'setFog');

  it('applies the fog through the adapter when the component attaches', () => {
    const spy = vi.fn();
    eventBus.on(FogEvents.APPLIED, spy);
    const e = world.createEntity();
    e.add(new FogComponent({ mode: 'exp2', color: [0.01, 0.01, 0.02], density: 0.11 }));
    expect(fogCalls()).toHaveLength(1);
    expect(renderer.fog).toEqual({
      mode: 'exp2',
      color: [0.01, 0.01, 0.02],
      density: 0.11,
      start: 10,
      end: 100,
    });
    expect(spy).toHaveBeenCalledWith({ entityId: e.id, mode: 'exp2', density: 0.11 });
  });

  it('stays quiet while nothing changes', () => {
    world.createEntity().add(new FogComponent());
    world.update(1 / 60);
    world.update(1 / 60);
    expect(fogCalls()).toHaveLength(1);
  });

  it('re-applies when a slider drives density live', () => {
    const e = world.createEntity();
    e.add(new FogComponent({ density: 0.05 }));
    e.get(FogComponent)!.density = 0.2;
    world.update(1 / 60);
    expect(fogCalls()).toHaveLength(2);
    expect(renderer.fog?.density).toBe(0.2);
  });

  it('re-applies on a colour, mode or range edit', () => {
    const e = world.createEntity();
    e.add(new FogComponent());
    const c = e.get(FogComponent)!;
    c.color[1] = 0.5;
    world.update(1 / 60);
    c.mode = 'linear';
    world.update(1 / 60);
    c.start = 2;
    world.update(1 / 60);
    c.end = 50;
    world.update(1 / 60);
    expect(fogCalls()).toHaveLength(5);
    expect(renderer.fog).toMatchObject({ mode: 'linear', color: [0, 0.5, 0], start: 2, end: 50 });
  });

  it('switches fog off when enabled flips false, and back on when it flips true', () => {
    const cleared = vi.fn();
    eventBus.on(FogEvents.CLEARED, cleared);
    const e = world.createEntity();
    e.add(new FogComponent());
    e.get(FogComponent)!.enabled = false;
    world.update(1 / 60);
    expect(renderer.fog).toBeNull();
    expect(cleared).toHaveBeenCalledWith({ entityId: e.id });
    // Off is off: nothing more to send while it stays disabled.
    world.update(1 / 60);
    expect(fogCalls()).toHaveLength(2);
    e.get(FogComponent)!.enabled = true;
    world.update(1 / 60);
    expect(renderer.fog).not.toBeNull();
    expect(fogCalls()).toHaveLength(3);
  });

  it('a component that starts disabled never touches the adapter', () => {
    world.createEntity().add(new FogComponent({ enabled: false }));
    world.update(1 / 60);
    expect(fogCalls()).toHaveLength(0);
  });

  it('clears the fog when the entity is removed', () => {
    const cleared = vi.fn();
    eventBus.on(FogEvents.CLEARED, cleared);
    const e = world.createEntity();
    e.add(new FogComponent());
    world.removeEntity(e);
    expect(renderer.fog).toBeNull();
    expect(cleared).toHaveBeenCalledTimes(1);
  });

  it('removing a disabled component does not clear (nothing was applied)', () => {
    const cleared = vi.fn();
    eventBus.on(FogEvents.CLEARED, cleared);
    const e = world.createEntity();
    e.add(new FogComponent({ enabled: false }));
    world.removeEntity(e);
    expect(fogCalls()).toHaveLength(0);
    expect(cleared).not.toHaveBeenCalled();
  });

  it('applies to entities that already exist when the system initializes', () => {
    const bus = new EventBus();
    const r = new MockRendererAdapter();
    const w = new World({ eventBus: bus, renderer: r, detectRaces: false });
    w.createEntity().add(new FogComponent({ density: 0.3 }));
    w.addSystem(new FogSystem(bus));
    w.initialize();
    expect(r.fog?.density).toBe(0.3);
  });

  it('no-ops on a renderer-less world', () => {
    const bus = new EventBus();
    const w = new World({ eventBus: bus, detectRaces: false });
    w.addSystem(new FogSystem(bus));
    w.initialize();
    const e = w.createEntity();
    expect(() => {
      e.add(new FogComponent());
      w.update(1 / 60);
      w.removeEntity(e);
    }).not.toThrow();
  });
});

Fog

Fog

What it does

Use it in a scene

Props

Events

Dependencies

Fog.defs.ts

Fog.events.ts

Fog.ts

Fog.contract.test.ts

Fog.contract.test.ts

Fog.test.ts

Fog.test.ts

More like this

Was this page helpful?