{"id":21361064,"url":"https://github.com/antzgames/godot_vertex_animation_textures_plugin","last_synced_at":"2025-04-15T11:11:58.722Z","repository":{"id":262641989,"uuid":"887896190","full_name":"antzGames/Godot_Vertex_Animation_Textures_Plugin","owner":"antzGames","description":"A plugin that extends the MultiMeshInstance3D node to support instanced vertex animations using vertex texture data.","archived":false,"fork":false,"pushed_at":"2025-02-13T07:42:32.000Z","size":38718,"stargazers_count":34,"open_issues_count":2,"forks_count":7,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-15T11:11:40.578Z","etag":null,"topics":["3d-animation","3d-graphics","addon","godot","godot4","plugin","vertex-animation","vertex-animation-texture"],"latest_commit_sha":null,"homepage":"","language":"GDScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/antzGames.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-13T13:24:05.000Z","updated_at":"2025-04-07T16:25:05.000Z","dependencies_parsed_at":"2024-12-07T02:29:27.830Z","dependency_job_id":null,"html_url":"https://github.com/antzGames/Godot_Vertex_Animation_Textures_Plugin","commit_stats":null,"previous_names":["antzgames/godot_vertex_animation_tool_plugin","antzgames/godot_vertex_animation_textures_plugin"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antzGames%2FGodot_Vertex_Animation_Textures_Plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antzGames%2FGodot_Vertex_Animation_Textures_Plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antzGames%2FGodot_Vertex_Animation_Textures_Plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antzGames%2FGodot_Vertex_Animation_Textures_Plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/antzGames","download_url":"https://codeload.github.com/antzGames/Godot_Vertex_Animation_Textures_Plugin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249058384,"owners_count":21205911,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d-animation","3d-graphics","addon","godot","godot4","plugin","vertex-animation","vertex-animation-texture"],"created_at":"2024-11-22T06:08:21.133Z","updated_at":"2025-04-15T11:11:58.714Z","avatar_url":"https://github.com/antzGames.png","language":"GDScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Godot Vertex Animation Textures Plugin\n\nA plugin that extends the `MultiMeshInstance3D` node to support instanced vertex animations\nusing vertex texture data generated by a Blender add-on, with a vertex shader inside [Godot Engine](https://godotengine.org).\n\nThe plugin is designed to simplify the process of animating meshes using VATs, providing a seamless integration with the Godot workflow.\n\nSee video of the plugin and demos here: \n\n[![YouTubeVideo](https://github.com/user-attachments/assets/c3af1ccb-24cb-4b5e-9f27-fd705b26e70d)](https://youtu.be/BIbEaiVOu6k)\n\n\n## What are Vertex Animation Textures?\n\nVertex Animation Textures (VAT) bakes animations of a mesh into textures. \nThese textures can then be used to create motion in a game engine.\n\nBest to watch this [video](https://www.youtube.com/watch?v=3ep9mkwiOjU) to understand fully.\n\n## Preview\n\n![github](https://github.com/user-attachments/assets/855ad356-6c63-4717-93e2-f058ad99f6ce)\n\n\n## Features\n\n- Can support multiple baked in animations (supports a total of 8192 combined frames).\n- Animation tracks' metadata is configured in the editor, not the code.\n- Animations tracks can be different frame sizes.\n- Ability to set a unique animation track per instance.\n- Ability to control the alpha channel for individual instances.\n- All the `MultiMeshInstance3D` features such as a unique transform (scale, rotation, and position) per instance.\n- Works on all renderers, and on HTML builds.\n\n## Limitations\n\n- Mesh must be less than 8192 vertices.\n- Total number of frames for all animations must be less than 8192.\n- No blending or transitions between animation tracks possible.\n- Animations will always loop, so you need to develop a custom solution for chaining different animations.\n- `MultiMeshInstance3D` `custom_data` is used by this plugin so you will not have access to it.\n\n## Requirements\n\n- Godot 4.x\n- Blender:\n\t- For Blender 3.x use: [Not Unreal Tools - Vertex Animation](https://github.com/yanorax/unreal_tools) \n\t- For Blender 4.x use: [Godot VAT Blender Tools](https://github.com/antzGames/Godot_VAT_Blender_Tool)\n- An animated 3D model with less than 8192 total vertices.\n- For encoding multiple baked in animations, you will need to learn how to concatenate multiple animation tracks into one animation track in Blender.  This is the hardest part of using this solution.  I have created a video on how to append (concatenate) Blender NLA strips into a single track here: https://youtu.be/YFPywP6LMZU\n\n## Installing\n\nMaybe if this plugin gets noticed, I will add it to Godot's AssetLib.  Until then follow these instructions:\n\n- Download this repository as a ZIP file.\n- Extract the ZIP file.\n- Copy the `addons` directory from the extracted ZIP file into your Godot project's `res://` filesystem.\n- Go to `Project \u003e Project Settings \u003e Plugins` and enable **Godot Vertex Animation Textures Plugin**.\n- Test to see if you can add the new `VATMultiMeshInstance3D` node into a scene.\n\n## `VATMultiMeshInstance3D`\n\nThis plugin provides a new node called `VATMultiMeshInstance3D` which inherits `MultiMeshInstance3D`.\n\n\u003cimg src=\"https://github.com/user-attachments/assets/e979158a-5bb1-43a5-9129-1ca210492b1c\" width=\"503\"\u003e\n\nThe Scene dock with show warnings when you first create a `VATMultiMeshInstance3D` node indicating that you need \nto define animation track data and add a `MultiMesh`.\n\n\u003cimg src=\"https://github.com/user-attachments/assets/f82b305b-ffc0-4cff-92b4-6e0b7d7873d8\" width=\"50%\"\u003e\n\nError messages will also appear in the Output console.\n\n\u003cimg src=\"https://github.com/user-attachments/assets/310cdb80-80f9-476a-8a73-e5e700d6dbdf\" width=\"50%\"\u003e\n\n## `VATMultiMeshInstance3D` Properties\n\n- **Instance Count**: `int` = the number of instances\n- **Rand Anim Offset**: `bool` =  randomize the animation offset (true/false)\n- **Animation Tracks**: `Array[Vector2i]` = the list of animation tracks with start frame = x, end frame = y information. \n\n\u003cimg src=\"https://github.com/user-attachments/assets/790f897a-ef70-434d-afa3-6acc55c255fc\" width=\"332\"\u003e\n\n## `VATMultiMeshInstance3D` Functions\n\n### Set/update functions\n\n#### `update_all_instances`(animation_offset: float, track_number: int, alpha: float)\n\n- Updates ALL INSTANCES with the provided `animation_offset`, `track_number`, and `alpha` unless `rand_anim_offset = false`, where it sets the `animation_offset` to 0.\n\n#### `update_instance_animation_offset`(instance_id: int, animation_offset: float)\n\n- Updates the current `instance_id` with the provided `animation_offset` (0..1), unless `rand_anim_offset = false`, where it sets the offset to `0`.\n\n#### `update_instance_track`(instance_id: int, track_number: int):\n\n- Updates the current `instance_id` with the provided `track_number` (`0`..`number_of_animation_tracks - 1`)\n\n#### `update_instance_alpha`(instance_id: int, alpha: float):\n\n- Updates the current `instance_id` with the provided `alpha` (`0`..`1`)\n\n### Get helper functions\n\n#### `get_start_end_frames_from_track_number`(track_number: int) -\u003e Vector2i\n\n- Get animation start/end frame `Vector2i` from `track_number`. `track_number` must be within (`0`..`number_of_animation_tracks - 1`)\n\n#### `get_start_end_frames_from_instance`(instance_id: int) -\u003e Vector2i\n\n- Get animation start/end frames `Vector2i` from `instance_id`. Instance must have been initialized.\n\n#### `get_track_number_from_track_vector`(track_vector: Vector2i) -\u003e int\n\n- Get `track_number` from start/end frame `Vector2i`. Returns `-1` if not found.\n\n#### `get_track_number_from_instance(instance_id: int)` -\u003e int\n\n- Get `track_number` from `instance_id`. Returns `-1` if not found.\n\n## `MutiMeshInstance3D` `custom_data`\n\n`MultiMeshInstance3D` `custom_data` is used by this plugin.  Here is how it is used:\n\n- `custom_data.r` = **animation offset**: used to randomize instances playing the same animation track\n- `custom_data.g` = **animation start frame**\n- `custom_data.b` = **animation end frame**\n- `custom_data.a` = **alpha of mesh**: used to fade in/out a unique instance\n\n## Vertex Animation Shader\n\nThe magic of vertex animations happens both in Blender and in the shader. \nThis is why you should understand what is happening in the shader.\n\nTo make it easy, it is recommended you use `GeometryInstance3D \u003e Geometry \u003e Material Override` \nto add the a new `ShaderMaterial`.\n\nIn the `Shader` property select `Quick Load` and select: `vat_multiple_anims.gdshader`\n\nOnce loaded expand `Shader Parametrs` and you will have access to configure the following\nshader parameters:\n\t\n- `FPS`: How many frames to play per second.  Use the same value you see in Blender.\n- `Offset Map`: A texture that encodes the position of each vertex for every frame.\n- `Normal Map`: A texture that encodes the normal of each vertex for every frame.\n- `Texture Albedo`: The UV color texture that is used for the mesh.\n- `Specular`, `Metallic`, `Roughness`: See Godot [docs](https://docs.godotengine.org/en/stable/tutorials/3d/standard_material_3d.html) for more information.\n\n\n\u003cimg src=\"https://github.com/user-attachments/assets/ef4625bc-910a-41cc-b90b-51867b61c7e8\" width=\"350\"\u003e\n\nMake sure both offset and normal textures are imported with Lossless format.\n\nThe `custom_data` in the `MultiMeshInstance3D` and the shader parameters are passed to the shader\nto do its magic.  Here is some of the shader code that uses this data:\n\t\n```C++\n\nuniform sampler2D offset_map;\nuniform sampler2D normal_map;\nuniform sampler2D texture_albedo;\n\nuniform float fps;\n\nuniform float specular : hint_range(0,1);\nuniform float metallic : hint_range(0,1);\nuniform float roughness : hint_range(0,1);\n\nvarying flat vec4 custom_data;\n\nvoid vertex(){\n\tcustom_data = INSTANCE_CUSTOM;\n\n\tfloat start_frame = custom_data.g;\n\tfloat end_frame = custom_data.b;\n\t\n\tfloat num_frames = end_frame - start_frame;\n\tfloat frame_offset = num_frames * custom_data.r;\n\t\n\t...\n}\n\t\t\nvoid fragment(){\n\tvec3 albedo_col = texture(texture_albedo, UV).rgb;\n\n\tALPHA = custom_data.a;  // fader\n\t\n\tALBEDO = albedo_col.rgb;\n\tMETALLIC = metallic;\n\tROUGHNESS = roughness;\n\tSPECULAR = specular;\n}\n```\n\n## Demos\n\nThere are two demo scenes in the `demo` subfolder:\n\t\n- **MultipleAnimations**: 108 instances with 20 animations, with different scales, and positions.\n- **AlphaTest**: Shows how to control alpha so that you can fade in/out individual instances.\n\nThe skeleton mesh included in the demo has 20 baked in animations.\n\n## Godot games made with this plugin\n\nitch.io: [Skeletron 2084](https://antzgames.itch.io/skeletron2084)\n\nYouTube: [Skeletron 2084 Gameplay](https://youtu.be/zTJlpS3jQCc)\n\n## Blender Add-On Guide\n\n- Blender 3.x use: [Not Unreal Tools - Vertex Animation](https://github.com/yanorax/unreal_tools) \n- Blender 4.x use: [Godot VAT Blender Tools](https://github.com/antzGames/Godot_VAT_Blender_Tool)\n\n1. Download the files from the correct addon version and install **vertex_animation.py** in the Blender -\u003e **Edit** -\u003e **Preferences...** -\u003e **Add-ons** -\u003e **Install...** menu. In the **3D Viewport** side bar, you should now have a **Not Unreal Tools** or **Godot Blender Tools** menu and if selected it will show a **Vertex Animation** panel.\n2. In **Object Mode** select the object you want to process, make sure the current animation you want is selected and playable in the **Timeline**.\n3. Adjust the **Frame Start**, **End** and **Step** values as required. Changing these settings will update corresponding **Timeline** values.\n4. Click the **Process Anim Meshes** button. This will create a new object named **export_mesh** in the **Outliner**, this is the special mesh that will be animated. In the source .blend file path there will be a newly created folder called **vaexport** and inside will be two files; **normals.png** and **offsets.exr**.\n5. The **export_mesh** needs to be exported as a glTF file for importing into Godot. Select the **export_mesh** object in the **Outliner** and then from the Blender **File** menu, select **Export** -\u003e **glTF 2.0 (.glb .gltf)**. Make the following changes to the export options and then click the **Export glTF 2.0** button:\n\t- Include -\u003e Selected Objects (**enable**)\n\t- Geometry -\u003e Materials (**disable**)\n\t- Animation -\u003e Animation, Shape Keys, Skinning (**disable all**)\n\t- Filename -\u003e can rename to anything\n\n![install](https://github.com/user-attachments/assets/85fd4f4d-177f-48de-bc1c-87c709d924e4)\n\n![tool](https://github.com/user-attachments/assets/a8943e6a-e3cc-447c-ad58-bc5898df2b8f)\n\n## Godot Import Guide\n1. You should now have 3 files generated from Blender: **normals.png**, **offsets.exr** and **export_mesh.glb** (whichever filename was chosen, this guide will refer to the default name).\n2. Copy the files into the Godot project folder of your choice. Godot will run the import process as soon as it detects the new files. The import settings for each file still need more changes to ensure all of them work properly with the vertex shader.\n3. In the Godot **FileSystem** dock, select the glTF file (**export_mesh.glb**) and then click the **Import** dock (default location is docked along side of the **Scene** tree). [Godot Docs - Importing 3D Scenes](https://docs.godotengine.org/en/stable/getting_started/workflow/assets/importing_scenes.html)\n4. Make the following adjustments and then click the **Reimport** button. There should be a new file called **export_mesh.mesh** in the same folder as the glTF file (**export_mesh.glb**). \n\t- Meshes:\n\t  - Compress -\u003e (**disable**)\n\t  - Ensure Tangents -\u003e (**disable**)\n\t  - Storage -\u003e **Files (.res)**\n\t- Animation:\n\t  - Import -\u003e (**disable**)\n5. Add a MeshInstance or MultiMeshInstance node to the scene. Drag the **export_mesh.mesh** file into the Mesh parameter slot for a MeshInstance or the Mesh parameter slot inside the MultiMesh for a MultiMeshInstance node. This guide will not cover loading Mesh resources via script.\n6. The import settings for **normals.png** and **offsets.exr** will need to be updated after they are added into the shader parameters since Godot will make changes based on what node the image was applied to (3D nodes apply import settings for images used in 3D).\n7. Apply the custom vertex animation shader material to a MeshInstance/MultiMeshInstance. Recommend using the GeometryInstance -\u003e Geometry -\u003e Material Override slot.\n8. Go to the **Shader Parameters** and click the drop-down arrow and select load for the following parameters:\n\t- Offset Map -\u003e load **offsets.exr**\n\t- Normal Map -\u003e load **normals.png**\n9. Now find **normals.png** and **offsets.exr** in the **FileSystem** dock, go to Import settings, make the following changes for both files and click the **Reimport** button:\n\t- Compress:\n\t  - Mode -\u003e **Lossless** for **normals.png**, **Uncompressed** for **offsets.exr** \n\t- Flags:\n\t  - Repeat -\u003e (**disable**) when changing the current frame using an AnimationPlayer or via script. (**enable**) when looping animations using shader TIME.\n\t  - Filter -\u003e (**disable**)\n\t  - Mipmaps -\u003e (**disable**)\n10. If you are importing more image files such as albedo textures, refer to [Godot Docs - Importing Images](https://docs.godotengine.org/en/stable/getting_started/workflow/assets/importing_images.html). For palettes and texture masks, recommend using Lossless compression and disable Filter and Mipmaps, so there is no blending of the colours.\n\n## Assets\n\n[Skeleton](https://kaylousberg.itch.io/kaykit-skeletons) by Kay Lousberg - [CC0 License](http://creativecommons.org/publicdomain/zero/1.0/)\n\n[Floor Tile](https://kenney.nl/assets/prototype-textures) by Kenney - [CC0 License](http://creativecommons.org/publicdomain/zero/1.0/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantzgames%2Fgodot_vertex_animation_textures_plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fantzgames%2Fgodot_vertex_animation_textures_plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantzgames%2Fgodot_vertex_animation_textures_plugin/lists"}