@Prof. Garfield , I think this is a great idea. It was actually something I was thinking about proposing as well, but you beat me to it!
My thoughts are that we eventually bundle the functions into a small number of .lua files and distribute those, possibly with TOTPP itself. Then, scenario makers use "require" at the top of their events.lua to access these functions. If bugs are found, then the library file has to be replaced, rather than requiring every scenario maker to update the code in their scenario.
What I want is to specify what these library functions should do, and let individual scenario makers rely on that specification. If someone finds that the library code doesn't work as specified, we fix the library code rather than working around it in each scenario. That should mean we can update the library without breaking scenarios.
What do you think of the idea of a separate "helper" library for each of the major game objects that TOTPP has made available in Lua: city, improvement, tech, tile, tribe, etc.? In my efforts writing events for various ongoing projects (my own, plus those of other members with whom I'm currently collaborating), I've found things like this valuable on multiple occasions. It just slims down the code in my main events.lua file (and the main triggers there) so it's more readable, and focused on the steps that are truly unique to that situation, rather than reinventing the wheel with generic behaviors.
On the one hand, I like the idea of separate libraries because it provides better organization of all the helper functions and the areas of the game they address. A developer with a particular need (for example, taking money away from a tribe while making sure their treasury doesn't fall below zero) can quickly pull up the "util_tribe.lua" file and see if there is a function related to changing money. If all of the functions are in a single huge library, with widely varying degrees of complexity and specificity, that could be a lot more daunting.
On the other hand, more files means more version numbers to manage, and more files to keep up-to-date. I don't think that would be too difficult, but it's hard to anticipate. Maybe my conclusion is that I think there's going to be some level of "administrative overhead" with either approach.
Since specific needs will vary, my suggestion is that we build general capabilities, and let users build "wrapper functions" around them.
...
An alternative method is to build fairly basic functionality, and let people modify the code if they need something more complicated. This would mean that people don't write and test super general code that never gets used, but means more bugs when people do need extra functionality.
I think I would advocate for both approaches, actually! The first being true libraries that are always intended to live
outside events.lua and be included via a "require" command, as described/discussed above. These should always contain general code that isn't specific to any one scenario. Most likely, these will contain functions that are pretty simple in nature -- focused on the most common operations and "pain points", or trapping for error conditions that can easily be overlooked.
Then separately, I'd propose a suite of "example" events files that aren't intended to be
referenced by events.lua, but rather used as starting points for scenario developers to enhance and tailor for their own needs. This would let someone say, for example, "I want my scenario to include units that are directly linked to city improvements, so that building the improvement creates a unit, and killing the unit removes the improvement." But whereas one developer may want this to work with mobile land units on a single map, and tie special popup text to the death of a unit, another developer may want this to work with immobile air units across three maps and involve terrain changes on specific tiles! Instead of having a library that anticipates or tries to accommodate all of the implementations, I'd like to see example files that give me a basic working version, which I can copy and then freely edit or enhance. Hopefully when someone is going to start building their events.lua file, they would be able to take three or five of these basic example files, out of a library of a dozen or more, and merge them into their own events file to give them a great foundation, so they're not starting at ground zero.
Topic of discussion: Should we "standardize" keys to trigger events? For example, creating ammo for a unit seems like it might be a fairly common event. Should we "recommend" that all scenarios use the same key for this kind of functionality? If so, what key?
Personally, I'm concerned that attempting to "standardize" or "recommend" an approach, even with the best of intentions, could start to come across as heavy-handed. I think it's especially important that whatever we put together
encourages creativity and experimentation, rather than stifling it or emphasizing conformity. That being said, if the library contains an example file for ranged units that uses "k" as the key to fire, many developers will just copy that and a de facto standard may arise. But if a developer has a reason why they
don't want to use "k", it certainly seems like they should be able to make that decision.
For example, in my own project, I have a goal of building ranged units that the AI can fire! Clearly this would not rely on a key press at all, but much of the other code related to ranged units may still be applicable. The idea of being able to copy a basic implementation, and then customize it, seems ideal to me.
Thanks again for this idea and thread, I think this is a very useful topic to pursue.
