EnvironmentTexture

Image-based lighting from a prefiltered cubemap so PBR materials reflect a real environment.

What it does

EnvironmentTexture is data-only: it holds a cubemap url, a reflection level, and an optional named preset. A preset ('studio' today) fills both url and level from a built-in HDRI, so a scene can say { "preset": "studio" } and get the marketplace figure-render lighting without knowing the asset URL — an explicit url/level you also pass always wins. On first tick (or when the entity is added later) the System reads the component and calls setEnvironmentTexture(url, { level }) on the active renderer, which sets scene.environmentTexture on Babylon (or the PMREM equivalent elsewhere). From then on metallic balls, polished floors, and any other PBR meshes reflect the environment instead of rendering flat. It applies exactly once per component; on entity removal the System calls clearEnvironmentTexture() and resets its init flag, so re-adding the entity re-applies cleanly.

Use it in a scene

A scene is just data — a list of entities, each with its components. At startup the SceneLoader turns this JSON into a live world; edit the file and reload to rebuild it.

Build it from scratch with the bjs CLI:

1Scaffold a project
```
npm create @babylonjsmarket/arcade@latest my-game
```
World, renderer, and dev server — ready to run.
2Install dependencies
```
cd my-game && npm install
```
3Add EnvironmentTexture
```
bjs download EnvironmentTexture
```
Copies its source into src/ so the scene resolves.
First time? Run bjs login once.
4Paste the scene into src/scenes/arcade-room.ts and run
```
npm run dev
```
SceneLoader builds the world from the JSON; reload to rebuild.

JSON

{
  "Env": {
    "components": {
      "EnvironmentTexture": {
        "preset": "studio",
        "level": 1.15
      }
    }
  }
}

Props

url (string, default '') — URL of the prefiltered cubemap (a Babylon .env, a Three .hdr + PMREM, etc.), one per renderer. Optional when you supply a preset. If it resolves to empty, the System no-ops and never touches the renderer.
level (number, default 1.0) — reflection strength multiplier; 1.0 is neutral, higher brightens the image-based lighting. Passed straight through to setEnvironmentTexture.
preset ('studio', optional, default unset) — named lighting setup that fills url + level. 'studio' = the neutral studio.env HDRI used by the marketplace figure-render pipeline (level 1.15). An explicit url/level overrides the preset's value.

Events

None. EnvironmentTexture is one-shot init — it drives the adapter's setEnvironmentTexture / clearEnvironmentTexture directly and emits nothing on the EventBus.

Dependencies

None. EnvironmentTexture needs no sibling component on its own entity. For the reflection to be visible you need PBR meshes in the scene with low roughness / metallic materials (a chrome sphere, a polished floor) — a fully rough surface reflects almost nothing.

Notes

It is applied once and never reconciled — changing url or level at runtime does not re-push to the renderer. To swap environments live, remove and re-add the entity (removal clears the texture and resets the init flag).
With no url and no preset, url stays '' and the System silently does nothing, so an empty component is a harmless no-op rather than an error.
Runtime state (the initialized flag) lives in a WeakMap keyed by the component, so it survives entity pooling without leaking.
On a renderer-less world the System is inert: adding the component and updating never throws and never applies a texture.
Pair it with a ToneMapping component for the full filmic look; on its own it only supplies the reflections and IBL, not the color grade.

EnvironmentTexture.core.ts

EnvironmentTexture.core.ts — pure data Component for image-based lighting.

Points the scene at a prefiltered cubemap URL (Babylon .env, Three .hdr + PMREM, etc.). The system applies it on init and clears it on detach. Most PBR materials in the scene then reflect the environment (metallic balls, polished floors). Without this, PBR meshes look flat.

A preset fills url + level from a named lighting setup, so a scene can say { preset: 'studio' } and get the marketplace asset-render HDRI without knowing the URL. Pair with a ToneMapping component for the full filmic look.

EnvironmentTexture.core.ts

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

/** Named lighting presets (url + level). Explicit url/level always win. */
const PRESETS = {
  /** The neutral studio HDRI used by the marketplace figure-render pipeline. */
  studio: {
    url: 'https://assets.babylonjs.com/environments/studio.env',
    level: 1.15,
  },
} as const;

export type EnvironmentPreset = keyof typeof PRESETS;

export interface EnvironmentTextureInput {
  /** URL of the prefiltered cubemap (one per renderer). Optional with `preset`. */
  url?: string;
  /** Reflection strength multiplier. 1.0 = neutral; higher = brighter IBL. */
  level?: number;
  /** Named preset that fills url + level (e.g. 'studio'). */
  preset?: EnvironmentPreset;
}

export class EnvironmentTextureComponent extends Component {
  url: string;
  level: number;
  preset?: EnvironmentPreset;

  constructor(data: EnvironmentTextureInput = {}) {
    super();
    const p = data.preset ? PRESETS[data.preset] : undefined;
    this.preset = data.preset;
    this.url = data.url ?? p?.url ?? '';
    this.level = data.level ?? p?.level ?? 1.0;
  }

  serialize(): EnvironmentTextureInput {
    const out: EnvironmentTextureInput = { url: this.url, level: this.level };
    if (this.preset) out.preset = this.preset;
    return out;
  }
}

EnvironmentTexture.ts

EnvironmentTexture.ts — renderer-agnostic System.

Loads a prefiltered cubemap onto scene.environmentTexture (Babylon) or the equivalent on other renderers, so PBR materials in the scene reflect a real environment. Applies once per component on first tick; clears on entity removal.

EnvironmentTexture.ts

import { System } from '@babylonjsmarket/ecs';
import type { EventBus, Entity } from '@babylonjsmarket/ecs';
import {
  EnvironmentTextureComponent,
  type EnvironmentTextureInput,
  type EnvironmentPreset,
} from './EnvironmentTexture.core';

export {
  EnvironmentTextureComponent,
  type EnvironmentTextureInput,
  type EnvironmentPreset,
};

interface EnvironmentTextureRuntime {
  initialized: boolean;
}

export class EnvironmentTextureSystem extends System {
  protected query = { required: [EnvironmentTextureComponent] };
  private runtime = new WeakMap<EnvironmentTextureComponent, EnvironmentTextureRuntime>();

  private getRuntime(comp: EnvironmentTextureComponent): EnvironmentTextureRuntime {
    let rt = this.runtime.get(comp);
    if (!rt) {
      rt = { initialized: false };
      this.runtime.set(comp, rt);
    }
    return rt;
  }

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

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

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

  protected onEntityRemoved(entity: Entity): void {
    this.world?.renderer?.clearEnvironmentTexture();
    const comp = entity.get(EnvironmentTextureComponent);
    if (comp) this.getRuntime(comp).initialized = false;
  }

  // Stateless beyond the one-shot apply, so onUpdate stays a no-op.
  protected onUpdate(_dt: number): void {
    /* event-driven (init only) */
  }

  private apply(entity: Entity): void {
    const comp = entity.get(EnvironmentTextureComponent);
    if (!comp || !comp.url) return;
    const rt = this.getRuntime(comp);
    if (rt.initialized) return;
    const r = this.world?.renderer;
    if (!r) return;
    r.setEnvironmentTexture(comp.url, { level: comp.level });
    rt.initialized = true;
  }
}

EnvironmentTexture.contract.test.ts

11 ✓

ArcadeECS contract: EnvironmentTexture

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-07-17

EnvironmentTexture.contract.test.ts

import { runMechanicContract } from '@babylonjsmarket/ecs/testing';
import {
  EnvironmentTextureComponent,
  EnvironmentTextureSystem,
} from './EnvironmentTexture';

runMechanicContract({
  name: 'EnvironmentTexture',
  componentClass: EnvironmentTextureComponent,
  systemClass: EnvironmentTextureSystem,
  sampleInput: { url: 'environment.env', level: 0.8 },
  events: {
    // EnvironmentTexture is one-shot init: it drives the adapter's
    // set/clearEnvironmentTexture directly and emits no events.
  },
});

EnvironmentTexture.test.ts

13 ✓

EnvironmentTextureComponent (core)

defaults to empty url and neutral level
accepts a url and level
defaults url to empty string when omitted from the input object
serialize round-trips through the constructor
the studio preset fills url + level
explicit url / level override the preset
serialize keeps the preset

EnvironmentTextureSystem — adapter integration

applies the environment texture through the adapter on entity add
applies only once across multiple updates
does not apply when url is empty
clears the environment texture when the entity is removed
no-ops on a renderer-less world (never applies a texture)
applies to entities that already exist when the system initializes

Last run 2026-07-17

EnvironmentTexture.test.ts

import { describe, it, expect, beforeEach } from 'vitest';
import {
  EnvironmentTextureComponent,
  EnvironmentTextureSystem,
} from './EnvironmentTexture';
import { EventBus, World } from '@babylonjsmarket/ecs';
import { MockRendererAdapter } from '@babylonjsmarket/ecs';

describe('EnvironmentTextureComponent (core)', () => {
  it('defaults to empty url and neutral level', () => {
    const c = new EnvironmentTextureComponent();
    expect(c.url).toBe('');
    expect(c.level).toBe(1.0);
  });

  it('accepts a url and level', () => {
    const c = new EnvironmentTextureComponent({ url: 'env.env', level: 0.7 });
    expect(c.url).toBe('env.env');
    expect(c.level).toBe(0.7);
  });

  it('defaults url to empty string when omitted from the input object', () => {
    // Input object present but without a `url` key → the `?? ''` fallback.
    const c = new EnvironmentTextureComponent({ level: 2 } as { url?: string; level: number } as never);
    expect(c.url).toBe('');
    expect(c.level).toBe(2);
  });

  it('serialize round-trips through the constructor', () => {
    const original = new EnvironmentTextureComponent({ url: 'studio.env', level: 1.5 });
    const copy = new EnvironmentTextureComponent(original.serialize());
    expect(copy.url).toBe('studio.env');
    expect(copy.level).toBe(1.5);
  });

  it('the studio preset fills url + level', () => {
    const c = new EnvironmentTextureComponent({ preset: 'studio' });
    expect(c.url).toContain('studio.env');
    expect(c.level).toBe(1.15);
    expect(c.preset).toBe('studio');
  });

  it('explicit url / level override the preset', () => {
    const c = new EnvironmentTextureComponent({ preset: 'studio', level: 2 });
    expect(c.level).toBe(2);
    expect(c.url).toContain('studio.env');
  });

  it('serialize keeps the preset', () => {
    const copy = new EnvironmentTextureComponent(
      new EnvironmentTextureComponent({ preset: 'studio' }).serialize(),
    );
    expect(copy.preset).toBe('studio');
    expect(copy.level).toBe(1.15);
  });
});

describe('EnvironmentTextureSystem — adapter integration', () => {
  let eventBus: EventBus;
  let world: World;
  let renderer: MockRendererAdapter;
  let system: EnvironmentTextureSystem;

  beforeEach(() => {
    eventBus = new EventBus();
    renderer = new MockRendererAdapter();
    world = new World({ eventBus, renderer });
    system = new EnvironmentTextureSystem(eventBus);
    world.addSystem(system);
    world.initialize();
  });

  it('applies the environment texture through the adapter on entity add', () => {
    const entity = world.createEntity();
    entity.add(new EnvironmentTextureComponent({ url: 'env.env', level: 0.8 }));
    const call = renderer.calls.find((c) => c.method === 'setEnvironmentTexture');
    expect(call).toBeDefined();
    expect(call?.args[0]).toBe('env.env');
    expect((call?.args[1] as { level: number }).level).toBe(0.8);
  });

  it('applies only once across multiple updates', () => {
    const entity = world.createEntity();
    entity.add(new EnvironmentTextureComponent({ url: 'env.env' }));
    world.update(0.016);
    world.update(0.016);
    const applied = renderer.calls.filter((c) => c.method === 'setEnvironmentTexture');
    expect(applied.length).toBe(1);
  });

  it('does not apply when url is empty', () => {
    const entity = world.createEntity();
    entity.add(new EnvironmentTextureComponent({ url: '' }));
    const call = renderer.calls.find((c) => c.method === 'setEnvironmentTexture');
    expect(call).toBeUndefined();
  });

  it('clears the environment texture when the entity is removed', () => {
    const entity = world.createEntity();
    entity.add(new EnvironmentTextureComponent({ url: 'env.env' }));
    renderer.calls.length = 0;
    world.removeEntity(entity);
    expect(renderer.calls.some((c) => c.method === 'clearEnvironmentTexture')).toBe(true);
  });

  it('no-ops on a renderer-less world (never applies a texture)', () => {
    const bus = new EventBus();
    const w = new World({ eventBus: bus });
    w.addSystem(new EnvironmentTextureSystem(bus));
    w.initialize();
    const entity = w.createEntity();
    expect(() => entity.add(new EnvironmentTextureComponent({ url: 'env.env' }))).not.toThrow();
    expect(() => w.update(0.016)).not.toThrow();
  });

  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 });
    const entity = w.createEntity();
    entity.add(new EnvironmentTextureComponent({ url: 'studio.env', level: 0.5 }));
    // System added AFTER the entity → onInitialize applies it.
    w.addSystem(new EnvironmentTextureSystem(bus));
    w.initialize();
    const call = r.calls.find((c) => c.method === 'setEnvironmentTexture');
    expect(call).toBeDefined();
    expect(call!.args[0]).toBe('studio.env');
  });
});