Usage in JavaScript

Install

Three Light Kit is a private repository, so it doesn't support installation via npm, yarn, or pnpm at the moment. Instead, just unzip the content of three-light-kit_2.2.2.zip, place the three-light-kit.mjs file in your app and import it, just like any other JS module.

To import you can either specify the path directly in the import statement:

import TLK from 'path/to/three-light-kit.mjs'

...

Or you can use an import map:

<script type="importmap">
{
    "imports": {
        "three-light-kit": "path/to/three-light-kit.mjs"
    }
}
</script>

<script type="module">
import TLK from 'three-light-kit'

...
</script>

Basic usage

Using TLK is a 2-step process:
1. First use the editor to select and tune your lighting setup before exporting it.
2. Then, import this setup, and turn the editor off if you don't need it anymore.

First use

Let's instanciate the editor.

import TLK from 'path/to/three-light-kit.mjs';

const tlk = new TLK();

tlk.apply( scene, { renderer, editor: true })

Note that we provided the renderer in the apply() method. This is not mandatory, but highly recommended as it will allow the editor to access its toneMapping and toneMappingIntensity attributes. If you use pmndrs' postprocessing, check the ToneMapping control section.

Once you're happy with your lighting setup, export it using the "Export" button. This will download a JSON file named tlk-preset.json.

Loading a preset

Move the tlk-preset.json file to the folder containing your project.
Then upload it using the following code:

const tlk = new TLK()

tlk.on( 'load', () => { 
    tlk.apply( scene, { renderer, editor: true })
})

tlk.load( 'tlk-preset.json' )

Options

If the editor option is not defined, or set to false, the editor won't show up.

editor.position

Defines the position of the editor within the window.
Possible values include top, bottom, left and right, in any order.
Default is top right.

const tlk = new TLK()
tlk.apply( scene, { 
    editor: { 
        position: 'top left' 
    }
})

editor.closed

Determines whether the editor is expanded or collapsed upon initialization.
Default is false.

const tlk = new TLK()
tlk.apply( scene, { 
    editor: { 
        closed: true
    }
})

editor.onMount

A callback function triggered once, when the editor is rendered in the DOM.

const tlk = new TLK()
tlk.apply( scene, { 
    editor: { 
        onMount: () => {
            console.log('TLK Editor is ready')
        }
    }
})

editor.onUpdate

A callback function triggered every time the editor is updated.

const tlk = new TLK()
tlk.apply( scene, { 
    editor: { 
        onUpdate: () => {
            console.log('TLK Editor has been updated')
        } 
    }
})

editor.opacity

Default opacity of the editor when not hovered.

const tlk = new TLK()
tlk.apply( scene, { 
    editor: { 
        opacity: .5
    }
})

target

Applies the environment lighting to a single material.

const tlk = new TLK();
tlk.apply( scene, { 
    renderer, 
    target: mesh.material, 
    editor: true 
});

Checkout the "target" example to see this property in action.

ToneMapping control

The editor lets you access the toneMapping and toneMappingIntensity properties of the renderer.

By default, all you have to do to see this option is to provide the renderer in the editor options, because Three.js tonemapping is managed through the renderer.tonemapping property.

// Vanilla three.js
const tlk = new TLK();
tlk.apply( scene, { renderer });

However, when using pmndrs' postprocessing, tone mapping is managed through an effect.
In this case, you'll need to provide the toneMappingEffect and toneMappingModes.

// Three.js + Postprocessing
import { EffectComposer, ToneMappingEffect, ToneMappingMode, EffectPass, RenderPass } from 'postprocessing';

const toneMappingEffect = new ToneMappingEffect({ mode: ToneMappingMode.ACES_FILMIC });

const tlk = new TLK();
tlk.apply(scene, { 
    renderer, 
    editor: true,
    toneMappingEffect,
    toneMappingModes: ToneMappingMode
});

Checkout the "postprocessing" example to see these options in action.

Usage with React Three Fiber

Install

Three Light Kit is a private repository, so it doesn't support installation via npm, yarn, or pnpm at the moment. Instead, unzip the contents of three-light-kit_2.2.2.zip, place both three-light-kit.mjs and three-light-kit.react.mjs in your app, in the same directory.

Then, import three-light-kit.react.mjs like any other JS module.

import ThreeLightKit from "./tlk/three-light-kit.react.mjs";

Example

import { Canvas } from '@react-three/fiber';
import ThreeLightKit from 'three-light-kit.react.mjs';

function Scene() {
return (
    <Canvas>
        ...
        <ThreeLightKit editor />
    </Canvas>
);
}

Props

editor

Enables the editor interface.

<ThreeLightKit editor />

editor.position

Defines the position of the editor within the window.
Possible values include top, bottom, left and right, in any order.
Default is top right.

<ThreeLightKit editor={{ position: 'top left' }} />

editor.closed

Determines whether the editor is expanded or collapsed upon initialization.
Default is false.

<ThreeLightKit editor={{ closed: 'true' }} />

editor.onMount

A callback function triggered once, when the editor is rendered in the DOM.

function handleMount() {
    console.log('Editor mounted')
}

<ThreeLightKit editor={{ onMount: handleMount }} />

editor.onUpdate

A callback function triggered every time the editor is updated.

function handleUpdate() {
    console.log('Editor updated')
}

<ThreeLightKit editor={{ onUpdate: handleUpdate }} />

editor.opacity

Default opacity of the editor when not hovered.

<ThreeLightKit editor={{ opacity: .5 }} />

load

Loads a predefined lighting configuration from a JSON file.

<ThreeLightKit editor load={'tlk-preset.json'} />

targetRef

Specifies a single mesh in the scene to target with the light editor.
Parameter should be of type `React.RefObject`.

<ThreeLightKit editor targetRef={meshRef} />

ToneMapping control

By default, with React, TLK automatically gives you access to tone mapping controls.

However, if you use pmndrs' postprocessing tonemapping, you'll have to provide the the effect to TLK like this:

import { EffectComposer } from "@react-three/postprocessing";
import { ToneMappingEffect, ToneMappingMode } from "postprocessing";

function App() {
    // Memoize to avoid unnecessary re-instantiation
    const toneMappingEffect = useMemo(
        () => new ToneMappingEffect({ mode: ToneMappingMode.ACES_FILMIC }), []
    );

    return (
        <Canvas>
            <ThreeLightKit editor 
                toneMappingEffect={toneMappingEffect}
                toneMappingModes={ToneMappingMode} />

            <EffectComposer>
                <primitive object={toneMappingEffect} />
            </EffectComposer>
        </Canvas>
    );
}

Checkout the "react-app-postprocessing" example.