Clash Coding Standards Discussion

[alms66]

Yes, I have to second that motion!

Point us who are trying to learn OOP to references that can teach us. It would be a good addition to the document, after all Clash is what prompted me to try to learn OOP, though the sources I talked to said C++ was better, so I began to learn that, though you have shown me Java is just as good, if not better F_Smith . I've been programming simple linear stuff for years, in BASIC, and I thought the switch to OOP would be relatively easy, but it's not as easy as I thought.

[F_Smith]

Mark:

I believe that you're using 'Listeners' to record and process the key events, so that is an example of a controller interface class in a classic M-V-C approach.

The Listener does the controlling.


Richard:

Sun's website has a
Object-Oriented Programming Tutorial. This would be a good start. Swing is just a catchy name for a bunch of good screen components Sun wrote. XML is the 'parent' of HTML, the stuff you use to put links on pages.


Toubabo:

Check that link above, and do other searches at the java.sun.com. It's got so much excellent free stuff your head will burst.

But you'll make it -- I started out as a Cobol programmer. I wrote some of the finest procedural code in Java you've ever seen!!!

[F_Smith]

Architecture Approval Request

I want to add the next post in the 'official' architecture thread. This one will be specifically on the 'data model' classes. I will basically just reiterate what I have above --

[*]All game data will be encapsulated in a single 'interface' class that (for now) is called 'GameData'.
[*]The use of observers.
[*]I'll put up a 'template' data classs.[/list]


I'll do this in the morning, unless the gang has any requests/objections.

[F_Smith]

Le Bump.

[puree]

just read this forum, or scanned through it anyway.

smith and i have discussed mvc elsewhere, ( and will continue by e-mail probably).

64k map squares , i havnt had a good chance to look at any code, but how did you arrive at that size !!

[Mark_Everson]

This is a kick-off for a discussion on some general features of our object models. Specifically, how the object models act in terms of customizability and supporting interactions within the game models. There has already been some discussion on this in the tech model, and in other places. My purpose here is for us to arrive at a decision as to our general approach for how to handle these issues.

(No time for extensive proofreading , so I apologize for any 'whoppers' herein. Since I used dictation software, if something bizarre shows up, try words that sound like what is there!)

In terms of object models the question is do we use inheritance to specify for instance each technology, or do we have a more generic technology object that has various fields and generic methods to modify other game objects? I'll give an example to make sure everyone knows what I'm talking about. Generic hardware that has game effects are called applications in the tech model. So for instance Rifles might be an application. Various technologies, like Metallurgy, modify the effectiveness of your civ's rifles. In the basic tech system, all that is modified is the overall effectiveness number. Now let's say the combat model also needs a precise estimate of the range of these rifles, which can change with technologies over time. And just as an example (I know it's not a very good one) let's say that the technology Aerodynamics plays in this. The big question here is how do we get the code to establish the links between the Aerodynamics tech and rifle range, and other similar things, in the "best" way.

The best way should support as well as possible:
1. High-quality, easy to maintain and extend code
2. Flexibility in playtesting (let the play tester change the behavior of the Aerodynamics/rifle range link, or even change the length to another tech, or put in a completely new dependency)
3. Customizability for scenario designers (much of this is automatically achieved if we can do 2.)

I'm aware of two basic ways to do these good things, and there are trade-offs involved depending on which one we choose to use. The first type is using inheritance explicitly to define each thing of interest as its own type of object. So there would specifically be an Aerodynamics class that extends from Technology with possible intermediate levels of inheritance. On the rifles side we would likely have something like Rifle extends RangedWeapons extends Weapons extends Tools extends Applications or some such. This approach affords an Enormous amount of flexibility, and it's the one F. Smith was pushing for in the quoted section below. I favor a more abstract approach that I will go over below the extensive quotes. This would have those links put in by means of initialization files, and would stop the inheritance tree a bit earlier. For instance, they would be no explicit Rifle class, just an instance of RangedWeapons with a type specifier "rifle" and supporting code for the specific links. Of course, we can (and probably will) use one way for some parts of the game, and another way for different parts.

To present F. Smith's position, at least as of earlier this year, I'm going to use a series of quotes that F. Smith made in the Technology System Version 5.1 Technology System Version 5.1 thread on page 3. If you want to look at them in context they were posted on or around March 13 2000. I apologize a bit for the choppiness of these, since I just grab them straight out of context. If there's a reference you don't understand in them, just ignore it, because I'm just using these posts as a general statement of some of the issues.

quote: One big question: So ya'll have decided to use encapsulation instead of an object inheritance hierarchy, it seems? One basic 'tech' object, with properties that can be set? This choice carries serious costs, as I'm sure ya'll know. Have those choices been discussed yet? Specifically, this means that the techs can not be too involved, in terms of how they interact with other models. Gains in flexibility have a cost. The other choice is to 'inherit'. It would be somewhat less simple to create custom techs 'on the fly', but the techs would be much, much more powerful and unique. It looks like Lordy has chosen 'inheritance' for the 'Wonder' model. Was a flexible system the prime directive? Or was power and uniqueness the goal? How often will custom techs be created? Should creating them be the focus of the model? Just asking . . . More detail: With this approach, would a tech be able to modify another object (wonder, unit, resource)? For example, can a tech decrease wonder build time? Or could a tech increase the speed/power/armor of a single, specific unit? Or could a tech increase the processing speed of grain (not all food, just grain)? Would a tech be able to increase the speed of aircraft? The range of a single weapon-type? With an object hierarchy, you have that power, that uniqueness, that customizability of behavior. That is usually what you give up when you use encapsulation. Encapsulation is usually used when you will change something often, on the fly, like in the middle of a game. And it doesn't seem like you will be doing that. Does this 'model' allow for those kinds of tech, in some way I missed? Is this really the correct design choice, in this instance? Actually, the reason I'm going on and on about OOA for the tech system is that this is not going to be powerful, as it currently stands. They have already made that design choice. There is no object hierarchy for tech objects. All tech objects will use a single method to apply their bonuses. Which means two things: 1. That method will have a switch statement with 100+ parts, and associated methods -- one for each tech (a coding nightmare!!!). 2. All tech objects will have to behave in a basically similar way. The problem is no one has yet done the basic analysis you're going thru for the wonder model. No one has identified the behaviors of a tech object. So now, all the tech objects will have to behave basically the same. Instead of each tech being it's own object, and behaving in a unique way, you have one object to represent all techs. Using an object approach, you can just have the 'applyTechBonus()' method take an 'object' parameter. And that parameter can be anything. So that tech can change anything in that object. Pass in a Wonder object, and you can modify anything in that wonder with that tech. Same with units -- individual or type. Or resource, or civ, or mapsquare, and on, and on. Any object. Any modification in that object. This is what you give up when you choose not to use an object hierarchy. They can try and simulate this behavior with a switch statement, but with so many different cases that will be almost totally impossible, for a half-dozen reasons. And it means you have to re-code the basic tech object for every new tech 'type'. And if whoever does that modification makes a mistake, it can bring down the whole tech system. And that's why I'm on about doing some OOA on this tech system before they get started coding!!! and the drum beats on . . .

Before I talk about the way I envision the alternative F. Smith didn't like above, I need to state some caveats. First, I haven't double checked with F. Smith that this is still the kind of thing he thinks is the right way to go. But at any rate, what he says above states one side of the discussion reasonably well. Soon we will know for sure what he thinks (right F. Smith?) The second warning here is that F. Smith is much more experienced with this stuff than I, so my approach may have some big holes in that I'm not aware of!

There are many places in the game where connections between models will be needed. For instance, the economics model has sectors of the economy (five right now) and infrastructure classes (perhaps 20-30). In the technology area, there will probably be several hundred objects between technologies and applications. Other models have further requirements, and I don't want to get into the details here. It is my contention that while using inheritance for things like rifles, giving a Rifle class, might be practical for the economy where there are only a handful of potential classes, putting in several hundred individual classes for technologies and applications is different. It seems to me to be More error prone than handling things in an automated fashion using less inheritance based on an initialization file as I outline below. So what I am trying to reach understanding on here is why my approach isn't better in All the areas 1-3 above and the approach presented by F. Smith. So tell me .

So here is my presentation of how it should work...
We have a RangedWeapon class, that covers everything from bows to bazookas (these are meant to be hand-held ranged weapons). Each instance of the RangedWeapon class has a designation "rifle", a bunch of information on the characteristics of rifles (range, lethality, etc.) and some objects whose purpose is to handle connections like that between Aerodynamics and rifle range. The purpose of these objects is to identify the connection between Aerodynamics and the range characteristic of rifles, and to support updates and modifications of rifle range when Aerodynamics tech changes. Note that the object that I'm talking about here is a generic rifle, not the rifles that are used by any specific civ. Here is a crude example of the initialization file line from which this information would come:

"Tech" 'Aerodynamics' Affects "RangedWeapon" 'Rifle', *range* (then some parameters describing the mathematics of the exact effect, TBD)

In this expression "" means that the name represents a Java class, ' ' represents a string that is the name of an instance of that class, and * * represents a parameter of that instance. It would be more readable in XML, but I think you can get the idea from this. This expression, after being properly parsed is put into an object recognizing this link. The aerodynamics instance of Tech will have a copy of this object, and the Rifle instance will have another. Updating the effects can be done using an Observer/Observable mechanism. I have left out the necessary step of having a specific aerodynamics-related object for my particular civ as opposed to the one that just says how aerodynamics works in the game in general. That could be done in a couple of different ways, but seeing as I have company coming, I will just go ahead and post this, and see where the discussion goes.

[Lord God Jinnai]

Mark:

Well, w/o hearing F_Smith's remarks, i'm more inclined with your view, with the understanding as follows for the tech model:

If there were a ranged weapons class, it would haveto be subdivided into hand-held and artillery ranged because these are so vastly differnt from each other that they cannot be the same. FE you could use cannons and crossbows in a battle if your hand-held weapons tech wasn't up to par (maybe because of size reduction problems or economic problems).

Ranged weapons could also come under a broader category also too.

There is only 1 other problem with your model and that is in reguards to mantainance and upgrading. Right now to make it more realistic a civ or whatnot's ability to upgrade and/or mantain their current level or equipment is factored in (as well as the social parameters for change in upgrading to new equipment). These are there for the reason that a country might continue to upgrade its crossbow technology evem if its more expensive because of social preasure for nonchange and lack of enemies, esp with superior tech. to spur radically new items which require new thought and in some cases can lead to the downfall of the status quo.

Again this argument may be mute depending on what F_Smith says and perhaps if i misjudged it also.

[F_Smith]

Hi, Guys:

Me again!

First, I agree with Mark about using packages, altho I think we should name them a little differently.

Can I suggest

clash.view (for GUI stuff)
clash.data (for all data objects)
clash.controller (for all 'turnhandler' and 'fileIO' code)

This is what will help coders the most.

If sub-packages are needed, then no problem -- clash.data.civ, etc.

But can I suggest using the data/view/controller paradigm as the first package level?

[Mark_Everson]

Sounds like a plan

Even a good one...

[F_Smith]

Now, regarding the tech architecture:

First, Mark's approach will work. That is the basic 'wargame' type approach that is used in most other games -- and it's fine.

But we can go deeper, providing more realism, if we want. We can break these objects up by their functional differences. One excellent example is in 'Sid Meirs Alpha Centauri', if any of you play that. You can mix and match chassis, bodies, weapons, armor and special abilities to custom-make units. That is the approach I am after here.

I would like a class 'RangeWeapon', then a class 'Rifle' extends 'RangeWeapon' and implements a 'HandHeldWeapon' interface. Off the top of my head, I can think of at least a few subclasses of 'RangeWeapon' that should have very different capabilities -- 'Bow', 'Crossbow', 'Rifle', 'Laser', 'Plasma', 'Mortar', etc. There are probably others.

This allows different types of behavior for each weapon type -- the 'train' method could vary. The 'breakdown' method has to vary, I think (bows don't explode accidentally, for example). The 'maintainance' methods have to vary (when you repair bows, the method should require wood, when you repair a modern rifle, you need spare parts).

All ranged weapons would require a subclass of an 'Ammunition' object to be effective, so different types of ammo are available (arrow, ball, bullet, explosive, laser battery, etc). Better ammo can be invented/created, and given to existing weapons (selectively, if it's expensive). Bayonets can be fitted onto rifles, but not bows. Iron arrow heads can be used where you have access to iron.

And this is just for rifles. Every tech type can gain added capability and realism with an object hierarchy.

Again -- Mark's idea is still a good one. It works fine. This added realism is likely going to bore 80% of our players, who will never use the depth. I've been playing Alpha Centauri for about 6 months, and I just started building custom units!

Comments?

[Mark_Everson]

I expect a compromise would work best for the project overall.

For short term stuff this is pretty much irrelevant since we will just throw things together.

I think in the middle term, when things are being actively tweaked in the military model, the way I proposed will allow faster progress. (Because a non-coder can put in whole new weapons by hand, etc.) We can implement most everything you (F_Smith) said above using my approach IMO. BTW I guess I should have called my example RangedHandWeapon since it wasn't meant to cover artillery etc.

In the long run I wouldn't object to some selected 'specialty' classes for things that really can't be handled well at the RangedHandWeapon level. We could have special tweaks based on inheriting from RangedHandWeapon and maybe an interface as you suggest. I do think that the detailed classes going down an extra level in inheritance should be the exception rather than the rule. The AI will Never be able to handle all those little nuances anyway, so the more detail tweaks, the more imbalanced will be the game IMO.

Also, I think having literally a hundred or so classes just for weapons, and another several hundred for techs is Waaaaay overboard. And most of the things that were suggested for the detailed class proposal frankly strike me as something only a few percent of the players would even care about. Who wants their empire to fall because the right ammunition wasn't available??? We would Lose, not attract, players over that one! Remember, this is a Strategic game, not Squad Leader .

So, do we have a deal? My approach in general, but the freedom to push the envelope in important cases. And for your personal version of the game you can do whatever you want!

[Mark_Everson]

Coders:

I think we need a logical package structure for the code. Things are already getting complicated in the new architecture, and IMO there's no time like the present to put in a logical package structure. I think the best would be along model lines since the names already help along MVC lines. What we used on the old code was packages of the type:

clash.util
clash.gui
clash.map
clash.civ
clash.econ
clash.ai

It really helps when you're looking for a class that you don't know the name of... I also think the lack of package structure will scare off some potential coders. What say you F_Smith, and others?

LGJ:

That's really a model issue rather than a coding issue per se. Why don't you put your comments in the tech model area, and we'll see how important people think is the effect you're talking about.

[F_Smith]

Absolutely, we can work from the general to the specific (if I understand correctly). We can begin with generic 'weapons' classes, and then add in specific subclasses if and when we have time.

I agree that by far most players will never want to go to that level of detail, at least at first. Altho what I find happens with my favorite games is that the complexity adds to the length of time it holds my interest. After I learn all about the basic game, and have played it a few dozen times, I lose interest unless there are new things for me to find.

Please forgive me for thinking that once you see the flexibility and power that the subclasses can give us, and how much easier it will be to code using the object hierarchy, you might end up on this side of the fence. Especially when it comes to coding up techs.

Because I'd like to point out that weapons are not the best example of a specific tech application for this discussion. The differences between a bow and a rifle, while significant, are minor compared to the differences in many other techs. I don't see a 'TransportationUnit' class being able to cover planes, trains and autos, for example.

But, as you said, we can make those determinations later.

One question, tho -- we do still need an 'Ammunition' class, don't we? So arrows aren't used to resupply M-16's?

[F_Smith]

P.S. -- Actually, I think what we're building is a game engine that is going to be both a grand strategy game *and* Squad Leader!

I hope when we're done with it, it can be used to play any level of detail.

[Mark_Everson]

We will work it out, and if you convince me, more power to you!

Ammunition: I don't think individual ammo types is a good idea at all. At least my take was if a unit is in supply and enough manufactured goods get to it, then its assumed it is supplied with ammo of whatever type it needs. Otherwise you get into a micromanagement nightmare IMO. So it is assumed that the medieval society produces arrows, and the modern one produces cartridges and whatever else is necessary. Only if a unit is cut off do we dock its effectiveness due to lack of ammo. For slingers the penalty would be slight, for modern units it could get quite severe if the out-of-supply lasts too long.

I am going to cross-post this in the mil thread since the discussion is pertinent there too.