ALPACA BRIDGE - INSTALLATION FOR BLENDER

Tested with Blender 5.0. The add-on targets Blender 4.2 or newer.
Alpaca3D must be installed with bridge support.

INSTALLATION

1. Find alpaca_bridge-<version>.zip next to this guide.
   If several archives are present, use the version supplied with this release.
   Do not extract the ZIP before installing it in Blender.
2. In Blender, open Edit > Preferences > Add-ons.
3. Open the menu at the top right, choose Install from Disk, and select the ZIP.
4. Find Alpaca Bridge in the add-on list and enable it.
5. In the 3D Viewport, press N to open the sidebar, then select the Alpaca tab.
6. Under Application, select the main Alpaca3D.exe in your installation.
   Select the application launcher, not blender.exe or an EXE inside versions.
   Click Save Preferences if preferences are not saved automatically.

After updating an existing add-on, save your Blender work and restart Blender.
Replacing files does not reload all Python modules already loaded in the open session.

FIRST TEST

1. In Object Mode, select a test mesh with UVs.
2. Under UV Operations, click Send. An Alpaca3D window opens.
3. Edit the UVs and click Send to Blender or press Ctrl+Enter in Alpaca3D.
   You can also click Apply UV in Blender's bridge panel.
4. Check the result. Ctrl+Z in Blender undoes the applied change.

Retopo Operations sends models for retopology. Bake Operations, below
UV Operations, sends models for baking.
Ctrl+S saves the Alpaca3D project; use Ctrl+Enter to send the result back.

UPDATING

Save your work. Install the new ZIP using Install from Disk, restart Blender,
and send the model again. Check the Alpaca3D.exe path if you moved the app.
Updating Alpaca3D delivers the ZIP but does not install it into Blender.

TROUBLESHOOTING

- No Alpaca tab: enable the add-on, place the pointer in the 3D Viewport,
  and press N to open its sidebar.
- Alpaca3D does not launch: check the Application path. A portable copy
  requires the complete application folder, not an EXE copied on its own.
- Apply is rejected after changes in Blender: send the model again.
- An old bridge version remains visible: fully restart Blender.

UV / RETOPO GEOMETRY RETURN (Bridge 0.1.37+)

A model sent to UV can be edited in Retopo and returned through the same UV
session. Install both the updated application and this add-on, restart Blender
and Alpaca3D, then Send again. Earlier transfers do not negotiate this feature.

Face deletion preserves source element correspondence and remaining UV maps,
materials, weights and custom attributes. Complex edits replace the object's
mesh while retaining the original mesh datablock (Fake User) as a backup;
new elements receive default data where no source correspondence exists.
The object, modifiers, transform and collection membership remain in place.

Geometry return with shape keys is rejected before applying changes. Changing
geometry/transforms in Blender after Send, or additional mesh data after a
geometry Apply, also rejects the result: Send again to establish a new baseline.
Adding/removing entire objects and returning a completely empty UV document
are not supported by this version. Maya retains the UV-only return contract.
