Outline API

Outline API

Butterfly API can render custom outlines around entities and block entities.

Outlines can be controlled from the server for synced behavior or directly on the client for local-only effects.

Basic Outline Style

Create an outline style with:

import moth.butterflyapi.outline.OutlinePlacement;
import moth.butterflyapi.outline.OutlineStyle;

OutlineStyle questStyle =
        OutlineStyle.builder("#FFFFFF")
                .thickness(2)
                .placement(
                        OutlinePlacement.CENTERED
                )
                .blackBorder(false)
                .visibleThroughWalls(true)
                .matchModelLayer(true)
                .consistentThickness(true)
                .build();

See Outline Styles for the individual style settings.

Server Outlines

Use ServerOutlines when an outline should be controlled by the logical server.

import moth.butterflyapi.outline.ServerOutlines;

Set an Entity Outline

ServerOutlines.set(
        targetEntity,
        questStyle
);

Clear an Entity Outline

ServerOutlines.clear(
        targetEntity
);

This is suitable when the outline should be synced for viewers.

Viewer-Specific Outlines

An outline can also be shown to one specific player.

ServerOutlines.setFor(
        player,
        targetEntity,
        OutlineStyle.builder("#66CCFF")
                .thickness(3)
                .placement(
                        OutlinePlacement.OUTSIDE
                )
                .build()
);

Clear that viewer-specific outline with:

ServerOutlines.clearFor(
        player,
        targetEntity
);

This allows different players to see different outlines for the same entity.

Block Entity Outlines

Server outlines also support block entities.

ServerOutlines.set(
        displayCaseBlockEntity,
        OutlineStyle.of("#FFFFFF")
);

Clear it with:

ServerOutlines.clear(
        displayCaseBlockEntity
);

Client-Only Outlines

For local effects that do not need server synchronization, use:

import moth.butterflyapi.client.outline.ClientOutlines;

Set an outline:

ClientOutlines.set(
        entity,
        OutlineStyle.builder("#FFAA33")
                .thickness(2)
                .build()
);

Clear it:

ClientOutlines.clear(entity);

Clear all local outlines:

ClientOutlines.clearAll();

Client outlines should be used from client-side code.

Server vs Client

Use ServerOutlines when:

• The logical server controls the effect
• The outline should be synchronized to clients
• Different players may need different outline states

Use ClientOutlines when:

• The outline is purely local
• Only the current client needs to know about it
• No server synchronization is required

Custom Renderers

Custom client renderers can contribute their own outline masks using:

OutlineRenderers.capture(...)

This is useful when a renderer cannot be represented correctly by the normal outline capture process.

Outline-Only Block Entities

A block entity whose renderer exists only to contribute to the outline mask can implement:

OutlineOnlyBlockEntity

This allows the renderer to participate in the outline system without being treated like a normal visible block entity renderer.

Cutout and Translucent Rendering

For custom renderers using cutout or translucent model layers, an outline style can use:

OutlineStyle.builder("#FFFFFF")
        .matchModelLayer(true)
        .build();

This helps the outline mask follow the source renderer's model layer.

Related Pages

• Outline Styles
• Server Outlines
• Client Outlines
• Troubleshooting