English

Crocotile 3D

Overview
Getting Started
Commands
Configuration
Tilesets
UVs
Animated Tiles
Painting
Transforms
Objects
Cameras
Lights and Shadows
Layers
Effects
Active Selection Mode
Animation
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.


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.

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


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

    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.


    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

    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 menu in the main window, there is a Skybox menu item with options to pick a skybox image, or to show/hide the skybox.

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

    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.

    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 while your mouse is not hovering any UVs will deselect everything.

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

    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.

    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.

    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!

    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.


    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!

    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

    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.


    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.

    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.

    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.

    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.


    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.

    Subdivide

     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.


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

    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.

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

    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.

    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.

    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!


    Exporting

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

    1. Choose a tileset that is being used in your scene.
    2. 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.
    3. Select which objects to include in the scene if necessary.
    4. Adjust the export settings to your liking. Details of these settings are outlined below.
    5. Click Export and pick a location to save your files.
    6. 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

    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},
	"color":		{"r":1,"g":1,"b":1},
	"intensity":		1,
	"distance":		100,
	"decay":		1,
	"angle":		30,
	"penumbra":		0,
	"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",
	"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,
		},
	}, ...]
}

    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], ...]
}
    🐊 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

    You can import .obj , .gltf , .glb , .dae, and .fbx 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.