> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apetopia.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Trait Overlays

> Let members generate composited NFT images with custom overlays directly from Discord.

Trait Overlays lets you create visual overlays — frames, badges, effects — that get composited on top of your NFT images on demand. Members request them through a Discord bot command and get the result back instantly as an image attachment.

<Card title="Open Trait Overlays →" href="https://apetopia.co/dashboard/overlays">
  Go directly to this feature in your dashboard.
</Card>

<Note>
  This is a **Pro** plan feature.
</Note>

## What it's used for

* Seasonal frames (holiday edition, anniversary overlay)
* Event badges for giveaway winners or raffle participants
* Special visual treatment for rare traits or community milestones
* Any on-demand NFT image composition you want members to trigger in Discord

## Creating an overlay

1. Go to **NFT Suite → Metadata & Assets → Trait Overlays**
2. Click **New Overlay**
3. Select the **collection** this overlay belongs to
4. Give it a short **code** (e.g. `gm`, `winner`, `halloween`) — this is what members type in Discord. Codes must be unique across all your overlays.
5. Give it a **display name** (shown in the bot's overlay list)
6. Upload your overlay image (transparent PNG recommended — it's composited on top of the NFT image). Dimensions are auto-detected from the file.
7. Click **Create Overlay**

Once created, the edit form opens right away so you can add variants and exclusions without any extra steps.

## Trait variants

By default, all NFTs in the collection use the same overlay image. You can add **variants** to swap the overlay image based on a specific trait:

* Select a **Trait Type** from the dropdown (loaded from your collection's NFT data)
* Select a **Trait Value** (loaded automatically once you pick a type)
* Upload the variant image to use for NFTs with that trait

**Example:** NFTs with `Fur = Gold` get a gold-colored frame instead of the default silver one.

## Exclusions

You can block specific trait combinations from using an overlay, with an optional custom message shown to the member when they try.

* Select the trait type and value to exclude
* Add an optional **custom message** (e.g. `"Zombie NFTs are not eligible for this overlay."`)

If no message is set, the bot uses a default response.

## Editing an overlay

Click any overlay in the list to open the editor. From there you can update the code, name, and image, and manage variants and exclusions — all in one place.

## How members use it in Discord

Members run a command in your server — for example:

```
/overlay 42 gm
```

Where `42` is their NFT number and `gm` is the overlay code. Your Discord bot posts the composited PNG back as a message attachment.

To see all available overlay codes, members can run:

```
/overlays
```

The bot replies with the full list of active overlay codes, their names, and which collection they belong to.

<Note>
  Trait Overlays generate composited images on the fly — they do not modify the on-chain metadata or stored image. To permanently update the NFT's on-chain image, use the **Update Asset** tool.
</Note>