Events model

[Gary Thomas]

This is about a model which spans all the other models, and assists them in communicating with each other.

There are really two kinds of events in Clash - those which have an immediate effect, and those which have an effect at the "round-up" at the end of each turn.

The first kind of event is normally dealt with within a model and will not be discussed here.

The second kind of event covers a great range of actual situations. Presently there is code which, in various ways, produces event for display at the end of the turn, and another kind for passing to the economic social models for effects of riots. A third kind saves up data for combat reports. The social model code also has some embryonic effects which at present are actually just messages (strings).

These events represent communication between models. It is easy to slip into the situation where every model talks to every other model, often in a variety of ways.

If that happens, every model becomes dependent on every other model. A change to any model's code means changing the code in every model. This means disaster in the coding.

What is needed is some sort of mechanism which means that each model talks only to a single entity, both to report events and to react to them. Also needed is a uniform event interface, implemented by all the varied kinds of event.

It must be possible to determine from the event itself who will be interested, so the event can be sent to the right destination or destinations.

There is in Java a publish/subscribe system (the Observer/Observable system). This is a system which I do not like at all, for a variety of reasons. It is not my purpose here to argue the pros and cons of that system. It is sufficient to point out that everything that is observable has its own list of observers, so that each of the observers needs to know about the thing observed. This leads to the kind of dependencies that I mentioned above.

The kind of model I suggest is based on the broker pattern.

There is a single entity (class instance) which is the event broker. Any events which happen are sent to the event broker, which stores them.

Anything interested in events of a particular kind registers itself with the event broker as being interested in events of that kind.

At the end of the turn, the event broker goes through all the events in the queue and "posts" them to the entities that have expressed an interest in that kind of event.

Thus, all models need to know about the event interface and the event broker, only.

If I have a coding battle cry, it is likely to be "Down with dependencies". And this model goes a long way toward achieving that.

It remains to design the event interface...

Cheers

[Lord God Jinnai]

what about events that trigger other events later on?

[LDiCesare]

Gary,
I basically agree.
Remarks:
Combat Reports is in my opinion internal to combat model, but indeed is called to display data at end of turn. I am very prone to changing the code soon anyway because I am having trouble with feeding it detailed info on how the battle went (which requires tracing the various phases of battle and thus is less event-oriented).
On the end-turn: Are we sure there won't be other times to react?
For example: Before the event actaully occurs (like do you really want to fight this battle). Look for threads about CTP2 modding language (slic) to see what it can be used for.

LGJ:
Events that trigger other events later can be modelled by the broker. You just log the event happened and increment a turn counter or change your state and register for another event and then send it.
It is more tricky if the eventA on turn1 is for some reason supposed to trigger eventB on the same turn, but it can be done.
I used to code an event manager which could manage delays: You wanted to react if eventA occurred, but only when eventB occurred, and could be interested in only the last eventA that had occurred. I am not sure we need something that rich, since eventB is likely to always be end of turn, and the events we have don't need forgetting/buffering, but it can be done easily if needed.

[Mark_Everson]

Sounds like a great idea in general.

I don't think the end-of-turn broadcast is sufficient, as Laurent was also mentioning. I may be misinterpreting one sentence, which I quote below. In which case, the sentence in the spec needs elaboration...

My issue:

The player pushes the button, and the turn ends. I assume this is what is meant by "At the end of the turn, the event broker goes through all the events in the queue and "posts" them to the entities that have expressed an interest in that kind of event." The problem is the events genererated by one model for immidiate effect upon another model, within the same turn.

Example:
1. end-of-turn exectued and Events distributed. City X is peaceful so there is no Event.
2. After that, in the government phase, there is a riot in City X whose Event is going to screw up a local economy.
3. In The Same Turn, but just a later phase, the economic phase for City X is executed. As the code works currently the economy knows about the riot and is affected appropriately. In the end-of-turn system it appears to me it would be Next turn when this turn's riot would take effect.

So long as the broker system can be structured to handle the intra-turn Events, it looks like a good start to me.

[LDiCesare]

Mark, in your example, do you need an event or do you change values that could be accessed by the other model?
Maybe we need to decide beforehand which package is allowed to prereq what. Starting there we can define what should be passed through events.
The obvious is that gui shouldn't be referenced by non-gui code, and test cases shouldn't be referenced anywhere, but other frameworks may need a few dependencies:
Classes like Civilization, MapSquare, are used a bit everywhere. Beyond that, any dependency could be checked.

[Gary Thomas]

After thinking about it, and realizing that everything except user input takes place "at the end of the turn", I don't think the the event broker should queue events - they should be despatched immediately. If they need to be queued, as, for example, display events, the recipient can queue them (as indeed the display events system does).

There doesn't seem to be any immediate need for delayed events, but, if the need develops they will be very easy to add.

Cheers

[colorrr]

The possibility exists to classify the events. There could be f.instance
-immediate
-end of turn

Then, the broker, upon receiving the event, checks to see the type of event.
If it is an immediate event, the broker immediately notices the destination class that
the event has passed, calling the correct class interface before letting the source class continue.
If it is an end of turn event, then the broker puts the event on a fifo queue or a stack
and stops executing, allowing the source class to continue it's processing.

When the end of turn button is pressed a code will call an interface that makes the broker send
all end of turn events to their destinations.

Later if we need to make more classifications that would be possible too.

[Gary Thomas]

When the end of turn button is pressed a code will call an interface that makes the broker send

The only time events can be put on the queue is AFTER the end of turn button is pressed, so all events are always immediate.

However, we may find it expedient to produce events in response to player GUI actions (it doesn't happen now - everything goes directly to its destination). If that were implemented, then such events would normally not be implemented until the end of turn button is pressed, if only because the player needs the opportunity to change their mind.

Cheers

[Mark_Everson]

I'm bumping this up for Vovan, who is considering using the events model for diplomatic state changes. The stuff in the first post may be of some use.

Vovan, if you want to consider changing the events model, or putting up more specifics about it, please do it here.

[vovan]

Thank you, Mark! My searching abilities seem to be diminishing by the day... I could have sworn that I searched for the word "event" in this forum. Any ways, I'll look into it.