This page provides an introduction for new artists thinking about developing assets for the Grit Game Engine.


There are various kinds of assets that must be combined to form an object in game. There are the obvious textures required, and graphical mesh. If the object is to have physical interactions (i.e. you can't walk straight through it) then it will need a Collision shape. There are also Lua files which are scripts capable of doing almost any amount of customisation. For non-programmers, do not be daunted by this, all that is required from you is the copy-pasting of some sample definitions and changing some of the values in intuitive ways. However, those with programming experience and interest can easily do much more.

We typically use a directory off the top-level game directory (in the SVN repository this is gritengine/grit_core/media) for each map. For instance the playground map is contained in the playground directory. By convention, the init.lua file in that directory is the 'starting point' of the map. It is the file first looked at by the engine, and all definitions, references to assets, etc are found by inspecting the init.lua file and then going from there.

Note that lua files can include other lua files, so the init.lua can be only the starting point of a beautifully organised tree of assets, grouped by categories and with other init.lua files doing subsections of the work to keep the files short and manageable. This works by linking the lua files together in a tree structure, e.g. the playground/init.lua file includes the img/init.lua file where more definitions are found.

Paths and Directory Organisation

The assets in Grit live in a system of directories on disk. Assets that exist in files obviously use the disk directories, but materials and classes for instance, that are defined in Lua files and have no representation on disk, are also part of this directory system. When you refer to an asset, this is with respect to a current directory. When typing on the console, the current directory is the root of the game directory, or /. Therefore these are the same:

 lua> place "vehicles/Evo"
 lua> place "/vehicles/Evo"

For code in a .lua file, the current directory is usually the directory in which the .lua file was put. If you're writing a lua file and you want to refer to a texture in the directory below, you would write "../texture.dds". You can also give absolute paths, e.g. "/common/tex/Rust.dds". This means it is best to keep the files which are used by the lua file close by in the directory structure, to minimise the amount of typing you need to do in order to 'reach' those files. It also means you can rename directories without having to modify lots of lua code.

As a fuller example, if you are making a map called 'spaceland' you would create a directory called 'spaceland' at the top level of the game directory. Put a mesh called 'planet.mesh' and a texture called "planet_surface.dds" in the 'spaceland' dir, and also create a lua file 'spaceland/init.lua'. In the lua file, define the material 'planet_surface' (a material that the mesh expects to find) to use the texture "planet_surface.dds", as well as defining the class 'planet' that has no collision shape but does use the 'planet.mesh' asset. Because everything lives in the 'spaceland' dir (even the things defined in the lua file), there is no need to worry about paths. You can also rename the directory 'spaceland' to 'outer_space' without having to modify any of the assets within.

If you later create a subdirectory 'spaceland/asteroid_field' and repeat the whole procecure, including creating a lua file called 'spaceland/asteroid_field/init.lua'. Include this new init.lua from the original lua file with the code:
 include "asteroid_field/init.lua"

This way you can create deep organised nestings of assets. If in doubt, define assets in the same directory as the init.lua file, and access everything without a path prefix.


Currently we only support 3D Studio Max and Blender.

There are exporters for the 3 kinds of things you do in a modeller:

  • Graphical meshes for rendering (Grit Ogre mesh exporter)
  • Collision shapes for physical simulation (Grit TCOL exporter)
  • Placement of objects within a scene (Grit map exporter).

These can also be done manually, but due to the large number of floating point values involved, and the precisions required, it is only practical to use the

Installing/Using The Exporters

See here? for installation instructions and there is a work-in-progress tutorial on using them here

Writing the Lua

There is additional work to be done manually by writing Lua files. Lua files are used to define the materials used by physical / graphical meshes. Only the material names are exported from 3DS Max, you must define materials in Lua with matching names for your meshes to work correctly. The graphical materials are defined separately to the physical materials.

Lua is also used for defining classes, which bring all of these assets together to define a single prop, piece of terrain, vehicle, etc.

After defining the materials and class definition, you can now try to place an object manually from the game's console. If you're in an empty map, you can type

 object "spaceland/planet" (0,0,0) { }

To create the planet at 0,0,0.

In order to place many objects in a scene, you would use the scene exporter.


See also