MudBun: Volumetric VFX & Modeling

Animated Details | Manual | Quick Guide Video

Email | Discord | Official Forum Thread

Compatibility

• Windows is the only platform under active development, maintenance, and testing. Non-Windows platforms are not guaranteed to run MudBun and support for them is limited. WebGL is not supported for now due to its lack of compute shader capabilities at the time of development.
• Unity 2021.3 (LTS), 2022.3 (LTS), and 6 (LTS): Built-in render pipeline, URP, and HDRP.
• Later versions of 2021.3 seem to crash upon creating a MudBun renderer. Unity is aware of this problem and is working on a fix (tracked here). The latest version of 2021.3 that has been tested to for all render pipelines is 2021.3.26f. The state between version 2021.3.27f and 2021.3.39f is unknown.
• Meshes locked in Mesh Renderer Mode or exported from MudBun are just standard meshes and can be used without requiring MudBun at run-time, so they should be compatible on all platforms.
• Compute shader support is required.
• It is highly recommended to target hardware with dedicated GPUs, as MudBun uses compute shaders. It is not recommended to target hardware with integrated GPUs, unless MudBun is only used at edit-time to build meshes to be exported or locked at run-time.

MudBun: Volumetric VFX & Modeling

MudBun is a real-time volumetric VFX mesh tool. It procedurally generates meshes from non-destructive “brushes” that define shapes, distortion, and surface modification. MudBun is intended for localized VFX, but it can also be used for volumetric modeling and provides a convenient auto-rigging feature. Locked meshes, including auto-rigged ones, can be exported using Unity's official FBX exporter package.

There are various render & meshing modes available with different styles & characteristics. Supported meshing modes include: marching cubes (balanced), dual quads (faster & stylized), surface nets (can blend to/from dual quads), and dual contouring (slower, excels at preserving sharp features, can blend to/from dual quads).

MudBun can be used to create organic-looking meshes, which makes it a great combo with Boing Kit, a tool for producing organic bouncy effects.

MudBun is customizable. Users can extend the framework to create custom brush shapes, distortion brushes, modifier brushes, and shaders. It is also possible to define custom rigging logic for the auto-rigging feature.

Using a special data representation, MudBun frees users from worrying about the constraints of a finite voxel grid when working within typical game settings.

Features (details with animations):

• Volumetric mesh generation & modeling.
• Built-in VFX & primitive brushes.
• Distortion & modifier brushes.
• User-defined custom brushes.
• Brush groups (compound brushes).
• Render modes: smooth mesh, flat mesh, circle splats, quad splats, decal, ray-marched surface (experimental & URP only), ray-traced voxels (experimental & URP only).
• Meshing modes: marching cubes, dual quads, surface nets, dual contouring.
• Brush operators: union, subtract, intersect, dye, cull inside, cull outside, no-op.
• Dynamic voxel density.
• 2D Mode.
• Mesh collider generation.
• Mesh locking & auto-rigging.
• Mesh auto-smoothing.
• Automatic vertex welding of generated mesh.
• SDF texture generation (for GPU particle collision).
• Smooth corners for dual contouring.
• Render pipelines supported: built-in RP, URP, HDRP, and custom RP.
• Custom Unity shader graph nodes.
• Borderless voxel workspace.
• GPU memory budgeting & auto adjustment.

Limitations:

• MudBun is intended and optimized for localized real-time volumetric VFX mesh generation with dynamic brushes. Modeling and terrain editing with many brushes are possible but should be kept at a reasonable scale.
• Non-desktop devices (e.g. laptops, tablets, etc.) generally have weaker hardware than desktops and might not be suitable to run MudBun.
• MudBun currently does not render in prefab mode. Unity APIs related to prefab mode/stage are still in flux. As a workaround, edit prefab instances in scene view and use the options accessible via the inspector panel to apply overrides.
• Scaling brushes might not work as users would normally expect. Due to the nature of signed distance fields, there is no general solution for non-uniformly scaled shapes. Non-uniform scaling is still possible for some special cases and sometimes through approximation. A brush's local scales are usually not used as typical scales, but are interpreted as shape-specific parameters. For example, local scales are used as actual scales for box brushes, but are used as approximation for sphere brushes, and are interpreted as various dimensions like height & radius for cylinder & torus brushes.

Notice on Importing & Upgrading:

• When upgrading from older versions of MudBun, please DELETE the entire MudBun folder before re-importing from a newer package. File structures might have changed, and directly re-importing a new package on top of an existing one could cause unexpected issues.
• Please don't move MudBun's root folder and leave it as is after importing. Due to certain limitations, some resources are referenced relative to the root asset folder. Moving the MudBun folder around can break the references.

Release Notes

NOTICE: Importing The Package & Building Executables

When updating from older versions of MudBun, DELETE the entire MudBun folder before re-importing from a newer package. File structures might have changed, and directly re-importing a new package on top of an existing one could cause unexpected issues. Also, there are folders specific to render pipelines: Built-In RP, URP, and HDRP. They exist in the folders MudBun/Examples and MudBun/Shader/Render. Only import the folders that are specific to the current render pipeline and leave out the rest. It wouldn't matter in play mode in editor, but can cause errors when building executables. DO NOT move the MudBun root folder away from the Assets root folder, as this is a necessary trade-off for not having to force users to place custom shaders in the same folder as MudBun's built-in shaders.

NOTICE: Bugs in Unity's Package Manager

At the time of writing, versioning and caching of asset packages in Unity's package manager are buggy. The local copy of MudBun can be out of date even if the package manager displays the asset's version as up to date. To check the actual version of the local copy of MudBun, create and select a renderer, and the version will be shown in the inspector panel. If the displayed version is different from what the package manager shows, then a manual deletion of local package cache is required. To do so, navigate to "C:\Users\(username)\AppData\Roaming\Unity\Asset Store-5.x\Long Bunny Labs" and delete the cache for MudBun.

NOTICE: Compatibility with Newer Unity Versions

MudBun is maintained for LTS (Long Term Support) versions of Unity, which means it might not work on the latest versions of Unity that are not marked as LTS.

NOTICE: Click Selection

Later Unity versions have disabled click selection on invisible gizmos if gizmo drawing is disabled in the Unity editor. In this case, gizmos drawing must be enabled for click selection to work.

NOTICE: Examples

There are different examples in each render pipeline’s example folder. Be sure to check each example's out under its corresponding render pipeline. The distribution is pretty uneven, unfortunately; most of the examples are in built-in RP and HDRP.

Version 1.6.52:
- Dye brush blend modes.
- Fix underestimated brush bounds when parented under a brush group.

Version 1.6.51

- Fully port URP & HDRP render materials to shader graphs, including preset/special render materials.

- Fix EveryFrame compute mode.

- Supported Unity versions are now 2021.3, 2022.3, and 6.

- Unity versions 2019.4 and 2020.3 are no longer supported.

Version 1.5.50

- URP & HDRP shader graphs for Unity 2021 and newer (up to Unity 6). NOTE: URP 12+ decal shader graph is not at full feature parity as on older Unity versions due to technical limitations. URP/HDRP preset render material & HDRP decal shaders are not ported to shader graphs yet and are still authored using Amplify Shader Editor; In Unity 2022+, the following HDRP preset render materials are not compatible yet and will show error messages, which can be safely disregarded as long as they are not used (so some examples are not fully functional): Clay, Claymation, Floater. These compatibility issues will be addressed in future updates.

- Fix exception on importing MudBun regarding creating ProjectPrefs.asset.

Version 1.5.49

- Fix errors due to Unity's new expectation of 5 ints in indirect draw argument buffers for mesh generation.

Version 1.5.48

- Fix errors due to Unity's new expectation of 5 ints in indirect draw argument buffers.

- Generated mesh contains texture weight info (UV5).

- Fix raycast-based click selection for Unity 2022.3+.

- Fix creation menu item order for Unity 2022.3+.

Version 1.5.47

- Fix incorrect referencing of noise volume's boundary angle property by boundary radius.

- Fix missing tangents when locking mesh in mesh renderer mode.

- Fix compatibility refresh on updating MudBun version.

Version 1.5.46

- Fix incorrect culling of renderers in decal render mode.

Version 1.5.45

- Unity shader graph nodes. For example usage, see the splat & mesh shaders for URP 12.

- Use Unity shader graph for default splat & mesh render materials in URP 12. Note that due to technical limitations, for URP 12, the decal shader is only a partial port without proper lighting, and the rest of the preset shaders are not ported over.

- Amplify Shader Editor nodes are no longer maintained.

- Add compatibility packages for URP & HDRP 12 (Unity 2021.3).

- Burst is now a requirement.

- Skip locked renderers for raycast-based click selection.

Version 1.4.44

- Add chamfer boolean operator type (for union, subtract, and intersect).

- Add pipe & engrave operators.

- Fix missing color space conversion in shaders.

- Append mbn_ prefix to MudBun's noise shader functions to avoid naming conflicts with other shader libraries.

Version 1.4.43

- Add renderer option to invert normals.

- Remove unnecessary color space change when locking mesh.

- Fix auto-rigging not working in run-time calls to MudRendererBase.LockMesh.

- Fix false negative SdfJobHandle.Completed.

- Fix IL2CPP build error regarding missing MonoPInvokeCallback attribute.

Version 1.4.42

- Fix excpetion on welding vertices when there is no texture UV.

- Fix duplicate inverse transforms of sample points in CPU-based SDF evaluation, causing incorrect results when renderers are not at the origin.

- Fix renderers not respecting disabled brush objects.

- Change ICollection return types to the more specific IList.

Version 1.4.41

- Add Burst detection confrmation message.

- Gracefully handle the case where release of renderer resources is attempted before they are allocated, which can happen when a renderer is dynamically created and destroyed in the same frame.

Version 1.4.40

- Change public MudRendererBase.Brushes property type to IList<MudBrushBase>.

- Fix null reference exception when building mesh with null bone list.

Version 1.4.39

- Add property to adjust max bones per vertex for auto-rigging.

Version 1.4.38

- Fix MudBun not accounting for disabled renderers when locking renderer meshes recursively.

- Replace GetComponent with TryGetComponent in hot sections to avoid garbage collection at edit-time.

- Move call to MarkNeedsCompute out of GenerateMesh, so calling GenerateMesh without any change doesn't trigger a full re-compute of meshes.

Version 1.4.37

- More aggressive multiplier for ellipsoid SDF estination to mitigate false positive voxel node culling that resulted in holes in meshes.

- Fix editor undos in play mode causing job errors.

- Fix destroyed object access error spam in editor.

- Fix broken default locked mesh material for URP.

- Expose MudRenderer.NeedsCompute. Client code can use this property to refresh logic upon mesh recomputation.

- Fix Unity's automatic color space conversion when forwarding master color to shaders (if you've changed master colors to non-white then the visuals might change a bit).

- Fix unexpected creation of rigid bodies when convex colliders are forced but no rigid body creation is specified.

- Fix reverse triangle winding when number of negative components of renderer is odd in mesh render modes.

- Fix editor error regarding duplicate menu item identifiers.

Version 1.4.36

- Fix error on unsafe code in SdfEval.cs.

Version 1.4.35

- Add links to online scripting API documentation to Tools > MudBun menu and start screen (online documentation still WIP).

- Fix asynchornous Sdf.EvaluateSdfAndNormal not running.

- Signature change to CPU-based evaluation functions: SDF and normal evaluation now both output Sdf.Result values (requires potential update to user code).

- Fix Unity FBX Exporter not properly exporting metallic and emission by moving them to UV3 and UV4 (old locked meshes need to be re-locked for the new locked mesh shader to work properly).

- Fix missing screen space ambient occlusion in URP10+.

- Add options to generate UVs for texture (UV1) and light map (UV2) when locking meshes in mesh renderer mode.

- Remove GC.Alloc calls from enum-int conversions.

- Cache material validation to improve play mode performance in editor.

Version 1.4.34 "Raycasts"

- CPU-based computations: SDF evaluation, gradient evaluation, raycasts, snapping to surface.

- Raycast-based click selection by default. Gizmo-based click selection is still an option on renderers.

- Burst is now required to use raycast-based click selection & CPU-based computations.

- MudMaterial.IntWeight is renamed to MudMaterial.TextureWeight to better reflect its use in default shaders (users can still do whatever they want with it in custom shaders).

- Add noise modifier brush.

- Add MUDBUN_FAST_ITERATION define in CustomBrush.cginc for even faster iteration.

- Only fill in necessary default values for render materials (improves build time by skipping compilation of unused render material shaders).

- Fix edge cases of voxel edges perfectly lining up with zero isosurface.

- Fix distortion brushes only being applied to the first brush group and not subsequent brush groups.

- New HDRP example: Raycasts

Older change log truncated due to character limit. See readme file for full log.