Kivicube Docs

English

简体中文

Appearance

Lighting ​

Related reference: Scene API / Lighting

The advanced Web API lets you read the default lights and also create new light objects at runtime.

Get the Default Lights ​

Default Ambient Light ​

js
const ambient = await api.getDefaultAmbientLight();

Default Directional Lights ​

js
const left = await api.getDefaultDirectionalLightLeft();
const right = await api.getDefaultDirectionalLightRight();

These defaults are built-in scene light handles and are a good place for lightweight adjustments.

Create New Lights ​

Ambient Light ​

js
const ambient = await api.createAmbientLight('#ffffff', 1.2);
await api.add(ambient);

Directional Light ​

js
const directional = await api.createDirectionalLight('#ffffff', 2);
await api.add(directional);

Read Light Color and Intensity ​

js
// Floating-point numbers in the [0-1] range. Multiply by 255 for 8-bit RGB.
const [r, g, b] = await api.getLightColor(directional);
const intensity = await api.getLightIntensity(directional);

Update Light Color and Intensity ​

js
await api.setLightColor(directional, '#ffd27f');
await api.setLightIntensity(directional, 1.5);

Directional Light Targets ​

A directional light also has a target object that controls the lighting direction:

js
const target = await api.getDirectionalLightTarget(directional);
await api.setPosition(target, 0, 0, 0);

Adjust the Default Lights First ​

If you only want to make a model slightly brighter, cooler, or warmer, start by changing the default lights.

Add New Lights Only When Necessary ​

Adding lights at runtime is flexible, but it also increases debugging complexity and performance cost. Too many lights will hurt performance significantly.

Pairing with Models ​

Lighting usually needs to be tuned together with:

In PBR model scenes, these three usually need to be adjusted as a set.