Skip to content

Unify Lua modding under GameMode#906

Draft
esbudylin wants to merge 1 commit intoDevelopmentfrom
yegor/unify-mod-loading
Draft

Unify Lua modding under GameMode#906
esbudylin wants to merge 1 commit intoDevelopmentfrom
yegor/unify-mod-loading

Conversation

@esbudylin
Copy link
Contributor

This PR continues the work on modding support for OpenCiv3. Huge thanks to @ajhalme (#891 (comment)) and @stavrosfa (https://discord.com/channels/909680526498082837/1457726459895484598) for the feedback on the current system! I tried to incorporate your ideas into this PR.

The main theme of this PR is to unite three separate scripting mechanisms of OpenCiv3 under one system.

Currently, Lua scripts are part of the logic for

  • defining textures,
  • defining custom behaviors,
  • defining rulesets.

This PR introduces a new class, GameMode, that serves as an entry point for all these Lua-based modding mechanisms. Similarly to rulesets in my previous PR (#848), the definition of each game mode consists of a base and addons. Each component (base or addon) is represented by a directory.

A base directory should hold the following files (for each scripting subsystem). Each of these Lua files must return a table.

  • ruleset.lua (or ruleset.json)
  • behaviors.lua
  • textures.lua

An addon directory may hold any of these Lua scripts. Unlike the base files, these scripts must return functions.

After the base table is loaded, it will be passed through a pipeline of Lua functions loaded from addons: each addon function will accept the current accumulated table, modify it, and return the result. Again, this is very similar to ruleset loading introduced in #848. However, now this mechanism is applied to behavior and texture definitions as well.

As a side effect, the Lua directory is reorganized: now files are grouped by the mod component they belong to. Since we have two components (civ3 as a base and standalone as an addon), the Lua directory looks like this (auxiliary scripts omitted).

civ3
--behaviors.lua
--ruleset.json
--textures.lua
standalone
--ruleset.lua
--textures.lua

Overall, this PR should give us a base for a system of composable mods. For now, the two game modes (civ3 and standalone) are still hardcoded, but in the future we may want to come up with a UI that will allow users to mix-and-match the mods at the start of the game (similarly to Unciv, for example).

For now, I'm opening this PR as a draft, since I want to do some additional work on commenting the code changes. However, I'd like to know your thoughts on my approach. As always, feedback is very welcome!

@esbudylin esbudylin added Lua anything relating to Lua modding related to scenario data or mod api labels Mar 4, 2026
@ajhalme
Copy link
Contributor

ajhalme commented Mar 4, 2026

Great stuff, the proposed Lua structure is exactly what I had in mind.

I don't know much Lua, but if the dynamic loading/composition works as advertised, then this should be a big win for mod efforts.

I'd be tempted to rebrand "standalone" to "openciv3".

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Lua anything relating to Lua modding related to scenario data or mod api

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants