Castle Game Engine
Downloads and docs for developers
(version 4.0.1)

Contents:

1. Introduction

This is a free/open-source (LGPL / GPL) 3D game engine. In short:

• Our main 3D scene format is VRML / X3D, which is an open standard (you'll find you can export to it from virtually any 3D modeler), and a lot of our strength comes from it (it's a 3D scene format that can also express interactive world features, scripting etc.). Even if you don't know VRML/X3D, the whole engine is designed as a general-purpose 3D engine, and other 3D model formats are supported as well (Collada, Wavefront, MD3 and others).

• We have a lot of 3D graphic features. Shaders, shadows, bump mapping, mirrors, custom viewports, screen-space effects, and much more. Just look at the screenshots on this page :)

• We have a comfortable and extensible implementation of scene manager and 3D objects. You have a ready implementation of levels, creatures (with AI), items, players and other things typical to 3D games. You can extend it in many ways. You can also make your own 3D objects (if your game 3D world doesn't fit in our idea of creatures/levels etc.) by descending from T3D and adding to TCastleSceneManager.Items directly.

• The engine is developed for the Free Pascal Compiler, an open-source cross-platform compiler, and the engine is cross-platform as well (Linux, Mac OS X, Windows, and more). We have Lazarus components for RAD development, although the core engine doesn't depend on Lazarus LCL and you can develop full games with pure FPC (we have our own OpenGL window management unit, if you want). The whole engine is 100% clean Object Pascal code.

The features section below on this page contains more exhaustive list of engine features, with links to detailed information.

Many demo movies about Castle Game Engine are available in Michalis Kamburelis YouTube channel.

2. Download

Download "Castle Game Engine" (version 4.0.1)

• As tar.gz archive
• As zip archive (easier to unpack on Windows)

---

If you like this software, please consider donating.

This archive contains the whole engine sources. There are many simple example programs included (see examples/ subdirectory). Compile everything with simple "make" inside the castle_game_engine/ directory. Compile examples by simple "make examples". Or you can compile and run from Lazarus.

For more details about compiling the engine and examples see the "Introduction" page in our reference.

An important strength of our engine is that you can express a lot of stuff inside your data, that is inside VRML/X3D models. So many features of our engine (shaders, screen effects, mirrors and many many more) don't have any special ObjectPascal examples, because they are simply not needed. For simple uses, you just define what you need inside VRML/X3D file (of course, for advanced usage you can do a lot more with ObjectPascal code, and you can always build/modify VRML/X3D graph by ObjectPascal code). So be sure to grab our demo VRML/X3D models and try opening them with any engine example program (like scene_manager_basic.lpr, or even our view3dscene) — you will find that everything just works, not requiring a single line of ObjectPascal code.

Remember to install required libraries: programs developed using our engine (engine examples and normal programs) may use a couple of libraries. The full list of libraries is at the "Requirements" section at the documentation of each program, and the reference also lists the libraries in the introduction section. In short, you will most likely want to have libpng, zlib, OpenAL, and vorbisfile.

• On Linux and FreeBSD you should install these libraries using your favourite package manager. Remember to install -dev versions of these libraries too (if you're under Debian or similar distribution) to be able to compile programs that link to these libraries.
• On Windows (32-bit) you can find all the necessary DLL files in this archive (622 KB). Download this and copy all DLLs to program's exe directory (or put them somewhere on $PATH).
• On Mac OS X: Mac OS X requirements are listed here.

Instead of downloading the archive, you can also get the latest (bleeding-edge) engine sources from Subversion by:

svn checkout http://svn.code.sf.net/p/castle-engine/code/trunk/castle_game_engine

3. Documentation

• Tutorial
• Classes overview (cheatsheet)
• Guide to creating game data
• API reference (generated by pasdoc)
• Engine Internals Documentation (a little outdated documentation, but contains some information about how the engine works)

4. Features

Exhaustive list of our engine features:

• Optimized OpenGL rendering of models in X3D, VRML 2.0 (97) and VRML 1.0 formats. Including support for advanced VRML/X3D features like prototypes and events (user can interact with the 3D world).
• Collada, 3DS, MD3, Wavefront OBJ file formats are also supported. They are internally converted into the VRML/X3D nodes graph, which means that they get all the optimizations for rendering, and 3D content from all file formats can be mixed (for 3D editing tools and such).
• We allow you to use any 3D modeler to design your 3D data. Blender? 3DS Max? Anything else? In part, that's because VRML and X3D are open and popular 3D formats, and decent exporters for them exist in practically every 3D authoring tool. For detecting "placeholders" on levels (see creating levels documentation), you can configure detection method.
• Saving the current state of VRML/X3D node graph to standardized XML and classic encodings. You can even use it to make your own 3D modeller on top of our engine. Various conversions between 3D model formats and limited editing capabilities are provided out-of-the-box by our tools.
• Animations are supported, in two flavors: interactive animation interpolated at runtime, or precalculated animation for fast playback.
• Octrees are used for various collision detection tasks. For dynamic scenes, a hierarchy of octrees is used, allowing accurate and fast collision detection even when the scene constantly changes.
• Scene manager for centralized 3D world handling, with custom viewports possible.
• Extensible system of 3D objects. You have ready, comfortable management of creatures, items, levels and players. You can extend it by deriving descendants of engine classes in CastleCreatures or CastleItems or CastleLevels. Or you can make your own management of 3D objects, by deriving descendants of base T3D and other classes. Engine tutorial contains detailed information about this.
• Shadows by both shadow volumes (full implementation, with z-fail / z-pass switching, silhouette detection etc.) and shadow maps. Our shadow maps are very comfortable to use, and shadows from multiple light sources are correctly rendered. We also have experimental Variance Shadow Maps implementation.
• Bump mapping is trivially easy to use. Various algorithms are available: from the classic bump mapping (take normal from the texture), through the parallax bump mapping, up to the steep parallax bump mapping with self-shadowing.
• Shaders:
  • We have classes to easily use GLSL shaders. But usually you don't need to use them, because...
  • You can design and control GLSL shaders inside VRML/X3D. So GLSL shaders are fully available for model designers, programmer doesn't have to do anything.
  • We have developed special extensions to composite shader effects, to enable custom GLSL effects cooperate with each other and with built-in shader effects.
  • We fully support rendering both in fixed-function and programmable pipelines. In the latter case, the whole shading is expressed through GLSL shaders (that you can override with ComposedShader or exhance with Effect, see links above).
• Screen-space effects in GLSL are very easy to create (see ScreenEffect docs).
• Advanced texturing, following X3D standard: multi-texturing, cube map texturing (can be loaded from separate files, DDS files, or captured during runtime), 3D textures, S3TC compressed textures, anisotropic filtering.
• Speeding up rendering by hardware occlusion query, a simple approach and more involved Coherent Hierarchical Culling.
• CastleWindow unit is available to easily create windows with OpenGL context. The intention of this unit is to be something like glut, but magnitudes better — using clean ObjectPascal, for start. Also it allows you to easily create menu bars, open/save file and similar dialogs that are implemented using native controls (GTK 2 or WinAPI).
• Reading and writing of images in various formats, processing them and using as OpenGL textures. Besides many common image formats (png, jpg, ppm, bmp, just for starters), included is also support for DDS (textures with compression, mipmaps, 3d, cube maps) and RGBE format (Radiance HDR format).
• Handling of fonts, including rendering them with OpenGL, as bitmap or outline (3D) fonts.
• Comfortable 3D sound engine, using OpenAL, with intelligent sound source management, supporting WAV and OggVorbis formats. Includes VRML/X3D integration ("Sound" component of X3D specification), so content creators can define sound sources themselves.
• Basic 2D controls rendered through OpenGL (buttons, panels, tooltips, menus etc.) are available. Good for games, where making a custom-looking GUI (that fits with your game theme) is important.
• Anti-aliasing (initializing OpenGL multi-sampling) is covered.
• Simple ray-tracer is implemented (see the gallery).
• Playing movie files. This includes loading and saving as image sequence or "real" movie files (ffmpeg is needed to encode / decode movie files). While the implementation is limited to a small movies for now (as memory consumption is large), it's perfect for flame or smoke animation in games. We even have a simple movie editor as an example program in engine sources.
• The engine is portable. Currently tested and used on Linux, FreeBSD, Mac OS X and Windows, i386 or x86_64 (common 32-bit and 64-bit processors). Porters/testers for other OS/processors are welcome, the engine should be able to run on all modern systems supported by FPC. Ports to Android and iOS devices (smartphones, tablets) are also within reach, as our 3D renderer uses modern OpenGL (VBOs, possibility to render everything by GLSL). The portability of our engine is of course in large part thanks to the great Free Pascal Compiler.
• There are many example programs, look in sources castle_game_engine/examples/ subdirectory.
• There are ready window classes (TCastleWindow) and Lazarus components (TCastleControl) to make simple VRML/X3D and other 3D models browser, on a Lazarus form or independent from Lazarus LCL. The engine is integrated with Lazarus — we have various Lazarus components.
• Engine components are independent when possible. For example, you can only take model loading and processing code, and write the rendering yourself. Or you can use our OpenGL rendering, but still initialize OpenGL context yourself (no requirement to do it by our CastleWindow unit). And so on. Of course, ultimately you can just use everything from our engine, nicely integrated — but the point is that you don't have to.

5. FPC (Free Pascal Compiler) version required

You need the Free Pascal Compiler (FPC) to use our engine. We always support and advice the latest stable (from freepascal.org) release of FPC (currently 2.6.2). Usually, we also support a couple of older FPC releases. Currently (for engine 4.0.1) FPC versions >= 2.6.0 are supported.

You may also find it comfortable to use Lazarus, which is an IDE (editor, debugger etc.) built around FPC with a visual classes library (LCL). Our engine components can be used together with Lazarus forms (although we also have an alternative window classes, independent from Lazarus LCL). Any Lazarus version based on FPC >= 2.6.0 is supported now.

6. License

The whole engine and all related programs' sources are licensed on terms of GNU General Public License. See www.gnu.org for more information about this license (including translations of it to various languages) and philosophy of free software.

Moreover, the core of the engine is also alternatively available under the more permissive GNU Lesser General Public License with the so-called "static linking exception". The idea of this exception is to allow statically linking with the engine on the same terms as dynamically linking. (Static linking is what normally happens when you compile a program using my units, without wrapping them in a DLL / Delphi runtime package.)

All this basically means that you have to share your modifications to the engine, and you can use the engine in closed-source programs.

The precise legal text of the "static linking exception" follows (it's the same as used by FreePascal Runtime Library and many other projects):

As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.

Important notes:

• If you want to use the engine on LGPL terms (as opposed to more strict GPL) you must compile the engine with CASTLE_ENGINE_LGPL symbol defined in file castle_game_engine/base/castleconf.inc. Just put there {$define CASTLE_ENGINE_LGPL} line (or simply remove the beginning space in already prepared comment { $define CASTLE_ENGINE_LGPL}).

  This is necessary to avoid pulling in GPL-only dependencies. For now, this is only the NURBS unit (uses GPL-only code from White_dune). This missing NURBS implementation is the only difference between LGPL and "strict GPL" engine version.

• Note that LGPL stuff concerns only the engine, i.e. things inside castle_game_engine archive. The rest of the programs (view3dscene, castle etc.) are still strict GPL.