GameEvents - new event suggestions

[SamBC]

I've been working on documenting the existing GameEvents system (products of this so far are on the wiki). The good FXSSSeckman has indicated that they hope to add lots more GameEvents, as the current crop were added specifically for the DLC scenarios; some aren't used in them, and thus possibly not well tested, but they were all added for that purpose. While they will, in that case, work through the game code looking for places that events should be added, it seems it would be useful to make suggestions. We might even hope that suggestions could be added before they work through systematically adding some.

On the other hand, we can assume that they won't want to add them in every conceivable place, as that will slow the game down in execution terms. As such, we should try to make sure our suggestions are good and genuinely useful, and try to avoid redundancy (not add events where an existing one can actually be used), so hopefully we can discuss suggestions, and I'll consolidate them here. In this post I will add those that there seems to be consensus on (although that consensus might be from elsewhere), and in the next post I'll keep a list of ideas for discussion, starting with my own top-of-my-head suggestions.

I'll try to cull suggestions from elsewhere, and if other people want to help by pointing me at them that'd would be a great help (as I'm not going to spend hours each day on this). Hopefully, we can suggest the following for each suggestion that's 'finalised': when it will fire, which of the categories described on the wiki it will be (hook, predicate - TestAll or TestAny, or accumulator - int or float), if it's a hook what behaviour will be up for replacement, and what parameters we would want it to take.

Consensus Suggestions:

None Yet

[SamBC]

Please make suggestions by posting them here or posting a link to them elsewhere. Every suggestion that hasn't been roundly dismissed will be copied here, and anything that there seems to be consensus over will be moved, with details, to the first post.

1. Events for buildings being constructed or destroyed (taking player and city id, and building id)
2. Events for buildings gained or lost by other means (for those gained and lost in city conquest)
3. A matching event for CityCaptureComplete, for CityCaptureBegins, that would occur while the owner is still the original owner. If this were before buildings get removed (could be a hook potentially replacing that behaviour) the two could between them be used for the purpose of 'buildings gained or lost by other means', provided some other cases get covered elsewhere, or count as destroyed (such as cities being Razed
4. A matching event for PlayerDoTurn of PlayerEndTurn (I hope the meaning is obvious)
5. Per-turn looping events over players' cities and units, and possibly over plots in general
6. Events that fire on start and end of combat, even if quick combat or strategic view are in use (game-rules equivalents of the CombatSim events)
7. Matching counterpart of CandDeclare war - CanMakePeace (Presumably filters UI actions that request peace, when major civs are concerned)
8. A range of (presumably hook) events for the map creation and starting plot assignment stage. Of course, these could be LuaEvents rather than GameEvents, what with the fact those things happen in Lua (at least a lot of them). Particularly would be nice to randomize the assignment of particular plots to particular civs, for example.
9. Unit promotion (level change)
10. Unit Upgrade - subsumed/split into new items regarding upgrade
11. UnitUpgrading (taking player ID, unit ID of pre-upgrade and unit ID of post-upgrade - could happen at a whole range of possible points in the upgrade process, but we'd want to know which; one purpose of this is to allow handling of mod-added behaviour/data being transferred from unit to unit, thanks to how the upgrade process works; might be useful to have location as well)
12. UpgradeUnit (taking player ID, unit ID pre-upgrade, unitType ID to upgrade to (possibly, as it can be derived) - should be a hook event allowing complete replacement of the whole upgrade mechanic)
13. UnitCanUpgrade (taking player ID, unit ID, could offer location as well - obviously this would be a test)
14. ImprovementCreated (taking the location at least, passing info on what the improvement is would also be helpful just to save retrieving the info - to only fire when the improvement is really there, unlike the Events.SerialEvent* version, in case that
    s not obvious)
15. ImprovementDestroyed (to give location and what the improvement was, seeing as we can't tell anymore at that point)
16. UnitBeingCaptured (giving the unit location, capturing playerid and playerid/unitid? - has to be beforehand, so the playerid/unitid combo is valid)
17. UnitCaptured (giving the unit location, original playerid, and playerid/unitid - sometimes this will be wanted - is one more useful than the other - is either not needed at all if the other is there?)
18. CanRebaseTo(unitId,cityId,playerId) - presuming that it will only fire on the unit and city belonging to the same player. Should override core game saying no
19. CanBoardTransport(unitID,transportUnitID,playerID) - assuming the same about players as above, to allow complex decisions about this. Not sure on what factors it should overrule core game saying no

It would also be good if there could be a version of accumulators that take a number and a matching string - this would be good for where the contributors get a UI; then it could be used for combat bonuses/penalties, bonus research, bonus happiness, culture, GPT...

[SamBC]

The modding community has been working on the idea of community standards for per-turn loops of various sorts, and these could be in the game engine instead, the idea being the multiple mods all looping over various things per turn will make a noticeable performance hit. However, if we're looking at an event framework that works on the rules side, and works for multiplayer, we probably don't want a loop over all players each turn (rather have an event that fires at the start of each player's turn). However, per-player city loops and unit loops, and some sort of plot loop, would be good. This would mean an event that fires at the start of each player's turn for every individual instance of each of cities and units for that player. A plot loop would also be good, but exactly when it would fire is an interesting question. In any case, this would give PlayerTurnCity(iPlayer,iCity), PlayerTurnUnit(iPlayer,iUnit) and possibly some sort of PlotTurn(x,y). For the player ones, the game engine could check that anything is registered before actually executing the loops.

[SamBC]

A few more added, culled from various places on CivFanatics.

[whoward69]

Events that trigger when various map creation points are reached - eg after civ starting plots are assigned but before units are placed (which would enable randomisation of Civs into starting plots), and also before starting plots are picked from a possible list (which would enable the list to be randomised) - at the moment civs are assigned 0 to N starting bottom right and working across and up into starting plots on a WorldBuilder map - which is kinda predictable :-(

[whoward69]

May already exists

OnUnitUpgraded (or OnUnitClassChange) - useful for changing all those ranged promotions into equivalent combat promotions
OnUnitPromoted (or OnUnitLevelChange)

[SamBC]

May already exists

OnUnitUpgraded (or OnUnitClassChange) - useful for changing all those ranged promotions into equivalent combat promotions
OnUnitPromoted (or OnUnitLevelChange)

Don't exist that I know of. There could be all sorts of uses for these, I imagine - giving some automatic promotions in addition at a certain level, incrementing some sort of central counter (could work on either) in order to permit access to a building, and so on. That brings to mind the idea of a PlayerCanTakePolicy, and a PlayerCanResearchTech. Probably lots of other 'can' ones that would be useful.

I'm struggling to think of really useful accumulators without the ability to give labels for display, unless there's a catch-all 'extra gold per turn', 'extra science per turn', 'extra culture per turn', and 'extra happiness'. That would be disappointing, but still useful.

[SamBC]

It has been noted in Another Place that the before/after battle events need different arguments to the ones given on the Events for combat sims, ideally at least giving position information so other details can be determined. Particularly, the existing events indicate when one of the units is a city, but not which city.

[SamBC]

So, which is more useful - having separate events for cities being lost (before buildings are removed and owner changes) and buildings being lost/gained other than by building or sale, or being expected to use events for cities changing hands to detect buildings being gained or lost? What other situations would need to be captured to cover buildings being gained or lost by means other than construction or sale?

[whoward69]

OnEraChange()

[whoward69]

OnGameStart() - or at least OnActivePlayerTurn() should fire at the start of turn 0 (as at the moment you get your initial units, move them etc, click Next Turn and then the first OnActivePlayerTurn() event fires - I want something before the player ever sees their starting units)

[SamBC]

OnGameStart() - or at least OnActivePlayerTurn() should fire at the start of turn 0 (as at the moment you get your initial units, move them etc, click Next Turn and then the first OnActivePlayerTurn() event fires - I want something before the player ever sees their starting units)

Have you tried using GameEvents.PlayerDoTurn() instead of Events.OnActivePlayerTurnStart()? It apparently fires at turn start, although for every turn. Just have a check on it being the first turn, or even the first invocation of the event (storing the fact it's fired before in the new modding save database).

[whoward69]

Yep, tried that one as well, it appears to behave exactly the same way (ie doesn't fire before turn 0)

[SamBC]

Yes, I see I even put that info on the wiki (based on someone else's reports). There is a PreGameStart, though I'm not sure where in the Lua you'd need to put code registering a listener for it to work (ie be registered early enough); it's also not necessarily been well-tested, as it didn't end up being used in the DLC scenarios.

[whoward69]

So thinking "out of the box", the initial Settler should get a UnitSetXY() event when they land on the map, and you could use that to detect the very first turn ... but they don't (in fact none of the initial units do). This could be becuase the unit did not "move" into that tile, but then why do units from policies and upgrade units get an initial "starting tile" UnitSetXY() event? Nothing like being consistent ... and that's nothing like consistent :-(

[SamBC]

So thinking "out of the box", the initial Settler should get a UnitSetXY() event when they land on the map, and you could use that to detect the very first turn ... but they don't (in fact none of the initial units do). This could be becuase the unit did not "move" into that tile, but then why do units from policies and upgrade units get an initial "starting tile" UnitSetXY() event? Nothing like being consistent ... and that's nothing like consistent :-(

There's almost certainly a very clear reason for it in the code, and that could be easy to work around (for the devs), or it might not. Possibly a good thing to ask for as well, though - UnitSetXY for everything, please...

[whoward69]

OnGameStart() - I want something before the player ever sees their starting units)

This may be Events.LoadScreenClose

function onLoadScreenClose()
  print(string.format("onLoadScreenClose()"))
end
Events.LoadScreenClose.Add(onLoadScreenClose);

has fired by the time you see your initial units in game. Unclear as to whether it fires before the units are created, before the units are placed or after the units are placed (need to do some more experimenting)

[whoward69]

Events.LoadScreenClose fires after ALL initial units are placed (all major and minor civs)

[whoward69]

Events.SerialEventImprovementDestroyed need to know what was destroyed, (not just on what hex something was, which you can no loger access to find out what it was ...)

[whoward69]

OnUnitCaptured()

[SamBC]

Events.SerialEventImprovementDestroyed need to know what was destroyed, (not just on what hex something was, which you can no loger access to find out what it was ...)

Well, what we really want is it as a GameEvent sort of event, rather than SerialEvents... that one apparently fires only when it's 'visible' to the player

[SamBC]

Events.LoadScreenClose fires after ALL initial units are placed (all major and minor civs)

I believe it also fires on reloads as well as new games... of course, sometimes you want that. Sometimes not. Something to think about.

[whoward69]

Well, what we really want is it as a GameEvent sort of event, rather than SerialEvents... that one apparently fires only when it's 'visible' to the player

What we need is only one type of event for events - ditch Events, GameEvent, LuaEvents, whatever and just have "Event"

[whoward69]

I believe it also fires on reloads as well as new games... of course, sometimes you want that. Sometimes not. Something to think about.

It does, but Game.GetGameTurn() returns the correct value, so you can test that to differentiate the two cases

[SamBC]

What we need is only one type of event for events - ditch Events, GameEvent, LuaEvents, whatever and just have "Event"

LuaEvents have to be separate for a clear architectural reason, as they are entirely within Lua, and principally exist as a way to send signals across contexts (states), as far as I can tell. Events and GameEvents are pre-determined and new ones can't be created in Lua, but LuaEvents are used entirely as such.

Otherwise, there may be a good architectural reason for the separation of Events and GameEvents, these things can be quite subtle, particularly in implementation. In some ways, I'd prefer for there to be a clear separation of UI-related events (which actually have different firing patterns) and game-rule related events. The firing patterns have to be different because, for example, as far as the UI/graphics are concerned, when an improvement is created, it's created twice - once when the 'half-built' version appears, and once when it's finished. Similarly, there's no need for the graphics system or UI to know when an improvement is created out of view. If it had to receive all of these and then filter them, that's a fair processing burden to send all the extra events and check them all, rather than checking at source, probably higher up in the control flow.

[whoward69]

LuaEvents have to be separate for a clear architectural reason, as they are entirely within Lua, and principally exist as a way to send signals across contexts (states), as far as I can tell. Events and GameEvents are pre-determined and new ones can't be created in Lua, but LuaEvents are used entirely as such.

Otherwise, there may be a good architectural reason for the separation of Events and GameEvents, these things can be quite subtle, particularly in implementation. In some ways, I'd prefer for there to be a clear separation of UI-related events (which actually have different firing patterns) and game-rule related events. The firing patterns have to be different because, for example, as far as the UI/graphics are concerned, when an improvement is created, it's created twice - once when the 'half-built' version appears, and once when it's finished. Similarly, there's no need for the graphics system or UI to know when an improvement is created out of view. If it had to receive all of these and then filter them, that's a fair processing burden to send all the extra events and check them all, rather than checking at source, probably higher up in the control flow.

I won't mention the single event pump in MFC and Swing then, or the fact that UI events in both systems can go to (partially) hidden windows and hence not need to change the display (oooo! I managed to find the sarcastic smiley this time!)

The display code in Civ 5 is so £$*! that it manages to fry my GPU anyway , so I'd hate for it to attempt to process anything it didn't have to

[Kruelgor]

I'd like to make a game event where Hannibal Barca, some elephants, and his army appear on a certain turn on the Italian peninsula right near the Alps.

or

A game event to replicate D-Day.

[Valkrionn]

....Completely wrong meaning of the term "event", as intended by this thread at least.

[whoward69]

I'd like to make a game event where Hannibal Barca, some elephants, and his army appear on a certain turn on the Italian peninsula right near the Alps.

Not what is meant by "event" in this context, but to do that you need to hook the GameEvents.PlayerDoTurn() event, test for a specific turn number and then manually deploy the army units onto a known hex and surrounding hexes - there is similiar code in the TurnsRemaining.lua file of the Vikings DLC

[SamBC]

I won't mention the single event pump in MFC and Swing then, or the fact that UI events in both systems can go to (partially) hidden windows and hence not need to change the display (oooo! I managed to find the sarcastic smiley this time!)

Except we don't actually have a MVC architecture in Civ, there's no way to choose different event sources for different listeners except by choosing different events. If you have semantically different events with different meanings, but similar firing points (and thus names), it's less confusing to put them in a different namespace than it is to give them subtly different names. Lua mods may want to respond to the graphics and (especially) UI-oriented events, so they have to get fired at Lua as well.

Really, this gist of this is that the events systems are not actually comparable to object-oriented events dispatching, because, well, they're not object-oriented. Lua isn't really object oriented, it just has some features and some tricks to make it look like it is. Of course, nothing that loosely-typed could ever easily meet some of the commonly-stated criteria for OO (such as polymorphism) and even the basic idea of data hiding isn't very compatible with the philosophy that seems to lie behind Lua.

[whoward69]

PlayerAdoptedPolicy() - counterpart of TeamResearchedTech() for policies

[SamBC]

PlayerAdoptedPolicy() - counterpart of TeamResearchedTech() for policies

Added to the discussion list. However, I will probably start moving simple and non-controversial ones to the 'consensus' list, as no-one has commented on them and there's no question involved in them. Comments on the more complex ones would be welcome. I will try to solicit such in Another Place as well.

[whoward69]

PlayerAdoptedPolicy() - counterpart of TeamResearchedTech() for policies

in addition to the playerId and policyId this needs a bFirstTime flag (to avoid the adopt, get benefit, adopt counter-policy, re-adopt, get benefit a second time exploit)

[SamBC]

in addition to the playerId and policyId this needs a bFirstTime flag (to avoid the adopt, get benefit, adopt counter-policy, re-adopt, get benefit a second time exploit)

Noted. Thanks.

[whoward69]

CityCanTrain - counterpart of CityCanConstruct, referring to units rather than buildings

Also CityCanBuy() - variant of CityCanTrain()

Or perhaps CityCanTrain() gets a bBuying parameter

[whoward69]

OnGameStart() - or at least OnActivePlayerTurn() should fire at the start of turn 0 (as at the moment you get your initial units, move them etc, click Next Turn and then the first OnActivePlayerTurn() event fires - I want something before the player ever sees their starting units)

The OnGameStart (non-)event is to just call a function at the end of the Lua file

-- Set up init() to be called after the load screen dialog closes 
--(with the units and partial map in the background)
Events.LoadScreenClose.Add(init)

-- Call init() at the end of the Lua file and it will be called *before* the 
--load screen dialog is even displayed (but after the map is generated
-- and all units have been placed, but the map not yet revealed to the player)
init()

[SamBC]

The OnGameStart (non-)event is to just call a function at the end of the Lua file

-- Set up init() to be called after the load screen dialog closes 
--(with the units and partial map in the background)
Events.LoadScreenClose.Add(init)

-- Call init() at the end of the Lua file and it will be called *before* the 
--load screen dialog is even displayed (but after the map is generated
-- and all units have been placed, but the map not yet revealed to the player)
init()

Interesting. This makes sense if it's an InGameUIAddin, given when the Lua files that call the Addin execute. If you modded a mapgen file to create a new AddIn, it would execute at a different point, defined by when the Addin hooks fire.

[SamBC]

Also CityCanBuy() - variant of CityCanTrain()

Or perhaps CityCanTrain() gets a bBuying parameter

You'd want the same duplication or parameter for Construct as well... note to that effect added to the list.

[whoward69]

CanRebaseTo(pUnit, pCity) - at the moment rebase range is a factor of range (currently 2x), which could remain the default, but I'd like to be able to build "refuelling tanker aircraft" at a city B which a plane at city A can reach, to extend its rebase range to city C which otherwise it couldn't reach

CanLoadOnto(pUnit, pTransportUnit) - which would enable programmed control of various combinations of planes/missiles/etc on various transports (carriers/cruisers/subs)

[SamBC]

Added, and those that were added in the June patch also removed