Merge branch 'master' into sidequest/single-soldier-coin-training

Author: Flamefire

.gitignore

@@ -1,4 +1,4 @@
-# Copyright (C) 2005 - 2021 Settlers Freaks <sf-team at siedler25.org>
+# Copyright (C) 2005 - 2026 Settlers Freaks <sf-team at siedler25.org>
 #
 # SPDX-License-Identifier: CC0-1.0
 
@@ -11,9 +11,12 @@
 *.user
 *~
 .DS_Store
+.opencode
 .vscode
 .vs
 .cache
+.opencode
+opencode.json
 /S2
 /build
 /external/boost*

CMakeLists.txt

@@ -1,8 +1,8 @@
-# Copyright (C) 2005 - 2025 Settlers Freaks <sf-team at siedler25.org>
+# Copyright (C) 2005 - 2026 Settlers Freaks <sf-team at siedler25.org>
 #
 # SPDX-License-Identifier: GPL-2.0-or-later
 
-cmake_minimum_required(VERSION 3.16..3.31)
+cmake_minimum_required(VERSION 3.16...3.31)
 
 if(NOT RTTR_VERSION)
     string(TIMESTAMP RTTR_VERSION "%Y%m%d")

cpp.hint

@@ -1,4 +1,4 @@
-// Copyright (C) 2005 - 2021 Settlers Freaks <sf-team at siedler25.org>
+// Copyright (C) 2005 - 2026 Settlers Freaks <sf-team at siedler25.org>
 //
 // SPDX-License-Identifier: BSL-1.0
 
@@ -15,5 +15,4 @@
 #define BOOST_REQUIRE_GT(x,y) BOOST_REQUIRE((x) > (y))
 
 #define RTTR_FOREACH_PT(PtType, size) for(PtType pt;;)
-#define SUPPRESS_UNUSED
 #define RTTR_Assert(cond) assert(cond)

doc/AddingCustomCampaign.md

@@ -6,7 +6,7 @@ SPDX-License-Identifier: GPL-2.0-or-later
 
 # Add a custom campaign
 
-You can have a look into the already existing original Settlers 2 campaigns in the subfolders `RTTR/campaigns/roman` and `RTTR/campaigns/continent` for an example.
+You can take a look into the already existing original Settlers 2 campaigns in the subfolders `RTTR/campaigns/roman` and `RTTR/campaigns/continent` for an example.
 We will now create an example campaign `garden`.
 
 ## Location for adding a new campaign
@@ -41,18 +41,20 @@ campaign = {
     name = _"name",
     shortDescription = _"shortDescription",
     longDescription = _"longDescription",
-    image = "<RTTR_RTTR>/campaigns/garden/garden.bmp",
+    image = "<RTTR_RTTR>/campaigns/garden/garden.bmp", -- Same as: image = "garden.bmp",
     maxHumanPlayers= 1,
     difficulty = "easy",
-    mapFolder = "<RTTR_RTTR>/campaigns/garden",
-    luaFolder = "<RTTR_RTTR>/campaigns/garden",
+    mapFolder = "<RTTR_RTTR>/campaigns/garden", -- optional
+    luaFolder = "<RTTR_RTTR>/campaigns/garden", -- optional
     maps = { "MISS01.WLD","MISS02.WLD"},
     selectionMap = {
-        background = {"<RTTR_GAME>/campaigns/garden/mapscreen/background.bmp", 0},
-        map = {"<RTTR_GAME>/campaigns/garden/mapscreen/map.bmp", 0},
-        missionMapMask = {"<RTTR_GAME>/campaigns/garden/mapscreen/map_mask.bmp", 0},
-        marker = {"<RTTR_GAME>/campaigns/garden/mapscreen/marker.bmp", 0},
-        conquered = {"<RTTR_GAME>/campaigns/garden/mapscreen/conquered.bmp", 0},
+        background = {"<RTTR_RTTR>/campaigns/garden/mapscreen/background.bmp", 0},
+        map = {"<RTTR_RTTR>/campaigns/garden/mapscreen/map.bmp", 0},
+        missionMapMask = {"<RTTR_RTTR>/campaigns/garden/mapscreen/map_mask.bmp", 0},
+        marker = {"<RTTR_RTTR>/campaigns/garden/mapscreen/marker.bmp", 0},
+        conquered = {"<RTTR_RTTR>/campaigns/garden/mapscreen/conquered.bmp", 0},
+        -- Each '<RTTR_RTTR>/campaigns/garden/' is optional: Paths are treated as relative to campaign file.
+        -- E.g.: conquered = {"mapscreen/conquered.bmp", 0},
         backgroundOffset = {0, 0},
         disabledColor = 0x70000000,
         missionSelectionInfos = {
@@ -75,7 +77,7 @@ The Lua campaign interface is versioned using a major version. Every time a feat
 
 Every map script must have 1 function:
 `getRequiredLuaVersion()`
-You need to implement this and return the version your script works with. If it does not match the current version an error will be shown and the script will not be used.
+You need to implement this and return the version your script works with. If it is higher than the current version an error will be shown and the script will not be used.
 
 ### Explanation of the campaign table fields
 
@@ -86,7 +88,7 @@ If you want a field to be translated you have to add the translation as describe
   3. `name`: The name of the campaign
   4. `shortDescription`: Short description of the campaign (like a headline to get a rough imagination of the campaign)
   5. `longDescription`: Extended description describing the campaign in detail. Will be shown in the campaign selection screen, when the campaign is selected.
-  6. `image`: Path to an image displayed in the campaign selection screen. You can omit this if you do no want to provide an image.
+  6. `image`: Path to an image displayed in the campaign selection screen. Can be any "archive" with an image, e.g. `.bmp`, `.lbm`. You can omit this if you do no want to provide an image.
   7. `maxHumanPlayers`: For now this is always 1 until we support multiplayer campaigns
   8. `difficulty`: Difficulty of the campaign. Should be one of the values easy, medium or hard.
   9. `mapFolder` and `luaFolder`: Path to the folder containing the campaign maps and associated Lua files. Usually your campaign folder or a subfolder of it.
@@ -95,7 +97,7 @@ If you want a field to be translated you have to add the translation as describe
 
 Hints:
 
-- To work on case-sensitive OS (like Linux) the file name of the Lua file must have the same case as the map file name. This applies to the map names in the campaign.lua file too.
+- To work on case-sensitive OS (like Linux) the file name of the Lua file must have the same case as the map file name. This applies to the map names in the `campaign.lua` file too.
 For example: `MISS01.WLD, MISS01.lua` is correct and `MISS01.WLD, miss01.lua` will not work on Linux
 - The Lua file of a map must have the same name as the map itself but with the extension `.lua` to be found.
 - The Lua and the map file don't need to be in the same folder because the path can be specified separately.
@@ -107,7 +109,7 @@ For example: `MISS01.WLD, MISS01.lua` is correct and `MISS01.WLD, miss01.lua` wi
 
 ### Optional map selection screen {#selection-map}
 
-This parameter is optional and can be omitted in the Lua campaign file. If this parameter is specified the selection screen for the missions of a campaign is replaced by a selection map. Like the one used in the original settlers 2 world campaign.
+This parameter is optional and can be omitted in the Lua campaign file. If this parameter is specified the selection screen for the missions of a campaign is replaced by a selection map. Like the one used in the original Settlers 2 world campaign.
 
 We have the following parameters:
 
@@ -124,6 +126,11 @@ Hint:
 All the images are described by the path to the image file and an index parameter. Usually the index parameter is zero.
 For special image formats containing multiple images in an archive this is the index of the image to use.
 
+### Image paths
+
+The paths to the campaign image and selection map images can be relative to the campaign folder and at most inside a single subfolder.  
+E.g. `images/garden.bmp` and `mapscreen/conquered.bmp` work, but `images/mapscreen/conquered.bmp` does not.
+
 ## Final view of the example garden campaign folder
 
 ```sh
@@ -140,3 +147,6 @@ RTTR/campaigns/garden/mapscreen/map_mask.bmp
 RTTR/campaigns/garden/mapscreen/marker.bmp
 RTTR/campaigns/garden/mapscreen/conquered.bmp
 ```
+
+Note that for custom campaigns, placed in `<RTTR_USERDATA>/campaigns/` the top-level `RTTR` folder won't exist.
+Hence, `<RTTR_RTTR>/campaigns/` should not be used in the campaign description file to refer to campaign files.

doc/lua/functions.md

@@ -1,5 +1,5 @@
 <!--
-Copyright (C) 2005 - 2021 Settlers Freaks <sf-team at siedler25.org>
+Copyright (C) 2005 - 2026 Settlers Freaks <sf-team at siedler25.org>
 
 SPDX-License-Identifier: GPL-2.0-or-later
 -->
@@ -24,7 +24,8 @@ Reference: [libs/libGamedata/lua/LuaInterfaceBase.cpp](../../libs/libGamedata/lu
 **rttr:GetFeatureLevel()**  
 Get the current feature level of the LUA interface.
 Increases here indicate new features.
-The current version is **6**.
+The current version is **7**.  
+See [list of changes](main.md#versioning).
 
 **rttr:Log(message)**  
 Log the message to console.

doc/lua/main.md

@@ -1,5 +1,5 @@
 <!--
-Copyright (C) 2005 - 2021 Settlers Freaks <sf-team at siedler25.org>
+Copyright (C) 2005 - 2026 Settlers Freaks <sf-team at siedler25.org>
 
 SPDX-License-Identifier: GPL-2.0-or-later
 -->
@@ -47,6 +47,10 @@ You need to implement this and return the major/main version your script works w
 If it does not match the current version an error will be shown and the script will not be used.
 See also `rttr:GetFeatureLevel()`.
 
+### Feature level 7
+
+- Allow relative paths for images referenced by campaign files.
+
 ## Example
 
 ```lua

external/CMakeLists.txt

@@ -17,8 +17,8 @@ if(EXISTS ${CMAKE_CURRENT_LIST_DIR}/dev-tools/CMakeLists.txt AND NOT DEFINED RTT
     if(APPLE) # Lua 5.2 required which is not easily available on OSX
       set(includeDevToolsDefault ON)
     else()
-      message(STATUS "Precompiled binaries are available to use for development."
-                     "They are not compatible with all platforms though."
+      message(STATUS "Precompiled binaries are available to use for development. "
+                     "They are not compatible with all platforms though.\n"
                      "Configure with -DRTTR_INCLUDE_DEVTOOLS=ON to make them available to CMake."
               )
     endif()