Godot: Automated Animation, keyed Collision Polygons from AnimatedSprite2D Generator Tool

https://gripfastgame.works/#subscribe

This automation tool runs in the Godot game editor, created for version 4.4.1 using the Forwarded+ renderer, using a node called: Auto_CollisionPolygon2D_from_AnimatedSprite2D with a script attached (this is not a plugin).

What does it do?

TL;DR: automates a bunch of time consuming animation, collision and key frame work typically done with 2D characters.

Demonstration Video:

How the tool works:

• On scene load, iterates over the SpriteFrames from the AnimatedSprite2D node and creates cached polygons using the native opaque_to_polygons function in the BitMap class, creating pixel-perfect collision shapes.
• The cache of polygons are then saved to two testing children nodes and the first CollisionPolygon2D node under the root node.
  • Alternatively, an "Export Collision Data to Desktop" checkbox is available in the Inspector, exporting the packedVector2Array data into a JSON file to your desktop. Note: this tool was built on Ubuntu Linux, but there is a fallback for Windows (it it fails, see below). The filename will match your SpriteFrames animation name.
  • Alternatively, an "Export Collisions to Project" checkbox will send a JSON file into a folder called generated_collisions, into the root of your Godot project.
• Using the "Generate Polygon Animation" checkbox, an animation .tres file will be created in the generated_animations folder in the root of your Godot project, naming the .tres file exactly like your AnimatedSprite2d SpriteFrames animation name. See the note on the paths in the .tres file down below.
• You must manually apply the generated animation .tres file to the AnimationPlayer (a child under the main character node) using the Animation dialog, selecting the .tres file into the global folder, importing into the AnimationPlayer.
• The AnimationPlayer's animation will already have keyed the pixel-perfect polygon collision shapes to each frame, in time and order, exactly as they appear in your AnimatedSprite2d node's SpriteFrames, found under the auto node.
• You can then simply disable the tool nodes in the scene for future use as required as animations change for future states or for new characters, just duplicate the scene and start anew.

Scene Setup:

ROOT + CHILDREN NODES: 🧑‍🧑‍🧒‍🧒
CharacterBody2D: (e.g. Player1)
--- AnimationPlayer (your main animation node)
--- CollisionPolygon2D (the saved polygon data)
--- other nodes (not related to this tool)

TOOL : Auto_CollisionPolygon2D_from_AnimatedSprite2D Node2d (attach this script) 📝
--- AnimatedSprite2d (with your .png SpriteFrames) 🏇
--- CollisionPolygon2D (holds cached data on scene load)  ℹ️
--- TargetCollisionPolygon2D (generated data statically using checkbox, optional) ☑️
--- DebugOverlay (optional) 🐞

Troubleshooting:

• You should see your character with a red overlay if you play the scene. This overlay can be helpful to see the cached collision data before applying it to your main nodes. There is an offset checkbox and options to move it around for easier review. ☑️

Note on moving nodes after using the tool vs. the .tres Files:

• Move tool's AnimatedSprite2D node into another section of the node tree after auto generation. ⚙️
• Modify .tres text file's relative path of the AnimatedSprite2D node location to your new node location in the tree. 🌲
• Other scripts won't know that the auto tool script wrote the AnimatedSprite2D path info relative as it's own child. 🧑‍🧑‍🧒

Support:

• Support is not planned, though likely the script will be updated in the future as Godot stable versions progress. We can always chat about it over on Bluesky or reach out to us at Grip Fast Gameworks. There is a mini thread on use and other notes here: https://bsky.app/profile/gripfastgame.works/post/3lo3fpafmvc2w