Fifengine - Developer Manual

Install these extensions for FIFE development:

Use Visual Studio 2022 Community or later. Open the CMake project directly or generate a solution with CMake.

Open the repository root. CLion auto-detects CMakeLists.txt and configures the project.

Firstly, we need to setup an IDE and several build tools.

Fifengine depends on several external libraries.

This is the detailed list.

Our next step is to ensure that all dependencies are installed properly, before you try to build fifengine itself. You have the choice of building the dependencies from source or fetching pre-build, packaged binaries.

Fifechan is a C++ GUI library that is required as an optional dependency for FIFE. You need to build it from source before building FIFE.

If you have Python 3 installed you can choose the Version with the command:

Finally, we can compile Fifengine.

To build Fife, you’ll of course need the Fife source code. You can download a Fife source code package or fetch the latest source using git.

Configure and build using CMake:

To specify a custom Python executable, add the -DPYTHON_EXECUTABLE option:

To build with the C/C++ library and header files:

For Debug builds, replace Release with Debug.

Firstly, we need to setup an IDE and several build tools.

Fife depends on a multitude of external libraries.

Our next step is to ensure that all dependencies are installed properly, before you try to build fifengine itself. You have the choice of building the dependencies from source or fetching pre-build, packaged binaries.

We do not provide a pre-packaged software development kit for Linux.

Additionally, you find more detailed information in the dependencies chapter.

Fifechan is a C++ GUI library that is required as an optional dependency for FIFE. You need to build it from source before building FIFE.

Finally, we can compile Fifengine.

To build Fife, you’ll of course need the Fife source code. You can download a Fife source code package or fetch the latest source using git.

If you have only an old version of cmake (2.X) then please do this:

To build fife with Python support only do:

To build it with Python support only do (with Clang instand of GCC Compiler):

To build fife with Python support and with c/c++ lib and header files do:

To build fife with Python support and with c/c++ lib and header files do (with Clang instand of GCC Compiler):

after that you can build the project using make and then install it:

Firstly, we need to setup an IDE and several build tools.

Fife depends on a multitude of external libraries.

Our next step is to ensure that all dependencies are installed properly. We do this by either compiling and installing them manually or by fetching and installing pre-compiled binaries.

We do not provide a pre-packaged software development kit for Mac.

Additionally, you find more detailed information in the dependencies chapter.

Fifechan is a C++ GUI library that is required as an optional dependency for FIFE. You need to build it from source before building FIFE.

Finally, we can compile Fifengine.

To build Fife, you’ll of course need the Fife source code. You can download a Fife source code package or fetch the latest source using git.

To build fife with Python support only do:

To build fife with Python support and with c/c++ lib and header files do:

after that you can build the project using make and then install it:

To create a minimal FIFE project from scratch:

The FIFE repository is organized as follows:

The engine is divided into loosely coupled modules within engine/core/. Each module has a clear responsibility:

Modules communicate through well-defined interfaces. The model module does not depend on video, and pathfinder does not depend on audio. Cross-cutting concerns (logging, settings) are in util and used by all modules.

From a code perspective, the engine is layered:

Each layer only depends on the layer below it. Game code can call either the Python API (via SWIG) or the native C++ API directly.

Depending on CMake options, the build produces:

When -Dbuild-library=OFF, only the Python extension is built (linked statically against the engine core).

FIFE uses a single-threaded model for the main game loop:

Pathfinding is the only operation that can be offloaded to a background thread (via RoutePather::setAsync(true)), but results must be consumed on the main thread.

FIFE follows these ownership patterns:

To add a new subsystem to the engine:

FIFE uses SWIG to generate Python bindings from C++ headers.

SWIG interface files (.i) are located in engine/swigwraps/. Each file corresponds to a subsystem:

To expose a new C++ method to Python:

SWIG-generated wrappers use reference counting. Key rules:

PyChan is a Pythonic wrapper around FifeChan, providing a widget-based GUI system.

PyChan widgets wrap FifeChan widgets. The GuiManager is the root container that manages focus, input routing, and rendering.

FIFE uses manager classes to cache and lazily load resources:

Resource managers follow a common pattern:

FIFE uses an observer pattern for events:

Available listener types: MouseListener, KeyListener, WidgetListener, TimeEventControllerListener.

Renderers are registered and executed each frame in order:

To register a custom renderer, subclass RendererBase and call View::addRenderer().

The logging system supports multiple modules and levels:

Levels: LOG_DEBUG, LOG_INFO, LOG_WARNING, LOG_ERROR

Modules can be filtered at runtime via Log::setModuleLogLevel().

The XML settings file maps directly to EngineSettings:

Each XML element maps to a setter in EngineSettings: * <Screen width="1024"> → settings.setScreenWidth(1024) * <Render backend="OpenGL"> → settings.setRenderBackend("OpenGL")

The Virtual File System (VFS) abstracts file access:

The pathfinder uses a cell cache for efficient lookups:

FIFE uses virtual methods and interfaces for extensibility. Common patterns:

To create a custom renderer:

For the complete API, see the C++ API Documentation.

SWIG interface files (.i) define which C++ declarations are exposed to Python. Each file follows this structure:

The %{ …​ %} block contains C++ code inserted into the generated wrapper (typically #include directives). The %include directives tell SWIG which headers to wrap.

To expose a new C++ method to Python:

SWIG generates reference-counted Python wrappers. Key rules:

SWIG converts C++ method names to Python conventions: * getSomething() → getSomething() (unchanged by default) * Use %rename to customize: %rename("get_something") getSomething;

C++ enums become Python classes with integer values:

std::vector<T> is automatically converted to Python lists. Return types of std::vector<T> become Python lists.

To write a Python extension that integrates with the engine:

PyChan wraps FifeChan widgets for Python. Engine developers working on PyChan:

FIFE maps are stored as XML files. The basic structure:

Objects are defined in separate XML files and loaded by ObjectLoader:

Image atlases group multiple images:

The MapLoader class handles loading maps from XML:

The MapSaver class writes maps back to XML, serializing the in-memory model.

To add custom data to the map:

Every program has to give some basic settings.

These are FullScreen, PlaySounds, ScreenResolution, RenderBackend and Lighting.

If any one of them is excluded, FIFE cannot load the program and will generate error:

AttributeError: 'NoneType' object has no attribute 'findChildByName' .

So, the basic xml file to load FIFE by the client looks like this:

When using the C++ API directly, settings are configured programmatically:

Apart from these basic settings, other settings are also possible.

All these settings are given below with a brief description attached to them below:

Users locally commit their changes to their working copy.

When they are happy with the outcome, they share these commits by pushing them to the remote server.

You need to either commit every change you did to your clone or select the files you want to update with the commit.

This is, amongst others, done with git add.

Add the changes in the two files export.h / module.h, move the index (of a file without changes) and remove a file as well:

git rm also removes your local copy of that file! You can use the flag -- cached to prevent this.

Now you can use git status to check of everything fits what you want to commit.

If so, run git commit

and $EDITOR opens up, asking you for a commit message. When you save this file (and it’s not empty), the commit is executed.

GitHub has a blog post about commit message guidelines. See also this very helpful resource.

After that, you can push your changes to the remote repository with git push origin foo if you worked on the branch foo. Normally you will use git push origin master.

Edit your most recent, local commit

Just work like you would do with your regular next commit (edit files, git add and so on). When you’re done, type git commit --am and edit the old commit message to fit the appended additions as well.

This should only be used if you are sure that nobody worked on anything in the meantime!

Move to the most recent pushed commit

Moving to any commit in general

Browse git log for the ID of the last commit you want to keep, removing every newer change. Then (with that ID) use

Most of the time git revert is what you are looking for.

It does a better job in reverting pushed commits (the two commits will be kept in the project history).

StackOverflow: How to delete a Git commit

Branches are what makes git awesome! They are easy, fast and incredibly useful for distributed development.

Check which branch you are currently on, show all available branches

Change to another branch

Track a remote branch

Create new branch named foo

Delete the branch named foo

If the branch was not yet merged, use -D instead of -d.

Try to merge the branch foo into your current branch

Note that this will create conflict markers in each file where auto-merging is not possible.

You will need to resolve these conflicts manually — there are several tools to do so, see git mergetool.

When ready, you need to commit the resolved files.

The commit message will automatically indicate what kind of conflicts we had.

If you are familiar enough with git, you may of course also customize the options given to the following. This is by all means only a recommendation and no rule to strictly follow.

Generate files containing the two most recent commits

After committing all your changes to a freshly-pulled repo, use

Where -4 instead of -2 would create patch files for the last four commits.

Applying such a file called 0001-user.patch is done using

Note that the Unix tool patch does not need to support patch file renaming, so git am is the preferred way to apply patches. Useful flags might be --resolve.

-M -B handles renaming correctly to create smaller patch files, but this will then only be recognized by git (no unified patch anymore).

To correctly display who did what in our history, please use the following flags to git commit:

If you already committed the files and now remembered you need to fix the author, use git commit --amend and proceed as above. This will edit the newest commit instead of creating a new one.

This is especially important for artists, who otherwise might not get proper credits. Ask them under which name and address they’d like to appear, then use that name consistently as Author Name.

Look up who introduced what in <path>

Check what happened in your repo

Use git log, git show, or git diff.

Find out which commit(s) cause a bug

Start with

and

Then continue to run the bisection with either entering git bisect good, if the bug does not show up or git bisect bad if it does. Repeating that, you will be presented a suspicious commit in the end: investigate there!

In general, don’t use friend declarations. Friends tend to get overused, since at first sight they provide quick and easy solution for problem at hand. In many cases however, they violate encapsulation and decrease modularity. There are cases where friends might be beneficial, but consult other developers before making the decision.

Template source files can be found from svn:

The level of commenting outlined here may seem excessive, but it will make the code much easier to understand when a new coder has to work with the system, something that will inevitably be happening in an Open Source project like FIFE. So please, don’t become lax with the commenting.

Along with other comments, use gotcha keywords to mark unfinished tasks in the code. Doxygen will parse your comments looking for these keywords, and making a report, so people can make a special effort where needed.

TODO: Add class documentation.

The level of commenting outlined here may seem excessive, but it will make the code much easier to understand when a new coder has to work with the system, something that will inevitably be happening in an Open Source project like FIFE. So please, don’t become lax with the commenting.

This is even more important as we only provide the engine. Remember each comment might fix a misunderstanding and thus problem for the game devs using FIFE.

Write the public documentation and comments from the point of a user.

All methods should be documented, no matter how trivial. Here’s an example of how to document using epydoc style. If possible link to other relevant functions, provide a use case and give information on the expected results of the function.

Comments inside the body of a method should be kept to a minimum in simple functions again. But in large functions, especially those that encapsulate key algorithms, relatively detailed descriptions of how the code is operating will make it much more maintainable.

Member variables should all be commented. Either individual variables, or blocks of variables with a similar function, as long as all member variables are in some way described. This is not a substitute for good variable names, but rather a way to make clear the use of each member variable.

The documentation should be in the init function.

Parameters are all commented in the method description comment block so additional comments are unnecessary.

Descriptions of local variables shouldn’t be necessary as long as descriptive names are used.

Along with other comments, use gotcha keywords to mark unfinished tasks in the code.

Python tooling is configured in pyproject.toml at the repository root.

The ./build-tools directory in the fifengine repository contains wrapper scripts that run the above checkers. Consult that folder for the exact scripts available and their usage. These scripts are typically used in CI and can also be run locally before submitting pull requests.

To build and run C++ tests:

To run specific test cases:

To run Python tests:

To run with verbose output:

Create test files in tests/ following the Catch2 pattern:

Create test files in tests/ following the pytest pattern:

For Python/C++ mixed debugging, use the Python Tools for Visual Studio (PTVS) extension.

Install extensions: * C/C* for C debugging * *Python for Python debugging * CMake Tools for CMake integration

Create .vscode/launch.json:

Open the repository root. CLion auto-detects CMake and provides integrated debugging. For KDevelop, import the CMake project and configure the run configuration.

Generate an Xcode project:

Set breakpoints and use Xcode’s integrated debugger.

To debug C++ code called from Python:

Use Xcode Instruments for CPU, memory, and GPU profiling:

Use the Performance Profiler in Visual Studio (Debug → Performance Profiler).

The CI workflow runs on every push and pull request:

Configuration: .github/workflows/ in the repository.

Appveyor builds Windows binaries:

Configuration: appveyor.yml in the repository.

The 1-download.bat script downloads all required software components. It uses aria2 (a lightweight download utility) to fetch:

Downloads are fetched from: * GitHub releases and official project websites * Appveyor artifact storage (for pre-built dependencies)

The download list is defined in download-lists/fifengine.txt and download-lists/fifengine-build-tools.txt. Each line specifies a URL and target filename.

The 2-extract.bat script extracts downloaded archives using 7zip (7z.exe). It:

The 3-copy.bat script copies files into the SDK staging directory:

The 3-stripdown.bat script removes unnecessary files to reduce installer size:

Launch the application to open the graphical interface:

For batch processing, use the command-line interface:

Options:

The supported Image File Types are: - png - jpg - jpeg - tga - bmp

See Source

Input images can be provided as: * A directory of images (processed recursively) * A list of individual files * A manifest file listing image paths

The tool produces:

This metadata file is compatible with FIFE’s object XML format and can be referenced directly in object definitions.

Create a sprite atlas from a directory of character sprites:

Create a tile atlas with specific padding: