File Formats

A list of all file types related to working with Defold.

Animation Set (*.animationset): Used for model animations. You can add one animation set to another if you have some animations which are shared between models. To use an animationset you define it as the animation file in the properties for an open model file.

Atlas (*.atlas): Texture atlases are methods of optimization which decrease texture space, and decrease load time. When your game’s textures are loaded into memory, due to the way older graphics hardware works (some newer graphics hardware handles texture memory better), they will always take up memory rounded up to the nearest power of 2 in each dimension. 128x256, 128x128, 256x256, 256x512, 512x512, 1024x1024, … When you have hundreds or even thousands of textures your game can end up wasting a large amount of memory without optimization - the difference in space which each of the textures actually takes vs its container size in memory. Texture atlas technology attempts to solve this problem by combining multiple textures into a single texture so that the memory your game takes is more optimized and less wasted. By using texture atlases, your game’s loading time is also reduced. It’s easy to understand - if every texture is a filesystem call when it is loaded, with hundreds of images, there is significant OS overhead with all of the load calls, which increases loading time. When you create an atlas file you will then want to add images to it, which must be within your project’s file structure. You can define the atlas texture’s margin, if it has extruded borders (useful for tiles to prevent color bleeding), and if it has inner padding (along with margin is useful to prevent texture color bleeding). Generally you will want to create multiple atlases with images defined in them that logically go together so that you only keep textures in memory that a currently necessary. Keep images which are always loaded while your game is running in their own image atlases referenced in your main collection. Put images which are loaded in and out as your game changes screens or levels in their own atlas files referenced in sub-collections.

Camera (*.camera): Cameras are how your game knows what to render onto the screen. Remember that even though Defold has been optimized for 2d game projects it is still a 3d game engine under the hood. Just like any 3d engine, you can have multiple cameras in your scenes which have different purposes. The “Camera Editor” allows you to change a camera’s aspect ratio, field of view (fov - expressed in degrees), near z (the z distance where a camera begins to draw), far z (the z distance where a camera no longer draws objects), and a flag to set to 1 to automatically set the aspect ratio based on your game project’s screen size settings. You do not technically need camera files for rendering, but they can be useful to for example place as a child component to a parent game object so that your camera follows a game object. As of this writing, it is better to use the Orthographic or RenderCam extensions rather than the builtin cameras. You should be using one or either of these most likely!

Collection (*.collection): Collections are hierarchies of game objects. Their editor is called the “Scene Editor” and allows editing collection contents within what first appears to be a flat 2d space, but is actually a 3d space. You can rotate the viewport camera by holding alt and left click while dragging the mouse pointer.

Collection Factory (*.collectionfactory): Collection factories can spawn collections which are pre-made, and used as blueprints, templates, or prefabs. Every Collection Factory File must have a “Prototype” collection defined inside of it. Collection Factories are related to Collection Proxies with some important differences. The Collections associated with Collection Factories are loaded into memory when its parent collection is loaded. Collection Factories are for creating multiple objects based on the prototype. The Collections associated with Collection Proxies are not loaded when its parent collection is loaded, they are loaded only when told to load, and load asynchronously - meaning when you call a Collection Proxy to load it loads on its own thread, and doesn’t cause your game to lag while loading, but you may still need to wait some time before a large collection loads. Collection Proxies are for arbitrarily loading external collections as their own independent “worlds” - you can use them to manage the different screens in your game project. If you wish you could add multiple game objects to each other inside of a .go file then you should be using collections instead and then spawning them using a collection factory. GOs can reference each other by name when inside of a collection. This means if you have a "head" and "body" GO you can address each "head" and "body" as such in the scripts of these GOs if they are inside of a collection, which means you do not need dynamic addressing for these cases. When you use collectionfactory.create() to create a collection based on a collection factory it returns a table of addresses of all of the GOs within that were just created.

Collection Proxy (*.collectionproxy): You define collections within collection proxies which you can then async load / unload as the contents of the defined collections are needed. These are often used for switching screens in games. The current best screen manager is Monarch. Use Monarch!

Collision Object (*.collisionobject): Collision Objects are used within the physics systems built into Defold. You place Collision Objects as child components of parent Game Objects. More on Collision Objects later in this chapter, and in the Physics chapter.

Cubemap (*.cubemap): Cubemaps are used as a type of texture useful for different kinds of things such as baked world reflections or sky boxes. Search Google for “cube mapping” for more information. These are currently not functional.

Factory (*.factory): A Factory is like a Collection Factory but for Game Objects. You define a Game Object prototype inside of the Factory, and then can communicate with the Factory to create new Game Objects based on the prototype. It’s up to you to keep track of and manage the created Game Objects - when you create a GO with factory.create() the return value is the address of the GO, which can then be stored in a table as a list of addresses to manage.

Font (*.font): Defold has great Font support. It supports creating bitmap fonts and distance field type fonts based on ttf font files. Distance field type fonts enable drawing great looking font glyphs at most sizes with keeping glyphs looking crisp. But they still have some gotchas, such as needing to generate a large enough glyph size, and some shapes still not looking right depending on the font you use. You may need to adjust the builtin distance field font material's fragment program to reduce smoothing if your fonts look blurry when scaled down. It is possible to use bitmap fonts, and for them to be scaled nearest neighbor, but you'll need to create a copy of the builtin fonts and set a sampler. View this video for a demonstration on distance field fonts: https://www.youtube.com/watch?v=CGZRHJvJYIg You can also use BMFonts generated by the BMFont tool (or any bitmap font generation tool that supports the BMFont format) this link shows an example of using BMFont fonts.

Fragment Program (*.fp): Fragment Programs (or Fragment Shaders) allow you to make graphical manipulations to your existing game textures to, for example, add borders, desaturate colors, or most any kind of effect you can think of. You can for example use DefBlend to shade your sprites with certain colors with different Photoshop like blending modes.

Game Object (*.go): Game Objects are an important building block of your projects. You can create Game Object Files external to Collections, which can then be easily imported into Collections, and when you modify the Game Object File its changes will be reflected in all of the Collections which have imported it. Game Objects created inside of Collections are unique to those Collections. If you want to be able to parent GOs to each other in your prefabs then you will want to put them inside Collections and then use a Collection Factory to spawn those assets.

GUI (*.gui): A GUI File allows you to build interfaces for your game projects. GUIs by default are rendered on their own render predicate tag layer in the builtin render script - on top of everything else. By default too, GUIs are rendered in a way that is more resolution and aspect ratio agnostic. GUIs ignore Z distance completely and do not use it for render ordering - instead they rely on relative order and parenting in the GUI file itself. If you have multiple .gui files inside of a scene then you can set each file's render order in each gui's gui_script file with gui.set_render_order(). This is usually used when you want a popup GUI above a game HUD GUI for example. You may want to define render order "layers" inside of a module which each gui_script can reference that way you can easily change the value of each type in a single place if necessary.

GUI Script (*.gui_script): GUI Scripts are special kinds of scripts meant for GUI objects only. The .gui_script files have specific GUI related API access that normal scripts cannot use.

Input Binding (*.input_binding): Defold supports many input methods: keyboard key events, mouse, text, touch, gamepad. You must define input bindings to keywords and then wait for the input which is associated action keyword to make actions. This is useful because you can define multiple inputs to the same keyword, and then only keep track of that single keyword. For example, you can define mouse left click, and touch to the same keyword, and then input for both are tracked with less code. Input is covered more in a later chapter. Light File (.light): This is deprecated and should not be used. It will be replaced in the future. It is still possible to create “lights” in scenes, but takes extra work and is not in standard Defold currently. This link is for a .input_binding with all possible options defined.

Label (*.label): A Label allows you to attach text to Game Objects as components. This allows an easy, direct way to associate nametags with minions which follow the minions around for example.

Lua Module (*.lua): Lua modules are different to GUI Scripts, Render Scripts, or Game Object Scripts (or just Scripts). You are always still coding in the Lua programming language, but every type of script has a different preset behavior and scope of available features to access. Generally you import Lua modules into other scripts to take advantage of their features in your project. There are many Lua libraries which are very useful with game development.

Material (*.material): Every visible object whether it be a sprite component of a game object, a font, or a model - all need a material set to it which defines how it is rendered. Inside of a material you can define its tags, which is used in the render script to render groups of objects, the vertex and fragment shaders, which define how the object which uses the material is rendered. You can also define default materials which you may want a material shader program to be able to access, and set the the sampler, which allows you to change how whatever it is you are rendering is filtered (nearest neighbor - good for keeping hard pixel edges when scaling pixel art, or linear- good for smoothing when scaling). In many cases, you will need to copy a builtin material into your project to make a custom version of it.

Model (*.model): A model file is a 3d object container where you define a mesh (currently only .dae files are supported), a 3d material, and textures for the material to use. You can also define a skeleton and, animationset, and default animation if you wish to animate your models.

Particle FX (*.particlefx): Defold has very good and efficient particles support. Particles are rendered on their own tag layer by default above game object sprites. If you wish particles to appear below game objects you could for example make a copy of the builtin material used by particles, give it a different tag name (or give it the "tile" tag so that it renders along with sprites - although this may cause more drawcalls), associate this new material with the particles you wish to draw below game objects, and then duplicate the particle tag in the render script so that the second tag is rendered before the game objects are. You can make multiple layers of game objects with this method too - you cannot otherwise mingle particles and game objects based on z distance ordering. Particle FX is currently only for 2D particle effects and does not function well in 3D space.

Render (*.render): Your Render file defines the location of your Render Script, which determines how your game is rendered. Tags are applied to materials, and you render objects with material based on the tags they have to render predicates. Rendering every tag is like an individual layer of paint, which can be made up of layer objects of its own, put on top of each other.

Render Script (*.render_script): The easiest way to create a new Render Script is to duplicate the one found in the builtins folder. You are more likely going to want to modify the builtin one than to create a new one from scratch. You will most likely want to use Orthographic or RenderCam community modules, or base a custom render script off those available in these projects.

Script File (*.script): If you create a new Script you will see that it is pre-made with several functions. If you add the script as a component to a Game Object which is part of an active Collection then some of these functions will be called automatically during the lifetime of your game and the Game Objects it is associated with. The init function is called when the associated Game Object first initializes. The final function is called when your game is about to quit, the collection the GO is in is about to be disabled, or the GO is deleted with go.delete() - to give your GOs a chance to do any final tasks, such as saving user data, before ending or letting other objects know it has been deleted. The update function is called every time your game updates - you can choose to increase or lower the update rate - a dt (delta time) argument is passed to the update function of a collection loaded through a collection proxy which allows you to modify your game’s simulation more reliably based on the real world time difference between the last update. The on_message function is for inspecting messages sent to the Game Object’s script - message passing is very useful, but has a cost and so should be wisely in the correct situations. Sometimes it's better to share data with Lua modules. The on_input function is for detecting, and using user input so that your game can react to player input to, for example, be able to move a hero around with a keyboard or touch a monster with a touch screen to attack it. Generally you only one to detect user input in a few scripts, then make that data accessible to other scripts through Lua modules. The on_reload function is used with the hot code reloading functionality of Defold - hot code reloading is very useful for development and debugging, and you should certainly use it - the on_reload function allows you to make special considerations to account for when reloading your game’s code.

Sound (*.sound): Defold currently only supports .wav and .ogg for sound. A good practice is to use WAV for short sound effects, and OGG for music or longer audio clips. If you need special audio features check the community asset portal as it has several useful options.

Spine Model (*.spinemodel): The Spine Model File is for defining information related to Spine Models created with the Spine application by Esoteric Software, which is a commercial, 2d puppet animation software. If you know games such as Dragon’s Crown this is the kind of tool that is used to make animations for games like that. It is really great software, and some very amazing effects are possible to create with it. Instead of rendering many frames of an animation to flat images you create parts of a body, and then animate those parts. In game, these parts are moved, and rotated based on the Spine animation date generated, which allows for much more efficient and smaller file sized games with great looking animated characters and doodads. You can also make Spine animations with the software Dragon Bones. You are allowed to use this without buying Spine as the Defold team wrote their own Spine runtime although you should certainly buy Spine if you are a professional to ensure that the official software can survive being developed. Not all newer features of Spine are supported in Defold's Spine runtime.

Spine Scene (*.spinescene): Before you can define a Spine Scene in a Spine Model, you must first create the Spine Scene and define the location of a spine_json file, which is the animation data generated by the Spine application, and you must create an Atlas file in Defold, which has all of the images used in your Spine animation. You can make many different spine animations, and then put all of their image parts into the same Atlases to be more efficient if it makes sense to do this. The sample_rate is by default at 30.0 but this is only how often the data of the spine model is simulated - it will not make your spine animations look bad - you can raise it if you need to, but try some animations first at this default sample rate. For some objects, you may even lower this as they don’t need to be sampled as often.

Sprite (*.sprite): It is more common to add Sprite Files directly as components to Game Objects, but you can still create them as single files too. After creating, you define the Atlas image from which you wish to grab a sprite image from by selecting the Default Animation once you have set the right Atlas. You can change the default material if you wish, and set the Sprite’s blending mode to be normal (Alpha), Add (additive - useful for making bright, shiny effects), or Multiply (useful in some situations, but you will probably use it rarely). If you create Animation Groups in your Atlases then Sprites can use this animation data to display flip book style frame by frame animations.

Texture Profiles (*.texture_profiles): You can define different texture compression for different sets of textures depending on which platforms you are targeting. This can enable you to enable very high texture compression on mobile targets as final binary size is very important. Keep in mind that if you have compression active it can greatly increase the time your game takes to bundle so only enable it while testing that / releasing a build. Defold supports WebP compression, which has significantly better compression than other formats. You may find that by using WebP compassion your game’s final binary is half the size. Use WebP!

Tile Map (*.tilemap): Tile Map files define information such as size of tile area, tile layers, and what tiles, from a Tile Source File, are set for each slot in a layer's grid. You can create level layouts in programs such as Tiled, and then export .tilemap files, or export .lua files, and import the .lua file into your in game .tilemap template along with any other metadata you wish to use in .lua layout files which are not possible in standard .tilemap files. For games with big, complex tilemaps either creating your own tile map editor inside of the Defold engine, or using Tiled is a very good idea.

Tile Source (*.tilesource): The Tile Source file defines the location of the image you would like to get tiles from, tile sizes, and has built in features for extruding tile edges (important to compensate for texture bleeding - you nearly always want this to be set to 2 for tiles).

Vertex Program (*.vp): Vertex programs (or Vertex Shaders) are part of the GLSL ES shader technology which Defold uses and defines the manipulation of vertex geometry. A Vertex Program is used along with a Fragment Program to define how your objects are rendered. Vertex Programs or Vertex Shaders handle individual vertices of objects. Most of your objects in Defold will be flat, 2d images, but even these have basic vertex geometry. Most likely you will not need to edit the builtin VPs.

More file formats which are possible to create but not on the default Assets list. You can find samples of these in the builtins folder.

Display Profiles (*.display_profiles): In the Display Profiles File you will define the sizes of displays you wish to target for GUI layouts. The builtin Display Profile default.display_profile has two Layouts for Portrait and Landscape at widescreen style sizes. With the use of a custom Display Profile, you can make a list of specific screen sizes you wish to build GUI layouts for, and then Defold can automatically pick the closets match when the game is ran on a device. Generally though the built in Landscape and Portrait profiles may be enough for you. To use these layouts you must add them to your GUI files as layouts and then set each layout active while you position the nodes within your GUIs.

Gamepads File (*.gamepads): A built in one can be found in the builtins/input folder. This file defines mappings and dead zones for specific gamepad models. A dead zone is the area on sticks where input is ignored. Unique mappings based on gamepad model is important to define because of variation of gamepad design and differences of how gamepads map with their driver compared to button position on the physical gamepad. If you make a game which is often played with gamepads you will most likely have complaints from people with rarer gamepad models. You can find gamepad related files on sites like Github which include lists of mappings / dead zone listings other people have already made for most popular models - the builtin file only includes a few. Defold does not currently support multiple gamepads at once; however, you can still have one gamepad and one keyboard input for example, and other more advanced setups, such as using mobile devices as gamepads, are currently possible.

You may also find references to .texture and .mesh, which are both used internally. There is also .emitter which is used by the ParticleFX files.