1. Fundamentals

1.1. Introduction

Grit Screenshot
The 'playground' map.

(TODO: This book is incomplete, but is posted online in the hope that its existing content be useful.)

The Grit Game Engine allows you to create interactive 3D environments such as computer games. Its fundamental architecture is based around the Lua scripting language. Games are created by writing scripts that have complete control all aspects of the engine, i.e. graphics, physics, game logic, audio, etc. This is done at a very high level, with an easy-to-use but powerful programming model. This book explains how to do this, by giving an introduction to the various APIs involved. The in-game Lua console allows experimentation, debugging, and development of these scripts while the game is running.

Grit is very general-purpose. This is achieved by having independent Lua APIs for the various subsystems (graphics, physics, audio, input, etc). The low level performance critical parts of the engine, such as the rendering pipeline and the collision detection, are written in C++. However, the Lua APIs are designed to be as expressive and safe as was possible without compromising on performance. Most of the APIs are object-oriented in style.

Some of these APIs allow one to create bodies, which represent some tangible thing, that can be seen, heard, or otherwise experienced by the player in some way. Lua code can modify fields of these objects in the usual way, controlling the way that they manifest, e.g. changing their colour (for graphical bodies) or their volume (for audio bodies). There are many such bodies and they each have many modifiable fields, according to their function. There are also other APIs that are less tangible like user input and resource management. Finally there is a category of Lua code that is very declarative and is approachable even for those with no programming experience. This is used for defining resources, like graphical materials.

Such APIs are a toolbox for achieving what you want, but there is another category of Lua code that allows one to create objects with their own behaviour. This is done by defining classes, and instantiating them as objects. Such objects have user-defined methods and fields like an object-oriented language. One can define game classes that instantiate into game objects. Such objects act as glue to bind together graphics, physics, audio, etc. bodies, as well as implement game logic. One can write a car game object class that handles all the simulation aspects of a car, as well as graphical details (e.g. exhaust smoke) and gameplay details (e.g. hit points), engine noise, and so on. The same technique is also used to give custom behaviour to particles, and for the GUI.

Finally, as the whole engine is open source, you can also modify the C++ code and either add functionality that way. However, this is advised if it is not possible to proceed by writing Lua scripts. For example, if you need to write a very optimised algorithm, using multicore, SIMD, and cache awareness, you would need to write it in C++. Even so, you would probably add a Lua binding for your new code, because developing high level code in Lua, using the in-game console is far easier than rebuilding the whole engine and debugging it in a C++ debugger. This book concentrates on the Lua APIs, there are some doxygen docs for the C++ code.

1.2. Licensing

Grit is open source and is released under a liberal license. It can be used for both commercial and non-commercial projects. However this does not apply to some of the example assets. It is not expected that third parties will be re-using and reselling these assets, as they exist only to demonstrate the engine. Furthermore, unlike source code, it is hard to find good quality assets under permissive licenses.

The copyright and license for the code and assets within the project package breaks down as follows:

1.2.1. Core Works

Grit core works are sufficient to build a game, if you provide your own assets. This covers all code released as part of Grit. The works are released under the MIT license:

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.

1.2.2. Example Content

Some assets have copyright owned by project contributors, and are released under liberal licenses such as MIT or CC-BY, just like the source code. But other assets have less liberal licenses such as CC- SA, CC-NC or GPL. Furthermore, many assets are taken from stock image sites and thus copyright is still owned by those sites. In these latter cases, care must be taken to use the assets in accordance with the appropriate licenses, as dictated by their copyright owners. Each directory has a copyright.txt file that lists the legal status of each asset in that directory.

1.2.3. Dependencies

Grit is linked to a number of other libraries that have different licenses that you must also be aware of. See the documentation that comes with these libraries for more information.