AmbientOcclusion.defs.ts

AmbientOcclusion — definitions.

Holds the AmbientOcclusionComponent class and the shapes its data travels in. No System lives here. Import from here, not from AmbientOcclusion.ts.

AmbientOcclusion.defs.ts

import { Component } from '@babylonjsmarket/ecs';

export interface AmbientOcclusionInput {
  /** Master switch (named `active`: `enabled` belongs to the base Component). Default true. */
  active?: boolean;
  /** How far, world units, a surface looks for occluders. Default 1.5. */
  radius?: number;
  /** How dark the occluded corners get. 0..2, default 1.0. */
  strength?: number;
  /** Floor of the darkening: 0 lets corners go black, 0.3 keeps them readable. Default 0.1. */
  base?: number;
  /** Depth samples per pixel. 8 is fast, 32 is smooth. Default 16. */
  samples?: number;
  /** Beyond this depth, world units, occlusion fades out. Default 120. */
  maxZ?: number;
  /** Below this fraction of `maxZ` the radius stops shrinking with distance. Default 0.2. */
  minZAspect?: number;
  /** Bilateral blur that respects edges. Slower, no halos. Default true. */
  expensiveBlur?: boolean;
  /** AO pass resolution as a fraction of the frame. Default 0.5. */
  ratio?: number;
}

export type AmbientOcclusionSettings = Required<AmbientOcclusionInput>;

export const DEFAULT_AMBIENT_OCCLUSION: AmbientOcclusionSettings = {
  active: true,
  radius: 1.5,
  strength: 1.0,
  base: 0.1,
  samples: 16,
  maxZ: 120,
  minZAspect: 0.2,
  expensiveBlur: true,
  ratio: 0.5,
};

/** Name the System looks the plugin up under. */
export const AMBIENT_OCCLUSION_EXTENSION = 'ambientOcclusion';

export interface AmbientOcclusionExtension {
  /** Apply settings to the active camera, creating the pipeline on first call. */
  apply(settings: AmbientOcclusionSettings): void;
  clear(): void;
}

export class AmbientOcclusionComponent extends Component {
  // Declared, not read off the class name: a minified build renames classes,
  // and arcade's built-in AmbientOcclusion must still match a copy in the project.
  static componentType = 'AmbientOcclusion';

  active: boolean;
  radius: number;
  strength: number;
  base: number;
  samples: number;
  maxZ: number;
  minZAspect: number;
  expensiveBlur: boolean;
  ratio: number;

  constructor(data: AmbientOcclusionInput = {}) {
    super();
    const p = { ...DEFAULT_AMBIENT_OCCLUSION, ...data };
    this.active = p.active;
    this.radius = p.radius;
    this.strength = p.strength;
    this.base = p.base;
    this.samples = p.samples;
    this.maxZ = p.maxZ;
    this.minZAspect = p.minZAspect;
    this.expensiveBlur = p.expensiveBlur;
    this.ratio = p.ratio;
  }

  settings(): AmbientOcclusionSettings {
    return {
      active: this.active,
      radius: this.radius,
      strength: this.strength,
      base: this.base,
      samples: this.samples,
      maxZ: this.maxZ,
      minZAspect: this.minZAspect,
      expensiveBlur: this.expensiveBlur,
      ratio: this.ratio,
    };
  }

  serialize(): AmbientOcclusionInput {
    return this.settings();
  }
}

AmbientOcclusion.panel.tsx

AmbientOcclusion.panel.tsx — the occlusion knobs, live.

Every field on the component is read each frame by the System, so a slider that writes it is a slider that shows. The toggle is the one people reach for: occlusion is the first post-process to suspect when a frame is slow, and switching it off should not mean editing a scene file.

Named AmbientOcclusionPanel in a scene. Press O to toggle the panel.

AmbientOcclusion.panel.tsx

import type { EventBus, World } from '@babylonjsmarket/ecs';
import {
  definePanel,
  PanelHostComponent,
  PanelHostSystem,
  type PanelHostInput,
  type PanelSpec,
  type ControlSpec,
} from '@babylonjsmarket/viz';
import { AmbientOcclusionComponent, DEFAULT_AMBIENT_OCCLUSION } from './AmbientOcclusion.defs';

const PANEL_ID = 'ambient-occlusion-panel';

type NumericField = 'radius' | 'strength' | 'base' | 'maxZ' | 'minZAspect' | 'samples' | 'ratio';

export class AmbientOcclusionPanelComponent extends PanelHostComponent {
  constructor(data: PanelHostInput = {}) {
    super({
      panelId: PANEL_ID,
      activationKey: data.activationKey ?? 'KeyO',
      position: data.position ?? 'bottom-right',
      visible: data.visible,
    });
  }
}

export class AmbientOcclusionPanelSystem extends PanelHostSystem<AmbientOcclusionPanelComponent> {
  constructor(eventBus: EventBus) {
    super(eventBus, AmbientOcclusionPanelComponent);
  }

  protected canBuild(world: World): boolean {
    return world.getEntitiesWithComponent(AmbientOcclusionComponent).length > 0;
  }

  protected buildSpec(world: World): PanelSpec {
    const all = (): AmbientOcclusionComponent[] =>
      world
        .getEntitiesWithComponent(AmbientOcclusionComponent)
        .map((e) => e.get(AmbientOcclusionComponent))
        .filter((c): c is AmbientOcclusionComponent => c != null);
    const first = (): AmbientOcclusionComponent | null => all()[0] ?? null;

    const knob = (label: string, field: NumericField, min: number, max: number, step: number, help: string): ControlSpec => ({
      kind: 'slider',
      label, min, max, step,
      bind: {
        persist: field,
        get: () => first()?.[field] ?? DEFAULT_AMBIENT_OCCLUSION[field],
        set: (v: number) => all().forEach((c) => (c[field] = v)),
      },
      help,
    });

    return definePanel({
      id: PANEL_ID,
      title: 'AmbientOcclusion',
      titleColor: '#8fb3d9',
      position: 'bottom-right',
      sections: [
        {
          controls: [
            {
              kind: 'toggle', label: 'occlusion',
              bind: {
                persist: 'active',
                get: () => first()?.active ?? true,
                set: (v: boolean) => all().forEach((c) => (c.active = v)),
              },
              help: 'The first post-process to suspect when a frame is slow. Off detaches the pass; the pipeline stays built for an instant return.',
            },
            knob('radius', 'radius', 0.1, 6, 0.1, 'How far a surface looks for occluders. Match it to the size of your joins.'),
            knob('strength', 'strength', 0, 2, 0.05, 'How dark the corners get.'),
            knob('base', 'base', 0, 1, 0.05, 'Floor of the darkening. Raise it if corners go black.'),
            knob('max depth', 'maxZ', 10, 400, 5, 'Beyond this distance the effect fades out, so the far town does not go muddy.'),
            knob('samples', 'samples', 4, 32, 4, 'Depth samples per pixel. Rebuilds the pipeline.'),
            knob('resolution', 'ratio', 0.25, 1, 0.25, 'Occlusion pass as a fraction of the frame. Rebuilds the pipeline.'),
            {
              kind: 'toggle', label: 'edge-aware blur',
              bind: {
                persist: 'expensiveBlur',
                get: () => first()?.expensiveBlur ?? true,
                set: (v: boolean) => all().forEach((c) => (c.expensiveBlur = v)),
              },
            },
          ],
        },
      ],
    });
  }
}

AmbientOcclusion.ts

AmbientOcclusion.ts — the dark in the corners.

AmbientOcclusion: { radius: 1.5 } on the sky entity turns on screen-space ambient occlusion for the active camera: the soft darkening where pieces meet, under ledges, along the foot of a wall — the depth cue that a shadow map alone never gives, because it comes from the sky, not the sun. Babylon's SSAO2 pipeline does the work, through an adapter plugin (adapter/register.ts); this System only decides WHEN to apply: on first sight and whenever a knob changes, so every field is live for a panel.

Renderer-agnostic: zero @babylonjs / three imports; constructor takes (eventBus) only. With no plugin registered it is a no-op.

AmbientOcclusion.ts

import { System } from '@babylonjsmarket/ecs';
import type { EventBus, Entity } from '@babylonjsmarket/ecs';
import {
  AMBIENT_OCCLUSION_EXTENSION,
  AmbientOcclusionComponent,
  type AmbientOcclusionExtension,
  type AmbientOcclusionSettings,
} from './AmbientOcclusion.defs';

interface AoRuntime {
  last?: AmbientOcclusionSettings;
}

export class AmbientOcclusionSystem extends System {
  protected query = { required: [AmbientOcclusionComponent] };

  private runtime = new WeakMap<AmbientOcclusionComponent, AoRuntime>();

  constructor(eventBus: EventBus) {
    super(eventBus);
    // After the cameras: the pipeline binds to whichever camera is active.
    this.priority = -50;
  }

  private extension(): AmbientOcclusionExtension | undefined {
    return this.world?.renderer?.extension<AmbientOcclusionExtension>(AMBIENT_OCCLUSION_EXTENSION);
  }

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

  protected onEntityRemoved(entity: Entity): void {
    const comp = entity.get(AmbientOcclusionComponent);
    if (comp) this.runtime.delete(comp);
    this.extension()?.clear();
  }

  protected onShutdown(): void {
    this.extension()?.clear();
  }

  private apply(entity: Entity): void {
    const comp = entity.get(AmbientOcclusionComponent)!;
    let rt = this.runtime.get(comp);
    if (!rt) {
      rt = {};
      this.runtime.set(comp, rt);
    }
    const next = comp.settings();
    if (rt.last && same(rt.last, next)) return;
    const ext = this.extension();
    if (!ext) return;
    ext.apply(next);
    rt.last = next;
  }
}

function same(a: AmbientOcclusionSettings, b: AmbientOcclusionSettings): boolean {
  for (const k of Object.keys(a) as (keyof AmbientOcclusionSettings)[]) if (a[k] !== b[k]) return false;
  return true;
}

export {
  AmbientOcclusionComponent,
  AMBIENT_OCCLUSION_EXTENSION,
  DEFAULT_AMBIENT_OCCLUSION,
  type AmbientOcclusionInput,
  type AmbientOcclusionSettings,
  type AmbientOcclusionExtension,
} from './AmbientOcclusion.defs';

adapter/AmbientOcclusion.babylon.ts

AmbientOcclusion — Babylon plugin around SSAO2RenderingPipeline.

The pipeline binds to the camera active when apply first runs and follows a camera swap on a later apply. ratio and samples are construction choices for the pipeline, so a change to either rebuilds it; the rest are live properties.

adapter/AmbientOcclusion.babylon.ts

import { SSAO2RenderingPipeline } from '@babylonjs/core/PostProcesses/RenderPipeline/Pipelines/ssao2RenderingPipeline';
import type { Camera } from '@babylonjs/core/Cameras/camera';
import type { Scene } from '@babylonjs/core/scene';
import type { AmbientOcclusionExtension, AmbientOcclusionSettings } from '../AmbientOcclusion.defs';

export interface BabylonExtensionHost {
  getScene(): Scene | null;
}

export function createBabylonExtension(host: BabylonExtensionHost): AmbientOcclusionExtension {
  let pipeline: SSAO2RenderingPipeline | null = null;
  let camera: Camera | null = null;
  let builtWith: { ratio: number; samples: number } | null = null;
  /** The constructor attaches; re-attaching a live pipeline is an engine error. */
  let attached = false;
  let warned = false;

  const dispose = (): void => {
    pipeline?.dispose();
    pipeline = null;
    camera = null;
    builtWith = null;
    attached = false;
  };

  return {
    apply(s: AmbientOcclusionSettings): void {
      const scene = host.getScene();
      const active = scene?.activeCamera ?? null;
      if (!scene || !active) return;
      if (pipeline && (camera !== active || builtWith?.ratio !== s.ratio || builtWith?.samples !== s.samples)) dispose();
      if (!pipeline) {
        if (!SSAO2RenderingPipeline.IsSupported) {
          if (!warned) {
            warned = true;
            console.warn('[AmbientOcclusion] SSAO2 not supported by this engine; occlusion off');
          }
          return;
        }
        pipeline = new SSAO2RenderingPipeline('ssao', scene, { ssaoRatio: s.ratio, blurRatio: 1 }, [active], false);
        pipeline.samples = s.samples;
        camera = active;
        builtWith = { ratio: s.ratio, samples: s.samples };
        attached = true;
      }
      pipeline.radius = s.radius;
      pipeline.totalStrength = s.strength;
      pipeline.base = s.base;
      pipeline.maxZ = s.maxZ;
      pipeline.minZAspect = s.minZAspect;
      pipeline.expensiveBlur = s.expensiveBlur;
      if (s.active && !attached) {
        scene.postProcessRenderPipelineManager.attachCamerasToRenderPipeline('ssao', active);
        attached = true;
      } else if (!s.active && attached) {
        scene.postProcessRenderPipelineManager.detachCamerasFromRenderPipeline('ssao', active);
        attached = false;
      }
    },
    clear(): void {
      dispose();
    },
  };
}

adapter/register.ts

AmbientOcclusion — adapter-extension registration. Call once at bootstrap; the playground finds it by name. Unregistered = no occlusion, no error.

adapter/register.ts

import { AMBIENT_OCCLUSION_EXTENSION } from '../AmbientOcclusion.defs';
import { createBabylonExtension, type BabylonExtensionHost } from './AmbientOcclusion.babylon';

interface ExtensibleAdapter {
  kind: string;
  registerExtension(name: string, impl: object): void;
}

export function registerAmbientOcclusionExtension(adapter: ExtensibleAdapter): void {
  switch (adapter.kind) {
    case 'babylon':
    case 'babylon-lite':
      adapter.registerExtension(AMBIENT_OCCLUSION_EXTENSION, createBabylonExtension(adapter as unknown as BabylonExtensionHost));
      break;
    default:
      break;
  }
}

AmbientOcclusion.contract.test.ts

11 ✓

ArcadeECS contract: AmbientOcclusion

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

Last run 2026-10-04

AmbientOcclusion.contract.test.ts

import { runMechanicContract } from '@babylonjsmarket/ecs/testing';
import { AmbientOcclusionComponent, AmbientOcclusionSystem } from './AmbientOcclusion';

runMechanicContract({
  name: 'AmbientOcclusion',
  componentClass: AmbientOcclusionComponent,
  // A post-process switch: no companions, no events. Under the mock no plugin
  // is registered, which is a supported state — the System stays quiet.
  systemClass: AmbientOcclusionSystem,
  sampleInput: { strength: 0.6 },
});

AmbientOcclusion.panel.test.tsx

3 ✓

AmbientOcclusionPanel

needs an occlusion component to build
the toggle switches the pass off and the next frame applies it
every knob writes its field live

Last run 2026-10-04

AmbientOcclusion.panel.test.tsx

// @vitest-environment jsdom
import { beforeEach, describe, expect, it } from 'vitest';
import { EventBus, World, MockRendererAdapter } from '@babylonjsmarket/ecs';
import { AMBIENT_OCCLUSION_EXTENSION, AmbientOcclusionComponent, type AmbientOcclusionSettings } from './AmbientOcclusion.defs';
import { AmbientOcclusionSystem } from './AmbientOcclusion';
import { AmbientOcclusionPanelComponent, AmbientOcclusionPanelSystem } from './AmbientOcclusion.panel';

describe('AmbientOcclusionPanel', () => {
  let world: World;
  let panel: AmbientOcclusionPanelSystem;
  let comp: AmbientOcclusionComponent;
  let applied: AmbientOcclusionSettings[];

  function control(label: string): Record<string, any> {
    const spec = (panel as unknown as { buildSpec(w: World): { sections: Array<{ controls: Array<Record<string, any>> }> } }).buildSpec(world);
    for (const s of spec.sections) for (const c of s.controls) if (c.label === label) return c;
    throw new Error(`no control "${label}"`);
  }

  beforeEach(() => {
    const eventBus = new EventBus();
    const renderer = new MockRendererAdapter();
    world = new World({ eventBus, renderer });
    applied = [];
    renderer.registerExtension(AMBIENT_OCCLUSION_EXTENSION, { apply: (s: AmbientOcclusionSettings) => applied.push(s), clear: () => undefined });
    world.addSystem(new AmbientOcclusionSystem(eventBus));
    panel = new AmbientOcclusionPanelSystem(eventBus);
    world.addSystem(panel);
    const e = world.createEntity('Sky');
    comp = new AmbientOcclusionComponent();
    e.add(comp);
    e.add(new AmbientOcclusionPanelComponent());
    world.initialize();
    world.update(1 / 60);
  });

  it('needs an occlusion component to build', () => {
    const bare = new World({ eventBus: new EventBus(), renderer: new MockRendererAdapter() });
    expect((panel as unknown as { canBuild(w: World): boolean }).canBuild(bare)).toBe(false);
    expect((panel as unknown as { canBuild(w: World): boolean }).canBuild(world)).toBe(true);
  });

  it('the toggle switches the pass off and the next frame applies it', () => {
    expect(applied).toHaveLength(1);
    const t = control('occlusion');
    expect(t.bind.get()).toBe(true);
    t.bind.set(false);
    expect(comp.active).toBe(false);
    world.update(1 / 60);
    expect(applied).toHaveLength(2);
    expect(applied[1]!.active).toBe(false);
  });

  it('every knob writes its field live', () => {
    control('radius').bind.set(3);
    control('strength').bind.set(1.5);
    control('base').bind.set(0.3);
    control('max depth').bind.set(60);
    control('samples').bind.set(8);
    control('resolution').bind.set(1);
    control('edge-aware blur').bind.set(false);
    expect(comp.settings()).toMatchObject({ radius: 3, strength: 1.5, base: 0.3, maxZ: 60, samples: 8, ratio: 1, expensiveBlur: false });
    expect(control('radius').bind.get()).toBe(3);
    world.update(1 / 60);
    expect(applied[applied.length - 1]!.radius).toBe(3);
  });
});

AmbientOcclusion.test.ts

7 ✓

AmbientOcclusionComponent

defaults, overrides and round-trips

AmbientOcclusionSystem

applies once, then only when a knob changes
is a no-op without a plugin, and applies later if one shows up
clears when the entity goes and on shutdown
runs after the camera systems

registerAmbientOcclusionExtension

registers for Babylon adapters only
the Babylon plugin does nothing without a scene or camera

Last run 2026-10-04

AmbientOcclusion.test.ts

import { beforeEach, describe, expect, it } from 'vitest';
import { EventBus, World, MockRendererAdapter } from '@babylonjsmarket/ecs';
import {
  DEFAULT_AMBIENT_OCCLUSION,
  AMBIENT_OCCLUSION_EXTENSION,
  AmbientOcclusionComponent,
  AmbientOcclusionSystem,
  type AmbientOcclusionSettings,
} from './AmbientOcclusion';
import { registerAmbientOcclusionExtension } from './adapter/register';
import { createBabylonExtension } from './adapter/AmbientOcclusion.babylon';

describe('AmbientOcclusionComponent', () => {
  it('defaults, overrides and round-trips', () => {
    const c = new AmbientOcclusionComponent();
    expect(c.settings()).toEqual(DEFAULT_AMBIENT_OCCLUSION);
    const custom = new AmbientOcclusionComponent({ strength: 0.3, samples: 8, active: false });
    expect(new AmbientOcclusionComponent(custom.serialize()).settings()).toEqual(custom.settings());
    expect(custom.strength).toBe(0.3);
  });
});

describe('AmbientOcclusionSystem', () => {
  let eventBus: EventBus;
  let world: World;
  let renderer: MockRendererAdapter;
  let applied: AmbientOcclusionSettings[];
  let cleared: number;

  beforeEach(() => {
    eventBus = new EventBus();
    renderer = new MockRendererAdapter();
    world = new World({ eventBus, renderer });
    world.addSystem(new AmbientOcclusionSystem(eventBus));
    applied = [];
    cleared = 0;
  });

  const plugin = () => renderer.registerExtension(AMBIENT_OCCLUSION_EXTENSION, {
    apply: (s: AmbientOcclusionSettings) => applied.push(s),
    clear: () => cleared++,
  });
  const tick = () => world.update(1 / 60);

  it('applies once, then only when a knob changes', () => {
    plugin();
    const e = world.createEntity('Sky');
    const c = new AmbientOcclusionComponent({ strength: 0.5 });
    e.add(c);
    world.initialize();
    tick(); tick(); tick();
    expect(applied).toHaveLength(1);
    expect(applied[0]!.strength).toBe(0.5);
    c.strength = 0.9;
    tick();
    expect(applied).toHaveLength(2);
    expect(applied[1]!.strength).toBe(0.9);
    tick();
    expect(applied).toHaveLength(2);
  });

  it('is a no-op without a plugin, and applies later if one shows up', () => {
    const e = world.createEntity('Sky');
    e.add(new AmbientOcclusionComponent());
    world.initialize();
    tick();
    expect(applied).toHaveLength(0);
    plugin();
    tick();
    expect(applied).toHaveLength(1);
  });

  it('clears when the entity goes and on shutdown', () => {
    plugin();
    const e = world.createEntity('Sky');
    e.add(new AmbientOcclusionComponent());
    world.initialize();
    tick();
    world.removeEntity(e);
    expect(cleared).toBe(1);
    world.shutdown();
    expect(cleared).toBe(2);
  });

  it('runs after the camera systems', () => {
    expect(new AmbientOcclusionSystem(eventBus).priority).toBeLessThan(0);
  });
});

describe('registerAmbientOcclusionExtension', () => {
  const fake = (kind: string) => {
    const registered: string[] = [];
    return { kind, registered, registerExtension: (n: string) => { registered.push(n); }, getScene: () => null };
  };
  it('registers for Babylon adapters only', () => {
    for (const kind of ['babylon', 'babylon-lite']) {
      const a = fake(kind);
      registerAmbientOcclusionExtension(a);
      expect(a.registered).toEqual([AMBIENT_OCCLUSION_EXTENSION]);
    }
    for (const kind of ['three', 'mock']) {
      const a = fake(kind);
      registerAmbientOcclusionExtension(a);
      expect(a.registered).toEqual([]);
    }
  });
  it('the Babylon plugin does nothing without a scene or camera', () => {
    const ext = createBabylonExtension({ getScene: () => null });
    expect(() => ext.apply(DEFAULT_AMBIENT_OCCLUSION)).not.toThrow();
    expect(() => ext.clear()).not.toThrow();
    const noCamera = createBabylonExtension({ getScene: () => ({ activeCamera: null }) as never });
    expect(() => noCamera.apply(DEFAULT_AMBIENT_OCCLUSION)).not.toThrow();
  });
});

Field	Default	What it does
`active`	true	Master switch.
`radius`	1.5	How far, in world units, a surface looks for things that occlude it. Match it to the scale of your joins: a cell-sized kit wants one or two units.
`strength`	1.0	How dark it gets.
`base`	0.1	Floor of the darkening. Raise it if corners go black.
`samples`	16	Depth samples per pixel. 8 is fast and grainy, 32 is smooth. Rebuilds the pipeline.
`maxZ`	120	Beyond this distance the effect fades, so the far town does not go muddy.
`minZAspect`	0.2	Keeps the radius from shrinking to nothing at distance.
`expensiveBlur`	true	Edge-aware blur. Slower, no halos.
`ratio`	0.5	Occlusion pass at half the frame's resolution. Rebuilds the pipeline.

AmbientOcclusion

AmbientOcclusion

Knobs

Pairs with

AmbientOcclusion.defs.ts

AmbientOcclusion.panel.tsx

AmbientOcclusion.ts

adapter/AmbientOcclusion.babylon.ts

adapter/register.ts

AmbientOcclusion.contract.test.ts

AmbientOcclusion.contract.test.ts

AmbientOcclusion.panel.test.tsx

AmbientOcclusion.panel.test.tsx

AmbientOcclusion.test.ts

AmbientOcclusion.test.ts

More like this

Was this page helpful?