For the complete documentation index, see llms.txt. This page is also available as Markdown.

GetTextureRegionsForFile

Introduction

The GetTextureRegionsForFile event lets a plugin tell the Texture Coordinates tab about named rectangles inside a Source File, such as the sprites of a sprite sheet or the slices of a PSD. The tab outlines every region reported for the selected object's Source File and shows a region's name while the cursor is over it. Clicking inside a region sets the object's Texture Address to Custom and its Texture Left, Top, Width and Height to that region, as one undo step, without moving the camera. Dragging does not apply a region. A double-click outside every region still creates the default rectangle.

The event receives the Source File as a FilePath and returns a list of TextureRegion, or null (or an empty list) if the plugin does not know the file. Each TextureRegion has a Key, a Name, and an X, Y, Width and Height in texture pixels. The Key identifies the region within its file (a layer id, a frame id), so it must be unique among the regions a plugin reports for that file. The Name is what the tab shows under the cursor, and several regions may share one.

The TextureRegionChosen event, described at the end of this page, tells a plugin which region the user clicked.

Available in December 2026, or now if building Gum from source.

Code Example

The following reports two regions for a file called Sheet.png. Add the following to your plugin's StartUp function.

GetTextureRegionsForFile += file =>
{
    if (file.FileNameNoPath != "Sheet.png")
    {
        return null;
    }

    return new[]
    {
        new TextureRegion("hero", "Hero", 0, 0, 48, 64),
        new TextureRegion("coin", "Coin", 48, 0, 24, 24),
    };
};

Complete Plugin Example

The following plugin reads regions from a JSON file that sits beside the image, so Sheet.png takes its regions from Sheet.png.regions.json. It is a full plugin class, so see Plugins for the project setup.

The JSON file is an array with one entry per region:

Details

  • If more than one plugin reports regions for the same file, the lists are combined.

  • The tab asks once per Source File and remembers the answer until the project is loaded again or the file changes on disk, so the event should be cheap.

  • A region with no width or height is ignored. A region that extends past the texture is cut to the texture, and one entirely outside it is ignored.

  • Where regions overlap, the smallest region under the cursor is used.

  • A plugin that throws is disabled for the session, like any other plugin event, and the tab keeps working.

TextureRegionChosen

PluginBase also has a TextureRegionChosen event of type Action<FilePath, TextureRegion>. It is raised once each time a click applies a region, after the object's Texture Address, Left, Top, Width and Height have been set. It carries the Source File and the region that was chosen, so a plugin can tell which one by its Key even when several regions share a Name. It is not raised for drags, for hovering, or for a click outside every region. The event cannot cancel or change the choice. A plugin that only needs the new rectangle can also watch the variable-set events, but those do not say which region it was.

Last updated

Was this helpful?