Tiles can have their UVs animated. There is an animation section located in the UVs panel where you can manage all your UV animations. Be sure to read the UVs section above, as the information there applies here as well. Using animated tiles can add a lot of life to your scenes.
To add animated tiles to the 3d scene, select an animation that you've added to a tileset and then draw the tile into the scene as you would normally do. As long as the animation is selected in the UVs panel, any tiles that get added to the scene will be assigned that animation. See below on how to add new animations and edit them.
When placing animated tiles into the 3d scene, you can specify which frame the animation begins on, or the exact time in seconds. To do this, set the Start value at the bottom of the UVs panel. Then any tiles placed into the scene will use this value to determine where the animation begins.
Once you've added a new animation to the tileset, it will appear as square located in the palette area below the tileset. You can click on this to select the animation and to reveal more options you can make to the animation.
If you have multiple animations, you can click and drag them to reorder and organize them in your animation palette.
When you select an animation, it will hide the UVs of any tiles that are selected in the 3d scene. The UVs belonging to the frames of the selected animation will become visible and editable instead. This allows you to easily edit the frames of the animations, and any operations you'd normally use to edit UVs of tiles will work on the frames as well. The frames will also be numbered, showing their order in the animation, beginning with zero.
- Name Each animation has a name that can be set. Double-click the name to edit it.
- Duration There is a Duration input box that defines the default duration to apply to new frames. Any new frames added will be assigned this duration. The value is measured in seconds. There is also a Set Frame Duration button to the right of this input box that will assign the duration to any selected frames when clicked.
- Add Frame Set a new duration for each of the selected frames. A frame must have all four UVs selected to be considered selected.
- Remove Frames Removes all the selected frames from the animation. A frame must have all four UVs selected to be considered selected.
If you right-click the tileset to open the uv context-menu, there are options located within Animation menu to Copy and Paste the selected frames. This allows you to easily duplicate multiple frames without having to recreate them one at a time. You can also copy frames from one animation and paste them into other animations, however, you can't mix tilesets within a single animation.
UV animations can be choreographed in the Theatre panel. This allows you to queue animations and play them in sequence with specific timings. Animated tiles must be placed inside Objects, and the Objects must then be assigned animations to play in the Theatre panel. To learn more, read the general Animation section in the documentation.
Export UV Animations
You can export your UV animations to other programs, however it will require a bit of extra work to implement it. It is pretty straightforward if you are comfortable with doing a bit of programming. There is an example Godot project listed below demonstrating how you can get UV animations working in a game engine using data exported from Crocotile.
When you export a model, you have the option to export the UV Animations. Doing so will output a text file containing JSON formatted data. Below is an example of the structure of this data.
"name": "Animation Name",
The JSON data consists of an array that contains any number of animations. Each animation in the array has a name, uuid, tileset, frame array, and custom array property. The tileset value corresponds to the tileset index. The frame value is an array that holds data pertaining to the duration and uv coordinates of each frame. There can be any number of frames, and each frame has four uv coordinates that correspond to each corner of the tile. The custom value is an array that holds custom start times that tiles might use.
This previous data is good, but it is not enough to get UVs animating in other programs yet. There needs to be a way for the vertices stored in the 3d model to know which animation they belong to, so that they can be animated. The way we handle this is by baking the Animation index number and the tile corner index into the UV X and Y coordinates of vertices in the model. Crocotile will do this for each vertex belonging to an animated tile when you export your models (enable Export UV Animations in the Export panel).
So if a vertex has its UV coordinates animated, the U value will be set to 100 + the animation index. The V value will be set to 100 * (the corner index of the frame + 1) + the index of the value in the custom array of the animation. Then we use this data to correlate it with the uvAnimation.txt data to apply the appropriate animation and frame to the vertex.
To demonstrate how to work with this data, a Godot project has been created using this data to animate UVs of a 3d model. Godot is a free and open-source program for developing games, and it is an excellent engine for importing your Crocotile work into if you are comfortable with more technical processes. You can just as easily do this with other engines, such as Unity, if you like. Watch the video for a demonstration on how to import your animated scenes into Godot!
Objects can be created by grouping tiles together. Object instances can then be added to the scene. Editing one instance allows all instances to be updated with the same changes.
To create an object, you must first highlight the tiles that will be grouped together while in Edit mode. Once highlighted, you can right click to open the context menu, then select the Create Object menu item within the Faces menu. You can also click the Create Object button in the Scene tab. Doing so will remove the tiles and replace them with an instance of the newly created object. Instances can be selected like tiles, moved, rotated, and scaled. The new object will also be listed in the Scene tab, and can be dragged into a layer to help organize your list of objects. When you create an object, its origin point will be placed relative to where the crosshair is located. Check the Object Points section below on how you can change this position.
There are two ways to rename an object. You can double click the name of the object listed in the Scene tab, or you can right-click and choose the Rename Object menu item.
- Apply name to Instances
You can use this option to apply the name of an Object to any instances belonging to the object.
Copy/pasting only works with tiles, but you can duplicate multiple instances by selecting them, right-clicking on one, and choosing the Duplicate Instance(s) item from the context menu that pops up. This will duplicate all of the selected instances with the new instances selected.
- Duplicate Instances Area
This opens a panel where you can specific the number of duplicates to make along the x,y,z axis, as well as the spacing along the x,y,z axis.
- Combine Instances
Selected instances in the scene can be combined into a new Object. This is useful if you want to merge multiple instances together without having to deconstruct them first. While in Edit mode, select the object instances in the scene. When they are highlighted, right-click an instance to open a context menu and choose Combine Instances or Combine Instances (Object only). The first option will replace the instances in the scene with a new instance of the new object, while the (Object only) option will only create a new object without placing it in the scene and without removing the other instances.
Instances in the scene can be deconstructed into separate tiles again. This may be useful if you want to make a change to an instance without affecting all of the instances. While in Edit mode, select the object instance in the scene. When it is highlighted, right-click to open a context menu and choose Deconstruct Instance.
While editing an instance, you can modify each tile that constructs the object. You can add or remove tiles to the object as well and these changes will be reflected in all of the instances. Basically every operation you can perform on a regular tile can also be performed when editing an instance's tiles. To edit an object, select an instance in the scene and right-click while in Edit mode. A menu will appear with the option to edit the instance. This will activate the instance's edit mode, displaying a yellow box around the instance. When you are done editing, you must deselect everything and then press Enter to exit the instance's editing mode. You can also press Enter to begin editing the instance.
There is an option in the settings Object Mode Constraint. If enabled it will prevent selecting/editing tiles that are not part of the object when you edit an instance. This will help prevent you from editing other things while you are editing an instance.
- Exit Editing an Instance
Deselect all faces and vertices of tiles and then press Enter to stop editing the object.
Instances / Prefab Brush
Instances can be added to the scene in two ways. One way is through the menu when right-clicking an object or instance in the Scene tab list and selecting Add to Scene. This will place the object at wherever the current position is of the 3d cursor. Another way is by left-clicking the object or instance in the list while in Draw mode. This will allow you to place objects in the scene near your mouse, relative to an invisible plane that sits against the 3d cursor (This acts just like when you place single tiles). You can also erase the instance by lining up the Prefab Brush with an instance, and right-clicking it in the scene, exactly as you would do with a normal tile.
The spacing of the prefab brush can be adjusted. There are inputs at the bottom of the Scene panel to specific the width and height in pixels that the prefab brush aligns to. The spacing will be relative to the 3d crosshair position. This acts similar to the spacing of tiles when they are drawn to the scene.
There is an option in the Settings to orient the Prefab Brush relative to the camera direction. This can be enabled by going to Edit > Settings > Draw Mode > Orient Prefab Brush to Camera.
- Q , E Rotate the prefab brush. Rotating the brush in combination with rotating the camera angle allows every 90 degree orientation to be attainable.
- Shift+Q , Shift+E To help keep rotation simpler, Holding shift will allow the object to rotate clockwise or counter-clockwise.
Below the Objects list is the Instance list. All of the instances in the scene are listed in this section. You can click and drag instances into other instances to nest them inside each other. This essentially groups them together and allows for more control. When clicking on an instance from the Instance list, it will change the prefab brush to represent the current instance and any nested instances while in Draw mode. This way you can add a group of instances to the scene and maintain the same nesting order! You can toggle between World and Local space when nesting Instances via the button in the lower right of the Scene panel.
Each object has an origin point that helps with the placement of the instances within the scene. At the time of creating an Object, the current location of the 3d cursor will determine where to place the origin point relative to the rest of the tiles in the object. The origin point can be re-positioned afterwards, as well as new points added for custom data.
There is also an option in the Layer context-menus, that allow you to set the origin point of all the Objects within the Layer (including sub-layers). This can be accessed by right-clicking a Layer listed in the Scene panel and choosing Set All Object's Origin Points To Crosshair. Doing so will set every origin point to the current location of the 3d crosshair. It will do this relative to the first Instance of each Object, so it is mainly useful if you only have one Instance per Object.
- Reposition a point
In the Scene tab, when an instance is being edited, the drop-down menu at the bottom of the scene tab window will list all the Object's points.
Selecting one will display the point (a white diamond shape) within the scene where it is located relative to the instance. Clicking the button next to the drop-down list will re-position the point to the current location of the 3d cursor.
- Rename a point
After selecting a point from the dropdown list in the scene tab while editing an instance, you can click the T icon to rename the point.
The origin point can't be renamed, but any additional points you have added can be renamed.
- Add/remove a point
At the bottom of the Scene tab window, there are two buttons to add or remove object points.
Points can be added/removed while editing an instance. The only point that can't be removed is the Origin point.
Right-click an object listed in the Scene tab and choose Properties. Alternatively you can Double-click the space to the side of its name to open the Properties. This will open a panel with special options such as Billboarding, Mirroring, and Custom.
With Billboarding enabled, instances of the object will always face the camera. You can also choose to lock it to the Y axis, which will make it keep its Y orientation while facing the camera. With this toggled you can rotate the object and it will keep its local Y orientation. When enabling billboarding, it is important to understand that the object should face down the Z axis. If you have tiles facing down a different axis, it may appear invisible when enabled because those will face away from the camera.
Enabling Mirror mode will cause all the tiles within an object to have a mirrored version of itself. Any changes to a tile will be updated in the mirrored version. This may be useful if you want to create a symmetrical object- you can create one side and as you are creating it, the other side will be auto-generated. It will retain symmetry across the origin point of the object. Check the Object section of this document to learn how to reposition the origin point.
Objects and instances can be given custom data! In this section, you have the option to add number or string values to the Object or its Instances. When you add a property, it will be displayed in the corresponding list. Then you can define its name, type, and default value. After adding a custom Instance property, you can access an Instance's properties in the same way you entered the Object's properties; by double-clicking the instance in the instance list of the Scene panel, or right-clicking and selecting Properties. From there you can set a unique value instead of the default value.
If you have registered and activated your program (non-Steam version), you'll have the ability to save and export.
- Choose a tileset that is being used in your scene.
- Click File on the menubar and choose either Export Scene or Export Objects. Export Objects will export each object separately whereas Export Scene will combine everything together.
- Select which objects to include in the scene if necessary.
- Adjust the export settings to your liking. Details of these settings are outlined below.
- Click Export and pick a location to save your files.
- Type in a name for your file and click Save.
When exporting, you can also export the textures as well as a .mtl file. If you export with the MTL file, then when you import the .obj file into a program that supports mtl files, it will import everything with the appropriate textures assigned. This is because the MTL file helps define the materials that the object uses, along with which textures there should be.
By default, Crocotile will export all the tiles (and the tiles of objects that you choose to include), but if you want to limit the tiles that get exported to just those that belong to a single tileset, you can enable the "Limit export to currently selected tileset" option. This will allow you to split up your scene into multiple parts. Then when importing into another program, you can load all of the exported .obj files, apply the correct tileset texture to each one, and position them to the same coordinates. Your scene will look fine, and everything will be together. This option usually isn't recommended though.
Watch this video to learn about all the options as well as how to import into Unity, Godot, Blender, Sketchfab.
GLTF & GLB formats
You can choose to export your scene and objects as .gltf files or .glb files. Gltf files are human readable json formatted files while the glb files are binary. The binary format has a smaller file size.
Gltf and Glb files can embed the texture images into the file. This way you can have just one file that contains everything you need to import into another program. Because of this, these formats are the preferred way to export.
DAE (Collada) format
In some cases you may want to export as a .dae, which is an XML formatted file. These files will store the file path to any textures that they use. In this case, they will assume they are in the same directory as the .dae file.
If you are exporting objects (not the scene), you can export them as .c3dp files. These are prefab files that are designed for importing into other Crocotile scenes. Use this format if your intention is to transfer Crocotile built objects into other Crocotile scenes.
- Merge Vertices
If this option is selected, any vertices that are overlapping will be merged together to create just one vertex. The UVs of the vertices must also be the same for them to be merged as there can only be one UV coordinate per vertex. If the UVs are different, then the vertices won't merge even though they have the same position in 3d space.
- Vertex Colors
You can choose whether or not to include any vertex colors in the exported model. The .obj file format doesn't officially support vertex colors, however some programs accept a modified form where the R,G,B values are written directly after each vertex X,Y,Z position (v X Y Z R G B). This modified format will be used if exporting vertex colors in .obj format.
- Vertex Normals
You can choose between flat or smooth normals. Flat will set all vertex normals to be the same as the face normal. This will give the impression of sharp edges to each polygon. Smooth will average the vertex normals based on all polygon faces connected to that vertex. With Smooth selected you can specify the angle threshold to control which face normals affect the vertex normals. Specify the angle in degrees. If the angle between surfaces are within this angle, the vertex normals will be averaged betweeen them.
- Decal Offset
This will offset any decals by the provided amount to avoid z-fighting. Usually this is handled by a shader, but if that is not a option you can bake it into the geometry by providing a value other than 0. Use a small fraction like 0.01.
- Polygon Type
Polygon type only applies to .obj files. You can choose to export your tiles as Triangles or Quads. Triangles are three-sided polygons and Quads are four-sided polygons.
If you have triangular tiles in the scene (tiles that have one of their polygons collapsed), these may mess up your export when Polygon type is set to Quads and Merge Vertices is enabled. There is an option in the context-menu when you right-click the 3d scene that allows you to select all the triangular tiles (if there are any). While in Edit mode, right-click the scene and goto Faces > Select triangular tiles.
- Use Groups
Use Groups only applies to .obj files. This option will organize the tiles of each instance to their corresponding object group. This may effect how your .obj gets imported into other programs. Some programs will separate each group into their own objects upon import. So if you need the tiles split up into their corresponding objects then you will select this, otherwise everything will be treated as a single object.
The Unlit option only applies to .gltf and .glb files. If unlit is chosen, it will export the model without any lighting/shading properties.
- Embed Textures
Embed Textures only applies to .gltf and .glb files. This option will embed the texture data with the rest of the data so that there is only one file.
- Tile Spacing
When exporting, the tile spacing option will add pixels around each tile. So if you choose a value of 2, each tile will have two rows/columns of pixels added on each side, so there would be 4 total pixels rows/columns between every tile. Example: [[Tile]][[Tile]][[Tile]]
This tile spacing implementation only works if you keep all your uvs square with the same dimensions (one tile size per tileset).
- Power of Two
With power of two option enabled, the tilesets will resize the canvas (it will add empty space) up to a power of two dimension if they aren't already. This may be necessary for some engines to render your textures correctly. For instance, if your textures look blurry, it may be due to tilesets not being power of two dimensions.
- Limit export to currently selected tileset
With this enabled, only the tiles that belong to the currently selected tileset will be exported.
- Export UV Animations
This will export a text file containing JSON formated data for all the UV animations in your project. It will also bake some corresponding animation data into the UV data of vertices in your model. For more details about this data and how to use it, check the Animated Tiles section of this documentation.
All vertices positions will be multiplied by this value. You can modify this value to magnify/scale the size of your model if you need to.
Export Scene Data
You can export entity data by going to the Scene panel and selecting Export Scene Data from within the Scene dropdown menu.
This will export object and instance data as a json formatted text document.
"name": "Instance 1",
Export Grid Map
Each tile placed inside an Prefab Object can correspond to a grid cell in a grid map. The tile index in the tilemap also gets saved to each grid cell when exported. Grid maps are useful for defining a three-dimensional map of cells. You can decide what these cells represent, but the most common use would be for defining collideable areas.
You can export Grid Map data by going to the Scene panel, right-clicking on a listed Prefab Object and selecting Export Grid Map from within the Export Misc section of the context-menu. The Grid Map panel will pop up with inputs for specifying the Cell Size. The Cell Size defines the dimensions of each cell and is measured in Pixels. When exported, it will be converted to Meters.
When you click Export, it will cycle through every tile in the Prefab Object and check the position immediately behind/under it. It will determine the location of the cell relative to the Object's origin point and store the x,y,z position as well as the tile index inside an array. The tile index is useful if you want to differentiate your cells; you can have one tile correspond with sloped collision cells for example. Tile indices begin with 0 at the top left corner of a tileset, and will be based on the Tilesize or the Tileset's Unique Tilesize if it is set.
Below is an example of some Grid Map data exported as a json formatted text document.
To demonstrate how to work with this data, a Godot project has been created that uses a Grid Map to define the collidable areas of a level. Godot is a free and open-source program for developing games, and it is an excellent engine for importing your Crocotile work into if you are comfortable with more technical processes. You can use the data in other engines, such as Unity, if you like. Watch the video to see how this data can be used in Godot!
"cells":[ [2,-1,0,0],[3,-1,0,0],[4,-1,0,0], ...]