English

Crocotile 3D

Overview
Getting Started
Commands
Configuration
Tilesets
UVs
Animated Tiles
Painting
Transforms
Objects
Cameras
Lights and Shadows
Bake Lighting
Layers
Effects
Active Selection Mode
Audio
Animation
Skinning & Rigging
Exporting
Importing
Miscellaneous


Overview

Crocotile 3D is a tile-based modeling editor. You can import tilesets and select tiles from the image to place into the 3d scene to construct environments, objects, characters or anything else you can imagine. Controls in the editor allow you to fine-tune and edit these tiles, allowing any shape or form to be made. This document outlines all the methods of interacting with the software and includes instructions on how to use it.
Click the 🐊 icons throughout this document to watch specific video clips on how to do stuff in Crocotile 3D.
📝 Would you like to translate this document to another language? Your help would be appreciated!
To translate this document click on any text and replace it with your translation. Click Save at the top of the document to export the data. You can import the data you've previously saved by clicking Load.
If you press F8, you can quickly switch between the current language you are editing and English.


Getting Started

🐊 When you open Crocotile 3D, you're presented with the main window that displays an empty scene (where you'll be placing the tiles), and a smaller window that contains tabs for the Tileset, UVs, Painting, Transforms, and Scene panels. The Tileset tab is open by default and is where you can choose which tiles to draw into the scene. Clicking on the tileset will select a portion of the image according to the tilesize values near the bottom of the window and this selected piece will be used when drawing your tiles into the scene.

To draw into the scene, you must be in Draw mode. This mode is activated by default. You can toggle between Draw mode and Edit mode by pressing Tab or by clicking the Mode button located at the top of the main window.

When you are ready to draw to the scene just click the scene to place a tile or click and drag to place multiple tiles. Right clicking will erase them. You can control the position where the tiles are created as well as their direction. The tile gets placed against an invisible plane that always aligns with the 3d crosshair.

The 3d crosshair is depicted by white lines that extend along the x, y, and z axis. By moving this crosshair, you can adjust where the tiles are drawn. You can press W, A, S, and D to move the crosshair up, left, down, and right. Holding Spacebar and pressing W will move the crosshair away from you while pressing S while Spacebar is held will move the crosshair towards you. Adjusting the Grid Rounding value found in the lower right of the Tileset window will define the distance the crosshair moves.

Rotating the scene/camera to look at it from another angle will allow you to change which invisible plane the tiles get drawn against. So for example, if you are looking down at the scene then the tiles will get drawn looking upwards. Hold Spacebar and click and drag using the mouse buttons to rotate, zoom, and pan the camera.

Try drawing tiles from various angles and moving the 3d crosshair to get comfortable with placing tiles. These controls are unique so it may feel strange at first, but they are designed to be intuitive. It will allow you to place tiles quickly from any angle and position. You could try rotating the tile brush by pressing Q or E. You can even flip it or mirror it by pressing F or R. You can also hold Alt and right-click an existing tile in the scene to eyedrop it to your tilebrush. You can hold Alt and left-click existing tiles to apply the tilebrush to them, which can be useful if the shape of the tile has been edited.

When you've had enough practice, you'll want to begin editing the tiles to gain greater control over their shape. Switching to Edit mode will allow you to interact with the tiles in various ways. In Edit mode, you can click on tiles to select/deselect their faces or click on their corner points to select/deselect their vertices. With these highlighted, now moving the 3d cursor via the W, A, S, and D keys will move the selected vertices and faces as well. Holding Shift will allow you to move the crosshair without moving the selection. Use a lower Grid Rounding value for more precise positioning.

Try selecting and moving faces and vertices. You can also press Q or E to rotate the selection in Edit mode. Notice that the selection rotates around the center of the 3d crosshair. F will flip the selection relative to the crosshair position and R will mirror it similarly.

There are other ways of moving the selected vertices and faces. One way is to interact with the 3d Gizmo that appears when a selection is made. The Gizmo allows you to translate, rotate, and scale your selection by clicking one or more of its axes and dragging them. You can turn off the 3d Gizmo by pressing X or by clicking the Gizmo toggle button at the top. You can press Shift+X to toggle between the transform, rotate, and scale modes, or you can click the button to the left of the Gizmo toggle button.

Another way to move vertices is by clicking and dragging them directly with the mouse. You can hold Shift while you drag a vertex to snap it onto another vertex.

A couple other things that you can do to tiles that are worth mentioning is reversing the face, or flipping the face edge. Try reversing a face by selecting a tile and pressing Shift+R. If it disappears, this is because it is now facing away from the camera in the opposite direction. Tiles aren't visible from their backside. Each tile consists of two triangles, and the edge these triangles share can be flipped by pressing Shift+F. Try flipping some edges to see the effect it has. This is useful if you want more control over how a tile is shaped.

Be sure to look over the list of commands and read through this entire document to understand all the ways you can interact with tiles, edit them, paint over them, and more.


Commands

General

 Hotkeys

Camera Controls
🐊 Holding Spacebar will toggle camera mode. In this mode, you can click and drag the scene using the mouse buttons to rotate, zoom, and pan the scene. This will allow you to change the direction of the plane that you draw your tiles on (see Draw mode for more info).
There is also the viewcube that can be used to rotate/zoom/pan the scene. It is styled as a lowpoly crocodile. Simply click it and drag- depending on whether you use left middle or right mouse button will determine whether it rotates, zooms, or pans. The viewcube can be re-positioned by dragging the small semi-transparent circle located next to it. You can also double-click the circle to toggle it on or off, or right click the circle. 🐊

Crosshair Controls

 🐊 The 3d crosshair is used to position the invisible plane that you draw tiles onto. It is also used to move selected vertices and faces or to rotate, mirror, and flip them. The 3d crosshair is visualized as white lines that extend along the x, y, and z axis. You can adjust the grid size to change how far the 3d crosshair moves per step.

You can also Tilt the crosshair. This allows you to draw and edit tiles at angles other than the default x,y,z. 🐊

Gizmo Controls

 🐊 The 3d Gizmo has three modes (move, rotate, and resize). You can toggle between them by pressing the corresponding button located at the top of the scene , or by pressing Shift + X. By clicking and dragging the Gizmo's lines representing the X,Y, and Z axes, you can move, rotate, or resize the selected faces and vertices in the scene. Adjusting the Grid Rounding value will effect how fine or coarse the changes are. You can also set the Rotation Interval value to rotate at specific intervals.

The 3d Gizmo will become visible when you select some vertices or instances. You can click the Gizmo toggle button at the top of the scene or press X to toggle the 3d Gizmo on/off. Pressing Shift+X will cycle through the translation, rotation, scale modes.

Pressing Alt+X will position the Gizmo to the nearest vertex, object or any other entity that the mouse is hovering over, or to the 3d crosshair. You can toggle between vert,object,entity location and crosshair location by pressing it again.

The Gizmo Alignment button will toggle between World and Object modes. When Object mode is set, the Gizmo and crosshair will automatically orient itself to the selected Object. You also can press Ctrl + Shift + X to toggle between World and Object mode.

  • X Toggle the Gizmo on/off.
  • Shift+X Toggle between the Translate, Rotate, Scale modes for the Gizmo.
  • Ctrl+Shift+X Toggle between the World and Object alignment for the Gizmo.
  • Alt+X Snap the gizmo to the nearest vertex, object or any other entity that the mouse is hovering over, or the 3d crosshair (press twice).
  • Shift+Alt+X Snap the gizmo to the center of the selection.
  • Shift (While in Translate mode) Move the Gizmo without moving the selection (When you hold Shift prior to dragging). If you press Shift after dragging, the Gizmo/Selection will snap to vertices that are hovered over.
  • Shift (While in Scale mode) This will keep the selection proportional while scaling in two axis.
  • Alt Transform the Crosshair relative to the Gizmo. This allows you to move and rotate the Crosshair via the mouse. This will activate Tilt mode. You can press T to deactivate Tilt mode.
  • Unnassigned Disable Gizmo Temporarily: While the assigned key is held down, you won't be able to interact with the Gizmo.


    • Draw Mode

     When drawing tiles or prefabs into the scene, they will be drawn onto an invisible plane that aligns with one of the 3d crosshair's axis. Which axis it aligns with will depend on the current direction of the camera. Changing the direction of the invisible plane allows you to draw the tiles and prefabs in different directions. Along with positioning the crosshair this allows you to draw at any position or orientation in 3d space. 🐊 Hotkeys There are several tools you can use while in Draw mode that alter the way you can place tiles into the scene. You can select a tool by clicking the buttons on the left side of the 3d scene, or pressing the corresponding number keys.

    Edit Mode

     Each tile consists of four vertices and two triangles/faces. These can be modified in various ways and in various combinations. You can toggle between Edit mode and Draw mode by pressing Tab. While in Edit mode you can right click the scene to open a menu with various actions that can be made on selected vertices or faces. Hotkeys 🐊 Tiles can be divided into two triangle shaped tiles. Select the tiles you want to divide and then right-click in the scene and select Triangle Divide from the Faces submenu. Also triangular tiles can be merged together to form a single square tile. Select Triangle Merge in the Faces context submenu while in Edit mode. This will merge pairs of triangles into single tiles. A pair of triangles must share two vertices together. There is a safe merge and a forced merged. The safe merge requires that the UV coordinates match where two tiles touch. The forced merge will merge them regardless.

    You can select all triangular tiles by opening the context-menu, and going to Faces > Select triangular tiles. This will select any tiles that have one or more of their polygons hidden. This may be useful in cases where you export the scene with polygon type set to Quads and Merge Vertices enabled, as triangular tiles could mess up the export in that case.

    You can select all overlapping tiles by opening the context-menu, and going to Faces > Select > Select Overlapping Faces. This will select tiles that overlap and are facing the same direction but will also leave one of the tiles unselected. This is useful if you accidentally create duplicate tiles and need to remove the duplicates.

    You can select a series of edges that connect end to end by using the Select Edge Loop action from the context-menu. It is located within the sub-menu of Edges when you right-click the 3d scene. You must have at least one edge already selected for it to select connected edges.

    You can merge tiles together by using the Merge Edges actions from the context-menu. This will remove the edges between two tiles and combine the tiles into one single tile. This action is located within the sub-menu of Edges when you right-click the 3d scene. There is a safe merge and a forced merged. The safe merge requires that the UV coordinates match where two tiles touch. The forced merge will merge them regardless.

    If you place down tiles and their UVs aren't oriented the same way, there is a way to orient all of them so that they match. Select their faces and then open the context-menu. Go to UVs, and select Orient UVs. There also is an associated keybinding you can set in the Buttons panel.

    Tilesets

     With the Tileset tab open, you can select a part of the image. This selection can then be drawn into the scene. 🐊 Multiple tilesets can be used. To add a new tileset click the tileset button and choose Add tileset. You can click the next and previous buttons to toggle between tilesets. 🐊

    UVs

     The following keys apply while the UVs panel is in focus. Read the UVs section to learn more about how to edit UV coordinates.

    Paint

     The following keys apply while the Paint window is in focus. Read the Painting section to learn more about how to use the tools.

    Scene

     Opening the Scene tab will display a list of layers and objects (if any exist in the scene). You can add layers and import prefabricated objects, or create objects from groups of tiles in the scene. To know more about this, check the Objects section.

    Animation


    Configuration

    Settings

     The settings and configuration of Crocotile 3d can be accessed from the Edit menu at the top of the main window, or by pressing F1.

    General Project Camera Draw Mode Edit Mode Tilesets Scene Animation

    Buttons

     🐊 The key bindings can be adjusted by accessing the Buttons menu item within the Edit menu at the top of the main window.

    Blender Controls

    If you are more comfortable with the way Blender handles the rotate/zoom/panning of the camera, you can adjust the bindings for these in Crocotile to match. Blender uses the middle mouse button for all these functions. In Crocotile, these functions are used in conjunction with the spacebar, so you will need to change the binding type to Mouse only if you want to rotate without holding the spacebar down. You can remap which mouse button these actions use, as well as the keys to press.

    Camera

    Skybox

     Included with the program is a skybox.png file. This image serves as a template for your skyboxes. Images can be larger or smaller as long as the layout remains the same. From the Edit menu in the main window, there is a Skybox menu item with options to pick a skybox image, to show/hide the skybox, or to export the skybox image.

    Render

    About

     This will show a box with information about the version of Crocotile 3D. If you are using the non-Steam version, then it will also provide input fields to type in your email and activation code if you have registered for one. Registering allows you to gain the ability to save a scene with more than 100 tiles and also allows exporting your work. It also helps support the development of this product.


    Tilesets

    Each tile in your scene displays an area of pixels from one of your tilesets. Simply click on the tileset to select a tile and apply it to your tilebrush. You can also click and drag to select a larger portion of the tileset. The size of your selection is determined by the UV Tilesize. You can also adjust the 3D Tilescale to change the size of the 3d tilebrush in the scene. Each tile uses UV coordinates to define what portion of the tileset to display on the tile's face. You can edit these UV coordinates in the UVs tab (read the UVs section on how to edit them)

    There is a toggleable button next to the UV Tilesize input boxes. When toggled on, the values you input into the Tilesize and Padding boxes will remain unique to the tileset. If it is toggled off (the default state), it will use the global values that other tilesets can use too. So if you need any tilesets to use their own tilesize and padding values, you can enable it by clicking this button. This way you won't have to keep inputting different values when you switch between tilesets.

    Menu

     The button with an image icon will open a menu with the following choices.

    Apply Tileset to the selected Faces

     This will switch the tileset of any selected tiles to the currently selected tileset. It essentially reassigns the tile texture to another texture (the currently selected tileset).

    The Keep UV pixel scale when reassigned tileset setting ensures that the UV coordinates don't become stretched if the tileset dimensions don't match. You can toggle this option on/off by going to Edit > Settings > Tilesets > Keep UV pixel scale when reassigned tileset.

    Re-size Tileset

     🐊 Opens a window with various options to customize how to re-size the currently selected Tileset. You can control from which side the Tileset gets re-sized from by clicking one of the nine buttons. Arrows on these butttons will show the direction the re-size will occur.



    Export Tileset

     If you make any changes to your Tileset, such as resizing it or painting on it, you can export the image in png format by selecting this menu item.

    Tileset List

     There is also a button between the buttons with arrow icons. Clicking it will toggle on/off a list of all your tilesets. This is a way to easily select another tileset. You can also press Ctrl+[ and Ctrl+] to cycle through them, or click the arrow buttons. You can reorder the tilesets by clicking and dragging them to a new position in the list.

    Double-clicking a tileset will open its material properties panel. In this panel, you can change the default name of the tileset.

    Tile Swapping

     🐊 You can swap tiles by selecting tiles in the tileset window and then right-click and dragging them to the desired location. UVs of tiles in the 3d scene will get updated to the new UV locations if their UVs were inside the tile area you are repositioning.

    Tileset Context Menu

     This menu allows you to perform various operations related to tiles.


    Tile Palette

     🐊 Tile palettes are used to randomize the tiles you draw to the 3d scene. When you draw tiles to the scene, it will randomly choose from the tiles in the selected Tile Palette.

    You can set the weight of tiles in a palette. A tile with a higher weight will be selected more often than other tiles from the tile palette. You can also combine tiles from different tilesets into the same palette.

    You can also randomize the Flip, Mirror, and Rotation of the tiles by toggling on the corresponding buttons next to the Tile Palette dropdown button.

    Tile Palette Mode

     The button to the left of the Tile Palette dropdown menu, controls the Mode of the Tile Palette. It can be either Random or Sequence. Random is the default and will choose randomly a tile from the palette. If Sequence is chosen, it will choose the tiles by order from left to right and repeat this sequence when placing tiles.

    Tile Palette Menu

    Tile Palette Context-Menu

    Repeating a Texture across a Tile

     🐊 Click the Wrap button in the Tileset tab to select a wrap mode for the current Tileset (Clamp to Edge, Repeat, Mirrored Repeat). With one of the repeat modes selected, a texture can then be repeated across a tile by moving the UV coordinates beyond the edges of the tileset. The UV coordinates will essentially wrap around, and the further you move them beyond the edge the more times it will repeat. By placing a tile into its own tileset and using that texture on a tile, you can adjust the vertices and their UV coordinates to get the desired result. Watch the video for a demonstration! This technique is useful for broad areas where you want to repeat a tile but want to keep the polygon count low. This helps optimize the geometry.

    Blurry Textures/Tiles

     If your tiles appear blurry, this is due to the tileset not having a power of two dimension. Examples of safe image dimensions are; 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 pixels. Tilesets are now capable of being repeated across a tile, and this requires them to have width and height values that are a power of two.

    Decals

     🐊 Click the Decal button in the Tileset tab to enable/disable the mode for the current tileset. Tilesets that have their decal mode enabled will have their tiles appear on-top of tiles from other tilesets that don't have their decal mode enabled. Watch the video for a demonstration! Use decals in combination with repeating textures to add variety without adding many polygons.

    Transparency

     Click the Transparent button in the Tileset tab to enable/disable the mode for the current tileset. If you plan to use tiles that are semi-transparent (uses the alpha channel of the texture image), you will need to place those tiles onto their own tileset that has Transparent mode enabled. This is necessary so that the renderer can draw the scene correctly and avoid occluding tiles behind the transclucent areas.

    Refresh

     The refresh button next to the Zoom menu will force the Tilesets to refresh. They won't refresh if there has not been any changes to their files outside of the program. Be careful if you are Painting over your Tilesets if you haven't refreshed them prior to that process as refreshing them may overwrite your work. You can enable auto-refresh in the settings to keep the Tilesets up to date if you are editing them outside of the program. Just take note that any changes you make to them inside Crocotile will not be updated outside of Crocotile.



    UVs

    As you may know, each tile in your scene displays a section of a tileset. Where these sections reside on a tileset are defined by the UV coordinates that the tiles use. Each vertex of a tile has a corresponding UV coordinate and these can be re-positioned to change what gets displayed. To change these, you must first select the faces in the scene. Selecting faces in the scene will display the corresponding UVs on the tileset panel within the UVs tab. To get a good idea on how to edit UVs, watch this video demonstration by clicking this crocotile link: 🐊

    UV Context Menu

     This menu allows you to perform various operations on UV coordinates. To open the menu, go to the UV tab and right-click the tileset. See below for more information regarding the various menu choices.

    Selecting UVs

     UV coordinates will be displayed in the UV panel whenever tiles in the 3d scene are highlighted. The UV coordinates will appear as small boxes. To select / deselect UV coordinates, simply click on them or click and drag a box around multiple UVs to select more than one. You can hold Alt while you drag to deselect multiple UVs.

    You can also click within the dotted lines that denote the tile, to select / deselect all the UVs of the tile. If you hold Ctrl while inside a tile's UVs, the coordinate closest to the mouse will be selected / deselected. 🐊

    Double-clicking within a tile's UVs will select/deselect the entire group of connected UVs. This is useful if you have a group of UVs that are neighboring each other and you want to select/deselect all of them.
    Double-clicking while your mouse is not hovering any UVs will deselect everything. Alternatively, you can set this to use a Single-click by going to Edit > Settings > Tilesets > Deselect all UVs with single-click.

    🐊 The Drag multiple UVs option in the Settings will allow you to select multiple UVs that are overlapping instead of just one. You can press B to toggle it on/off. There is also a button in the UVs panel to toggle this on/off.

    Snapping Together

     🐊 When you click and drag UVs, you can then hold Shift and hover over other UVs to snap them together. This allows you to snap a single UV coordinate to another coordinate, or snap a tile's UV edge to another edge. Which way it snaps depends on whether you drag a specific UV coordinate or whether you drag from within the tile's UV area. The closest edge to where you've clicked will be the edge that gets snapped when hovering over other tiles.

    Rotating

     🐊 To rotate the selected UVs, hold Shift to activate rotation mode (the UV boxes will switch to a circle shape), and then click and drag the UVs.

    If you hold Shift while rotating, it will rotate in increments. You can specify how many degrees in the Rotation input box.

    Hovering over other UVs while hold Shift will snap the angle to that UV coordinate.

    Scaling

     To scale the selected UVs via the mouse, hold Shift+Alt and then click and drag one of the resize handles that appears or within a UV tile or one of the UV coordinates. The UV coordinates will be scaled relative to the crosshair position.

    While scaling, if you continue to hold Shift the increments will be rounded to the pixel, whereas if you release the Shift key, it will be rounded to the UV Precision value.

    While scaling, if you continue to hold Alt the aspect ratio of the selected UVs will remain the same.

    Crosshair

     There is a small crosshair that becomes visible when you select UV coordinates. It automatically centers itself on the selection unless you begin to manually move it. Pressing C will recenter it again. You can also completely lock/unlock the crosshair by clicking the Lock/Unlock Crosshair button at the top of the UVs panel. Locking the crosshair will prevent it from being moved.

    To move the crosshair, simply click and drag it like you would a UV coordinate.

    If you hold Shift while dragging the crosshair, it will snap to any UVs you are hovering over.

    The crosshair is used as a point of reference for UV transformations. If you rotate the coordinates, they will rotate around the crosshair position. The same occurs for mirroring, flipping, and scaling. 🐊



    Animated Tiles

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

    UV Animation Menu

     The UV Animation menu is below the tileset canvas located within the UVs panel.

    Edit Animations

     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.

    Animation Palette Context Menu

     Right-clicking in the animation palette will popup a context menu.

    Copy/Paste Frames

     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.

    Animation Choreography

     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",
	"uuid":		"F51FB197-2BAC-4462-A568-3CA664290476",
	"tileset":	0,
	"frame":[ {
		"uv":[ {
			"x":	0.34375,
			"y":	0.484375
		}, ...],
		"duration":	1
	}, ...],
	"custom":[
		0,
		1.25,
		0.75
	, ...]
}, ...]
    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!
    Note! New versions of Godot may require setting the "force disable mesh compression" in the import settings of the model so that the UVs and alpha scissors work correctly. By default, Godot might compress the UV data, which will break the animation system. The "force disable mesh compression" option can be set in the Projects Settings. If you find the Import Defaults, there is a Scene section for the Importer where you can set the option.

    Export Sprite Animations

     🐊 If you setup sprite sheets in Crocotile you can use the uvAnimation data to construct sprite animations in your game projects. This video demonstrates how to do this in Godot. You can also download the Godot project files.
    Note! New versions of Godot may require setting the "force disable mesh compression" in the import settings of the model so that the UVs and alpha scissors work correctly. By default, Godot might compress the UV data, which will break the animation system. The "force disable mesh compression" option can be set in the Projects Settings. If you find the Import Defaults, there is a Scene section for the Importer where you can set the option.


    Painting

    When you select a tile or group of tiles in the Tileset tab, this portion of the image then becomes editable when clicking on the Paint tab.

    🐊 The Grid line button can be toggled to show/hide the Grid lines. These show where one tile begins and ends in the tileset based on the tilesize values.

    🐊 The UVs button can be toggled to show/hide the UVs of the selected tiles while you paint. This is helpful if you want to paint onto a specific location of a tile and need to reference the UV coordinates.

    Drawing Tools

     These tools modify the pixel data of the textures/tilesets. You will see your changes in real-time reflected on the 3d model.

    Selection Tools

     🐊 Limits painting to within the selection. The selection can be moved, cut, copied, pasted, and re-sized. Add, subtract, and intersect modifiers can be accessed when combining Alt, Shift keys. Cut and copy modifiers can be accessed with the Ctrl, Alt keys. You can also Flip, Mirror, and Rotate the selection by 90 degrees using the corresponding buttons at the top.

    Move Tools

    Re-size Selection

     🐊 After a selection has been made, handles will appear on the corners and sides of the selection. These handles can be clicked and dragged to adjust the size. If a portion of the image has been clipped, it will also be re-sized. The following keys can be held down to control how the selection is re-sized.

    Palette

     🐊 The palette allows you to save specific colors so that you can pick and re-use colors you have defined previously. The top edge of the palette box can be clicked and dragged to adjust the size of it. You can also click and drag individual colors to reorder them. There are a few options in the Palette menu by clicking the Palette button at the top, right of the palette box.

    Menu

    Color Menu

     You can also Right-click inside the palette box to show a context menu with a couple options.


    Transforms

    The Transform tab is where you can make specific translation, resize, and rotation adjustments to your selected tiles, vertices, and objects. Specify x,y,z values and hit Apply. There is a button "Axis relative to Camera orientation", near the top of the panel. This allows you to toggle between (x,y,z) and (right,up,backward). The first option will treat the transforms as normal, however the second option will treat the transforms relative to the camera orientation. If the Gizmo option is selected, transformations will be relative to the Gizmo.

    Align

    Property

     When selecting an Object, Camera, or other entity, these properties will display the current values of that selected element. Modifying these properties while the element is selected will update the element with the new values. Beware that you can have multiple elements selected and they will ALL be updated with the new value that you input!

    Randomize

     🐊 The selected vertices and objects can have their positions translated a randomized amount. Selected objects' rotation and scale can also be randomized. The transform unit type (pixels or meters) applies only to positions.

    Crosshair

     🐊 These allow you to retrieve the current crosshair position by hitting Get. Pressing Set will move the crosshair to the specified x,y,z position. If the move selection option is checked, it will also move the selected geometry along with the crosshair. There is also a translate option as well to shift the crosshair relative its current position.

    Camera

     Position Rotation Magnification

    Primitive

     These properties apply to the Primitive brush tool that you can use while in Draw Mode. It can be selected from the list of tools on the left side of the 3d viewport. You can choose between a number of primitive shapes, such as cube, wedge, cylinder, cone, and sphere. You can also specify the number of sides or segments the shapes have, as well as its dimensions.

    Extrude

     🐊 Extrusions allow you to extend the geometry outwards or inwards, creating new tiles automatically in the process. You can extrude selected faces, or selected edges. In addition to extruding via the Apply button in the Transform panel, you can also hold Alt+E and click and drag in the 3d scene to extrude! You can even click and drag the Gizmo while holding Alt+E to extrude linearly along a specific direction.

    Smoothing Groups

     When exporting models, the Vertex Normals option can be set to Smooth. This allows the normals for each vertex to be calculated based on surrounding polygons that connect with the vertex. This can help make the model appear smoother.

    Smoothing Groups allow you to have more control over which tiles get smoothed together. By specifying a group number for specific tiles, only tiles belonging to the same group will be smoothed together.

    Skin

     If a Prefab Object has its Skin property enabled, you can edit the vertex weights of its skinned mesh. The Show option controls whether or not the vertex weights get shown when editing the Object. Each vertex can be assigned up to four bones along with a weight for each one. For more information, check the Skinning section of this documentation.


    Objects

    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.

    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.

    Nested Instances

     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.

    There is also an option to hide/show the instance list. It is located via the menu button located in the lower right corner of the Scene panel.

    Object Points

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

    Object Context Menu

     This menu allows you to perform various operations related to an object. To open the menu, go to the Scene tab and right-click an object that is listed. See below for more information regarding the various menu choices.

    Instance Context Menu

     This menu allows you to perform various operations related to instances. To open the menu, go to the Scene tab and right-click an instance that is listed in the Instance list. See below for more information regarding the various menu choices.

    3d Scene Context Menu

     When you select instances in the 3d viewport, you can right-click on them to open this context menu (Must be in Edit Mode). See below for more information regarding the various menu choices.

    Properties

     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.


    Cameras

    🐊 Cameras are used when rendering out images of the scene. You can pick which camera(s) to render an image from by going to Edit > Render > Camera. Cameras can be either Perspective or Othographic. You can add cameras to the scene by clicking the Add Camera button in the Scene tab. When clicked, a camera will be added to the scene at the current location and angle being viewed. You can reset this position and orientation and also specify whether it is perspective or orthographic. By default the camera will always point towards its target position with its local up vector pointing up, however you can disable this in the properties if you prefer.

    Camera Context Menu

     This menu allows you to perform various operations related to a camera. To open the menu, go to the Scene tab and right-click a camera that is listed. See below for more information regarding the various menu choices.

    3d Scene Context Menu

     When you select cameras in the 3d viewport, you can right-click on them to open this context menu (Must be in Edit Mode). See below for more information regarding the various menu choices.

    Properties

     Right-click a camera 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 Perspective and Orthographic where specific properties for the camera can be set. You can also Reset the Camera to set these properties to the current view in the 3d scene.

    Rendering

     You can pick which camera(s) to render an image from by going to Edit > Render > Camera. A panel will open with a list of cameras that are in the scene. Select which cameras you want to render. You can hold down Ctrl and click more than one camera, and when you render it will render them all at once. This may be useful in cases where you want to get multiple angles of something, for example, such as an isometric object that will be rendered into a 2d asset. 🐊 There are various properties you can set when you render your images.


    Lights and Shadows

    🐊 Lights can be added to your scene by clicking the Add Light button at the top of the Scene panel. However, in order for light and shadows to render in the scene, you must change the material type that your tilesets use. You can change the tileset material by selecting Tileset Material Settings from the Tileset menu in the Tileset panel. Inside the Tileset Material Settings, you can change the type to Phong or Lambert, material types that can interact with the lights. You must set this for any tilesets that you want interacting with the lights.
    When you add lights to the scene, some will spawn with targets that they point towards (Spotlight and Directional). You can select the light or its target and move them in the scene.

    It is suggested to keep the number of lights low as lights and shadows may require more processing power. Performance will be dependent on your hardware.

    In the Lights menu, there is an option to toggle lights on/off. This will disable all the lights and illuminate the scene completely. This is a quick way to toggle the lighting of the entire scene.

    Light Context Menu

     This menu allows you to perform various operations related to a lights. To open the menu, go to the Scene tab and right-click a camera that is listed. See below for more information regarding the various menu choices.

    3d Scene Context Menu

     When you select lights in the 3d viewport, you can right-click on them to open this context menu (Must be in Edit Mode). See below for more information regarding the various menu choices.

    Properties

     Right-click a light 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 where specific properties for the light can be set.


    Bake Lighting

    🐊 The lighting in the scene can be baked into the vertex colors on each tile. This is useful in some cases since once the vertex colors are baked, you don't need to render the lights anymore. How much light a vertex receives, as well as the lights properties, will determine what the color of the vertex ends up becoming. Ambient occlusion can also be baked into the vertex colors, and this option doesn't require any lights to be in the scene.
    1. First select the vertices that you want the lights and or ambient occlusion baked to.
    2. Press Alt+B to open the Bake Lighting panel. Alternatively you can right-click while in Edit mode to bring up the context-menu then go to Vertices > Vertex Colors > Bake Lighting.
    3. Set the options how you would like them and then click Apply. It may take some time to complete if your scene is large.
    The following list outlines all the options you have when baking.


    Effects

    🐊 You can add some special effects to your scenes. They are accessed via the Effects panel that can be opened by clicking Edit in the menu bar and then choosing Effects.


    Layers

    🐊 Layers allow you to organize your object list inside the Scene tab. You can drag objects into and out of layers and label them to help you when sorting through them. You can even have nested layers! To add a layer, simply click the layer button near the top of the window while the Scene tab is open. If you right-click a layer, a menu will display with the following options.


    Active Selection Mode

    🐊 If you are in Edit mode and have at least one face selected, you can press Shift+Enter to toggle Active Selection Mode, or you can press the middle mouse button. The tiles will become highlighted in a green color. This mode prevents editing tiles that weren't selected so that you can focus on editing only the selected tiles. It also allows you to perform some special operations which are outlined below.

    Tile Splitting

     🐊 While in Active Selection Mode, you will see a yellow line appear on selected tiles when you hover your mouse over them. The line represents where you can choose to split a tile. Adjusting the Tile Splitting value located in the lower right corner of the Tileset window in the Tileset tab will give you more control over where you can split a tile. Setting the value to four will let you split the tile at every fourth pixel for example.
    1. Position the yellow line where you want to split a tile.
    2. Right click to bring up the edit menu.
    3. Go to Faces, and click on Split Tile.
    Alternatively, you can simply press Alt+S to split the tile along the yellow line without using the menu.

    As of version 2.2.0 you can now just hold Alt+S and Left click tiles to split them without having to be in Active Selection mode.

    Subdivide

     Update: You no longer need to be in Active-Edit mode in order to subdivide tiles. You can simply access it from the context-menu or by pressing Alt+D while in the standard Edit mode.

    A tile can be subdivided. This process will create new tiles in a grid formation across the original tile. When you select subdivide, a window will popup where you can set the rows and columns. Settings the rows to 3 and columns to 3 will divide the tile up into 3 by 3 tiles. This process might be heavy if you try to divide into a large amount of tiles, so make sure to keep it manageable.

    The subdivide panel also has a menu that allows you to choose between Segments and Pixels mode. The Pixels mode will divide the tiles at the specified pixel increments based on the tile's UVs. So if you had a large tile that displayed 96x64 pixels from the tileset, if you divide it by 16x16 pixels it would result in 6 columns by 4 rows of tiles, and each tile would display the corresponding 16x16 pixels from the tileset.


    Audio

    As of version 2.3.7 some basic audio support has been implemented. You can now link audio files to your project and play them while the Animation or Theatre panel is running. This is useful if you want to sync some animation keyframes up with some sounds.

    You can add audio files by going to the Scene panel, and clicking the dropdown menu there. Then click the Add Audio option and then pick the audio file you want to link to your project.

    Each audio file has the following properties that can be set. To edit the properties, double-click the audio item listed in the Scene panel or right-click on it and choose Properties.


    Animation

    🐊 Animation features are unfinished and may be changed in future updates! Many things still need to be implemented and some things may not work currently as everything is in development.

    To access the animation features, you will need to open the Animation panel by going to Edit > Window > Animation. This panel has two tabs; Animation and Theatre. In each panel there is a timeline where the animation keyframes and theatre segments are organized. Below you can find information specific to each section.

    Animation

     This panel is where you create the individual animation clips for the object instances in the scene. When you select an instance in the scene, it will become listed on the left side. When you deselect it, it will be removed from the list. However, you can click the Pin button next to the instance's name to keep it listed even when deselected.

    On the right side there will be a horizontal bar next to the listed instances that extends across the timeline. The first dropdown box is where the Actions for an instance are listed. To create a new Action, click the gear icon located next to the list. The gear icon provides options to add a new Action, remove an Action, and rename an Action. You can also Copy and Paste an entire Action. Above the timeline there are similar menus that allow you to add/remove/rename actions to all the listed entities in one step. When you have created an Action and have it selected, you will then be able to add new Keyframes to the Action. You can use the dropdown boxes towards the right of the bar to select the type of Keyframe and which attributes of the instance it influences. There are plus and minus icons to the right that you can click on to add or remove Keyframes. You can also choose the interpolation type located in the dropdown box in the header of the panel. Keyframes that are added will use the specified interpolation.

    When Keyframes have been added, they will become listed below, and you will be able to select them and reposition them by clicking and dragging. You can select multiple keyframes and drag multiple. You can also double-click the timeline to deselect everything. You can press Delete to remove selected keyframes. There is a Key Menu button to the right side of the Action bar. Within this menu there are options to Copy the selected keyframes from the action, or Paste keyframes into the action. This way keyframes can be copied from one action/object and pasted into another.

    With keyframes selected, you can right-click in the timeline to open a context-menu. Here there are options to change the type of interpolation that the selected keyframes use. The interpolation assigned to a keyframe applies to the time between the keyframe and whatever keyframe is next. New keyframes that are added to the timeline will be assigned the current interpolation type that is selected at the top of the Animation panel.

    Theatre

     This panel is where you setup theatre Acts that will contain the choreography for the Actions you have made. In the header of the Theatre panel, there are a series of dropdown selection boxes. The one on the left side holds all your theatre Acts. You can add, remove, reposition, and rename Acts by clicking the gear icon next to it. Once you have an Act created and selected, you can choose an Actor and an Action from the two dropdown lists to the right and then click the plus icon to add the Action to the Act. It will also add a default Weight for the segment at the beginning of the timeline.

    If you select the * option in the Actor list, this will reference any Actor. This will allow you to play all the Actions with the same name simultaneously regardless of which Actor they belong to. Just choose the name of the Action that you want to play from the Action list and add it to the timeline.

    Once an Action is added to the Act, you will see it listed in the timeline. You can resize the segment by clicking and dragging the beginning or end of the segment. You can also click and drag the segment itself to reposition it. You can click and drag a marquee selection box around multiple segments and weights to select and move multiple at the same time. Double-clicking the timeline will deselect everything. To the left, the name of the Action is displayed, and there is an eye icon to disable/enable the Action. There is also a loop icon to enable/disable the looping mode. If it is set to loop, the action will loop through the duration of the segment. So to make it loop longer, you would need to extend the length of the segment by clicking and dragging the end of the segment.

    You can double-click the Action listed to the left of the timeline to open the properties for the specific segment. Here you can change which action gets played during the segment and also set the looping mode and timescale value. The timescale value allows you to adjust the speed of the action, and you can use negative values to play the action in reverse. You can also disable/enable the segment from within the properties as well. If the segment represents a UV animation, you can specify which UV animation to play here.

    Weights

     Every Action has a default Weight added along with it. These display as a rectangle box with a small dot inside. You can reposition them just like you can with the segments. Weights control the blending of Actions that affect the same object. If you have two or more actions affecting the same object, you can control which segment has more influence. Basically, the Weights determine how much of an influence the segment has on the object. By hovering the mouse over a Weight and using the mouse-wheel, you can increase or decrease the Weight, controlling the amount of influence the Action has on the object. To add more Weights, right-click the segment you want to add a Weight to, and a context-menu will appear. In the Add Weight sub-menu, you can select the type of Weight to add; Discrete, Linear, Ease in cubic, Ease out cubic, Ease in out cubic. You can also change the type for any selected weights by right-clicking and choosing a new type from the Apply Interpolation context-menu.

    Markers

     Cameras have a special Marker that can be added to theatre Acts. These control which camera is used when playing the theatre Acts. To add a Marker to the Act, select the camera from the list of objects, and then choose Switch Camera from the action list. Then when you click the plus icon, it will add a Marker to the marker bar below the timeline. These indicate the time when it will switch to the chosen camera. You can click and drag these Markers to reposition them, and you can delete them by pressing the Delete key after they have been selected.

    UV Animation

     Objects with animated tiles have an action that can be added to theatre Acts that allow control over which animation is displayed. To access this action, choose UV Animation from the action list. Once the Action is added to the Act, you can double-click the item in the left panel to open the properties and select the UV animation that this segment will play. For more information on how to create and edit animated tiles, visit the Animated Tiles section of this documentation.

    Timeline

     The timeline lists all the animation Keyframes and theatre Segments. When an animation Actions or theatre Acts are played, the Playhead moves across the timeline and represents the current position in time. You can click and drag the Playhead to reposition it. The Playhead moves across a bar of numbers representing the time. You can hover the mouse over the time bar and use the mouse scroll-wheel to adjust how much time gets displayed along the timeline. This can provide the ability to set animation Keyframes and theatre Segments at more precise positions.

    An important thing to know, is that object instances won't remember any changes made to their position, rotation, scale states when the animation is Paused. This is because the Paused state acts similar to a Record state. When you click Stop, it will reset the object instances to their default states. So it is important to be in Paused mode when making changes that you want only applied to the animation.

    Context Menu

     Right-click in the timeline to open the context-menu. Below is a list of the options that can be accessed.

    Render Movie

     When you have your animation Acts all setup, you can render them out as a movie/video clip. To access the Movie panel, go to Edit > Render > Movie. The animation Acts will be listed on the left side, and you can select which ones will be rendered. Hold Ctrl to select/deselect more than one, or Shift to select a series of Acts. Below you can find more information about each option in the Movie panel.

    FFmpeg

     Here are the steps for using ffmpeg, a free tool that can compile video files from a group of image files.
    1. Download ffmpeg from https://ffmpeg.org/
    2. In Windows search bar type "path" without quotes and hit enter to open the system properties to "edit the system environment variables."
    3. Click "environment variables..." button. It will open a new panel.
    4. Select the Path line from either the User or the System, depending on whether you want just the User access or the entire System. Then hit "Edit..." below the corresponding one. It will open a new panel.
    5. Click "New" and type in the path to where the ffmpeg.exe is located.
    6. Then click "Okay" and exit out of the previous panels. The ffmpeg program can now be run from any directory because the system knows where to check for it when you call for it in the command line.
      7. --
    7. Now open the location of your images that you want to convert to a video.
    8. Click the path in the explore window and type "cmd" without quotes. Hit enter, and it will open the command line at the directory the images are located in.
    9. Now type:
      ffmpeg -framerate 30 -i prefix%01d.png -c:v libx264rgb -crf 0 videoname.mp4
    10. Replace the prefix with whatever your files use. The %01d specifies a number and it will count up from 0 unless you provide a starting number in the command using for example "-start_number 100" without quotes.
    11. If the numbers on your image files are padded with 0s, such as 0000, 0001, 0002, etc.. then you will need to modify the %01d and change the 01 to 04 to denote that the number has 4 characters in length for example.
    12. Change the framerate and filetype depending on the settings you used in Crocotile. Hit enter and it will create the video file!


    Skinning & Rigging

    🐊 Each Prefab Object can have its Skin property enable in the object's properties panel. A Skinned Object can have Bones attached to it which can then be used to bend and morph the vertices of the tiles belonging to that object. The Bones construct a Skeleton that acts as a Rig for your 3d model, and this Rig can be posed and animated.

    Bones

     Bones can be added to the project by opening the menu at the top of the Scene panel and selecting Add Bone or by clicking the Bone button at the top of the scene panel. Bones can be nested inside each other, allowing Bones to become children of other Bones. Simply click and drag a Bone inside another Bone listed in the Scene panel to nest them together. By nesting them together, you can create a Skeleton of connected Bones that can be bound to the Skinned Object.

    Bones can be manipulated just like Object Instances can be. You can select them as you would select any instances, and move them with the WASD keys or the Gizmo. You can move, rotate, and scale bones, and they can also be animated just as you would animate an Object Instance.

    Within the Scene dropdown menu, there is an option to Hide/Show All Bones. This allows you to toggle on/off the rendering of the bones. If you have any instances nested inside bones, those will still be visible.

    Properties

     Double-clicking the bone listed in the Scene panel will open its properties panel. You can also right-click and select Properties from the context-menu. Here you can set the visual length and thickness of the bone (this does not set its scale). Alternatively, you can set the Length and Thickness of bones that are selected in the 3d scene by going to the Transform panel, and scrolling to the Skin section. Here there are inputs where you can set the Length and Thickness.

    Scene Context Menu

     Right-clicking a bone listed in the Scene panel will reveal a context-menu with the following options.

    3d Scene Context Menu

     When you select bones in the 3d viewport, you can right-click on them to open this context menu (Must be in Edit Mode). See below for more information regarding the various menu choices.

    Skinned Objects

     When you have a Skeleton built that you want to bind to an Object, double-click the Object listed in the Scene panel. This will open the Properties panel for the Object. There is a Skin section where you can enable the Skin. Once the Skin is enabled, a new skeleton container will be nested inside the instance listed in the Scene panel. This container is where you will place your bones that you want the Skin to be bound to. If you don't have any instances of the Object in the scene, you will need to first add one in order to attach bones to it.

    Vertex Weights

     With a Skeleton bound to a Skinned Object, vertices can then be influenced by the bones in the Skeleton. Each vertex can be assigned up to four bones with a corresponding weight value for each one. These weights determine the amount of influence each bone has on the vertex. For example, you can have one bone influencing a vertex by 20%, another bone influencing it by 30%, and a third bone influencing it by 50%. The total amount of influence of the bone assigned to a single vertex should equal 100%.

    Since it can be confusing to calculate this percentage for every bone, Crocotile ensures that the values never go over 100%. You can simply set a value between 0 and 1 for every vertex weight, and Crocotile will store this value. Whenever the influences are calculated, Crocotile will normalize the sum of the weights. So, you can set the weights to 0.2, 0.3, 0.5, 0.0, and get a similar total influence as described previously. But if the sum is greater than one, for example if you set the weights to 1.0, 1.0, 1.0, 1.0, each weight in this case would equal 25% of the total influence (assuming that each weight corresponds to a unique bone).

    Setting Weights and Bones

     There are a couple ways to set the weights and assign the bones to vertices. The first way is via the Skin section in the Transform panel. The other way is via the Vertex Weight painting tool. However, you must be in Object Edit mode so that the tiles of the Skinned Object are editable.

    Transform panel

     If you look at the image to the right, there are four specific parts marked with the letters A, B, C, and D. Each part is explained in more detail below.
    1. The Show option controls whether or not the vertex weights get displayed visually when you edit the object and have a bone selected. If you have multiple bones selected, it should display the vertex weights that apply to the last bone that was selected.
    2. You can set the visual length and thickness of bones here, or in a bone's properties panel. If you set it here, it will apply to any bones that are currently selected. It does not affect their scale values. It may be useful to set these so that the bones fill more space and can be clicked more easily.
    3. This section allows you to assign bones and weights to any selected vertices. Depending on whether you have Restrictive mode enabled, it will operate differently. When you select a bone from the dropdown list, it will also select it in the 3d scene ( it will also deselect any other bones that were selected ).
      • If the Restrictive mode is enabled, it will only apply weights to selected vertices that have the selected bone assigned. So in this case, if you have Bone4 selected and set a weight of 0.5, it will check any selected vertices to see if this bone is attached to them ( each vertex can be attached to four unique bones ) and it will set the weight that bone has on those vertices.
      • If Restrictive mode is disabled, it will assign the bone and weight to any open index/slot on any of the selected vertices.
    4. Every vertex of a Skinned Object can be assigned up to four bones that can influence it. This section lists the four weight index/slots that a vertex has. You can use these to manually set the bone and weight that is assigned for each index/slot in a vertex. The bone and weight will be assigned to the corresponding index/slot of any selected vertices when you click on of the Set buttons.
      • Additionally, if you have any vertices selected, you can hover the mouse over on the the dropdown lists to get a list of bones that are assigned to the corresponding index/slot for those particular vertices ( note: a bone that is listed might not be assigned to all of the selected vertices, it might only be assigned to some of them ).
      • You can also get information about the weights if you hover over the input boxes. If you have any vertices selected, it will show what weight values have been assigned to the corresponding index/slot for those particular vertices, as well as how many vertices have the same weight value.

    Weight Painting

     You can paint the weights directly to the tiles in the 3d scene instead of selecting the vertices and manually specifying the values for each index/slot. To do this, you must first be editing the object and have the Show option enabled in the Transform panel. You must also have a bone selected. Switch to Draw Mode, and select the Vertex Color / Weight tool from the left side of the 3d scene. This tool will allow you to paint directly to the tiles, thus assigning the bone and weights to their vertices. Simply click and drag, and the color of the tiles will change to indicate the current weights that the vertices have been assigned ( you can customize the colors in the Settings ).

    The weight value that will be painted to the vertices is based upon the input box in the Transform panel shown in section C of the image above. Changing this value will control the weight that gets assigned as you paint. A lower value will result in less influence the bone has on the vertices, while a higher value will result in a greater influence the bone has. Values range between 0 and 1, and the total influence on a vertex is a combination of all the bones that are assigned.

    Right-clicking and dragging will erase the weights. This maybe be a useful operation if you want to reset a weight and remove a bone from infuencing vertices.

    Posing

     When you exit Object Edit mode, the Skeleton will become bound to the Skin and posable. You can rotate and move the Bones to pose the Skeleton. The weighted vertices of the Skin will bend and morph with the Skeleton as you pose it. You can restore the base pose by going to the Scene panel and right-clicking the root bone and selecting Restore Pose All. It will return the bone to its original pose as well as any nested bones. You can select Restore Pose to restore a single bone's pose without restoring any nested bones.

    To change the base pose, you would need to go into Object Edit mode, and pose the bones while they are unbound from the Skin. While they are unbound, you can make changes to them without influencing the Skin. When you exit Object Edit mode, the new base pose will become set. Then if you choose Restore Pose All from the Scene panel, it will restore the new base pose.

    With a skeleton bound to the skin, and the vertices assigned bones and weights, you can begin animating the bones in the Animation panel. Check the Animation section of this documentation for more information on how to animate objects and entities, including bones. Actions that share the same name will be grouped together when exported. So for example, you can have multiple bones each with an Action named "Run", and they will all be exported as one Animation clip. You can have multiple animations exported, but the only file formats that support animations are the .Gltf and .Glb formats.


    Exporting

    If you have registered and activated your program (non-Steam version), you'll have the ability to save and export.

    1. 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.
    2. Select which objects to include in the scene if necessary.
    3. Adjust the export settings to your liking. Details of these settings are outlined below.
    4. Click Export and pick a location to save your files.
    5. Type in a name for your file and click Save.

    OBJ format
    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.

    C3dp format
    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.

    Export Options

    Texture Names
    Each tileset is assigned a name when they are added to your Crocotile scene. By default it will be a number such as 0,1,2,etc.. You can change a tileset's name by going to the Tileset Material Settings panel. This can be accessed in the Tileset menu, or by double-clicking the tileset in the tileset list. Check the Tileset section of this documentation if you need to learn more about the Tileset panel.

    When tilesets get exported as textures for your models, they will use their tileset name to distinguish them. Each tileset name in a Crocotile scene will be unique to prevent tilesets from overwriting other tilesets when exporting, however if you are exporting multiple scenes it is possible that you may be using the same names in two or more scenes. To prevent exported tilesets being overwritten, you can add a prefix to your textures if you need to via the Texture Prefix option in the Export panel. You can set a custom prefix, or use the project name as the prefix. Another way to avoid overwriting textures is to export to separate folders so that all your files for one scene is located in its own folder.

    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. It will also include Light and Camera data if you have any in the scene. 
      {
"objects":[ {
	"name":"Object 1",
	"points":[ {
		"name":		"Origin",
		"pos":		{"x":0,"y":0,"z":0}
		},{
		"name":		"Point",
		"pos":		{"x":0,"y":0,"z":0}
		} ...],
	"billboard":{"enabled":false,"y":false},
	"custom":[ {
		"name":		"Name",
		"uuid":		"E6205BF6-0FA3-47F7-90BD-7D895DAD9DD1",
		"type":		"object",
		"valueType":	"number",
		"value":	25
		},{
		"name":		"Name2",
		"uuid":		"19E722F6-E597-489A-B766-BA575DB71D63",
		"type":		"instance",
		"valueType":	"string",
		"value":	"hey"
		} ...],
	"instances":[ {
		"name":		"Instance 1",
		"uuid":		"0D08FF35-7E44-422B-9C62-4F104857209F",
		"parent":	null,
		"pos":		{"x":0,"y":0,"z":0},
		"rot":		{"x":0,"y":0,"z":0,"order":"XYZ"},
		"sca":		{"x":0,"y":0,"z":0},
		"custom":[ {
			"uuid":		"19E722F6-E597-489A-B766-BA575DB71D63",
			"value":	"hi"
			} ...]
		}, ...]
	}, ...],
"lights":[ {
	"name":		"Point Light",
	"pos":		{"x":0,"y":0,"z":0},
	"rot":		{"x":0,"y":0,"z":0,"order":"XYZ"},
	"sca":		{"x":0,"y":0,"z":0},
	"parent":	null,
	"color":		{"r":1,"g":1,"b":1},
	"intensity":		1,
	"distance":		100,
	"decay":		1,
	"angle":		30,
	"penumbra":		0,
	"target": {
		"pos":		{"x":0,"y":0,"z":0},
		"rot":		{"x":0,"y":0,"z":0,"order":"XYZ"},
		"dir":		{"x":0,"y":0,"z":-1},
		"parent":	null,
		},
	"castShadow":		true,
	"shadow": {
		"bias":		-0.001,
		"mapSize":		{"x":512,"y":512},
		"camera":		{"near":0.5,"far":500,"left":-10,"right":10,"top":10,"bottom":-10},
		"valueType":	"number",
		"value":	25
		},
	}, ...],
"cameras":[ {
	"name":		"Camera 123",
	"cameraZoom":	1.22773766,
	"zoom":		1,
	"cameraType":	"PerspectiveCamera",
	"parent":	null,
	"perspective": {
		"pos":		{"x":0,"y":0,"z":0},
		"rot":		{"x":0,"y":0,"z":0,"order":"XYZ"},
		"sca":		{"x":0,"y":0,"z":0},
		"zoom":		1,
		"near":		0.01,
		"far":		500,
		"aspect":	1.3132530120481927,
		"fov":		50,
		},
	"orthographic": {
		"pos":		{"x":0,"y":0,"z":0},
		"rot":		{"x":0,"y":0,"z":0,"order":"XYZ"},
		"sca":		{"x":0,"y":0,"z":0},
		"zoom":		1,
		"near":		0.01,
		"far":		500,
		"left":		-10,
		"right":	10,
		"top":		10,
		"bottom":	-10,
		},
	"target": {
		"pos":		{"x":0,"y":0,"z":0},
		"rot":		{"x":0,"y":0,"z":0,"order":"XYZ"},
		"dir":		{"x":0,"y":0,"z":-1},
		"parent":	null,
		},
	}, ...]
}

    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. 
      {
"size":{"x":1,"y":1,"z":1},
"cells":[ [2,-1,0,0],[3,-1,0,0],[4,-1,0,0], ...],
"dimensions":{"x":10,"y":10,"z":10},
"min":{"x":-5,"y":-5,"z":-5},
"max":{"x":5,"y":5,"z":5}
}
    🐊 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!


    Importing

    Crocotile Scenes

     You can import other crocotile scenes into the currently opened crocotile scene. You can also choose which objects in the scene get imported in-case you do not want to import everything. There are also extra options to help customize what gets imported.
    1. Click File on the menubar and select Import Scene
    2. Select the .crocotile file you want to import and then click open.
    3. A panel will appear with options for you to customize the import.
    4. When you are ready to import, click the Import button and everything will begin loading into your scene.

    Models

     You can import .obj , .gltf , .glb , .dae, .fbx, and .c3dp files. This allows you to take models that have been made in other programs and continue working with them in Crocotile.

    1. Click File on the menubar and select Import Model
    2. Select the file you want to import and then click open.
    3. The model will import into your project and a new prefab object will be created in the Scene tab.
    4. Click on the prefab object listed in the Scene tab, and while in Draw mode, add it to your scene!


    Miscellaneous

    Touchpad

     If you are using a touchpad and run into issues where the controls lock up, then try settings the sensitivity of the touchpad higher in the settings of your operating system. On windows, you'll need to set the Tap sensitivity higher. The higher sensitivity is necessary to make sure the touchpad continues operating while pressing the keyboard.

    Wacom Stylus

     If you are using a wacom tablet to draw, you will have to disable Windows Ink in your wacom settings. Windows Ink causes issues preventing it from working correctly in Crocotile 3d. Open your Wacom Tablet Properties. Then navigate to the Mapping tab. There you should find a checkbox for disabling Windows Ink.