FishSim - Fish Simulator

** Edit - Version 0.2.0 - the ‘Goldfish’ version is now available **
**Edit - Version v0.2.1 has a slight improvement to the pectoral fin action
**Edit - Version v0.3.0 is a first pass at a Blender 2.8 Beta version
**Edit - Version v0.3.1 updated for Blender 2.8 Release Candidate
**Edit - Version v0.3.2 updated for Blender 2.81
**Edit - Version v4.00.0 updated for Blender 4.00

For fun I’ve written an addon that works with the Rigify Shark rig (and an included custom Goldfish metarig). It allows you to create a target that you can then animate. Clicking ‘Simulate’ causes the fish to swim after the target, baking keyframes as it goes.

There are also tools to help copy and animate multiple rigs and meshes if the targets are generated and animated by one of the powerful tools available like CrowdMaster or Animation Tools.

Download the v4.00.0 addon:
Versions for Blender 2.79 to 3.6 are also available in the Github release section


Rigged models for a shark, goldfish, and archer fish are also available from the Github site.

A tutorial also - it’s a little old, but still relevant:

Extra information for the 'Goldfish version:

I’d be interested in any comments on the general philosophy of this addon. ie Rigify to create a rig with uniform controls, an addon like CrowdMaster to provide the ‘AI’, and an addon like FishSim to provide the link between the two. Perhaps the next version will use geometry nodes for the ‘boid’ behavior?


Thanks for sharing.


Absolutely a good idea.
Moreover it’s totally funny…
Dragons please!

Great work Nerk.

I think this is awesome.

This looks great mate! Look forward to trying it out soon.

Thanks for the comments! Version 2 - the ‘Goldfish’ version is coming along. After that my vague roadmap says ‘FlySim’, so @kabu, I don’t see why dragons shouldn’t fit that category.

Goldfish would be great. I’ve got a project that could be completely useful for!
And yes I think this is probably most useful for schools of fish, to get them animated quickly, otherwise I’d probably rather have the control over animation.
I still haven’t tried it out. Are the actions animator friendly after they’re created?
Keep up the good work!

Hi @Hammers, I have a couple of little projects planned myself.

I would use the CrowdMaster animated targets for background fish, and for the ‘hero’ character, animate the target directly to get a base swimming action. After that, they’re just keyframes - you can scale them, simplify them, bake to NLA strips and fade from auto generated keyframes to customised animation for key scenes. The auto generated keyframes affect the spine, tail fin and pectoral fins, but other parts of the rig like eyes and mouth can be animated separately.

Thanks for this great work

This is really neat… thanks for sharing.

I’m now finished with version 0.2 of the FishSim addon - the ‘Goldfish’ version.

This version includes a new Rigify Goldish metarig, which is available at the ‘Add Amature’ menu with the other Rigify metarigs as long as both FishSim and Rigify are enabled. It is basically the same as the shark rig, but with the shark dorsal fins moved back and new, more flexible dorsal fins added. The original shark metarig can still be used, but the new features are disabled.

The new version adds a ‘hover’ function, where the fish will hold it’s place with dorsal fin movement and air bladder. Of course this isn’t only relevant to goldfish - it applies to most aquarium and reef fish, and basically most fish you’re likely to model.

The Github site with the addon download and documentation can be found here:

Github site:

The goldfish model is on Blendswap here:

Goldfish model:

A Youtube guide to the extra features (The orignal guide is still relevant - you should watch that first if you haven’t seen it):

Hopefully someone finds a use for this! I know it’s not something you use every day, but it’s nice to know it’s there if you ever need it. I don’t have any more specific development in mind, at least for fish, but let me know if you find any problems with it.

i am always getting this error while installing

Exception in module register(): ‘C:\Users\Admin\AppData\Roaming\Blender Foundation\Blender\2.79\scripts\addons\FishSim-master\’
Traceback (most recent call last):
File “C:\Program Files\Blender Foundation\Blender\2.79\scripts\modules\”, line 350, in enable
File “C:\Users\Admin\AppData\Roaming\Blender Foundation\Blender\2.79\scripts\addons\”, line 534, in register
from . import metarig_menu
File “C:\Users\Admin\AppData\Roaming\Blender Foundation\Blender\2.79\scripts\addons\FishSim-master\”, line 193, in
metarigs_dict = get_metarig_list("")
File “C:\Users\Admin\AppData\Roaming\Blender Foundation\Blender\2.79\scripts\addons\FishSim-master\”, line 131, in get_metarig_list
metarigs_dict[f] = get_metarig_list(f, depth=1)
File “C:\Users\Admin\AppData\Roaming\Blender Foundation\Blender\2.79\scripts\addons\FishSim-master\”, line 142, in get_metarig_list
metarigs += [get_metarig_module(module_name, METARIG_DIR + ‘.’ + path)]
File “C:\Users\Admin\AppData\Roaming\Blender Foundation\Blender\2.79\scripts\addons\FishSim-master\”, line 92, in get_metarig_module
submod = importlib.import_module(name, package=MODULE_NAME)
File “C:\Program Files\Blender Foundation\Blender\2.79\python\lib\”, line 126, in import_module
return _bootstrap._gcd_import(name[level:], package, level)
File “”, line 981, in _gcd_import
File “”, line 931, in _sanity_check
SystemError: Parent module ‘FishSim’ not loaded, cannot perform relative import

Exception in module register(): ‘C:\Users\Admin\AppData\Roaming\Blender Foundation\Blender\2.79\scripts\addons\FishSim-master\’
Traceback (most recent call last):
File “C:\Program Files\Blender Foundation\Blender\2.79\scripts\modules\”, line 350, in enable
File “C:\Users\Admin\AppData\Roaming\Blender Foundation\Blender\2.79\scripts\addons\”, line 533, in register
File “C:\Users\Admin\AppData\Roaming\Blender Foundation\Blender\2.79\scripts\addons\FishSim-master\”, line 647, in registerTypes
ValueError: register_class(…): already registered as a subclass

Hi @cortesffm,

From the error messages, I think perhaps you have downloaded the wrong file from the github site. (The addon directory should be addons\FishSim, not addons\FishSim-master)

The latest zip file can be downloaded here:

I suggest you close Blender, delete the directory at FishSim-master directory under C:\Users\Admin\AppData\Roaming\Blender Foundation\Blender\2.79\scripts\addons as well as any FishSim directory and then try installing the file in the usual way.

By the way, version v0.2.1 is a slightly improved version. I’ll update the link on the first entry.

Fine, yes i got the wrong one. Everything is ok now. Thanks

This is exactly what I need! Wow, thanks so much! I am looking forward to using this and will share my project with you when I’m done.

Hope it works for you. I’ll be interested to see how it goes!

1 Like

I was checking out your other projects and they’re all fantastic. You are doing some great work, keep it up and let me know if you come up with something new!

Looks great once I figure out how to install plugins. Can we suggest fish like Guppies?

good work. Thank you