-
Notifications
You must be signed in to change notification settings - Fork 0
User Guide
This guide covers the process of integrating Gator into a Godot project, and can used as a reference of Gator's features.
- Installation
- Gator Workflow Overview
- Preparing Godot Assets
- Preparing the Godot Scene
- Creating Crocotile3D Scenes
- Building
- Using Object Properties in Godot
- Advanced Features
- Additional Information
To install Gator into a Godot project, download a release from the releases page and follow these steps:
- Extract the
gator
folder into theres://addons
directory of your Godot project (Create one if needed) - Open the project in Godot
- Go to
Project > Project Settings
and open thePlugins
tab - Check the
Enable
checkbox for the Gator plugin
Gator bridges the gap between Crocotile3D and Godot by using the concept of Entities.
Entities are Godot scenes/nodes that are linked to objects and instances created in Crocotile. Gator parses scene data exported from Crocotile and re-creates the C3D scene using Godot nodes.
Gator is quite flexible with how entities are set up, but as a rule of thumb: complex entities are configured using Godot assets, and simpler entities are configured in Crocotile. More info on this in the following sections.
NOTE: |
---|
Before explaining the way Gator entities are defined, it is important to understand the basics of resources in Godot. In essence: resources are data containers. They can contain any GDScript built-in data type, can be saved/loaded from disk, and can easily be edited inside the Godot editor. Godot has many built-in resource types, including things like textures and fonts, but also allows the user to define custom resources with their own custom properties. Gator makes use of a few custom resource types (namely GatorEntityDefinition and GatorEntityCollection , detailed in the following sections) to store information about entities the user creates. For further reading about how resources work in Godot, see the Additional Information section. |
The primary way to associate an object in Crocotile with Godot nodes/scripts is to create GatorEntityDefinition
files using the Godot editor.
A GatorEntityDefinition
is a resource that defines the properties an entity will be assigned when the plugin builds the Crocotile scene.
To create a new GatorEntityDefinition
file:
- Right-click on the desired destination directory in Godot
- Select
New Resource...
- Type "Gator" into the search bar
- Select
GatorEntityDefinition
and clickCreate
- Finally, name the file and click
Save
One GatorEntityDefinition
resource should be created for each unique entity type needed for your project.
For example: while making a platformer game, one could create definitions for player/enemy spawn points, item pickups, etc.
To assign values to the file, double-click it to open the Inspector.
Entity definitions have quite a few properties, but not all of them are used at once. Each property is explained below:
The Entity Tag is a String
that represents a unique name for the entity type.
The name can be anything you want, but it is recommended to name the entity after the object it represents. For example, when defining a coin pickup entity for a platformer game, you could name it "Coin".
The Instance Type of an entity determines how it should be instanced when built.
Type | Description |
---|---|
Scene |
Entities with this type will instance a saved Godot scene. |
Node |
Entities with this type instance standalone nodes of any build-in type. |
When an instance type is selected, the Inspector will update with new properties that pertain to that type.
Only available with Scene
Instance Type
This is a reference to the saved Godot scene to instance.
NOTE: |
---|
The data type that Godot uses for saved scenes is the PackedScene type, they can be assigned by dragging a scene file into the property slot in the Inspector. For links to the official Godot documentation on PackedScene s, see the Additional Information section. |
Only available with Node
Instance Type
The type of built-in node to instance.
NOTE: |
---|
This property is set differently depending on the version of Godot you are using. In Godot 3, this property is just a plain String . Set it by typing the name of the desired node type. (Case-sensitive.) In Godot 4, clicking this property field will open a type selection dialog window. Only types descending from Node should be used! |
Only available with Node
Instance Type
The script to attach to the instanced node.
NOTE: |
---|
This property is optional. If no script is assigned, no script will be attached. |
Flags for importing Crocotile3D geometry.
Flag | Description |
---|---|
Visual |
When enabled, a textured mesh is generated using the geometry from the C3D object. |
Collision |
When enabled, a collision mesh is generated using the geometry from the C3D object. |
Only available if Collision
Geometry Flag is enabled
The type of collision shape to generate.
Type | Description |
---|---|
Convex |
Collision shape that can only hold convex geometry. |
Concave |
Collision shape that can hold both convex and concave geometry. |
NOTE: |
---|
Convex collision shapes are generally faster performance-wise, but cannot contain any concave geometry. |
Only available if Collision
Geometry Flag is enabled
The type of collision node to generate.
There are four values available, but the names and generated node types nodes vary depending on version of Godot you are using:
Godot 3 | Godot 4 |
---|---|
StaticBody |
StaticBody3D |
Area |
Area3D |
RigidBody |
RigidBody3D |
KinematicBody |
CharacterBody3D |
The default property values to assign to instances of the entity.
Each key in the dictionary must be a String
, and can have any value that can be parsed by Godot's str2var()
(Godot 3) / str_to_var()
(Godot 4) function.
After creating the necessary GatorEntityDefinition
files, they must be placed in a GatorEntityCollection
.
A GatorEntityCollection
is another resource that simply contains a list of GatorEntityDefinition
files.
Only one GatorEntityCollection
is strictly required for a project, but multiple different collections can be created to better organize entity definitions.
Creating a GatorEntityCollection
is done in the same way as creating a GatorEntityDefinition
.
With the collection open in the Inspector, add entity definition files to the Entity Definitions
array.
With all entity definitions and collections configured, it's time to set up the Godot scene.
The key component for building the Crocotile scene in a Godot scene is to create a GatorScene
node.
A GatorScene
node will act as the parent for all scenes/nodes generated by the plugin for a given C3D scene file.
The GatorScene
node type should be available when adding a new node into the scene tree.
Multiple GatorScene
nodes can be placed in the same Godot scene, if desired. Each with different settings applied.
A path to the scene file exported from Crocotile3D.
This can point to either a .txt
file containing only the C3D object data, or a .crocotile
scene file.
.crocotile
files allow for more options when building, such as geometry importing.
The GatorEntityCollection
to use when building the entities in the Data File.
A multiplier for the scale of the C3D's coordinate system. A setting of 1 will build the scene at 1:1 scale.
When enabled, Godot's world origin will be used as the origin point for all instanced scenes/nodes, rather than the GatorScene
's position.
The path to a directory containing textures and materials to use when building any visual meshes.
If no path is specified, the texture/tileset data embedded into the .crocotile
file will be loaded instead, and the material defined in the Default Material property will be used.
Textures in this directory must have the same names and file extensions as the ones used in the .crocotile
file in order to be loaded.
If a material has the same name as a texture used in a tileset (minus the file extension), it will be used for any faces using that tileset.
Only available in Godot 3
Flags to use for any embedded textures loaded from the .crocotile
file.
This property does not exist in Godot 4, as these flags are set per-material in that version, rather than per-texture.
The default material to use for any visual meshes. If no unique material is loaded for a given tileset/texture, a copy of this material will be used instead.
No texture needs to be assigned to this material, as each tileset's texture will automatically be assigned to each copy.
Only available if the Default Material is a ShaderMaterial
The name of the shader uniform to use to pass the tileset texture to the shader of the Default Material.
If left as an empty String
, no attempt will be made to set a texture uniform.
Flags for importing Crocotile3D geometry that does not belong to any object.
Flag | Description |
---|---|
Visual |
When enabled, a textured mesh is generated using the geometry from the C3D scene. |
Collision |
When enabled, a collision mesh is generated using the geometry from the C3D scene. |
Only available if Collision
Scene Geometry Flag is enabled
The type of collision shape to generate for the scene collision mesh.
Type | Description |
---|---|
Convex |
Collision shape that can only hold convex geometry. |
Concave |
Collision shape that can hold both convex and concave geometry. |
NOTE: |
---|
Convex collision shapes are generally faster performance-wise, but cannot contain any concave geometry. |
Only available if Collision
Scene Geometry Flag is enabled
The type of collision node to generate for the scene collision mesh.
There are four values available, but the names and generated node types nodes vary depending on version of Godot you are using:
Godot 3 | Godot 4 |
---|---|
StaticBody |
StaticBody3D |
Area |
Area3D |
RigidBody |
RigidBody3D |
KinematicBody |
CharacterBody3D |
When creating a Crocotile3D scene to use with Gator, special properties can be given to objects in the scene to associate them with entities or give them functionality when built in Godot.
To associate an object with a entity type defined by a GatorEntityDefinition
file, follow these steps:
- In Crocotile3D's Scene panel, right-click the object (not the instance) and select
Properties
. - Under the
Custom
section, create an Object property of typeString
with the namegt-tag
.- For the property value, enter the Entity Tag of the entity.
- Create an Instance property for each property that the
GatorEntityDefinition
defines in its Properties dictionary.- Properties of type
int
andfloat
should be set to theNumber
type - Any other type must be set to the
String
type, and formatted according tostr2var()
/str_to_var()
parsing
- Properties of type
- Finally, set the desired values for any Instance properties created.
Any Crocotile objects that lack a gt-tag
property will be implicitly ignored by Gator. Ignored objects will not be included in the scene tree when built, unless they have a non-ignored child. In which case, they will be instanced as Spatial
/Node3D
nodes.
Objects can also be explicitly ignored by giving them a gt-ignore
Object property.
Any objects given a gt-empty
Object property will be instanced as a plain Spatial
/Node3D
node in Godot.
The gt-geometry
Object property can be given to to an object to import its geometry without the need for creating a GatorEntityDefinition
file.
The gt-geometry
property must be a String
, and its value can contain any of the following flags separated by commas:
Flag | Description |
---|---|
"visual" |
Generates a textured mesh from the object's geometry. |
"collision" |
Generates a collision mesh from the object's geometry. |
"all" |
Generates both visual and collision meshes. |
The "collision"
or "all"
flags can be given sub-flags, which define the shape and node type to use for collisions.
These sub-flags are separated by colons (:
), and can have the following values:
Sub-Flag | Description |
---|---|
"convex" |
Generates a convex collision shape for the mesh. Default |
"concave" |
Generates a concave collision shape for the mesh. |
"staticbody" |
Generates a StaticBody /StaticBody3D node. Default
|
"area" |
Generates an Area /Area3D node. |
"rigidbody" |
Generates a RigidBody /RigidBody3D node. |
"kinematicbody" |
Generates a KinematicBody node. Godot 3 Only
|
"characterbody" |
Generates a CharacterBody3D node. Godot 4 Only
|
For example: to import a C3D object as a StaticBody
/StaticBody3D
with a concave shape and visual mesh:
"visual,collision:staticbody:concave"
or "all:staticbody:concave"
When all objects and instances have been configured, the scene or object data can be exported.
To export only object data (does not allow for geometry importing):
- Go to the
Scene
panel - Select
Export Scene Data
from the Scene menu.
To export the scene (allows for geometry importing):
- Save the scene using the
File
menu or by pressingCTRL+S
.
The resulting file can be placed wherever you like, it does not need to be inside your Godot project. However, doing so is recommended, as it keeps files for the project self-contained.
NOTE: |
---|
When placing a .crocotile file inside a Godot project, Godot will try (and fail) to import the file when loading the project. To avoid this, place the file in its own directory along with an empty file named .gdignore . This will prevent anything in that directory from being automatically imported by Godot. |
With everything properly configured and all steps completed, select the GatorScene
node in Godot to reveal the Build
button in the 3D scene toolbar.
Click Build
to begin the build process, any errors will be printed to the Output
console.
If the root node of the Godot scene (or a standalone node) instanced by an entity has a script attached, certain variables will automatically be assigned data from that entity's instance if they are declared.
Field | Description |
---|---|
properties |
Will be assigned a Dictionary containing all instance property values. |
points |
Will be assigned a Dictionary containing all of the points defined by the object as local-space Vector3 values. |
NOTE: |
---|
An object's points are defined per-C3D-object, and not per-instance. All instances of an object will contain the same set of points. |
NOTE: |
---|
This example assumes you are using Godot 4, but the concepts can easily be transferred to Godot 3 projects. |
For this example, we will be creating a simple coin pickup entity for a hypothetical platformer game.
The entity will instance an Area3D
node with CollisionShape3D
and MeshInstance3D
children.
When the player enters the coin's Area3D
, the coin will add to the player's score and delete itself.
To begin: let's create a GatorEntityDefinition
file named example_coin_def.tres
and a script extending Area3D
called example_coin.gd
.
Configure example_coin_def.tres
like so:
Here, we are using the Node
Instance type to spawn an Area3D node and attach the example_coin.gd
script. (More on the script later.)
We have enabled the Collision
Geometry Flag so that the geometry from the C3D object will be used as the Area3D
's hitbox.
Note that since we are spawning an Area3D
directly, the Collision Type setting will be overridden. However, setting it to Area3D
makes things more clear.
Lastly, the entity has a custom property called value
with a default value of 1, which will be used in the script.
For the next step, we will create a GatorEntityCollection
called example_collection.tres
, and add example_coin_def.tres
to it.
Lastly, we can fill in the example_coin.gd
as follows:
extends Area3D
@export var properties: Dictionary # properties assigned by Gator
var value: int # actual pickup value
@onready var mesh: MeshInstance3D = $coin_visuals/mesh # visual mesh child
func _ready() -> void:
# extract the "value" property
if "value" in properties:
value = properties["value"]
# register our body_entered signal handler
body_entered.connect(on_body_entered)
func _process(delta: float) -> void:
# spin the visual mesh around
mesh.rotate_y(deg_to_rad(360) * delta)
func on_body_entered(body: Node) -> void:
# if the body entering this area has a "score" variable,
# add our value to it
if "score" in body:
body.score += value
# destroy ourselves
queue_free()
In Crocotile3D, lets build a simple scene that looks like this:
This scene contains two objects, one called coin
which will be linked to our example_coin_def.tres
, and another called coin_visuals
which will contain the coin's visual mesh.
Open the coin
object's properties, and add the following properties:
It's hard to see the underscore from the screenshot, but the gt-tag
value is "example_coin"
, matching the Entity Tag from our GatorEntityDefinition
.
Next, we'll set up the coin_visuals
object properties like so:
NOTE: |
---|
This example entity imports Crocotile geometry directly for its visual model, in order to showcase Gator's geometry building features. For more complex projects where an entity may need to spawn a pre-made 3D model, a GatorEntityDefinition using the Scene Instance Type to instance the model as a scene may be preferable. |
With all these steps done, the Crocotile scene is finished.
Save the scene as a .crocotile
file into the Godot project, with the path res://c3d/example_coin.crocotile
.
Back in Godot, a GatorScene
node should be added to the scene and configured like this:
Nothing too special here, we've just set the Data File property to the .crocotile
file, set the Entity Collection to our example_collection.tres
from earlier, and created a default material.
The default material is a simple material that is unlit and has texture filtering disabled.
Finally, the only thing left to do is build the scene and test the entity!
Here's what the custom entity looks like in action, after adding a simple player character, GUI, and floor to the scene:
Gator has a few features that probably won't be needed for every use case, but can be used for more complex projects.
During the final step of the build process, Gator will traverse the generated scene tree and call a special callback function on any applicable nodes.
The node must have a script attached to it, the script must be a tool
script (if building in the editor), and the script must define a _on_build_completed()
function.
This callback can be used to perform any task the user may want, such as additional configuration on the scene.
NOTE: |
---|
Runtime Building is still experimental and has not been thoroughly tested. Please report any bugs! |
The GatorScene
node has a build()
function that will begin the build process. This function is usually called in the editor by Gator when the Build button is pressed, but can also be called at runtime by the user.
build()
does not return information regarding the build results. Instead, signals are used to pass build status information.
Signal | Arguments | Description |
---|---|---|
build_success |
N/A | Emitted when a build is completed successfully. |
build_fail |
N/A | Emitted when a build fails for any reason. |
build_progress |
build_progress_percentage: float |
Emitted after each build step. |
For information about resources in Godot, check out the following links: