Skip to content

Commit b03d30d

Browse files
jakochjakoch
committed
document map format and lighting, fixes #2 
1 parent 0b2d6b6 commit b03d30d

3 files changed

Lines changed: 212 additions & 9 deletions

File tree

‎README.adoc‎

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -8,15 +8,16 @@ image:https://travis-ci.org/fifengine/fifengine-docs.svg["Build Status", link="h
88

99
[width="100%",options="header", cols="2,^1,4"]
1010
|====================
11-
| Resource | Format | Language / Link
12-
| User Manual | HTML | {USR-MAN-HTML-EN}
13-
| Developer Manual | HTML | {DEV-MAN-HTML-EN}
14-
| FAQ | HTML | {FAQ-HTML}
15-
| C++ API Documentation | HTML | https://fifengine.github.io/fifengine/api/
16-
| Python API Documentation | HTML | https://fifengine.github.io/fifengine/api/python
17-
| Wiki | HTML | https://github.com/fifengine/fifengine/wiki
18-
| Github Pages | HTML | https://fifengine.github.io/fifengine-docs/
19-
| Docs Repository | ASCIIDOC | https://github.com/fifengine/fifengine-docs
11+
| Resource | Format | Language / Link
12+
| User Manual | HTML | {USR-MAN-HTML-EN}
13+
| Developer Manual | HTML | {DEV-MAN-HTML-EN}
14+
| FAQ | HTML | {FAQ-HTML}
15+
| C++ API Documentation | HTML | https://fifengine.github.io/fifengine/api/
16+
| Python API Documentation | HTML | https://fifengine.github.io/fifengine/api/python
17+
| Wiki | HTML | https://github.com/fifengine/fifengine/wiki
18+
| Github Pages (fifengine) | HTML | https://fifengine.github.io/fifengine = https://wwww.fifengine.net/
19+
| Github Pages (fifengine-docs) | HTML | https://fifengine.github.io/fifengine-docs/ = https://docs.fifengine.net/
20+
| Docs Repository | ASCIIDOC | https://github.com/fifengine/fifengine-docs
2021
|====================
2122

2223
:FIFEGUI-DEV-MAN-HTML-EN: https://fifengine.github.io/fifechan/docs/developer-manual/en/[EN]

‎user-manual/en/book.adoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,8 @@ include::chapter01_what-is-fifengine.adoc[]
6464

6565
include::chapter02_getting-started.adoc[]
6666

67+
include::chapter03_map-format-and-lighting.adoc[]
68+
6769
:!sectnums:
6870

6971
//include::appendix.adoc[]

‎user-manual/en/chapter03_map-format-and-lighting.adoc‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
== Working with Maps
2+
3+
This chapter explains how maps work in Fife, including the XML file format and lighting system.
4+
5+
=== Map Format
6+
7+
Fife uses a custom XML-based map format. Maps are structured hierarchically with layers, cells, and instances.
8+
9+
==== Map Structure Overview
10+
11+
A map consists of the following components:
12+
13+
[horizontal]
14+
*Map*:: The top-level container that holds all layers, cameras, and settings.
15+
*Layer*:: Contains a grid of cells with instances. Multiple layers can exist per map.
16+
*Cell*:: A single tile or position on the grid.
17+
*Instance*:: A game object placed on the map at a specific location.
18+
19+
==== XML File Structure
20+
21+
The basic map XML structure looks like this:
22+
23+
[source,xml]
24+
----
25+
<?xml version="1.0" encoding="utf-8"?>
26+
<fife version="0.4.0">
27+
<map id="mymap">
28+
<name>My Map</name>
29+
<grid type="square">
30+
<cell_scale>1.0</cell_scale>
31+
<x_scale>1.0</x_scale>
32+
<y_scale>1.0</y_scale>
33+
<rot>0</rot>
34+
<tilt>0</tilt>
35+
<x_offset>0</x_offset>
36+
<y_offset>0</y_offset>
37+
</grid>
38+
<elevation id="el1">
39+
<name>Ground Floor</name>
40+
<layer id="layer1">
41+
<name>Ground Layer</name>
42+
<grid type="square">
43+
<cell_scale>1.0</cell_scale>
44+
<x_scale>1.0</x_scale>
45+
<y_scale>1.0</y_scale>
46+
<rot>0</rot>
47+
<tilt>30</tilt>
48+
</grid>
49+
<instances>
50+
<instance object="myobject" x="0" y="0" id="inst1"/>
51+
</instances>
52+
</layer>
53+
</elevation>
54+
</map>
55+
</fife>
56+
----
57+
58+
==== Grid Types
59+
60+
Fife supports different tile and object grids with independent geometries:
61+
62+
* *Square* - Standard square tile grid
63+
* *Hexagonal* - Hexagonal grid for more natural movement
64+
65+
Grids are defined by:
66+
67+
* `cell_scale` - Size of each cell
68+
* `x_scale` / `y_scale` - Scaling factors
69+
* `rot` - Rotation angle
70+
* `tilt` - Camera tilt angle for 3D-like view
71+
72+
==== Layers
73+
74+
Each map can have multiple layers. Layers are useful for separating different types of content:
75+
76+
* Ground layer for terrain
77+
* Object layer for buildings and decorations
78+
* Agent layer for game characters
79+
* Static layer for performance (renders entire layer as one texture)
80+
81+
==== Instances
82+
83+
Instances are game objects placed on the map. Each instance references an object (archetype) that defines its properties.
84+
85+
[source,xml]
86+
----
87+
<instance object="tree" x="5" y="3" id="tree1"/>
88+
<instance object="building" x="10" y="7" id="building1" rotation="90"/>
89+
----
90+
91+
==== File Loaders
92+
93+
Fife provides multiple loaders for map files:
94+
95+
* **MapLoader** - Main loader that orchestrates map loading from XML
96+
* **ObjectLoader** - Loads object and instance data from XML
97+
* **AnimationLoader** - Loads animation definitions from XML
98+
* **AtlasLoader** - Loads image atlas definitions
99+
100+
Maps are typically saved in the same XML format using MapSaver.
101+
102+
=== Lighting System
103+
104+
Fife includes a lighting system for creating atmospheric lighting effects in your game.
105+
106+
NOTE: The lighting system is only available when using the OpenGL renderer. The SDL renderer does not support lighting effects.
107+
108+
==== Light Sources
109+
110+
Fife supports three types of light sources:
111+
112+
===== Image-Based Lights
113+
114+
Use images as light sources. This allows for complex, custom lighting effects.
115+
116+
[source,python]
117+
----
118+
lightrenderer = map.getLightRenderer()
119+
lightrenderer.addImageLightInfo(
120+
layer=my_layer,
121+
image="my_light.png",
122+
x=5, y=5
123+
)
124+
----
125+
126+
===== Animation-Based Lights
127+
128+
Use animations as light sources. Useful for flickering or animated lighting effects.
129+
130+
[source,python]
131+
----
132+
lightrenderer.addAnimationLightInfo(
133+
layer=my_layer,
134+
animation="my_light_animation",
135+
x=5, y=5
136+
)
137+
----
138+
139+
===== Simple Procedural Lights
140+
141+
Create simple lights programmatically with full control over properties.
142+
143+
[source,python]
144+
----
145+
lightrenderer.addSimpleLightInfo(
146+
layer=my_layer,
147+
x=5, y=5,
148+
color=[255, 255, 128], # Warm yellow light
149+
intensity=200,
150+
radius=5.0,
151+
subdivisions=32,
152+
xstretch=1.0,
153+
ystretch=1.0
154+
)
155+
----
156+
157+
==== Light Parameters
158+
159+
The simple light type supports these parameters:
160+
161+
[horizontal]
162+
*x, y*:: Position of the light on the map
163+
*color*:: RGB color value (0-255 per channel)
164+
*intensity*:: Brightness of the light (0-255)
165+
*radius*:: How far the light reaches
166+
*subdivisions*:: Quality of the light circle (more = smoother)
167+
*xstretch*:: Horizontal stretch factor
168+
*ystretch*:: Vertical stretch factor
169+
170+
==== Blending Modes
171+
172+
Light sources use additive blending by default. You can configure the blend modes for custom effects:
173+
174+
[source,python]
175+
----
176+
lightrenderer.setBlendMode(
177+
src_factor="src_alpha",
178+
dst_factor="one" # Additive blending
179+
)
180+
----
181+
182+
==== Fog of War
183+
184+
Fife supports fog of war effects in the OpenGL renderer. This creates areas of the map that are hidden from the player until they explore them.
185+
186+
NOTE: Fog of war is only available when using the OpenGL renderer.
187+
188+
==== Light Groups
189+
190+
You can group lights together for easier management and organization. This is useful when you have many lights in a scene and want to control them as a group.
191+
192+
[source,python]
193+
----
194+
lightrenderer.setGroupIndex(my_group_index)
195+
lightrenderer.addSimpleLightInfo(...)
196+
----
197+
198+
==== Editor Support
199+
200+
The Fife Map Editor includes a Light Editor plugin for visual creation and editing of light sources. This provides a WYSIWYG interface for placing and configuring lights on your map.

0 commit comments

Comments
 (0)