AutoSkeletonBuilder LITE
========================
A runtime auto-rigging plugin for Virt-A-Mate. Free edition.

WHAT IT DOES
------------
AutoSkeletonBuilder Lite takes a rigid CustomUnityAsset (hair, tentacles,
cloth strips, or any similar multi-piece mesh) and turns it into a
physically simulated, jiggling object - entirely inside VaM, with no
external rigging tool needed at runtime.

It automatically:
- Merges all the separate mesh pieces under a chosen root object into one
  continuous mesh (welding vertices that touch but don't literally share
  geometry, so pieces don't visually tear apart as they move).
- Detects each individual strand via real mesh connectivity, and handles
  BRANCHED meshes: a hairdo whose locks all weld together at the scalp is
  rigged as a proper bone tree, one chain per lock radiating from the
  attachment point.
- Places bones along the strand's real curvature (geodesic distance along
  the mesh surface), so spirals, hooks and U-shapes keep clean chains.
- Skins the mesh with a smooth curvilinear multi-bone blend: wide
  sections bend as a unit, no pinching at the joints.
- Physicalizes every bone from a single shared kinematic "Base", with
  stiffness tapering from root to tip for natural, whip-like motion.
- Anchors that Base automatically on the bone closest to the CUA's
  control point.
- Lets you link the result to any atom or body part, and PIN the bones
  touching that body part so the attached part stays glued to it while
  the free strands swing.

WHAT'S NOT IN THE LITE EDITION
------------------------------
- NO COLLISION SYSTEM. No colliders are generated: the object moves and
  sways, but passes through everything (including the body it is linked
  to). This also makes it cheaper on physics cost.
- NO ADVANCED PARAMETERS. Skin smoothing, linear/angular drag, swing and
  twist limits, solver iterations, auto mass, soft limits, smooth
  activation, rigidbody interpolation, joint projection and strand
  inversion are fixed at their tuned defaults instead of being exposed.

The full edition adds all of the above: capsule colliders fitted to the
mesh, self-collision control, friction, push-out speed limiting, plus
every advanced slider and toggle.

REQUIREMENTS
------------
1. Your CustomUnityAsset must be built with "Read/Write Enabled" checked
   on the mesh(es) in Unity's import settings. Without this, the plugin
   cannot read the mesh's vertices at runtime and will show a clear error
   telling you so.
2. VaM 1.20+ recommended. No other plugin is required.

INTERFACE
---------
LEFT COLUMN (always visible)
  Root object, bone count, weld threshold, skin blend width, mass per
  bone, joint spring, joint damper, tip softness.

RIGHT COLUMN
  [ ] --- LINK & PINNING ---     (collapsed; click to expand)
      Parent atom and body part (with search bars), link/unlink,
      auto-pin margin and buttons, base placement, snap to control.
  ALWAYS VISIBLE
      Activate physics, Build Skeleton, Reset (rigid mesh).
  [ ] --- BONE PINNING LIST ---  (collapsed, filled after a build)
      One "pinned" toggle per generated bone.

HOW TO USE
----------
1. Add AutoSkeletonBuilderLite.cs as a plugin on the CustomUnityAsset
   atom.
2. In "Root object (merges its children)", pick the parent object that
   contains all the mesh pieces you want combined (e.g. a full hairdo).
   If the list is empty, wait a few seconds - the CUA may still be
   loading, and the list refreshes itself automatically.
3. Adjust "Bone count (per strand)" and "Weld threshold (m)" if needed
   (defaults work for most assets).
4. Click "Build Skeleton". The mesh is rebuilt as one skinned object,
   fully frozen (kinematic) - nothing moves yet, by design. The Base is
   automatically anchored on the bone closest to the CUA's control point
   (see the log for which one was chosen).
5. (Optional) Open "LINK, PIN & ATTACH", pick a parent atom and body part,
   and click "Link Base to this body part" so the object follows it.
6. (Optional) Click "Auto-pin bones touching body part": every bone in
   contact with that body part is pinned (frozen, following the body
   rigidly) while the free strands keep simulating. Fine-tune with the
   per-bone toggles in "BONE PINNING LIST" or reset with "Unpin all
   bones".
7. Check "Activate physics" when you're ready - the object settles into
   motion smoothly over a short stiffness ramp.
8. "Reset (rigid mesh)" at any time reverts everything back to the
   original static mesh.

ATTACHING BOTH ENDS
-------------------
To hold an object at two different places (a cape between the shoulders,
a chain between two hands):

1. Build the skeleton and position the object where you want it.
2. Open "LINK, PIN & ATTACH", pick the first atom + body part, and use
   "Link Base to this body part" (or leave the Base as it is) so one end
   follows that anchor.
3. In the same section, pick the SECOND body part in the "Parent atom"
   / "Body part" selectors, then click "Attach to selected body part".
   The bones at that end become anchored to it. "Attachment size"
   chooses how they are picked: 0 uses contact detection (same as
   auto-pin), any other value takes that many bones nearest the target.
   Each attachment gets its own "Remove" button below.
4. Activate physics. The bones between the two anchors simulate and sag
   naturally; both ends stay put.

If the object does not touch its second anchor yet, set "Attachment
size" to the number of bones you want taken (e.g. 3) - they are picked
by proximity instead of contact. Keep some bones free in between, or
there is nothing left to simulate; the log warns you if that happens.

TIPS FOR GOOD RESULTS
----------------------
- If movement looks too stiff/robotic: lower "Joint Spring" (strongest
  lever), then lower "Tip softness". Both apply live, no rebuild.
  Reference with the default 0.02 kg bones: Spring 10 gives about 9 deg
  of gravity droop over a chain, Spring 3 about 29 deg, Spring 1 about
  87 deg (which starts losing the hairdo's silhouette).
- Spring scales with mass: raise "Mass per bone" tenfold and you need
  about ten times the spring, or the object collapses.
- If it wobbles or jitters: raise "Joint Damper" (0.14 is roughly
  critical damping for the default mass).
- If tips flop around lifelessly: raise "Tip softness" toward 1, or
  raise "Joint Damper".
- If wide sections pinch or crease at the joints: raise "Skin blend
  width" (e.g. 1.5-2.0) and rebuild. Increasing "Bone count (per
  strand)" helps too.
- If separate pieces visually tear apart at their seams: increase "Weld
  threshold (m)" slightly so nearby vertices merge properly. If
  unrelated pieces start incorrectly fusing together, lower it instead.
- Auto-pin margin ranges from 0.1 mm to 1 m (default 2 mm). If it grabs
  too many bones (free strands frozen), lower it and re-run after
  "Unpin all bones"; if it misses the contact area, raise it. The log
  prints the margin, the body part used and the contact count on every
  run.
- If the object does not move at all once physics is on, check the
  auto-pin log line: pinned bones are frozen by design, so if it says
  "all N bones are pinned" the object is rigid on purpose. Click "Unpin
  all bones", lower "Auto-pin margin" to a few millimetres, and run
  auto-pin again so only the bones really touching the body get pinned.
- The object passing through the body is expected in the Lite edition -
  pinning the contact bones is what keeps the attached part in place.

KNOWN LIMITATIONS
------------------
- Designed for elongated / branched strand-like geometry (hair,
  tentacles, straps, chains). Compact non-elongated blobs may rig less
  predictably.
- The plugin generates its own SkinnedMeshRenderer at runtime; it does
  not modify or save changes back to your original Unity asset.

VERSION
-------
Lite 2.13.2
- FIX: objects barely reacted to gravity. Unity derives a rigidbody's
  centre of mass from its COLLIDERS, and this edition creates none - so
  every bone had its centre of mass sitting exactly on its own joint
  anchor. Weight applied straight through the pivot produces no torque
  at all, which is why the chain would not fall. The inertia tensor was
  falling back to a default around a thousand times too large as well.
  Both are now computed from each bone's measured size, so the Lite
  edition moves like the full one.

Lite 2.13.1
- FIX: a scene where the object had only been built and had its physics
  started - no link, no pinned bones, no attachments - saved nothing, so
  on reload the skeleton was never rebuilt and the object came back
  inert. A rigged object now always records itself, and physics
  are switched back on once the bones exist.

Lite 2.13
- NEW: the setup is SAVED WITH THE SCENE. The Base link, the pinned
  bones and every attachment are restored on load, and the skeleton is
  rebuilt automatically once the CUA has finished loading ("Auto-build
  & restore on load", on by default). Scenes can now be shared ready to
  use instead of needing the whole setup redone by hand.
- NEW: PRESETS - Hair / Tentacle / Cape / Chain set mass, spring,
  damper, tip softness and the limits in one click.
- NEW: "Keep stiffness when mass changes" - the spring follows the mass
  slider, so raising the mass no longer makes the object sag flat.
- NEW: WIND - strength, turbulence and direction. Applied as an
  acceleration, so thick sections and thin tips react the same way.
- NEW: a warning past ~180 bones, where the solver cost starts to show.

Lite 2.12.1
- FIX: the "Parent atom" list was filled once when the plugin opened, so
  any atom added afterwards (the usual order - load the CUA, then add
  the Person) never showed up. It now follows the scene automatically,
  keeping your current selection whenever that atom still exists, and a
  "Refresh atom / body part lists" button forces it on demand.
- The attachment controls now sit inside "LINK, PIN & ATTACH" rather
  than in their own section: they are driven by the same "Parent atom"
  and "Body part" selectors, so separating them meant you could open
  the attachment section with no way to choose a target.
- NEW: section headers are now BUTTONS instead of checkboxes - click a
  header to fold or unfold it. The "-" / "+" in front tells you which
  it is.
- Colour-coded actions: "Build Skeleton" is green, everything
  destructive ("Reset", "Unpin all bones", "Clear all attachments",
  "Unlink Base", each attachment's "Remove") is red, and section headers
  share their own colour so they read as headers rather than settings.
- "Activate physics" and "Activate collisions" are highlighted so they
  stand out from the settings around them.
- NEW: ATTACHMENTS - anchor several parts of the object to different
  targets at once ("one anchor at each end"): a cape spanning both
  shoulders, a chain between two hands, a rope tied at each end. The
  bones in between keep simulating and hang between the anchors.

Lite 2.11.1
- FIX: on some assets the 2.11 pose capture made the object come out
  giant and floating above the scene. Which coordinate space BakeMesh
  writes into depends on the Unity version and the rig, so the plugin
  now tests each possible interpretation against the renderer's real
  on-screen bounds and keeps the one that matches - and falls back to
  the rest pose if none of them does.

Lite 2.11
- FIX: source meshes that carry their own rig were read in their BIND
  POSE, so anything posed by its own bones (a character tail curved away
  from its modelling shape) was rigged straight and snapped back the
  moment the skeleton was built. The current deformed geometry is now
  captured, blend shapes included.
- FIX: welding merged coincident vertices and averaged their UVs, which
  destroyed every UV seam - the texture stretched across the seam
  instead of jumping, smearing stripes along tails and hair locks.
  Welding now only groups vertices for the connectivity graph; the
  render mesh keeps all its original vertices, and coincident ones share
  the same skin weights so nothing tears apart.
- Custom normals, tangents and vertex colours are carried over from the
  source meshes instead of being recalculated or dropped (this used to
  flatten stylised shading and break normal-mapped materials).
- "Joint Spring" range raised to 300 for heavier assets.

Lite 2.10.4
- Auto-pin now warns when it has pinned every bone (or nearly all of
  them). Pinned bones are kinematic, so pinning the whole object makes
  it completely rigid - which looks exactly like "physics does nothing".
  A large "Auto-pin margin" (say 1 m) pins everything on most assets.

Lite 2.10.3
- FIX (root cause of the drift): the generated skeleton was a child of
  the CUA's root object. Once the atom is attached to a character, VaM
  re-parents the CUA's content under it, so the Transform hierarchy
  dragged every bone each frame while the plugin was pushing kinematic
  targets into PhysX for those same bodies. The two fought and the error
  accumulated in the direction of travel - the object drifted away
  uniformly, which is why pinning all the bones did not help. The
  skeleton now lives at the scene root and is moved only by physics.
- The anchor distance printed at build is now reported in real world
  centimetres (it was in the asset's local units, so it looked wrong on
  scaled assets).

Lite 2.10.2
- FIX (follow-up): the anchor drift fix only applied when the plugin's
  "Link Base" button had been used. If the CUA atom was attached to the
  character with VaM's own parent link instead, the Base was still just
  a Rigidbody dragged by a moving parent - so the object kept drifting,
  pinned bones included, since they hold their pose relative to it. The
  Base is now kinematically driven in both cases.
- NEW: "Diagnose anchor drift" button - reports how far the Base and the
  pinned bones are from their intended pose, in cm.

Lite 2.10.1
- FIX: an object linked to an animated character slowly drifted away
  from its anchor point over time, even when auto-pinned. Joint anchors
  were being silently recomputed by Unity whenever bodies slept and woke
  during the animation, and the Base was re-parented under a moving
  transform instead of being given proper kinematic targets. Anchors are
  now frozen at build, bodies never sleep, and the Base and pinned bones
  are driven with MovePosition/MoveRotation each physics step.
- Side benefit: the free strands now pick up the real velocity of the
  character's motion, so they swing from a dance animation instead of
  merely being carried along by it.

Lite 2.10 (same rigging pipeline as the full 2.10 release)
- Joint twist axis fixed (it defaulted to a perpendicular axis, so the
  twist limit clamped a bending plane and chains could not bend past
  8 degrees) and drive recalibrated for fluid, light motion.
- Existing scenes keep their saved values: reset Joint Spring / Joint
  Damper to get the new feel.

Questions or issues: please leave a comment on the resource page rather
than a low rating first - most setup issues are quick to resolve.
