Mushroomer

Purpose

The "Mushroomer" takes a selection of editable mesh objects (the 'mushrooms') and distributes them on the surface of another editable mesh (the 'target object'). The script parents the mushrooms to the nearest three vertices in the target object. The distribution starts from a selected face (or faces), and the script uses pathing algorithms to determine which other faces receive mushrooms. The mushrooms can either be supplied by the user with shape key animation on frames 0-100, or with a set of shape keys which the script will generate an animation of smooth transitions from one shape to the next.

Status

The Mushroomer is currently in BETA status.

The latest revision is available here.

Prerequisites

Python must be 3.1.2 or greater. Open a new console window in blender to check which version you are using.

Currently the script is not an add-on. To use it open it in a text editor and click run script. Press spacebar to search for "Mushroomer".

Both the mushrooms and the target object must be selectable, editable, local meshes.

If you simply want the mushrooms to be distributed and not to have any animation data added, you do not need to create 'lifecycle' shape keys on the mushrooms. If you want to use a manually timed animation simply create as many shape keys as you wish and animate their values. The animation of the mushrooms should be contained within frames 0-100. If you wish to use auto-animation the mushrooms need to have a

shape keys are used to automatically add animation, variation or bend the mushrooms upwards. they must have an alphabetic prefix and must end in a number (eg. bend1,bend2,bend3 is acceptable. bendA,bendB,bendC is not). to make the mushrooms grow upwards add a shape which makes the object bend up its local Y axis. the script will automatically add a driver to turn up the value as the mushroom gets tilted away from the vertical. the mushrooms get vertex parented by the script to the nearest face on the target.

Optionally the script can add a modifier to each mushroom instance to shrinkwrap the base (or any vertices you wish) to the target object. To use this feature you need to weight paint a vertex group in each mushroom object. This vertex group can then be selected in the script's UI.

Parameters

the mushrooms get added to a group, so you can delete them easily when you realise that glowing mushrooms are no longer in vogue.

the mushroomer works by populating the selected face and then looking for neighbouring faces to crawl onto and populate. this variable sets how many times the face crawling algorithm will find run.

the frame number to start the crawling on.

each face will be populated with a family of mushrooms. to choose how many mushrooms are in each family you get to choose the first and the last family size, how these two values are interpolated, and how much jitter is added to the family size. for example if you choose to have 5 generations and the first family size is 1 and the last is 5 and you have 0 jitter, the sizes wil be 1,2,3,4,5.

the “child bearing age” is how old a generation gets (in number of frames) before it grows a family of mushrooms on a neighbouring face. you can add jitter too.

to animate the mushrooms you can either manually create animation data on your mushroom object using shape keys (between frame 0-100), or you can create a sequence of numbered shapes (eg. s1,s2,s3...) which the script will apply in order with smooth transitions between. the death age is the length of time (in frames) between the first animated shape key on that mushroom to the last.

to make sure the animation looks a bit more organic the children in any one generation can be born over a length of time (the generational spread) rather than all at once. if you want your mushrooms to have twins, triplets, quadruplets etc all simultaneously then you can set this to 0. you can even add jitter.

the script tries to size the mushrooms so they don’t bump into each other. your job is to make sure that the mushroom model has any rotation or scaling applied to it, its origin is dead central at the bottom (the origin is the part placed on the surface) and that the mesh fits in a 1 blender unit radius in the XY plane. lazy pack is faster but tends to leave more gaps, tight pack leaves less gaps but is much slower. packing works better with larger family sizes and squarer (rather than rectangular) quads (rather than tris).

by default the script will pick a random mushroom from the selection. you can make the script choose a mushroom (rather than at random) by painting vertex weights on the target object. if one of your mushrooms is called “tallmushroom” then painting a group called “OBtallmushroom” will make sure that the specific mushroom “tallmushroom” is used on those faces. if you paint more than one group on any given face then the amount of each mushroom type used on that face will be roughly proportional to the weights of the different groups.

by default the script will keep materials associated with their objects. if you want all of the mushrooms on any given face to receive the material “red” then you need to paint the face with a group called “MAred”. if you want the material to be selected completely at random, check the randomize materials box.

“limit to vertex group” limits the paths of mushrooms to growing only on faces in the given group.

there are different algorithms for spreading the mushrooms around the surface of the target object. put briefly “splurge” grows forked paths which can cross over each other and grow any which way they want. “crossed paths” grows paths which try to avoid each other but will cross if there’s nowhere else to go. “forked paths” grows paths which fork but will never cross. “simple selection increase” is the same as pressing Ctrl+ to grow a selection. “conways” allows you to play the slowest implementation of the game of life on the face of a mesh. some of the path algorithms read the parameters here: upwards attraction makes the paths prefer to grow up, probability of fork is the chance a path will try to fork (result depending on if there is space to) at each iteration. the family wipeout chance is the chance the fork will just die out.

the mushrooms get added to a group, so you can delete them easily when you realise that glowing mushrooms are no longer in vogue.

the mushroomer works by populating the selected face and then looking for neighbouring faces to crawl onto and populate. this variable sets how many times the face crawling algorithm will find run.

the frame number to start the crawling on.

each face will be populated with a family of mushrooms. to choose how many mushrooms are in each family you get to choose the first and the last family size, how these two values are interpolated, and how much jitter is added to the family size. for example if you choose to have 5 generations and the first family size is 1 and the last is 5 and you have 0 jitter, the sizes wil be 1,2,3,4,5.

the “child bearing age” is how old a generation gets (in number of frames) before it grows a family of mushrooms on a neighbouring face. you can add jitter too.

to animate the mushrooms you can either manually create animation data on your mushroom object using shape keys (between frame 0-100), or you can create a sequence of numbered shapes (eg. s1,s2,s3...) which the script will apply in order with smooth transitions between. the death age is the length of time (in frames) between the first animated shape key on that mushroom to the last.

to make sure the animation looks a bit more organic the children in any one generation can be born over a length of time (the generational spread) rather than all at once. if you want your mushrooms to have twins, triplets, quadruplets etc all simultaneously then you can set this to 0. you can even add jitter.

the script tries to size the mushrooms so they don’t bump into each other. your job is to make sure that the mushroom model has any rotation or scaling applied to it, its origin is dead central at the bottom (the origin is the part placed on the surface) and that the mesh fits in a 1 blender unit radius in the XY plane. lazy pack is faster but tends to leave more gaps, tight pack leaves less gaps but is much slower. packing works better with larger family sizes and squarer (rather than rectangular) quads (rather than tris).

by default the script will pick a random mushroom from the selection. you can make the script choose a mushroom (rather than at random) by painting vertex weights on the target object. if one of your mushrooms is called “tallmushroom” then painting a group called “OBtallmushroom” will make sure that the specific mushroom “tallmushroom” is used on those faces. if you paint more than one group on any given face then the amount of each mushroom type used on that face will be roughly proportional to the weights of the different groups.

by default the script will keep materials associated with their objects. if you want all of the mushrooms on any given face to receive the material “red” then you need to paint the face with a group called “MAred”. if you want the material to be selected completely at random, check the randomize materials box.

“limit to vertex group” limits the paths of mushrooms to growing only on faces in the given group.

there are different algorithms for spreading the mushrooms around the surface of the target object. put briefly “splurge” grows forked paths which can cross over each other and grow any which way they want. “crossed paths” grows paths which try to avoid each other but will cross if there’s nowhere else to go. “forked paths” grows paths which fork but will never cross. “simple selection increase” is the same as pressing Ctrl+ to grow a selection. “conways” allows you to play the slowest implementation of the game of life on the face of a mesh. some of the path algorithms read the parameters here: upwards attraction makes the paths prefer to grow up, probability of fork is the chance a path will try to fork (result depending on if there is space to) at each iteration. the family wipeout chance is the chance the fork will just die out.