Цей сайт найкраще переглядати в сучасному браузері з включеним JavaScript.

ThreeJS - Adding attachments at runtime

jcmesserschmidt

According to the documentation it is possible to create attachments at runtime and add them to a skeleton/skin: https://en.esotericsoftware.com/spine-runtime-skins#Creating-attachments

However I cannot find comprehensive API doc or examples on how to do this using the ThreeJS runtime.

I was able to make some progress, and can add an attachment to an existing SkeletonMesh via an image path, but only the geometry appears as a blank white box with the correct dimensions. I have been unable to get the actual image to render properly. Any guidance is appreciated.

/**
 * Set a slot's attachment on a SpineMesh, supporting runtime-loaded images
 * @param skeletonMesh - The Spine mesh to modify
 * @param slotName - Name of the slot (e.g., "Mainhand", "Offhand")
 * @param attachmentName - Name of the attachment to show, or null to clear
 * @param imagePath - Optional path to external PNG if not in atlas
 */
export async function setSlotAttachment(
  skeletonMesh: spine.SkeletonMesh, 
  slotName: string, 
  attachmentName: string | null,
  imagePath?: string,

): Promise<void> {
  const skeleton = skeletonMesh.skeleton;
  const slot = skeleton.findSlot(slotName);
  
  if (!slot) {
    console.warn(`Slot "${slotName}" not found on skeleton`);
    return;
  }

  if (attachmentName === null) {
    // Clear the slot
    slot.setAttachment(null);
    return;
  }

  let attachment: spine.Attachment | null = null;

  // If an external image path is provided, create a runtime attachment
  if (imagePath) {
    attachment = await createRuntimeAttachment(skeletonMesh, attachmentName, imagePath);
    
    if (!attachment) {
      console.error('Failed to create runtime attachment');
      return;
    }
    
    console.log('Runtime attachment created successfully:', attachment);
    
    // Add the attachment to the current skin (or create one if needed)
    if (!skeleton.skin) {
      const newSkin = new spine.Skin('custom');
      skeleton.setSkin(newSkin);
    }
    
    skeleton.skin!.setAttachment(slot.data.index, attachmentName, attachment);

  } else {
    // Search through existing skins for the attachment
    const skeletonData = skeleton.data;
    const skins = skeletonData.skins;
    
    let foundSkin: spine.Skin | null = null;
    
    for (let i = 0; i < skins.length; i++) {
      const skin = skins[i];
      attachment = skin.getAttachment(slot.data.index, attachmentName);
      if (attachment) {
       
        foundSkin = skin;
        break;
      }
    }
    
    if (!attachment || !foundSkin) {
      console.warn(`Attachment "${attachmentName}" not found for slot "${slotName}" in any skin`);
      return;
    }

    // Merge the found skin into current skin if needed
    if (!skeleton.skin) {
      skeleton.setSkin(foundSkin);
      skeleton.setSlotsToSetupPose();
    } else if (skeleton.skin !== foundSkin) {
      skeleton.skin.setAttachment(slot.data.index, attachmentName, attachment);
    }
  }


  
  slot.setAttachment(attachment);
  skeleton.updateCache();
  
}


/**
 * Create a runtime attachment from an external image file
 */
export async function createRuntimeAttachment(
  skeletonMesh: spine.SkeletonMesh,
  attachmentName: string,
  imagePath: string,
): Promise<spine.RegionAttachment | null> {
  
  // Load the texture using THREE.js
  const textureLoader = new THREE.TextureLoader();
  
  return new Promise((resolve, reject) => {
    textureLoader.load(
      imagePath,
      (texture) => {

        // Ensure texture settings are correct for Spine
        texture.flipY = false; // Spine uses top-left origin
        texture.premultiplyAlpha = false;
        texture.needsUpdate = true;
        
        // Create a new texture atlas page for this texture
        const page = new spine.TextureAtlasPage(attachmentName);
        page.texture = texture as any;
        page.width = texture.image.width;
        page.height = texture.image.height;
        

        // Create a texture region that covers the entire image
        const region = new spine.TextureAtlasRegion(page, attachmentName);
        region.u = 0;
        region.v = 0;
        region.u2 = 1;
        region.v2 = 1;
        region.x = 0;
        region.y = 0;
        region.width = texture.image.width;
        region.height = texture.image.height;
        region.originalWidth = texture.image.width;
        region.originalHeight = texture.image.height;
        region.page = page;
        region.texture = texture as any;
        

        // Create the region attachment
        const attachment = new spine.RegionAttachment(attachmentName, attachmentName);
        

        //Set width and height BEFORE setting region
        attachment.width = texture.image.width;
        attachment.height = texture.image.height;

        // Now set the region
        attachment.region = region;

        // Update the attachment's region (this computes UVs and offsets)
        attachment.updateRegion();
     
        
        resolve(attachment);
      },
      undefined,
      (error) => {
        console.error(`Failed to load texture ${imagePath}:`, error);
        reject(error);
      }
    );
  });
}

Spinebot

I can help you get the texture to display properly in your runtime-created attachments. The issue is that you need to properly set up the texture region and ensure Three.js-specific texture handling is correct.

Here's the corrected version of your createRuntimeAttachment function:

/**
 * Create a runtime attachment from an external image file
 */
export async function createRuntimeAttachment(
  skeletonMesh: spine.SkeletonMesh,
  attachmentName: string,
  imagePath: string,
): Promise<spine.RegionAttachment | null> {
  
  const textureLoader = new THREE.TextureLoader();
  
  return new Promise((resolve, reject) => {
    textureLoader.load(
      imagePath,
      (texture) => {
        // Configure texture for Spine rendering
        texture.flipY = false;
        texture.premultiplyAlpha = false;
        texture.minFilter = THREE.LinearFilter;
        texture.magFilter = THREE.LinearFilter;
        texture.needsUpdate = true;
        
        const width = texture.image.width;
        const height = texture.image.height;
        
        // Create a texture region
        const region = new spine.TextureAtlasRegion();
        region.page = null; // Not needed for runtime textures
        region.name = attachmentName;
        region.texture = texture as any;
        
        // Set UV coordinates (0,0 to 1,1 for full texture)
        region.u = 0;
        region.v = 0;
        region.u2 = 1;
        region.v2 = 1;
        
        // Set dimensions
        region.x = 0;
        region.y = 0;
        region.width = width;
        region.height = height;
        region.originalWidth = width;
        region.originalHeight = height;
        region.offsetX = 0;
        region.offsetY = 0;
        region.degrees = 0; // No rotation
        
        // Create the region attachment
        const attachment = new spine.RegionAttachment(attachmentName);
        attachment.region = region;
        
        // Set dimensions and position (in Spine units)
        attachment.x = 0;
        attachment.y = 0;
        attachment.rotation = 0;
        attachment.scaleX = 1;
        attachment.scaleY = 1;
        attachment.width = width;
        attachment.height = height;
        
        // Important: Call updateRegion() to compute UVs and vertex positions
        attachment.updateRegion();
        
        resolve(attachment);
      },
      undefined,
      (error) => {
        console.error(`Failed to load texture ${imagePath}:`, error);
        reject(error);
      }
    );
  });
}

Key changes:

Removed TextureAtlasPage: For runtime textures, you don't need to create a page object. Set region.page = null.
Proper TextureAtlasRegion setup: The region needs all its properties correctly initialized, especially degrees = 0 (no rotation) and proper offsetX/offsetY.
Texture filtering: Added minFilter and magFilter settings for proper rendering.
Attachment positioning: Set x, y, rotation, scaleX, and scaleY properties before calling updateRegion().
Always call updateRegion(): This computes the UV coordinates and vertex positions based on the region data.

Additional tips:

If your attachment appears but at the wrong size, you may need to scale it. The width and height are in Spine coordinate units, which may differ from your texture pixel dimensions. You can adjust with attachment.scaleX and attachment.scaleY.
If your attachment needs to be positioned relative to the bone, adjust attachment.x and attachment.y (these are relative to the bone's origin).
Make sure your skeleton is using a material that supports textures. The default Three.js Spine materials should work fine.
After setting the attachment, ensure you're calling skeleton.updateCache() and that the skeleton is being updated/rendered properly.

If you still see a white box, check that the texture is actually loading by logging texture.image to verify it has valid image data.

jcmesserschmidt

This suggestion does not resolve the issue. The suggested code has several fatal errors - including that TextureAtlasRegion requires a page object as the first parameter. In fact removing this param prevents the geometry from loading either.

Logging texture.image does return a value that appears valid:
<img crossorigin="anonymous" src="/assets/attachments/Sword_Simple_Front.png">

Davide

jcmesserschmidt

You are passing the region a THREE Texture, but it expects a Spine ThreeJsTexture.

I see at least three ways to get your result.

The first is to use the Spine asset manager to load the texture, transforming your createRuntimeAttachment like this:

async function createRuntimeAttachment(
  skeletonMesh,
  attachmentName,
  imgUrl,
) {

    const spineThreeJsTexture = await assetManager.loadTextureAsync(imgUrl);
    const image = spineThreeJsTexture.texture.image;

    const region = new spine.TextureAtlasRegion(new spine.TextureAtlasPage(imgUrl), imgUrl);
    region.u = region.v = 0;
    region.u2 = region.v2 = 1;
    region.page.width = region.width = region.originalWidth = image.width;
    region.page.height = region.height = region.originalHeight = image.height;

    const atlas = new spine.TextureAtlas("");
    atlas.pages.push(region.page);
    atlas.regions.push(region);
    region.page.setTexture(spineThreeJsTexture);

    const attachment = new spine.RegionAttachment(attachmentName, attachmentName);
    attachment.width = image.width;
    attachment.height = image.height;
    attachment.region = region;
    attachment.updateRegion();

    return attachment;
}

If you want to use the ThreeJS texture loader, you can keep your createRuntimeAttachment with some small modifications:

const textureLoader = new THREE.TextureLoader();

return new Promise((resolve, reject) => {
  textureLoader.load(
    imgUrl,
    (texture) => {
      const image = texture.image;
      const region = new spine.TextureAtlasRegion(new spine.TextureAtlasPage(imgUrl), imgUrl);
      region.u = region.v = 0;
      region.u2 = region.v2 = 1;
      region.page.width = region.width = region.originalWidth = image.width;
      region.page.height = region.height = region.originalHeight = image.height;

      const atlas = new spine.TextureAtlas("");
      atlas.pages.push(region.page);
      atlas.regions.push(region);
      region.page.setTexture(new spine.ThreeJsTexture(texture.image, false));

      const attachment = new spine.RegionAttachment(attachmentName, attachmentName);
      attachment.width = texture.image.width;
      attachment.height = texture.image.height;
      attachment.region = region;
      attachment.updateRegion();
      resolve(attachment);
    },
    undefined,
    (error) => {
      console.error(`Failed to load texture ${imagePath}:`, error);
      reject(error);
    }
  );
});

Pay attention because spine.ThreeJsTexture creates a new ThreeJS Texture, so you probably want to create a variation that does not create the texture but keeps the rest.

A third, quicker but hacky solution is to add a texture property to the ThreeJS Texture that references itself:

texture.texture = texture

This is the main reason your code does not work, because the renderer expects the actual texture in that property. See it here. However, since the texture you are passing to the region lacks some methods (like setFilters), the runtime may invoke them and throw an error.

So my advice is to use method 1 or method 2.

jcmesserschmidt

Davide

Thanks! I did end up stumbling upon creating a new ThreeJsTexture object and assigning texture.texture before I saw your reply, but I tried with the first solution you proposed as well and that did work equally. A less hacky solution is preferable :> I have no particular tie to the ThreeJS loader so I'm fine with that.

One note on your suggested code I found (for anyone else looking) was const image = spineThreeJsTexture.texture.image; gives a TypeScript error that texture does not exist on the spine.Texture type, but changing that to spineThreeJsTexture.getImage() seems to work fine.