Sprite troubleshooting

Find a sprite failure by checking the requested file, the loaded atlas, the registered element name, and the drawable lifecycle in that order. A magenta, invisible, or wrong sprite can come from different stages, and changing several names at once makes the cause harder to find.

Begin with the exact path passed to Futile. FAtlasManager.LoadAtlas(string) uses the supplied name for both the atlas name and resource lookup. LoadImage(string) creates a single-image atlas instead. Both return an existing atlas with the same name. A later call with corrected source files will therefore keep the earlier loaded atlas until the runtime is rebuilt or its owner performs a verified reload.

For a PNG that is meant to be one element, use one unique image name. For an atlas, make the atlas name and each exported element name unique to the mod. The runtime stores element keys in one shared registry. FAtlasManager.AddAtlas(FAtlas) throws a FutileException when an element name already exists. A generic key such as icon can collide with the game or another enabled mod.

Check the element before constructing or changing an FSprite:

const string elementName = "myexample_dash_icon";
 
if (!Futile.atlasManager.DoesContainElementWithName(elementName))
{
    Logger.LogError("Missing sprite element: " + elementName);
    return;
}
 
sprite.SetElementByName(elementName);

DoesContainElementWithName checks the registry directly. GetElementWithName has a fallback search based on the final path part of a requested name. Do not depend on that fallback. A full unique element name makes a failure report actionable and prevents a similarly named asset from masking a bad request.

If the element check passes, inspect the drawable path. For a room IDrawable, make sure the owner creates the sprite once, puts it in a named RoomCamera.SpriteLeaser slot, updates it in DrawSprites, and adds it to a Futile container through AddToContainer. The leaser tracks the sprite, while container membership puts it in the room camera’s render hierarchy. A sprite tracked by that room leaser but absent from its container will not render through this recipe. Menus and direct container code have different owners. Drawable lifetime describes the room callback order and camera ownership.

Then check placement. Sprite coordinates use camera-relative drawing in most room drawables. Compare a known visible sprite’s position with the camera position and verify the container selected in AddToContainer. Camera coordinates has the conversion pattern. If the image appears at the wrong scale or has transparent edges, inspect its imported dimensions and atlas metadata before changing code.

Use this short test sequence after every asset rename:

1. Start from a fresh game process and enable the package.
2. Record the atlas name, requested element key, and result of DoesContainElementWithName.
3. Spawn or enter the state that creates the drawable.
4. Confirm creation, draw, and cleanup across a room transition.
5. Repeat with another mod that supplies rendering assets.

If loading fails, check the complete asset path through Asset resolution. The path resolver only chooses a file. It does not register PNG files as Futile elements. If the source reports a duplicate key, rename the exported element and every code reference. If the sprite vanishes after changing rooms, inspect the owner’s leaser cleanup rather than unloading a shared atlas. ActuallyUnloadAtlasOrImage removes its element keys from the shared registry.

Sources

• Rain World v1.11.8, Steam build 22785462: FAtlasManager.LoadAtlas(System.String), FAtlasManager.LoadImage(System.String), FAtlasManager.AddAtlas(FAtlas), FAtlasManager.DoesContainElementWithName(System.String), FAtlasManager.GetElementWithName(System.String), FAtlasManager.ActuallyUnloadAtlasOrImage(System.String), global::IDrawable.AddToContainer(global::RoomCamera.SpriteLeaser,global::RoomCamera,FContainer), and global::RoomCamera.SpriteLeaser.AddSpritesToContainer(FContainer,global::RoomCamera) in the assembly identified by Runtime reference.
• Atlases and shaders, Drawable lifetime, and Camera coordinates