Creature Godot Engine Plugin
This repository contains the Creature Animation Tool’s plugin for Godot Engine.
Creature Animation Tool Website: https://creature.kestrelmoon.com/
Godot Engine Website: http://www.godotengine.org/
Sample UtahRaptor Artwork: Emily Willoughby (http://emilywilloughby.com)
Video Tutorials
Getting Started
An introductory video tutorial about using the plugin is here
Animation Player / Animation Properties
Watch this tutorial to learn how to manipulate/playback a Creature Godot object with Godot’s AnimationPlayer node here
Godot 3 + Future Roadmap
This documentation is updated for the new Godot 3.0 engine. Make sure you grab the latest engine sources from the Godot Engine Github. The source for the new Creature Godot 3 Runtimes is located here. Moving forwards, all new features will be added to the Godot 3 Creature Runtimes.
New features of this runtime:
- Smooth Animation Transitions or Blending + Playback
- Point Caching for super fast Playback Performance
- Supports the new Animation Gap Step Compression from Creature Game Export
- Skin/Item Swapping
- Animated Layer Ordering
- Creature Events with Godot Signals
- Godot 3 Visual Scripting Support
- Lots of bug fixes/enhancements
- Ready for Godot 3
Godot 3 Sample Project/Demo
There is a sample Demo Project for Godot 3 located here In it, there are a couple of simple scripts in both GDScript and Godot VisualScript format showing you how to drive the Creature characters using the runtimes. They demonstrate basic animation blending/switching as well as Skin/Item swapping.
Compilation & Installation
1. Grab the Godot Engine Source
First, download the Godot Engine source from here
Make sure you can compile Godot Engine by following their instructions for your platform here
2. Drop in creaturegodot into modules
The Creature Godot plugin must be compiled with Godot Engine in order to run. Compilation is very easy and simply involves dropping the creaturegodot directory into Godot Engine’s modules directory.
For example take a look at the image below:
The creaturegodot directory has been put into the modules directory of Godot Engine.
3. Build Godot Engine
Go ahead and build Godot Engine from the terminal with
scons. It will build the Creature Plugin with it. You are done!
For example, to build in Windows, you go into the Godot source directory and type:
scons platform=windows
Once again, please look at the documentation from the official Godot Website for compilation instructions.
Usage
1. Add CreatureGodot Object
Create a new node in Godot Engine, and type/search for creature:
You should see CreatureGodot show up which means the plugin is now active in Godot Engine. Add CreatureGodot into your scene.
First, set the Asset Filename property. This points to the exported Creature JSON
filename living within your project directory.
The Asset Filename has to be in the format: res://myfilename.json.
If all goes well, you should see your character load up:
3. Activating it with a Script
Now it is time to load up scripting to make the character animate.
First, assign and create a new script to the character using the typical way you would in Godot.
Open up the script and type:
extends CreatureGodot
func _ready():
set_process(true)
pass
func _process(delta):
self.update_animation(delta)
func _ready() calls set_process(true) to make the the update tick _process(delta) call active.
In _process(delta) itself, we play forward the animation by a delta timestep via the update_animation call.
Play the game and you should see your character running!
4. Skin/Item Swapping
First, make sure that you have setup Skin Swapping in Creature. For more information on how to set this up, please head over here
Setup:
-
Copy the MetaData File ( .mdata ) from your exported Creature Character Game Export Folder into your Godot Game Project Folder
-
In your CreatureGodotNode, there is a property called metadata_filename. Point this to your MetaData File, something like this: res://myCharMetaData.mdata .
Code:
Now let’s take a look at how to activate and run Skin Swapping. As you can see it is rather simple:
extends CreatureGodot
func _ready():
set_process(true)
self.blend_to_animation("cape", 0.1)
self.set_skinswap_name("cape")
self.enable_skinswap()
pass
func _process(delta):
self.update_animation(delta)
func _input(event):
if(event is InputEventKey):
if(event.scancode == KEY_A):
self.set_skinswap_name("cape")
elif(event.scancode == KEY_S):
self.set_skinswap_name("dressSword")
elif(event.scancode == KEY_D):
self.set_skinswap_name("defaultGun")
In the above example, we have a character with 3 Skin Swaps: cape, dressSword, defaultGun. The character swaps between 3 different Skin Swap Sets based on user input keys ( A, S, D ).
To activate Skin Swapping, you do this:
self.enable_skinswap()
Then to swap in a new Skin Swap Set, you run:
self.set_skinswap_name("mySwap")
You can also add your own Custom Skin Swap at runtime by calling:
self.add_skinswap("NewSwap", swapNameList)
This adds a new custom Skin Swap with the specified name and item list into the system. Similarly, you can remove a Skin Swap by calling remove_skinswap(name). To disable Skin Swap and return back to normal playback mode, call:
self.disable_skinswap()
5. Morph Targets
Real-time Morph Targets enable you to achieve some sophistcated effecs, including the ability to have user-controllable front facing characters that will turn their Heads/eyes towards a desired target point. Please read up on Morph Targets to learn how to setup Morph Targets in the Creature Animation Tool first before continuing.
Morph Targets data are stored in the MetaData file so make sure you have connected/setup the MetaData slot of the CreatureGodot node before you start.
To activate Morph Targets, do the following:
self.set_morph_targets_active(true)
Then at each update step, make sure you point your morph targets to a target point with a source base point and radius:
self.set_morph_targets_pt(target_pos, src_pos, radius)
The full demo sample ( An Owl Head turning character, Artwork by David Revoy, CC-BY-SA) has an Owl Character that will look at a target tracker polygon. The full simple example looks like this:
extends CreatureGodot
func _ready():
set_process(true)
self.set_morph_targets_active(true)
pass
func _process(delta):
var poly = get_node("../Polygon2D")
self.set_morph_targets_pt(poly.global_position, self.global_position - Vector2(-10, 200), 10.0)
self.update_animation(delta)
func _input(event):
var poly = get_node("../Polygon2D")
if(event is InputEventKey):
if(event.scancode == KEY_A):
poly.position.x -= 10
elif(event.scancode == KEY_D):
poly.position.x += 10
elif(event.scancode == KEY_W):
poly.position.y -= 10
elif(event.scancode == KEY_S):
poly.position.y += 10
Here, we have a polygon node object that is driven by the W, A, S, D keys. The owl character which is of CreatureGodot node type uses Morph Targets to perform a head-turning action tracking the position of the polygon. Play around with the provided sample to learn more about this powerful functionality.
Animation Functions
set_mirror_y(flag_in) - Sets a boolean to flip the character along the Y axis
blend_to_animation(name, blend_factor) - Switches to another animation smoothly based off the blend_factor. blend_factor is a value > 0 and <= 1.0. The higher the value, the faster the blending to the target animation.
set_should_loop(flag_in) - Sets whether the animation should be looping or not.
set_anim_speed(speed) - A multiplier on how quickly the animation plays back.
Item Swapping
set_active_item_swap(region, id) - Sets up a region for item swapping with the given region name and internal swap id. Read the Creature Tool Docs to see how to set this up.
remove_active_item_swap(region) - Removes the currently swapped out region/item.
Anchor Points
set_anchor_points_active(flag) - Activation of Anchor points setup for the character
Speeding up playback with Point Caching
make_point_cache(animation_name, gap_step) - Creates a point cache for the animation for super fast playback. gap_step determines the accuracy of the point cache, the higher the step the less accurate but faster the cache generation.
Grabbing the position along a bone for attachments
get_bone_pos( bone_name, slide_factor) - Returns a Vector2 that denotes the position along the 2 end points of a given bone in world space. The slide_factor determins how far along the bone you are. So if the value is 0.5, you are retrieving the mid point of the bone. A value of 0 gives you the starting point, a value of 1 gives you the end point.
Export Issues for CreatureGodot
If you are facing export issues from Godot Engine, this issues thread here might help.
Here is the remedy from alperc84 :
My Godot 3.1.1 builds works in windows 10 and android without any problem. I am adding json file to my build and copying it to user:// folder in runtime and using it from user:// (not res://)
Do the following:
Go export->resource settings in Godot and add *.json to filters to export non-resource files (this will add your json file to res://) I mean you adding your json file to your build with this way.
But we need to export json file to user:// directory for access in correct way.
Create a root node (2d scene) attach a script for it:
extends Node2D
func _ready():
var dir = Directory.new()
dir.copy("res://some.json","user://some.json")
This script will copy your json from res:// to user:// in runtime (you can add some error handling, check file if exist or something like that if you want)
Now you can add creaturegodot node to your root node and use user://some.json instead of res://some.json in Assetfilename.
When you launch the game your json file will be copied to user:// and will work without any problem in android and windows builds (probably for mac and linux too). Plus, you don’t have to put your json file next to your final exe. Because json file in your game already now.
You will find you json in this directory when you launch your game if you did the things correctly.
C:\Users{username}\AppData\Roaming\Godot\app_userdata{projectname}\some.json
I don’t know android user:// directory location but it’s working in same way.
IMPORTANT: Do not forget to enable Write External Storage permission in your android export settings ->Permissions (no write permission = no json)
License
The Creature Runtimes operate under 2 License types depending on whether you own a Licensed copy of Creature or not.
-
People who own a licensed copy of Creature: You use the standard Creature License included with the runtime code. TLDR: You are free to publish/modify/sell your product with the Creature runtimes without needing to state you are using the runtimes/put the copyright notice in your code/app. If you already have been using the Creature runtimes as a licensed owner of Creature, nothing changes :)
-
Everyone else: The runtimes are released under the very permissive Apache License :)
Both Licenses allow for private use and do not require any disclosure of your source code.
评论