#### Repository
https://github.com/godot/godot-docs

http://docs.godotengine.org/en/latest/_static/docs_logo.png

#### Details
This contribution is made out of two brand new tutorials that walk the user through ways of animating and controlling thousands of objects in Godot. The inspiration came from the game ABZU, which has thousands of fish beautifully animated. 

By the end of the tutorial the reader is able to animate a fish like the one below:

http://docs.godotengine.org/en/latest/_images/all_motions_mask.gif

The unique thing about this animation is that it is done in the vertex shader rather than with bones and a skeleton. A skeleton is the go to form of animation, but it requires every bone for every object to be updated on the CPU. With vertex animation, the animation is calculated on the fly by the GPU and is thus much faster. The only limitation is that you have to make your animation in code rather than using animation software.

Using this method you are able to have thousands of fish on-screen at once all animated, even on low end hardware:

[Here](https://i.imgur.com/wxTVKQQ.gif) is an example of a scene captured on a low-end chromebook (the gif is too large to embed in the post).

The biggest difference I see this tutorial making is to expose users unfamiliar with rendering to an easy method to squeeze high-end performance out of low end-hardware. Using this tutorial you could easily animate thousands of objects on a mid-range smartphone. On a gaming computer you can easily animate tens of thousands of objects (or even hundreds of thousands, depending on the complexity of the mesh). Hopefully as users pick up on this tutorial we will see the creation of more complex scenes in Godot. 

#### Components
Each tutorial focuses on one type of node that can be used for drawing thousands of objects efficiently. The first uses the [MultiMesh](http://docs.godotengine.org/en/latest/classes/class_multimesh.html) and the second uses [Particles](http://docs.godotengine.org/en/latest/classes/class_particles.html).

MultiMeshes are typically used for drawing thousands of static objects, such as trees or grass. However, using vertex animation, you can animate the objects for little cost. MultiMeshes are a great way to squeeze performance out of low-end hardware. Currently, there are no tutorials in the official docs on how to use them, accordingly lots of users did not know that they exist, or even if they did, they do not know how to use it. Now, however, we should see them used more and more. 

Particles are usually used for VFX like explosions or trails behind objects. However, they take advantage of static instancing (which uses the GPU to draw the same object thousands of times very efficiently) and transform feedback (which uses the GPU to compute movement of objects. More tutorials can be added on particles because they are such a useful and powerful concept in game programming. Hopefully this tutorial serves as a good, practical introduction for new users. 

#### Links
[Part 1: Animating thousands of fish with MeshInstance](http://docs.godotengine.org/en/latest/tutorials/3d/vertex_animation/animating_thousands_of_fish.html)
[Part 2: Controlling thousands of fish with Particles](http://docs.godotengine.org/en/latest/tutorials/3d/vertex_animation/controlling_thousands_of_fish.html)

#### GitHub Proof of Authorship
- GitHub Account: https://github.com/clayjohn
- Pull Request: https://github.com/godotengine/godot-docs/pull/2184
- In order to get everything in the tutorial working I also fixed the following bugs: https://github.com/godotengine/godot/pull/25725, https://github.com/godotengine/godot/pull/25623
And I filled in the class reference for [MultiMesh](https://github.com/godotengine/godot/pull/25728)