feat: init LUA

.github/workflows/main.yml

@@ -132,6 +132,17 @@ jobs:
         with:
           name: ${{ matrix.name }}
           path: deploy/
+  lua-api:
+    name: Lua API
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Upload Lua API artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: Lua API
+          path: res/lua/
   windows:
     strategy:
       fail-fast: false

CMakeLists.txt

@@ -232,6 +232,41 @@ set(ZIP_FILES
     ${PROJECT_SOURCE_DIR}/ext/zip/zip.c
 )
 
+set(LUA_FILES
+    ${PROJECT_SOURCE_DIR}/ext/lua/lapi.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/lauxlib.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/lbaselib.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/lcode.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/lcorolib.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/lctype.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/ldblib.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/ldebug.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/ldo.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/ldump.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/lfunc.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/lgc.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/linit.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/liolib.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/llex.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/lmathlib.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/lmem.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/loadlib.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/lobject.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/lopcodes.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/loslib.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/lparser.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/lstate.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/lstring.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/lstrlib.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/ltable.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/ltablib.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/ltm.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/lundump.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/lutf8lib.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/lvm.c
+    ${PROJECT_SOURCE_DIR}/ext/lua/lzio.c
+)
+
 set(PLATFORM_FILES
     ${PROJECT_SOURCE_DIR}/src/platform/arguments.c
     ${PROJECT_SOURCE_DIR}/src/platform/augustus.c
@@ -306,6 +341,7 @@ set(CORE_FILES
     ${PROJECT_SOURCE_DIR}/src/core/smacker.c
     ${PROJECT_SOURCE_DIR}/src/core/speed.c
     ${PROJECT_SOURCE_DIR}/src/core/string.c
+    ${PROJECT_SOURCE_DIR}/src/core/terminal.c
     ${PROJECT_SOURCE_DIR}/src/core/time.c
     ${PROJECT_SOURCE_DIR}/src/core/xml_parser.c
     ${PROJECT_SOURCE_DIR}/src/core/xml_exporter.c
@@ -557,6 +593,19 @@ set(SCENARIO_FILES
     ${PROJECT_SOURCE_DIR}/src/scenario/event/condition_comparison_helper.c
     ${PROJECT_SOURCE_DIR}/src/scenario/event/condition_handler.c
     ${PROJECT_SOURCE_DIR}/src/scenario/event/condition_types.c
+    ${PROJECT_SOURCE_DIR}/src/scenario/lua/lua_state.c
+    ${PROJECT_SOURCE_DIR}/src/scenario/lua/lua_hooks.c
+    ${PROJECT_SOURCE_DIR}/src/scenario/lua/lua_api_game.c
+    ${PROJECT_SOURCE_DIR}/src/scenario/lua/lua_api_city.c
+    ${PROJECT_SOURCE_DIR}/src/scenario/lua/lua_api_finance.c
+    ${PROJECT_SOURCE_DIR}/src/scenario/lua/lua_api_scenario.c
+    ${PROJECT_SOURCE_DIR}/src/scenario/lua/lua_api_map.c
+    ${PROJECT_SOURCE_DIR}/src/scenario/lua/lua_api_ui.c
+    ${PROJECT_SOURCE_DIR}/src/scenario/lua/lua_api_building.c
+    ${PROJECT_SOURCE_DIR}/src/scenario/lua/lua_api_resource.c
+    ${PROJECT_SOURCE_DIR}/src/scenario/lua/lua_api_population.c
+    ${PROJECT_SOURCE_DIR}/src/scenario/lua/lua_api_sound.c
+    ${PROJECT_SOURCE_DIR}/src/scenario/lua/lua_api_empire.c
 )
 set(GRAPHICS_FILES
     ${PROJECT_SOURCE_DIR}/src/graphics/arrow_button.c
@@ -710,6 +759,7 @@ set(WINDOW_FILES
     ${PROJECT_SOURCE_DIR}/src/window/numeric_input.c
     ${PROJECT_SOURCE_DIR}/src/window/option_popup.c
     ${PROJECT_SOURCE_DIR}/src/window/overlay_menu.c
+    ${PROJECT_SOURCE_DIR}/src/window/lua_input_dialog.c
     ${PROJECT_SOURCE_DIR}/src/window/plain_message_dialog.c
     ${PROJECT_SOURCE_DIR}/src/window/popup_dialog.c
     ${PROJECT_SOURCE_DIR}/src/window/race_bet.c
@@ -813,6 +863,7 @@ set(SOURCE_FILES
     ${SPNG_FILES}
     ${SXML_FILES}
     ${ZIP_FILES}
+    ${LUA_FILES}
     ${PROJECT_SOURCE_DIR}/res/augustus.rc
     ${MACOSX_FILES}
     ${IOS_FILES}
@@ -888,6 +939,13 @@ if(MSVC)
     set_source_files_properties(${SOURCE_FILES} PROPERTIES COMPILE_FLAGS "/W4")
     set_source_files_properties(${PROJECT_SOURCE_DIR}/res/augustus.rc PROPERTIES COMPILE_FLAGS "")
     set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} /utf-8 /wd4100 /wd4244 /we4013")
+    set_source_files_properties(${LUA_FILES} PROPERTIES COMPILE_FLAGS "/W0")
+else()
+    if(${TARGET_PLATFORM} STREQUAL "ios")
+        set_source_files_properties(${LUA_FILES} PROPERTIES COMPILE_FLAGS "-w -DLUA_USE_IOS")
+    else()
+        set_source_files_properties(${LUA_FILES} PROPERTIES COMPILE_FLAGS "-w")
+    endif()
 endif()
 
 # Show debug info on crash on 32 bit builds compiled with MinGW

README.md

@@ -74,6 +74,83 @@ Augustus changes are explained in detail in the comprehensive manual. Below you
 |Polish   |[Download](https://github.com/Keriew/augustus/raw/master/res/translated_manuals/augustus_manual_polish_3.0.pdf)|
 |Russian   |[Download](https://github.com/Keriew/augustus/raw/master/res/translated_manuals/augustus_manual_russian_3.0.pdf)|
 
+## Lua Scripting
+
+Augustus supports **Lua scripting** for maps and scenarios, allowing you to add custom logic, dynamic events, and interactive dialogs to your scenarios.
+
+### Getting started
+
+1. Create a `.lua` file with the same name as your scenario (e.g. `valentia.lua` for `valentia.map`).
+2. Place the script file next to the scenario file or in the game data directory.
+3. The script is automatically loaded when the scenario starts.
+
+### Lifecycle hooks
+
+Define any of these functions in your script to react to game events:
+
+| Hook | Called when |
+|------|------------|
+| `on_load()` | Scenario starts (after script is loaded) |
+| `on_tick()` | Every game day |
+| `on_month()` | Start of each month |
+| `on_year()` | Start of each year |
+| `on_event(event_name)` | A scenario event fires |
+| `on_building_placed(type, x, y, id)` | Player places a building |
+| `on_building_destroyed(type, x, y, id)` | A building is destroyed |
+| `on_victory()` | Player wins |
+| `on_defeat()` | Player loses |
+| `on_invasion_start(type, size)` | An invasion starts |
+| `on_trade_completed(route_id, resource, amount)` | A trade is completed |
+
+### Available APIs
+
+The following API modules are available in your scripts:
+
+| Module | Description |
+|--------|-------------|
+| `scenario.*` | Scenario properties, variables, and events |
+| `game.*` | Game time and flow control |
+| `city.*` | City status and ratings |
+| `building.*` | Building queries and counts |
+| `map.*` | Map tiles and terrain |
+| `resource.*` | Resource and trade goods |
+| `finance.*` | Treasury and tax control |
+| `population.*` | Population statistics |
+| `empire.*` | Empire cities and trade routes |
+| `ui.*` | Dialogs, messages, and log output |
+| `sound.*` | Sound effects and music |
+
+### Example script
+
+```lua
+function on_load()
+    ui.log("Scenario loaded!")
+    ui.input_dialog({
+        title = "The Senate's Offer",
+        text = "Accept a gift or gain favor with the gods?",
+        buttons = {
+            { label = "Accept Gold",  on_click = function() finance.add_treasury(1000) end },
+            { label = "Pray to Gods", on_click = function() city.change_favor(10) end },
+            { label = "Decline" },
+        }
+    })
+end
+
+function on_year()
+    local pop = city.population()
+    if pop >= 500 then
+        ui.show_custom_message({
+            title = "Growing City",
+            text = "Your city has reached " .. pop .. " citizens!",
+        })
+    end
+end
+```
+
+### IDE autocomplete
+
+Download the **Lua API** artifact from the latest [GitHub Actions build](https://github.com/Keriew/augustus/actions) and extract the API definition files into your workspace to get full autocomplete and type hints in editors that support Lua Language Server (e.g. VS Code with the [Lua extension](https://marketplace.visualstudio.com/items?itemName=sumneko.lua)).
+
 ## Bugs
 
 See the list of [Bugs & idiosyncrasies](https://github.com/bvschaik/julius/wiki/Caesar-3-bugs) to find out more about some known bugs.

config.ld

@@ -0,0 +1,6 @@
+-- config.ld
+project = 'Augustus'
+title = 'Augustus LUA API'
+description = 'API'
+file = 'res/lua' -- Source directory
+dir = 'doc' -- Output directory