========================================================================
  CRACK DECAY  -  Procedural Damage Generator for Blender
========================================================================

  A single-file Blender add-on that carves detailed, art-directable
  damage into any mesh: wandering branching cracks, irregular holes and
  pits, broken-off corners, edge chips, plus micro-noise, relaxing,
  bevels and remesh finishing - all built with a NON-DESTRUCTIVE boolean
  workflow you can regenerate and tweak freely, then bake when happy.

  Version:        1.0.0
  Compatibility:  Blender 3.0 - 4.x  (pure Python + bmesh, no dependencies)
  License:        MIT


------------------------------------------------------------------------
  WHAT'S IN THIS ZIP
------------------------------------------------------------------------

  Crack Decay.py   -  the add-on (this is the file you install)
  README.txt       -  this file


------------------------------------------------------------------------
  INSTALLATION
------------------------------------------------------------------------

  1. Keep "Crack Decay.py" as a .py file (do NOT unzip it further or
     rename the extension).

  2. Open Blender.

  3. Go to:  Edit  >  Preferences  >  Add-ons.

  4. Click  "Install..."  (top-right).  In Blender 4.2+ use the
     drop-down  "v"  >  "Install from Disk...".

  5. Browse to "Crack Decay.py", select it, and click
     "Install Add-on".

  6. In the add-on list, tick the checkbox next to
     "Object: Crack Decay"  to enable it.

  7. (Optional) Click the star / "Save Preferences" so it stays enabled
     next time you open Blender.


------------------------------------------------------------------------
  OPENING THE PANEL
------------------------------------------------------------------------

  1. In the 3D Viewport, select a MESH object.

  2. Press  N  to open the right-hand Sidebar.

  3. Click the  "Crack Decay"  tab.


------------------------------------------------------------------------
  QUICK START  (30 seconds)
------------------------------------------------------------------------

  1. Select your mesh.
  2. Click a preset:  Light  /  Worn  /  Heavy  /  Ruined.
     (All sizes auto-scale to fit your object.)
  3. Press  "GENERATE DAMAGE".
  4. Not feeling it?  Hit the refresh icon ("New Seed") to roll a new
     variation, or "Regenerate Damage" after changing any setting.
  5. Happy?  Press  "Apply"  to bake the damage into the real mesh.
  6. Want it gone?  Press  "Clear"  to remove everything and leave the
     original object untouched.

  The damage is a LIVE boolean preview until you press Apply, so you can
  experiment as much as you like with zero risk to your mesh.


------------------------------------------------------------------------
  THE PANELS
------------------------------------------------------------------------

  Main
    - Status of the active object, preset buttons, Seed + New Seed,
      and the Generate / Apply / Clear actions.

  Cracks
    - Count, Length, Width, Depth and per-crack length variation.
    - Wiggle (chaos), Roughness, Taper (pointiness), Segments (resolution).
    - Branches (side forks) and Branch Scale.

  Holes
    - Count, Size Min/Max, Penetration (shallow scoop -> deep puncture),
      Irregularity (smooth -> rocky), and cutter Detail.

  Broken Corners & Chips
    - Corner Breaks + Break Size (sharp convex corners are auto-detected).
    - Edge Chips + Chip Size (small nicks along sharp convex edges).
    - Jaggedness of the broken surfaces.

  Surface Detail & Finishing  (applied when you press Apply)
    - Tag Damage Surfaces: gives cut faces an inner material and builds a
      "CrackDecay_Damage" vertex group  (great for texturing later).
    - Micro Noise: fractal displacement for a rough, broken look.
    - Relax Damage: smooths boolean artifacts.
    - Rim Bevel: chamfers sharp damage rims.
    - Dissolve Flat Faces / Triangulate N-gons: topology clean-up.
    - Shading: Keep / Smooth (angle-based) / Flat.
    - Voxel Remesh: unify topology  (WARNING: discards UVs, materials
      and vertex groups).

  Advanced
    - Boolean Solver (Exact = robust, Fast = quicker but less reliable).
    - Show Cutters: reveal the hidden boolean cutter objects as wireframes.


------------------------------------------------------------------------
  TIPS
------------------------------------------------------------------------

  * Presets are tuned then scaled to your object automatically - start
    there, then fine-tune individual panels.

  * If "No damage geometry was generated" appears, your object may have
    no sharp corners/edges (for corner breaks / chips) - enable Cracks or
    Holes, which work on any surface.

  * Keep the Exact solver unless you need speed; Fast can fail on
    overlapping or coplanar geometry.

  * After Apply, the "CrackDecay_Damage" vertex group and inner material
    make it easy to mask/texture only the broken surfaces.

  * Voxel Remesh is destructive to UVs/materials/groups - only use it if
    you want a clean unified mesh and don't need those.


------------------------------------------------------------------------
  UNINSTALL
------------------------------------------------------------------------

  Edit  >  Preferences  >  Add-ons  >  find "Object: Crack Decay"  >
  expand it  >  "Remove".


------------------------------------------------------------------------
  LICENSE
------------------------------------------------------------------------

  MIT License.  Free to use, modify and distribute.

========================================================================
