Skip to content

Commit 41fa13a

Browse files
jakochjakoch
committed
add dev-manual chapters
1 parent 78a9fdf commit 41fa13a

20 files changed

Lines changed: 1557 additions & 162 deletions

‎developer-manual/en/book.adoc‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -46,13 +46,13 @@ endif::backend-pdf[]
4646
:license: https://github.com/fifengine/fifengine/blob/master/LICENSE.md
4747
:issue-ref: https://github.com/fifengine/fifengine/issues
4848
:docs-issue-ref: https://github.com/fifengine/fifengine-docs/issues
49-
:irc-ref: http://webchat.freenode.net/?channels=%23fife
49+
:community-ref: https://github.com/fifengine/fifengine/discussions
5050

5151
[NOTE]
5252
.This document is under active development and discussion!
5353
====
5454
If you find errors or omissions in this document, please don't hesitate to {docs-issue-ref}[submit an issue or open a pull request] with a fix.
55-
We also encourage you to ask questions and discuss any aspects of the project on {irc-ref}[IRC].
55+
We also encourage you to ask questions and discuss any aspects of the project in {community-ref}[GitHub Discussions].
5656
New contributors are always welcome!
5757
====
5858

@@ -73,17 +73,16 @@ include::chapter03_contributing.adoc[]
7373

7474
include::chapter04_coding-standards.adoc[]
7575

76+
include::chapter04-testing-debugging.adoc[]
77+
78+
include::chapter04-release-process.adoc[]
79+
7680
include::chapter05_fife-windows-sdk.adoc[]
7781

7882
include::chapter06_image-atlas-creator.adoc[]
7983

8084
:!sectnums:
8185

82-
//include::appendix.adoc[]
83-
//include::bibliography.adoc[]
84-
8586
include::list-of-dependencies.adoc[]
8687

8788
include::glossary.adoc[]
88-
89-
//include::colophon.adoc[]

‎developer-manual/en/chapter01-building-fifengine-on-mac.adoc‎

Lines changed: 0 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -98,18 +98,6 @@ cmake -G Ninja -DCMAKE_INSTALL_PREFIX=/usr/local -DCMAKE_BUILD_TYPE=Release ..
9898
cmake --build .
9999
sudo cmake --install .
100100
----
101-
git clone https://github.com/fifengine/fifechan.git && cd fifechan
102-
----
103-
104-
[source,bash]
105-
----
106-
mkdir _build; cd _build; cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr ..
107-
----
108-
109-
[source,bash]
110-
----
111-
make && sudo make install
112-
----
113101

114102
==== Building Fifengine
115103

‎developer-manual/en/chapter01-building-fifengine-on-windows.adoc‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,7 @@ You'll now find the dependencies the `fifengine-dependencies` folder:
8686
dir ..\fifengine-dependencies
8787
dir ..\fifengine-dependencies\downloads
8888
dir ..\fifengine-dependencies\includes /s
89+
----
8990

9091
==== Building Fifechan
9192

@@ -142,3 +143,39 @@ With "-DPYTHON_EXECUTABLE=/PATH/TO/PYTHONEXECUTABLE" you can change the Python V
142143
----
143144

144145
Finally, we can compile Fifengine.
146+
147+
To build Fife, you'll of course need the Fife source code.
148+
You can download a Fife source code package or fetch the latest source using git.
149+
150+
[source,bash]
151+
----
152+
git clone https://github.com/fifengine/fifengine.git && cd fifengine
153+
----
154+
155+
Configure and build using CMake:
156+
157+
[source,bash]
158+
----
159+
mkdir _build
160+
cd _build
161+
cmake -G "Visual Studio 17 2022" -A x64 ..
162+
cmake --build . --config Release
163+
----
164+
165+
To specify a custom Python executable, add the `-DPYTHON_EXECUTABLE` option:
166+
167+
[source,bash]
168+
----
169+
cmake -G "Visual Studio 17 2022" -A x64 -DPYTHON_EXECUTABLE=C:\Python311\python.exe ..
170+
cmake --build . --config Release
171+
----
172+
173+
To build with the C/C++ library and header files:
174+
175+
[source,bash]
176+
----
177+
cmake -G "Visual Studio 17 2022" -A x64 -Dbuild-library=ON ..
178+
cmake --build . --config Release
179+
----
180+
181+
For Debug builds, replace `Release` with `Debug`.

‎developer-manual/en/chapter01-running-the-demos.adoc‎

Lines changed: 59 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,65 @@
22

33
The demos have their own git repository: https://github.com/fifengine/fifengine-demos
44

5-
Assuming that you have successfully built fife,
5+
Assuming that you have successfully built fife,
66
you will be able to change directory to one of the fife demos located in `<fifengine-demos>` and type: `python run.py`.
77

88
NOTE: You might also run the demos by double-clicking the `run.py` file in your file browser. This requires python to be associated with .py files in order to work.
9+
10+
==== Available Demos
11+
12+
[cols="1,3", options="header"]
13+
|===
14+
| Demo | Description
15+
16+
| *rio_de_hola*
17+
| The flagship demo. Shows isometric rendering, pathfinding, agent movement, and layered maps.
18+
19+
| *pychan_demo*
20+
| Demonstrates the PyChan GUI toolkit: buttons, text fields, windows, and layouts.
21+
22+
| *fife_test*
23+
| Minimal test case for engine initialization and basic map loading.
24+
|===
25+
26+
==== Troubleshooting
27+
28+
* *ImportError: No module named fife* — FIFE Python bindings are not installed or not on `PYTHONPATH`. Build FIFE first and ensure the bindings are accessible.
29+
30+
* *SDL2 not found* — Install SDL2 development libraries for your platform (see build instructions for your OS).
31+
32+
* *Black screen / no rendering* — Verify OpenGL drivers are installed. Try setting `RenderBackend=SDL` in the engine settings to use software rendering.
33+
34+
* *Segfault on startup* — Often caused by mismatched FIFE library and demo versions. Ensure both are from the same commit or release.
35+
36+
==== Creating a Minimal Project
37+
38+
To create a minimal FIFE project from scratch:
39+
40+
1. Create a directory for your project:
41+
+
42+
[source,bash]
43+
----
44+
mkdir my-fife-game && cd my-fife-game
45+
----
46+
47+
2. Create `run.py` with minimal engine initialization:
48+
+
49+
[source,python]
50+
----
51+
import fife
52+
53+
settings = fife.Settings()
54+
engine = fife.Engine(settings)
55+
engine.init()
56+
57+
# Your game logic here
58+
59+
engine.destroy()
60+
----
61+
62+
3. Create a `settings.xml` file to configure the engine (see xref:chapter02-engine-settings.adoc[Engine Settings] for available options).
63+
64+
4. Create an `objects/` directory for your game objects and a `maps/` directory for your map files.
65+
66+
NOTE: For a complete working example, see the `rio_de_hola` demo in the fife-demos repository.

‎developer-manual/en/chapter01_compiling-fife.adoc‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
Compiling Fifengine is a complicated and time consuming task.
44
This chapter explains how to setup a compilation environment for Fife.
55

6-
You'll find detailed setup steps for fifengine on the operating systems Linux, Windows and Mac.
6+
You'll find detailed setup steps for fifengine on the operating systems Windows, Linux and Mac.
77

88
The individual subchapters have the same structure:
99

@@ -15,10 +15,10 @@ Thirdly, we'll show how to build fifengine itself.
1515

1616
Without further ado, let's get started.
1717

18-
include::chapter01-building-fifengine-on-linux.adoc[]
19-
2018
include::chapter01-building-fifengine-on-windows.adoc[]
2119

20+
include::chapter01-building-fifengine-on-linux.adoc[]
21+
2222
include::chapter01-building-fifengine-on-mac.adoc[]
2323

2424
include::chapter01-cmake-configuration-options.adoc[]

‎developer-manual/en/chapter02-cpp-development-patterns.adoc‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
=== C++ Development Patterns
2+
3+
This section covers common patterns for extending and developing with the FIFE engine in C++.
4+
5+
==== Extending FIFE Classes
6+
7+
FIFE uses virtual methods and interfaces for extensibility. Common patterns:
8+
9+
* *Subclass and override* — Create a derived class and override virtual methods (e.g., `RendererBase`, `MouseListener`).
10+
* *Register your implementation* — Pass your subclass to the appropriate manager or subsystem.
11+
* *Use existing patterns* — Follow the observer/listener pattern for events, the manager pattern for resources.
12+
13+
==== Implementing a Custom Renderer
14+
15+
To create a custom renderer:
16+
17+
1. Subclass `fife::RendererBase`:
18+
+
19+
[source,cpp]
20+
----
21+
class MyRenderer : public fife::RendererBase {
22+
public:
23+
MyRenderer() : fife::RendererBase("MyRenderer") {}
24+
void render(fife::RenderBackend& backend, fife::Layer* layer) override {
25+
// Custom rendering logic
26+
}
27+
};
28+
----
29+
30+
2. Register with the view:
31+
+
32+
[source,cpp]
33+
----
34+
view->addRenderer(new MyRenderer());
35+
----
36+
37+
==== Adding a New Pathfinder Algorithm
38+
39+
1. Create a new class in `engine/core/pathfinder/` inheriting from the pathfinder interface.
40+
2. Implement the search method (A*, Dijkstra, etc.).
41+
3. Register in the pathfinder router so it can be selected via `RoutePather::setPathingStrategy()`.
42+
43+
==== Adding a New Resource Type
44+
45+
1. Create a resource class (e.g., `MyResource`) with load/release methods.
46+
2. Create a manager class (`MyResourceManager`) following the pattern of `ImageManager`.
47+
3. Register the manager in the engine initialization.
48+
49+
==== Key Internal Classes
50+
51+
[cols="1,3", options="header"]
52+
|===
53+
| Class | Purpose
54+
55+
| `Engine`
56+
| Entry point; owns all subsystems, manages lifecycle
57+
58+
| `Model`
59+
| Game world container; owns maps, layers, instances
60+
61+
| `Map`
62+
| A single game map; owns layers and cameras
63+
64+
| `Layer`
65+
| A grid of instances; provides spatial queries
66+
67+
| `Instance`
68+
| A placed object in the world; has position, rotation, animation
69+
70+
| `Object`
71+
| Template/archetype defining instance properties
72+
73+
| `RendererBase`
74+
| Base class for all renderers
75+
76+
| `View`
77+
| Manages cameras and renderer pipeline
78+
|===
79+
80+
For the complete API, see the https://fifengine.github.io/fifengine/api/[C++ API Documentation].

0 commit comments

Comments
 (0)