extend user-manual

Author: jakoch

README.adoc

@@ -15,7 +15,7 @@ image:https://github.com/fifengine/fifengine-docs/actions/workflows/build-docs.y
 | C++ API Documentation         | HTML     | https://fifengine.github.io/fifengine/api/
 | Python API Documentation      | HTML     | https://fifengine.github.io/fifengine/api/python
 | Wiki                          | HTML     | https://github.com/fifengine/fifengine/wiki
-| Github Pages (fifengine)      | HTML     | https://fifengine.github.io/fifengine = https://wwww.fifengine.net/
+| Github Pages (fifengine)      | HTML     | https://fifengine.github.io/fifengine = https://fifengine.net/
 | Github Pages (fifengine-docs) | HTML     | https://fifengine.github.io/fifengine-docs/ = https://docs.fifengine.net/
 | Docs Repository               | ASCIIDOC | https://github.com/fifengine/fifengine-docs
 |====================

user-manual/en/chapter03_core-concepts.adoc

@@ -166,6 +166,182 @@ dt = time_manager.getTimeDelta()  # Time since last frame in seconds
 
 Use `dt` to scale movement and animation speeds for consistent behavior regardless of frame rate.
 
+=== Engine Change Listener
+
+Monitor engine-level changes such as screen mode switches:
+
+[source,python]
+----
+class MyEngineChangeListener(fife.IEngineChangeListener):
+    def onScreenModeChanged(self, newmode):
+        print("Screen mode changed")
+
+listener = MyEngineChangeListener()
+engine.addChangeListener(listener)
+
+# Later, remove it
+engine.removeChangeListener(listener)
+----
+
+=== Changing Screen Mode at Runtime
+
+Change the display mode without re-initializing the engine:
+
+[source,python]
+----
+# Get available screen modes from device capabilities
+device_caps = engine.getDeviceCaps()
+modes = device_caps.getNearestScreenMode(width, height, bpp, fullscreen)
+
+# Apply the new mode
+engine.changeScreenMode(modes)
+----
+
+The `changeScreenMode()` method handles re-creation of internal objects that depend on the display.
+
+=== Device Capabilities
+
+Query supported display configurations:
+
+[source,python]
+----
+device_caps = engine.getDeviceCaps()
+
+# Get available screen modes
+modes = device_caps.getAvailableScreenModes()
+
+# Get available render drivers
+drivers = device_caps.getAvailableRenderDrivers()
+----
+
+=== Additional Engine Accessors
+
+The Engine provides access to additional subsystems:
+
+[source,python]
+----
+# Logging subsystem
+log_manager = engine.getLogManager()
+
+# Special renderers (owned by engine, do not delete)
+off_renderer = engine.getOffRenderer()
+target_renderer = engine.getTargetRenderer()
+
+# Cursor control
+cursor = engine.getCursor()
+----
+
+=== Engine Settings Reference
+
+==== Display Index
+
+For multi-monitor setups, select which display to use:
+
+[source,python]
+----
+settings.setDisplay(0)  # Primary display (default)
+settings.setDisplay(1)  # Secondary display
+----
+
+==== SDL Render Driver
+
+Select a specific SDL render driver:
+
+[source,python]
+----
+settings.setSDLDriver("software")  # Platform-dependent values
+----
+
+==== Video Driver
+
+Set the video driver (platform-dependent):
+
+[source,python]
+----
+settings.setVideoDriver("x11")  # Linux X11
+----
+
+==== Color Key Transparency
+
+Enable global colorkey-based transparency:
+
+[source,python]
+----
+settings.setColorKeyEnabled(True)
+settings.setColorKey(255, 0, 255)  # Magenta as transparent color
+----
+
+==== Monochrome Rendering
+
+Render in grayscale (OpenGL only):
+
+[source,python]
+----
+settings.setGLUseMonochrome(True)
+----
+
+==== Alpha Test Value
+
+Set the alpha threshold for depth buffer discarding (OpenGL only):
+
+[source,python]
+----
+settings.setGLUseDepthBuffer(True)
+settings.setGLAlphaTestValue(0.1)  # Discard fragments with alpha < 0.1
+----
+
+==== SDL Fake Alpha Removal
+
+Remove fake alpha in SDL backend:
+
+[source,python]
+----
+settings.setSDLRemoveFakeAlpha(True)
+----
+
+==== Joystick Support
+
+Enable or disable joystick and gamepad input:
+
+[source,python]
+----
+settings.setJoystickSupport(True)  # Enable gamepad support
+----
+
+==== Frame Limit
+
+Limit the frame rate at the settings level. Also documented in xref:chapter06[Rendering].
+
+[source,python]
+----
+settings.setFrameLimitEnabled(True)
+settings.setFrameLimit(60)  # 60 FPS max
+if settings.isFrameLimitEnabled():
+    print("Frame limit:", settings.getFrameLimit())
+----
+
+==== Mouse Sensitivity
+
+Configure mouse input sensitivity and acceleration via settings
+(also configurable at runtime through xref:chapter08[EventManager]):
+
+[source,python]
+----
+settings.setMouseSensitivity(1.5)       # Speed factor (1.0 = default)
+settings.setMouseAccelerationEnabled(True)  # Enable mouse acceleration
+----
+
+==== Native Image Cursor
+
+Use a native OS cursor backed by an image file:
+
+[source,python]
+----
+settings.setNativeImageCursorEnabled(True)
+if settings.isNativeImageCursorEnabled():
+    print("Using native cursor")
+----
+
 === Log Modules
 
 FIFE uses a hierarchical logging system. Each subsystem is a log module:

user-manual/en/chapter04_coordinate-systems.adoc

@@ -115,6 +115,29 @@ map_coords = location.getMapCoordinates()
 print(f"Map: ({map_coords.x}, {map_coords.y}, {map_coords.z})")
 ----
 
+==== Coordinate Mapping Between Layers
+
+Convert coordinates to a different layer:
+
+[source,python]
+----
+# Get exact coordinates mapped to a specific layer
+other_exact = location.getExactLayerCoordinates(target_layer)
+
+# Get cell coordinates mapped to a specific layer
+other_cell = location.getLayerCoordinates(target_layer)
+----
+
+==== Cell Offset Distance
+
+Get the offset from the nearest cell center:
+
+[source,python]
+----
+offset = location.getCellOffsetDistance()
+# Returns distance between exact position and cell center
+----
+
 ==== Checking Location Validity
 
 A location is valid if:
@@ -281,3 +304,100 @@ camera.setZToY(32)          # 1 z-unit = 32 y-pixels
 ----
 
 Understanding these coordinate systems is key to working with FIFE's rendering and input systems effectively.
+
+=== Point Utilities
+
+The `Point` and `Point3D` classes provide vector math utilities.
+
+==== Point2D Operations
+
+[source,python]
+----
+p = fife.Point(3, 4)
+
+# Vector operations
+p2 = p + fife.Point(1, 2)   # (4, 6)
+p3 = p - fife.Point(1, 1)   # (2, 3)
+p4 = p * 2                   # (6, 8)
+p5 = p / 2                   # (1, 2)
+
+# Length (magnitude)
+length = p.length()  # 5.0
+
+# Normalize to unit vector
+p.normalize()
+
+# Rotate around origin (degrees)
+p.rotate(90)
+
+# Rotate around a specific point
+origin = fife.Point(0, 0)
+p.rotate(origin, 45)
+
+# Set coordinates
+p.set(10, 20)
+----
+
+==== Point3D Operations
+
+[source,python]
+----
+p = fife.Point3D(1, 2, 3)
+
+# Same operations as Point2D, plus z-component
+length = p.length()
+p.normalize()
+p.set(10, 20, 30)
+----
+
+==== Type Conversions
+
+Convert between integer and double point types:
+
+[source,python]
+----
+# Double to int (rounds)
+int_point = fife.doublePt2intPt(double_point)
+
+# Int to double
+double_point = fife.intPt2doublePt(int_point)
+----
+
+==== Typedefs
+
+[horizontal]
+*Point*:: `PointType2D<int32_t>` - 2D integer point
+*DoublePoint*:: `PointType2D<double>` - 2D double point
+*Point3D*:: `PointType3D<int32_t>` - 3D integer point
+*DoublePoint3D*:: `PointType3D<double>` - 3D double point
+
+=== Rect Utilities
+
+The `Rect` class provides rectangle operations for screen areas:
+
+[source,python]
+----
+rect = fife.Rect(x, y, width, height)
+
+# Edge coordinates
+right = rect.right()    # x + width
+bottom = rect.bottom()  # y + height
+
+# Point containment
+if rect.contains(fife.Point(px, py)):
+    print("Point is inside rect")
+
+# Rectangle intersection
+if rect.intersects(other_rect):
+    print("Rectangles overlap")
+
+# In-place intersection (modifies rect)
+rect.intersectInplace(other_rect)
+----
+
+==== Typed Rectangles
+
+[horizontal]
+*Rect*:: `RectType<int32_t>` - Integer rectangle
+*FloatRect*:: `RectType<float>` - Float rectangle
+*DoubleRect*:: `RectType<double>` - Double rectangle