ALPACA BRIDGE - INSTALLATION FOR MAYA

Bridge 0.2.11 is tested with Maya 2024 and Maya 2025 standalone/API (Python 3).
The interactive Maya 2025 panel is not separately verified.
Alpaca3D must be installed with Maya Bridge support.

INSTALLATION

1. Extract alpaca_maya_bridge-<version>.zip into a normal folder.
2. Open the extracted AlpacaMayaBridge folder. It must contain install.py
   and the alpaca_maya folder side by side. Keep this structure intact.
3. Start Maya and drag the extracted install.py from File Explorer into
   Maya's viewport. Do not drag the file directly from inside the ZIP.
4. The installer copies the bridge into the current Maya profile's scripts
   folder and adds an Alpaca button to the Alpaca shelf.
5. Restart Maya, especially when updating an existing bridge installation.
6. Click Alpaca. Under Application, click the folder button and select the main
   Alpaca3D.exe in your installation, not maya.exe or an EXE inside versions.

OPENING FROM THE SCRIPT EDITOR

If the shelf button is not available, open the Python tab in Maya's Script
Editor and run both lines:

import alpaca_maya
alpaca_maya.show()

FIRST TEST

1. In Object mode, select a test polygon mesh with a complete UV layout.
2. Under UV Operations, click Send. Under Import Settings, leave UV set empty to use each
   object's current UV set, or enter a specific set name.
3. Edit UVs in Alpaca3D and click Send to Maya or press Ctrl+Enter.
   Leave Auto apply enabled. For manual application, select the
   transfer under UV Operations and click Apply UV.
4. Check the result. One Undo command in Maya reverses the applied change.

Retopo Operations sends High/Low meshes for retopology. An existing editable
Low must have no construction history; UV transfer preserves history.
Bake Operations is below UV Operations and sends models for baking.
Export baked textures from Alpaca3D; baking does not use mesh Apply.
Ctrl+S saves the Alpaca3D project; use Ctrl+Enter to send the result back.

UV / RETOPO GEOMETRY RETURN (Bridge 0.2.9+)

UV Operations also supports: Send to UV, switch to Retopo, delete polygons,
switch back to UV, then Send to Maya. Update both Alpaca and this bridge,
restart them, and Send again to negotiate the new return protocol.

UV-only return keeps the existing live UV transfer behavior. Geometry return
keeps the same object/shape and applies a mesh snapshot. Previous construction
history remains connected to a backup input, but no longer drives the returned
topology. One Undo restores the previous connection; Redo reapplies the result.
Native alpacaMeshReturn network nodes retain the previous mesh, material
assignments and constraint metadata as a backup, and survive scene saving.

Source element IDs preserve remaining additional UVs, colors, materials and
creases. New elements get default material and no unknown secondary UV/color
data. Secondary UV constraint records are cleared after topology changes.
Geometry return with skin, blend shapes or other deformers is rejected before
changing the scene; use a history-free duplicate. UV-only still works.
Adding/removing entire objects and completely empty results are unsupported.
Changes in Maya after Apply may require a new Send to preserve those edits.

MAYA USER DATA FOLDER

The bridge installs into the scripts folder used by the current Maya profile.
To find it, run this in the Python Script Editor:

from maya import cmds
print(cmds.internalVar(userScriptDir=True))

If the user data root is C:\Autodesk, a typical Maya 2024 path is:
C:\Autodesk\2024\scripts\alpaca_maya

If Maya asks for a user data folder at startup, C:\Autodesk is one option.
To set this root persistently, set the Windows user environment variable
MAYA_APP_DIR to C:\Autodesk. Restart Maya from the updated environment;
sign out of Windows and back in if necessary. The bridge installer does
not change this variable or move an existing profile.

UPDATING AND TROUBLESHOOTING

- Repeat installation from the new ZIP and restart Maya. The installer
  backs up the previous package. It adds a shelf setup block to userSetup.py
  and backs up that file before modifying it.
- Updating Alpaca3D delivers the ZIP but does not install it into Maya.
- No module named alpaca_maya: install from the correct Maya version and
  check its scripts path using the command above. That path must contain
  the alpaca_maya folder with __init__.py inside it.
- No shelf button: use the Script Editor commands above to open the panel.
- Alpaca3D does not launch: check Application. Keep the complete application
  folder and its dependencies when using a portable copy.
- After Undo/Redo, opening a different scene, or changing source geometry,
  send again. References, instances, and component selection are currently
  unsupported by this bridge.
