User Guide

Overview

This guide covers the process of integrating Gator into a Godot project, and can used as a reference of Gator's features.

Contents

• Installation
• Gator Workflow Overview
• Preparing Godot Assets
  • Creating Entity Types
    • GatorEntityDefinition Properties
  • Organizing Entity Types
• Preparing the Godot Scene
  • GatorScene Properties
• Creating Crocotile3D Scenes
  • Special Crocotile3D Object Properties
  • Exporting
• Building
• Using Object Properties in Godot
  • Entity Example
• Advanced Features
  • Gator Callbacks
  • Runtime Building
• Additional Information

Installation

To install Gator into a Godot project, download a release from the releases page and follow these steps:

• Extract the gator folder into the res://addons directory of your Godot project (Create one if needed)
• Open the project in Godot
• Go to Project > Project Settings and open the Plugins tab
• Check the Enable checkbox for the Gator plugin

Gator Workflow Overview

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.

Preparing Godot Assets

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.

Creating Entity Types

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 click Create
• 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.

GatorEntityDefinition Properties

Entity definitions have quite a few properties, but not all of them are used at once. Each property is explained below:

Entity Tag

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".

Instance Type

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.

Scene

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 PackedScenes, see the Additional Information section.

Node Type

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!

Node Script

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.

Geometry Flags

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.

Collision Shape

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.

Collision Type

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

Properties

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.

Organizing Entity Types

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.

Preparing the Godot Scene

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.

GatorScene Properties

Data File

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.

Entity Collection

The GatorEntityCollection to use when building the entities in the Data File.

Scene Scale

A multiplier for the scale of the C3D's coordinate system. A setting of 1 will build the scene at 1:1 scale.

Use Global Origin

When enabled, Godot's world origin will be used as the origin point for all instanced scenes/nodes, rather than the GatorScene's position.

Textures Directory

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.

Embedded Texture Flags

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.

Default Material

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.

Default Albedo Uniform

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.

Scene Geometry Flags

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.

Scene Collision Shape

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.

Scene Collision Type

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

Creating Crocotile3D Scenes

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 type String with the name gt-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 and float should be set to the Number type
  • Any other type must be set to the String type, and formatted according to str2var()/str_to_var() parsing
• Finally, set the desired values for any Instance properties created.

Special Crocotile3D Object Properties

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"

Exporting

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 pressing CTRL+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.

Building

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.

Using Object Properties in Godot

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.

Entity Example

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.

Creating the Godot Assets

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()

Creating the Crocotile3D Scene

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.

Preparing the Godot Scene

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:

Advanced Features

Gator has a few features that probably won't be needed for every use case, but can be used for more complex projects.

Gator Callbacks

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.

Runtime Building

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.

Additional Information

For information about resources in Godot, check out the following links:

• Official Godot Tutorial on Resources
• Godot Documentation for the Resource Class

Official Godot Documentation for the PackedScene Class