Interface Redesign

[zenzike]

i don't understand what you want with the NULL_EVENT. when would the engine send one of these?

Null events are useful when we're using patterns that always generate events, but we don't want one in a particular case. For example, I might have it so that every time a unit is damaged it calls a function damaged() that generates and returns an event. Typically this would be the UNIT_DAMAGED_EVENT, but if say, our unit was on a kamikaze attack, it might make sense to return a NULL_EVENT that didn't do anything. This is just an example, but the point is that we don't need to change the underlying mechanisms by which events are handled -- we have a defined way of producing and handling null events.

why do you want to remove the fromId? we said this could be used for AI->AI communication in the future.

Because if there is AI/AI communication, then I'm assuming it will have to be via the engine, using some sort of Command. The engine would then produce an Event that would be parametrised with the fromID as necessary. In most cases we won't need a fromID, since it's just from the engine, so having this field seems like a useless waste -- of course having AI/AI communication would be great, but I think it won't happen for a long time, and the right way of doing it is through particular Events, not inherently in the handleEvent().

why do you want to remove the eventId? we said this could be used for asynchronous communication in the future.

Oops, my mistake, I meant it to be:

Code: Select all

int handleSEvent(int teamID, int eventID, void* event)

We are passing SEvents (since we're actually handling event structs, and the C++ interface makes these real events) to one another, not Messages. The events need an eventID for the cast, and nothing more. I still don't quite get what you mean by asynchronous communication -- surely we can achieve everything we need by sending an Event?

will the old C++ interface be built up directly on the C interface, or use your new C++ interface underneath?

I'm afraid I disagree with AF here : the old C++ interface should be built on top of the new C++ interface. The reason (I think), is that there's a natural transition from the handleSEvent() C struct passing way of doing things to real Event handling C++ mechanisms that handle the cases as appropriate. One way of handling these cases is to provide the old AI interface. It also gives a good case example of how to use the new interface.

If we were to build the old C++ interface directly, we would be reproducing much of the new interface code, but specialising it. This is more efficient, but we lose a massive advantage of the handleEvent() way of doing things: exception handling and logging.

I am still pro functions (things like making a struct for an int ... :/ ).
...
if i understand it right, an new AI will always crash with an old engine, and vise versa not, wether we use functions or events, no?
adding an event(= future extension) is more trivial with functions.

That's the point: if a new AI uses functions on an old engine, the engine will crash because the function doesn't exist in callback.
However, if a new AI uses State callbacks (in the style of handleEvent), the old engine won't understand and can send back a NullState. Then the AI can decide if it can carry on without the data it has requested. If it can't it can fail gracefully, otherwise, it might be able to go on but not take into account certain information that's unavailable in the old engine.

The question is whether or not this level of safety is worth the hassle of horrible IntState type structs (yuk, they do look horrible).

i dont understand the last point, about internal representation of the engine. as we pass only primitives through the functions, this applies to functions aswell

The engine is subject to all kinds of change : one day we might decide to make higher dimensional 4d spring. Of course that's a silly example, but what I'm saying is that the engine could change in ways we don't expect, even at a fundamental level. Maybe in future versions we won't be using UnitDef anymore is a more realistic example.

(a float3 will be passed as float[3] through the C interface eg, wether we use functions or events).

Will it? I thought it would be passed as a float3 struct.

The CAIObject layer is to be as small as possible and should only concern itself with taking the C API and presenting a simple C++ OO interface which we can build an AI framework with.

I like this idea, I thought that's what we were going for from the beginning? We've been talking about how handleSEvent() as a C function feeds almost directly into a framework for the parent CAIObject to use (using handleEvent in the real OOP sense).

[AF]

I think that if we build the compatibility layer directly onto the SDK initially then we will have teething troubles because the SDK will be brand new a liable to change, resulting in us continually breaking and fixing the compatibility layer.

Once we have a stable compatibility layer well be able to test and develop the SDK and have a fall back.

I also think this would encourage us to rush development of the OO SDK in order for us to have something to test with which would make us compromise design in favour of development time.

I do think that once the OO SDK matures the compatibility layer should be lifted up on top of it to further ease the transition of existing code from old to new. The highest level of the API that the compatibility layer should deal with is CAIObject.

[hoijui]

i don't understand what you want with the NULL_EVENT. when would the engine send one of these?

Null events are useful when we're using patterns that always generate events, but we don't want one in a particular case. For example, I might have it so that every time a unit is damaged it calls a function damaged() that generates and returns an event. Typically this would be the UNIT_DAMAGED_EVENT, but if say, our unit was on a kamikaze attack, it might make sense to return a NULL_EVENT that didn't do anything. This is just an example, but the point is that we don't need to change the underlying mechanisms by which events are handled -- we have a defined way of producing and handling null events.

hehe :D i still don't get it :D, sorry!
why would a unit on kamikaze be handled special, why not return a UNIT_DAMAGED_EVENT?
if we get a NULL_EVENT, how should we know that the kamikaze unit did its job? could be that anything else that causes a NULL_EVENT happend, no?

why do you want to remove the fromId? we said this could be used for AI->AI communication in the future.

Because if there is AI/AI communication, then I'm assuming it will have to be via the engine, using some sort of Command. The engine would then produce an Event that would be parametrized with the fromID as necessary. In most cases we won't need a fromID, since it's just from the engine, so having this field seems like a useless waste -- of course having AI/AI communication would be great, but I think it won't happen for a long time, and the right way of doing it is through particular Events, not inherently in the handleEvent().

hmm... seems to be a matter of taste, as you gave no reason why this way is "the right way".

I still don't quite get what you mean by asynchronous communication -- surely we can achieve everything we need by sending an Event?

The eventTopic is meant for casting the struct, and the eventId is for asynchronous communication.
I had an example for asynchronous communication in my drafts (not in the current one anymore though).
an example:
AI to engine: pls give me a list of all unitDefs, eventID=55 -> engine returns nothing
<some frames pass>
engine to AI: here you have the unitDefs you requested earlier with eventId=55 -> sending an event containing unitDefs

will the old C++ interface be built up directly on the C interface, or use your new C++ interface underneath?

I'm afraid I disagree with AF here : the old C++ interface should be built on top of the new C++ interface. The reason (I think), is that there's a natural transition from the handleSEvent() C struct passing way of doing things to real Event handling C++ mechanisms that handle the cases as appropriate. One way of handling these cases is to provide the old AI interface. It also gives a good case example of how to use the new interface.

If we were to build the old C++ interface directly, we would be reproducing much of the new interface code, but specializing it. This is more efficient, but we lose a massive advantage of the handleEvent() way of doing things: exception handling and logging.

good points :/

I am still pro functions (things like making a struct for an int ... :/ ).
...
if i understand it right, an new AI will always crash with an old engine, and vise versa not, whether we use functions or events, no?
adding an event(= future extension) is more trivial with functions.

That's the point: if a new AI uses functions on an old engine, the engine will crash because the function doesn't exist in callback.
However, if a new AI uses State callbacks (in the style of handleEvent), the old engine won't understand and can send back a NullState. Then the AI can decide if it can carry on without the data it has requested. If it can't it can fail gracefully, otherwise, it might be able to go on but not take into account certain information that's unavailable in the old engine.

The question is whether or not this level of safety is worth the hassle of horrible IntState type structs (yuk, they do look horrible).

hmm.. right, for some events that would work.
so to decide if it is worth that... how feasible is it that pl will end up with an old engine and new AIs?
x) We can expect every user to have the current stable release of spring.
x) AI devs will usually not publish an AI that needs an SVN version of spring, in a way that users will easily find it.
o) To let release-version-spring users profit from bug fixes in the AI, it is more complicated with functions for the AI dev (he had to maintain 2 versions of his AI).
i don't see any other points right now, some AI devs can maybe help here.

i dont understand the last point, about internal representation of the engine. as we pass only primitives through the functions, this applies to functions as well

The engine is subject to all kinds of change : one day we might decide to make higher dimensional 4d spring. Of course that's a silly example, but what I'm saying is that the engine could change in ways we don't expect, even at a fundamental level. Maybe in future versions we won't be using UnitDef anymore is a more realistic example.

(a float3 will be passed as float[3] through the C interface eg, wether we use functions or events).

Will it? I thought it would be passed as a float3 struct.

no, as float[3]
the idea is, to keep the interface simple. i have seen that this would be a good idea, when working on JAI. it is very complicated as it is now; nobody really knows which classes are used or useful for the AI interface. with the C interface, everything the AI needs to know from the engine will be in one header file. we will not pass any structures used in the engine directly to the AI, not float3 nor UnitDef nor anything else. this applies whether we will use functions or events, and therefor this can not be an argument pro events.

The CAIObject layer is to be as small as possible and should only concern itself with taking the C API and presenting a simple C++ OO interface which we can build an AI framework with.

I like this idea, I thought that's what we were going for from the beginning? We've been talking about how handleSEvent() as a C function feeds almost directly into a framework for the parent CAIObject to use (using handleEvent in the real OOP sense).

I think it was, we just never talked about it, as it was mainly me pushing, and this is not of high interest to me, sorry!

[AF]

Would an update message not be an example of a null event since it would not pass any parameters with it? We could make it pass along the current game frame though.

[zenzike]

Would an update message not be an example of a null event since it would not pass any parameters with it? We could make it pass along the current game frame though.

No, because an update event ought to have side-effects -- the AI will probably do some calculations when it receives an update. A null event has no side-effects, except possibly logging (though that's an effect due to the way handleEvent is programmed, not because NullEvent does anything).

The whole point of a null event is so that the spring engine can (later) be designed to work more closely with the AI, and handle certain messages to the AI generically.

Here's an elaborate example, where we pretend that spring plays games on a truly epic scale, where the engine might support platoons and squads as well as troops. Let's suppose these all subclass unit like this (in a collection hierarchy):

Code: Select all

Unit
  Platoon
    Squad
      Troop

Now Unit would have a method like damaged(int amount), that is called when the unit is damaged. Let's say that the Platoon has been damaged. Then we would recursively call damage() on all the squads in the platoon, and then again on all troops. Maybe a whole platoon receives an amount of damage, and this is distributed amongst the troops -- The point is that we can define a single method damage(), and we don't need to redefine it at each level of the recursion, since we can make it generic enough to call its children appropriately. However, we might want the AI to handle these events differently, so for the platoon, we might have a PlatoonDamagedEvent, for a troop a TroopDamagedEvent. This means that the Event property of each Unit can be different, and the damage() function calls the handleEvent() function of the AI without caring what event is being sent.

However, we might not want the AI to handle Squad damage (for whatever reason ... maybe it's just a distinction for spring to render things efficiently, it really doesn't matter). Now we can set the squad's event to NullEvent, meaning we don't have to rewrite the damage() function, and yet the Squad does not send any event information to the AI that can be used (and that's what we want!).

Of course this is just an example -- I'm sure there are problems with it. The general idea though, is that by supporting NullEvent, we can save other developers (and ourselves) time when we build generic functions that generate events that are to be handled by the AI.

hmm... seems to be a matter of taste, as you gave no reason why this way is "the right way".

I think its the right way because in most cases we will not have AI/AI communication. It currently exists in no AI, and even when it does exist, I'm assuming there won't be many of these messages passed around. If this is the case then it's a wasted parameter -- we won't be using it 95% of the time. We should keep the handleEvent() method as light as possible, since all engine information will flow through that method.

[hoijui]

hmm...
i am still confused :/
will we call:

Code: Select all

handleEvent(temId, NULL_EVENT, NullEvent);

or

Code: Select all

handleEvent(temId, SQUAD_DAMAGED_EVENT, NullEvent);

?
I can not see the sence in the first call, and the second will crash the AI, as it will try to cast the NullEvent to a SquadDamagedEvent, and retrieve values from that.

hmm... seems to be a matter of taste, as you gave no reason why this way is "the right way".

I think its the right way because in most cases we will not have AI/AI communication. It currently exists in no AI, and even when it does exist, I'm assuming there won't be many of these messages passed around. If this is the case then it's a wasted parameter -- we won't be using it 95% of the time. We should keep the handleEvent() method as light as possible, since all engine information will flow through that method.

the performance loss of passing an additional int to a function is very small, as is the chance that AI<->AI communication will be used. it kind of remains a matter of taste.

usually event systems have a generic way to always determine where a message came from, even if it is generally clear who sent it. so for a clean design, as you always want it, it would be better to have it as separate parameter. Think of EventObject.getSource() in Java eg.; common to all Events in Java.

[zenzike]

We send

Code: Select all

handleEvent(teamID, NULL_EVENT, NullEvent);

The advantage is not for the AI, but for the engine developers. It means that they don't have to worry about special cases when creating events, but not wanting the AI to do anything about them. Look at my example above: the engine devs have less work to do because a NULL_EVENT is available to them, and the program can stay as generic as before. (I'm also going to be using the handleEvent internally in my AI, and I can see uses for a NULL_EVENT from a design perspective -- it means less work later!). Either way, is it such a big deal to have a NULL_EVENT? If you can't see a use for it, but I can, why not include it anyway?

the performance loss of passing an additional int to a function is very small

Agreed, though it does increase the size of the function by 50%, that's a big proportional increase!

Think of EventObject.getSource() in Java eg.; common to all Events in Java.

My point exactly: even the Java monkeys decided that putting the getSource() is better in the Event, not the handler.

The advantage is that the event carries its own information with it, so that we don't have to keep track of sentTeamID separately. We can just pass the event around and eventually, the function that is interested in this data can take the information out of the event itself. This is an important advantage.

[AF]

I am totally confused.

As I see it this is what you want:

You want the ability to send a 'null event'.

what I object to most is the null part, as it is totally paradoxical.

The very concept of sending a message that the AI should not process or react to defeats the whole point of sending the message in the first place.

And your example wasn't very good. I got totally confused halfway through the first paragraph which was incidentally far too long winded.

As I see it this is somewhat identical to the following analogy.

I make empty box, wrap it up, and send it in the post. You receive empty box from mail man.

Basically making an event so generic that it has no meaning or data, its just an event, and its 100% ambiguous. A total waste of communications bandwidth between the AI and the engine.


I'm sorry zenzike but what your trying to describe at first glance looks like something which is a logical fallacy, and such a simple one that it cant possibly be what you mean. At second glance it just makes no sense whatsoever

[hoijui]

About the NullEvent
There are two reasons i want to understand it:
* i am curious
* maybe we don't understand it, cause you have an error in your thoughts/logic, and it is useless, or better done with an other technique

In your example, we do not want the AI to recieve SquadDamagedEvents. Instead of sending a NullEvent, we could do this:
If the Engine is very generic once in the future, and uses events internally, we can put an EventFilter before the AI interface, and filter out events we don't want the AI to receive.
More natural and more performant (filter out once, instead of sending many times).

the performance loss of passing an additional int to a function is very small

Agreed, though it does increase the size of the function by 50%, that's a big proportional increase!

Hehe! :D
good one!
i say: the additional int will only take 1/3 of the functions size

Think of EventObject.getSource() in Java eg.; common to all Events in Java.

My point exactly: even the Java monkeys decided that putting the getSource() is better in the Event, not the handler.

The advantage is that the event carries its own information with it, so that we don't have to keep track of sentTeamID separately. We can just pass the event around and eventually, the function that is interested in this data can take the information out of the event itself. This is an important advantage.

The point is, that every Event in Java has a source, and in C we can only ensure that if we have it as a parameter in handleEvent(), as there is no inheritance. The events will not be passed around in the C interface, and will be converted to other structs or classes anyway when going further into C++ or Java. In the C++ or Java interface, we could include the source in the event then. When adding a new event, one would not have to remember to include the source as a member.

[zenzike]

I'm sorry zenzike but what your trying to describe at first glance looks like something which is a logical fallacy, and such a simple one that it cant possibly be what you mean. At second glance it just makes no sense whatsoever

I'm sorry I'm not being clear. I know it sounds odd, but it is a well recognised pattern that allows us to avoid headaches later. I don't think it's a big deal, and we shouldn't let it dominate the rest of this thread (which I think has made great progress).

All I can do is point you to some useful references, and there are plenty in the references section of the wiki article [1]. These two links are particularly useful [2],[3]. If you want a good worked through example, take a look at [4].

As I've said before, even if you don't see a use for it, I certainly do -- adding a single event for the sake of "maybe he's right" doesn't seem that much of a cost. If you're right, then fine, no loss. If I'm right, then we'll be glad we have it. In either case I don't mind, since adding an event afterwards isn't hard (actually, we've been designing it to make additions easy), so we can even not add it now, and have it there later (though in my mind, the Null object is akin to the number 0, and ought to be the 0th entry. If I can't convince you of this, never mind, I won't fuss).

Please let's keep conversation civilised -- if there are bad explanations, or people who don't understand clarification will help everybody.

I make empty box, wrap it up, and send it in the post. You receive empty box from mail man.

This shows you've understood what I'm trying to get at perfectly -- the misunderstanding is that empty boxes are actually useful -- not for the receiver, but for the sender who is already committed to sending a box to everybody on his mailing list, even if there's no message.

If the Engine is very generic once in the future, and uses events internally, we can put an EventFilter before the AI interface, and filter out events we don't want the AI to receive.

This is exactly the idea -- we can filter out NullEvents if we want to keep good performance -- but NullEvents still have to exist in order for us to filter it out.

[1] http://en.wikipedia.org/wiki/Null_Object_pattern
[2] http://exciton.cs.rice.edu/javaresource ... attern.htm
[3] http://www.owlnet.rice.edu/~comp212/00- ... isited.htm
[4] Head First Design Patterns, Freeman & Freeman p214

[hoijui]

If the Engine is very generic once in the future, and uses events internally, we can put an EventFilter before the AI interface, and filter out events we don't want the AI to receive.

This is exactly the idea -- we can filter out NullEvents if we want to keep good performance -- but NullEvents still have to exist in order for us to filter it out.

sorry but.. no! we do not need NullEvents for that. The Filter is on the Engine side, right between the inner engine and the AI interface part of the engine. In your example, it looks like this:

Code: Select all

class AIEventFilter {
   int handleEvent(int teamId, int eventTopic, ...) {
      if (eventTopic != SQUAD_DAMAGED_EVENT) {
         aiInterface.handleEvent(teamId, eventTopic, ...);
      }
   }
}

If i understood you correctly, you would have exchanged the SQUAD_DAMAGED_EVENT with a NULL_EVENT at the place where i have my filter. then sent the NULL_EVENT to all AIs and then let them filter it out?

[zenzike]

If i understood you correctly, you would have exchanged the SQUAD_DAMAGED_EVENT with a NULL_EVENT at the place where i have my filter. then sent the NULL_EVENT to all AIs and then let them filter it out?

Yes, I am saying that the developer makes it so that the squad sends a NullEvent, since there's no appropriate behaviour -- ie, no SquadEvent makes sense. Then there could be a filter that filters all NullEvents before sending to the AI. NullEvents don't necessarily just come from squads, they could be from many places -- the thing they have in common is that no suitable behaviour exists, so we just put a null placemarker.

If there's an internal call to NullEvent, this isn't a problem because the NullEvent won't break anything.

I'm happy to carry on discussing this, but I think this thread is the wrong place for it. If you want to learn more about null objects, read the articles I suggested, and then PM me, or start a new thread (and let me know about it).

[AF]

I do not understand why one would send a null event when you could just never send it in the first place.

Reasons why I would send someone an empty box:

Someone needs a box to put things in. But this is a computer, we don't need to use the engine as an object factory because that would involve a C++ interface which defeats the whole point, besides we have keywords such as new for that.

As a message or sign. This is sort of self defeating. Say I say Ill send a null event when my unit walks in a circle, why not just call it a circle event? And what if I say Ill send one when it spins around on the Z axis? How do I know this null event came from a Z axis spin and not a circle? What does it apply to?

While I understand what the point of the concept of null is for, I dont see why sending a 'null' value by itself across the C API. The very notion of sending nothing but 'null' anywhere in a generic message system seems like an utter waste of resources. Why should I have to go through 30 or so if else checks or a switch statement only to reach null and have to abort the check wasting resources in the process??

hmm Ive just gone to post and saw your last post zenzike, tbh this looks more like a helper for the programmer that serves no functional role, and should really serve as annotation or commenting rather than actual code.

[zenzike]

this looks more like a helper for the programmer that serves no functional role, and should really serve as annotation or commenting rather than actual code.

That's right, it has deliberately got no functional role. It is there to help the programmer, not to do anything! Please start a new thread if you want to continue this discussion. Let's stay focused on the AI here.

[hoijui]

ahh.. now i understood a bit more.
your NullEvent has some right, inside the engine, but not at all in the C AI interface, as it whould be filtered out before that, and therefore we dont need it there.

[hoijui]

Aehm...
whats left?
are we still unclear with:
* the arguments of handleEvent() (and handeCommand())
* the NullEvent thing
?

about AI->AI communication:
zenzike: you you think, that if we will have it in the future, we should have a separate functions for it; something like handleAIEvent()? not use handleEvent() and handleCommand()?
(i would be ok with that?)

what about the id for asynchronous communication? should it be inside the S*Command an S*Event structs, or a parameter of the handle*() functions? or should we have a handleAsynchronousCommand() and handleAsynchronousEvent() method?

[AF]

I think that an ID indicating where the message is intended to go, with 0 or -1 being the engine is necessary. I thought Id already included this in my spec but obviously not.

[zenzike]

Absolutely, a destination ID is necessary, since the AI needs to forward the message to the right team. I've actually nearly finished implementing the interface we've been discussing and have made a wrapper that makes the old AIs work with the new interface.

As for your asynchronous ideas, everything should be done through the same handleEvent method; this includes AI/AI communication.

Finally, I think there's a strong case for having separate Init, Update, Load and Save functions that are not part of handleEvent. I'll justify this when I've finished the first version: probably tomorrow evening. The reason is that in terms of implementation it's much more sensible. I'll show you with examples, though in a bit of a rush right now.

[hoijui]

wow!
good i did not start it at the same time. the Id we are talking about is the indicator for where the event came from, not where it has to go to. so when an AI receives an event, it knows who sent it.

am eager to see your work

[Agon]

Absolutely, a destination ID is necessary, since the AI needs to forward the message to the right team. I've actually nearly finished implementing the interface we've been discussing and have made a wrapper that makes the old AIs work with the new interface.

As for your asynchronous ideas, everything should be done through the same handleEvent method; this includes AI/AI communication.

Finally, I think there's a strong case for having separate Init, Update, Load and Save functions that are not part of handleEvent. I'll justify this when I've finished the first version: probably tomorrow evening. The reason is that in terms of implementation it's much more sensible. I'll show you with examples, though in a bit of a rush right now.

Wow that is amazing, wonderful, if it will work .

So that the interface is in developing, I have a question about the wrapper for Mono (C#)? Is someone planing to make a wrapper for Mono?
Hughperkins seems to me away again. So do I need to do it for myself?
If true, what do I need to learn? C++ or only the Mono part wrapper (C#)?

What about the dll/jar loading code?