# Getting started

> Install Blender to TSL, turn on updates with your licence key, and pick how you want to use it.

Blender to TSL docs · https://tools.ashthornton.dev/blender-to-tsl/docs/

## Install

> **Check your email for your download**
>
> After you buy, Payhip emails a receipt to the address you used at checkout. It has the download link for the add-on zip and your **licence key**. If it isn't in your inbox, check your spam folder.

Blender to TSL is sold on Payhip. Your purchase comes with the add-on zip and a **licence key**, which gets you updates inside Blender. There's no limit on how many of your own machines you use it on.

1. Download the zip from your purchase, e.g. `blender_to_tsl-<version>.zip`.
2. In Blender, open **Edit ▸ Preferences ▸ Get Extensions**. In the **⌄** menu at the top right, choose **Install from Disk…** and pick the zip.
3. Go to **Add-ons**, search for *TSL*, and expand **three.js TSL Material Export**. Its preferences hold the **Updates** box and the **Report a Bug** button:

   ![The add-on's preferences: an Updates box saying it was installed from a file, a Licence Key field with Enable Updates, and Found a problem? with a Report a Bug button.](https://tools.ashthornton.dev/_astro/prefs.Y7IVftfQ.png "Preferences ▸ Add-ons ▸ three.js TSL Material Export")

The add-on is ready to use now. The next step only sets up updates.

## Turn on updates

1. Turn on **Allow Online Access** in **Preferences ▸ System**. Without it, **Enable Updates** stays greyed out.
2. Paste your licence key under **Updates**. It's in your Payhip receipt email.

   ![The Updates box before setup: a Licence Key field and an Enable Updates button.](https://tools.ashthornton.dev/_astro/prefs-updates-off.BpThsxut.png)

3. Click **Enable Updates**. This checks the key, adds the *TSL Export Updates* repository with the key as its access token, and reinstalls the add-on from it. Your export settings are saved in your .blend files, so they aren't affected.

   ![The Updates box after setup: Updates are on, Blender checks TSL Export Updates for new versions, with a Change Key button.](https://tools.ashthornton.dev/_astro/prefs-updates-on.CjxN9yY6.png)

From then on, new versions show an **Update** button in **Get Extensions**. Blender checks on startup, or straight away with **Check for Updates** in the same **⌄** menu. **Change Key** replaces the key if you get a new one.

### If updates don't work

- **"Licence key not recognised, or the purchase was refunded."** Copy the key again from your Payhip receipt, without spaces around it. Refunded purchases stop getting updates.

  ![The Updates box showing the error: Licence key not recognised, or the purchase was refunded.](https://tools.ashthornton.dev/_astro/prefs-updates-error.BRvSOYYA.png)

- **Enable Updates is greyed out.** Turn on **Allow Online Access** in **Preferences ▸ System**.
- **Get Extensions says "HTTP Error 401" for TSL Export Updates.** The key stored on the repository isn't accepted any more. Paste your current key and click **Change Key**.
- **"The licence check is unavailable right now."** The update server or Payhip is down. Your installed copy keeps working; try again later.
- **Offline machines.** Install the zip from your purchase. The add-on works fully offline; only updates need online access.

**Setting up the update repository by hand**

In **Get Extensions ▸ Repositories ▸ + ▸ Add Remote Repository**, enter

```text
https://tools.ashthornton.dev/blender-to-tsl/index.json
```

tick **Authentication**, paste your licence key as the access token, and tick **Check for Updates on Startup**. Then uninstall the copy you installed from the zip and install *three.js TSL Material Export* from the new repository.

> **Watch out**
>
> Two copies installed at once will clash. Keep only the one from the repository.

## Overview

Blender to TSL turns a Blender material's shader nodes into a JavaScript module that rebuilds the material with three.js [TSL](https://threejs.org/docs/#api/en/nodes/TSL) node materials. In Blender it's listed as **three.js TSL Material Export**.

There are two ways to use it:

- **With an AI coding agent.** Your agent (Claude Code, Codex, Cursor and others) reaches into the Blender file you have open, exports the material and wires it into your three.js project. See [AI agents](https://tools.ashthornton.dev/blender-to-tsl/docs/ai-agents.md).
- **By hand.** Export a `.js` module from the material panel and import it yourself. See [Exporting a material](https://tools.ashthornton.dev/blender-to-tsl/docs/exporting.md).

![Blender with an iridescent Suzanne in the viewport, its generated TSL module open in the Text Editor below, and the three.js TSL Export panel in the material properties.](https://tools.ashthornton.dev/_astro/overview.CtvXgKYz.png "Blender ▸ the exported module in the Text Editor")

## What you need

- **Blender 5.0 or newer.**
- **A three.js project that renders with `WebGPURenderer`** from `three/webgpu`. It falls back to WebGL 2 by itself in browsers without WebGPU. The add-on is tested with three.js r186. Projects that only use the classic `WebGLRenderer` can't run node materials.
- **For the agent workflow:** the [Blender MCP add-on](https://www.blender.org/lab/mcp-server/) (Blender 5.1 or newer), or an agent that can run Blender from the command line. The [AI agents](https://tools.ashthornton.dev/blender-to-tsl/docs/ai-agents.md) page has the details.

## Where next

- [AI agents](https://tools.ashthornton.dev/blender-to-tsl/docs/ai-agents.md): Set up Claude Code, Codex, Cursor or another agent to bring materials into your project for you.
- [Exporting a material](https://tools.ashthornton.dev/blender-to-tsl/docs/exporting.md): The material panel, its options, and what the notes mean.
- [Using the module](https://tools.ashthornton.dev/blender-to-tsl/docs/threejs.md): Import the material in three.js, load its textures and drive its uniforms.