Clash events: coding discussion

[vovan]

Well, I am finally at the stage of making the diplomatic statuses, attitudes, and reputations dynamic. (Yay...) So, I basically need to start implementing such things as automatic declaration of war, when a nation attacks another one (i.e. takes over their province or attacks their unit), change of diplomatic status from no contact to peace (or possibly the automatic appearance of the contact screen) when one civ encounters another for the first time, and such.

So, it is time for me to dig into the events model. Unfortunately, this is where the brevity of the javadocs comes in. The descriptions of things are short and unsubstantial, that I cannot quite make out how the system is set up. I mean, if the only comment about class Event is "This is the class for an event" (well duh!) it doesn't really tell me what I am supposed to do with it. So, before I go digging into the code to figure out what's going on, I was thinking that maybe somebody could explain to me the dynamics of the events model in clash in terms of classes. For instance, like this:

"When the game starts up, all events are registered in class X. Then, every turn, class Y checks the state of the game to see if any of the events have occured. If an event has occured, if fires method W.method(), and notifies class X. After which action, class X calls the appropriate methods of the appropriate classes."

That kind of stuff. It would be very helpful, and would save me a lot of time of useless code digging.

Thanks in advance.

(Also, if you feel that this discussion is better held via e-mail, that's no problem at all. )

[Mark_Everson]

Re: Clash events: coding discussion

Originally posted by vovansim
So, before I go digging into the code to figure out what's going on, I was thinking that maybe somebody could explain to me the dynamics of the events model in clash in terms of classes. For instance, like this:

"When the game starts up, all events are registered in class X. Then, every turn, class Y checks the state of the game to see if any of the events have occured. If an event has occured, if fires method W.method(), and notifies class X. After which action, class X calls the appropriate methods of the appropriate classes."

That kind of stuff. It would be very helpful, and would save me a lot of time of useless code digging.

Glad you've gotten to this point Vovan! It will add a Lot to the game.

One possibility is that the events model might not actually be what you need. AFAIK events are only checked at one point in the turn, and things like changes in diplomatic status should take place immediately. If you do think you still need to understand it. . .

I don't know much about the events model. Have to see if Laurent can take a better stab at this. Gary was the one that coded it and mostly used it. Since he's largely unavailable, we're on our own.

I suspect that looking over the dawn scenario file (dawn1.xml) which heavily uses events might be of use. At least it will show you the sort of uses Gary put them to when he designed the events model. When you figure it out, please update the javadocs

[LDiCesare]

The events in game are mostly for-scenario events. I think they are checked only once per turn, but am not sure.
There is no pervasive event model, though we had at a time a lot of Observable/Observer patterns, they are largely unused. Basically, we use the game.interface package as a communication channel between the models (I think it is growing into something too big and may need refactoring soon btw, but don't have any good ideas about that now).
So the way the code is now is: Make a class/interface method that can be retrieved from that package and to which we will send information when interesting stuff happens. For instance, if you need a trespassing border event, or something like that, I can call that method from the military side, and you look at it. It can also send an event that will be analyzed by the event model for scenario purposes (or yours).
Which actually means there is little or no framework.

[LFS]

== I just re-read this it doesn't read as good as when I wrote it a few minutes ago, I shouldn't write at 1 in the morning==

Just noticed the design.html and couple of html docs from gary- excellent reading. Pity he is not around still, with only a few minor differences I agree/believe in what he says ( I judge he has more experience than myself though) - and his cannot recommend enough books (design patterns and refactoring) are my 2 fave books as well, what a guy.

I've only looked at a tiny fraction of the code so far, but it is a HUGE improvement over what what it looked like a couple of years back (when i briefly tried to get involved).

Oh yes, Events - had a quick scan through they aren't as daunting as they first look, but yes they are only fired at the start of the game and at the start of each turn, so far it looks like they have only been used as a means to implement XML descriptors.

It seems to go as follows

All possible events are registered in RegisterEvents, ScenarioFile reads the xml and sets up the xml parser which will cause Event objects to be created and placed in Events queue.

Game calls Events at the start of the game, which performs and removes any Event's that are activated. Then each turn NextTurn also fires up Events to execute/remove any events that have been activated (or just remove if they are canclled).

Event's are activated based on a hasOccured method, which is a method your Event class implements (this is where you say has A crossed B's border), if hasOccured returns true then performActions is called (provided by AbstractEvent) where all the Action's that your event contains are performed. You add Action's by calling addxxxxx on AbstractAction, this will add to a list of Action's which gets performed when Event hasOccurred.

It looks like a fairly flexible system, Events maintains a list of Event's that are still waiting to be triggered, and new events can be added to the list with Events.addToList. As an Event's Action's can in turn add/remove Event's you can get nice long term effects, there are also cancel Condition's that can cancel an Event before it is activated.

on a side track, One thing that shocked me, It looks like someone (gary?) has written an XML parser, I know he says he doesn't like external dependencies - but writing xml parsers !!, a 3rd party parser (Xerces, James clarks or whatever) would do the job and do the validation of the xml files.

== that was bad, hope i got the real bad gobbledigook=

[LDiCesare]

Yes, Gary wrote the xml parser, but it is actually the third iteration of a parser we used.
We started with xerxes/sax. Gary used one thing the way he was doing at work, that worked, but was a bit cumbersome. I used the sax api differently so it was easier to plug new classes into the xml framework. Then Gary realized that what I did was simpler than what he did, so he pushed the idea even farther and used reflexion, making integration an almost no-brainer.
Now, why did he have to rewrite a parser instead of using sax?
Well, xerxes is BIG. It would have drastically augmented the download size of the demo.
Of course, it would also check for errors in the file format etc., but that is really of interest only to a scenario designer, who can use Internet Explorer to get the same result.

[LFS]

yes Xerces is big, and slow compared to other parsers, The JClark one is smaller and faster but doesn't validate (if I remember correct). I suppose for what we need the hand cranked one is quite adequate - namespce support and all the fancy stuff is not really needed.

One possibility is that the events model might not actually be what you need. AFAIK events are only checked at one point in the turn, and things like changes in diplomatic status should take place immediately

The event model does look quite decent and flexible - shame if it went to waste, plus although some diplomacy probably needs to be instant, I would think in a turn based game having all diplomatic changes immediate might not work to well.

[vovan]

OK, so back to the events.

Lee, thanks for the explanation. I think I can see now how the venets work, and you are right - they are mostly for the use of the scenario, and would kind of be of not much use for me now. (Though it might be interesting to implement diplomatic scenario events at a later date.)

Laurent, thanks for your input, also. But I am not quite sure how the military model works now, and quite frankly, I don't know if I should spend the time trying to figure it out right now. (Though it might be useful...) So, I was wondering, since as I understand you are playing with the model right now, could you maybe help me out a little bit with the following stuff:

(assuming that I have some class Diplomacy in the interfaces subpackage)

1) I basically need the two civilizations, if they are in peace, and one of them crosses the border of the other, or attacks a unit, a war would be declared. So, when either of those two happens, interfaces.Diplomacy.attack(Civilization attacker, Civilization defender) should be called.

2) I also need it so that when one civilization discovers another for the first time, the status changes from no contact to something else. So, essentially, if a unit of one civilization comes within two squares (or, the visibility range) of either another civ's unit or province, that interfaces.Diplomacy.visualContact(Civilization discoverer, Civilization discovered) is called.

If you could either do it for me yourself (so that we would avoid code collisions), or tell me which class to look at, that would be awesome.

Thank you for your time,
Vovan

[LFS]

and you are right - they are mostly for the use of the scenario, and would kind of be of not much use for me now. (Though it might be interesting to implement diplomatic scenario events at a later date.)

I was not saying that, They have been used for scenario setup so far, but look more than capable of elegantly handling other event type situations (ie. yours). The only stumbling block may the frequency at which they are checked. But that could probably be altered.

[vovan]

Originally posted by LFS
I was not saying that, They have been used for scenario setup so far, but look more than capable of elegantly handling other event type situations (ie. yours). The only stumbling block may the frequency at which they are checked. But that could probably be altered.

Well, the things that I need checked right now, at this particular stage, are to be checked essentially when troops move, as you can see. And since the toops move at the end of each turn, then checking for the events I need at that time is just fine.

Soooo, I suppose I need to come up with some FirstEncounterEvent class to deal with point #2 I raised there, and have it observe military.EncounterManager class, and when all of the statuses are changed from nocontact, remove it from the list of observers to save the resources... I think that should work, right?

Now, for point #1. I suppose EncounterManager would once again be useful here.

[Mark_Everson]

Originally posted by vovansim
And since the toops move at the end of each turn, then checking for the events I need at that time is just fine.

Just a quick correction. Troops move during a number of 'ticks' that subdivide a turn. It is to make movement more fluid, and make sure collisions between units won't be missed amongst other reasons.

One reason I think you want diplomatic states to change instantaniously IMO is so that if Vovan attacks me on tick 1 my units on tick 3 won't let his units do somthing that they could while we were at peace.