Usage notes

Executables

// SWServer

SWServer -- persistance:

SWServer writes SWServerModel to file
SWServer reads SWServerModel from file

SWServer -- I/O:

SWServer reads SWCommand from file
SWServer writes SWReport to file

// SWClient

SWClient is the app that the player uses to explore the game world (as accessible to him through "reports"), and to create "orders that are issued to her troops.

The SWClient is very 'thin' in capability. Most functionality is aquired by ".helper" bundles.

SWServer -- persistance:

The SWClient actually does not have any persistance features. All persistance is handled by the server. Changes to a report has absolutely no impact on the game.

SWClient -- I/O:

SWClient reads SWReport from file
SWClient writes SWCommand to file

Top level Models

// SWServerModel

SWServerModel provides a means of saving and loading the entire game, not just a single player's turn. It is for the use of the SWServer.

SWServerModel must have:

• an array of SWPlayers
• current turn indicator
• time limit for turns -- ideally adjustable by players
• time last turn was played
• SWBoard -- which will contain units and hexes

// SWClientModel

Owned by SWClient -- seperates GUI code from the Model

SWServerModel must have:

• an array of open reports (selected by the user)
• one active report (can by nil if no reports are loaded)

Lower level Models

// SWHex

SWHex must have:

• height
• location
  
• terrain
  
• contents (any units in it)

// SWUnit

SWUnit must have:

• a unique ID -- this is to distinguish on unit from all other units it does not need to be shown to the player, but it will be used in report and command files
• command queue (*not* same as SWCommand)
  
• component technologies:
  this must include at the very least a "chassis" technology.

// SWPlayer

SWPlayer must have:

• email address
• list of all owned units
• social choices (e.g. research goals)
• list of resources (and quantities)
• list of known hexes
• diplomat object (like a mailbox for incoming diplomacy offers)

File handling Objects

// Reports

A report includes all the information a player is allowed to know in clear text. It is an XML formatted file. A DTD will be made available when it is finalized.

Reports include an expiration date determined by the Server after which a command file based on this report will not be accepted -- a new command file will need to be generated, based on a current report. The purpose of the "freshness date" is, amongst other things, to prevent a player from sending commands to her troops without basing them on her units' current location/health/etc.

SWReport is an object that is initialized from a ".swreport" XML file. SWReport parses the file and returns useful game components upon demand.

// Commands

Commands are created by the player through the SWClient. They are formatted into an XML file and sent to the server where they are issued to the units and executed.

Etc.

// ".helper" bundles

.helper bundles are loaded by the SWClient to give the player

Some Helpers might write SWReport to file (e.g. send edited maps to other players)

// ".content" bundle

A .content bundle has:

• unique name - e.g. "BuckRodgers"
• version string - e.g. "version 1.2"
• additional bundle dependencies
  this is to allow "cascading" bundles -- the idea is to allow for one bundle that has certain features and allow ".content" bundle developers to build off of that (so there is only one "Forest" terrain, but a second bundle could require the bundle which includes "Forest" and add resources that could be harvested from a Forested hex.
• list of terrains
• list of technologies
• list of resources
• list of research areas

// Terrain

A terrain is a property that a hex can have. A hex can only have one terrain at a time. It is possible that a player could aquire technology which enables them to convert a hex from one terrain to another.

Terrains have:

• names (internationalized strings)
• This is used for display to the player
• unique ID -- if we have multiple names for something we need an unambiguos way of referring to an item in a bundle -- this could be something like "BuckRodgers-MudPits" the idea is to make sure there isn't a name clash if another bundle creates a similarly named Terrain, and allow for internationalized name strings
• terrain textures (image file)
• (default color for use when image file can't be shown?)

// Technology

A technology is an object that can be used to equip an SWUnit. There are 4 basic categories of technology:

1. Chassis -- only one per unit.
   Chassis would determine mobility and the ability to "carry" other technologies (meaning a person on foot can only carry so much stuff, if he was driving a truck he could mount a big weapon on the back and lead plate it -- which might make it as slow as a person walking, but that is the choice a player would have to make). Examples would be:
   - Immobile -- used for buildings
   - Horse
   - Bicycle
   - Giant Eagle
   - Etc.
2. Weapon -- 0 or more per unit.
   Weapon could be an optional technology so that some units would have no offensive capacity (and use that carrying capacity for something else (extra armor, or some special technology (something to increase vision?). A player might even choose to forgo the weapon for no other reason than to make the unit cheaper and faster.
3. Armor -- 0 or more per unit.
   Another optional technology, although this would place the unit at risk of being captured.
4. Special -- 0 or more per unit.
   This should be a very popular category :) It would include Espianage equipment, or "Sheilds" (see discussion on list), etc. etc. etc. Note that heroes can be implemented using "Special" technologies. Just make sure that the technology creation conditions (see below) will permit only one instance of the hero to exist per game.
   Example: a bundle named "BuckRodgers.content" is loaded; it contains a technology called "Jet Pack" in English. A player in the game, who had the requisite knowledge (research) and resources (it is also possible for the technology to require that it be created *in* a particular terrain, or by a unit equipped with a particular technology), can create a new unit with the "Jet Pack" chassis.

Technologies have:

• names (internationalized strings)
• unique ID -- as per Terrain above)
• tech image file
• possibly a model and texure -- details to follow
• category (chassis, weapon, armor, or special).
• "weight" -- or mass
  only for technologies of categories weapon, armor, and special. This is a number used to determine if the chassis can support it and what effect it might have on speed

Chassis technologies would have additional things:

• max weight
• max speed
• perhaps this is the 3D model used to represent a unit in an OpenGL view?
• creation conditions
  what conditions must be met in the hex that the "manufacturing" of the technology is taking place? Is there a Shaman present? Are we in a swamp? Does the player have "Woodcraft"? etc. etc. etc. This will be a bit of code, not simply a line in a plist file.

// Resource

A resource is kind of an abstract thing that an SWPlayer object can have. It is not represented by a unit on the board. ".content" bundles are free to create their own resources, as well as the rules for their extraction, which typically requires some combination of terrain and technology (which implies some kind of research).

Resources are consumable, meaning they can go down as well as up.

examples:

• a player might use up all their "Wood" resource building a raft.
• workers might consume a "Food" resource. If the owning SWPlayer does not have enough "Food" to feed a worker it will die.

Resources can be traded using diplomacy.

Technologies have:

• names (internationalized strings)
• unique ID -- as per Terrain above
• resource image file
• creation conditions -- as per Technology above

// Research

This is the knowledge base an SWPlayer has, or the required knowledge an SWPlayer would need to have in order to produce/use some technology.

.content bundles define areas of research.

An area is researched by consuming resources. This might be "Research Points" or it might be something special defined by the bundle, such as "Mana", or some combination of resources ("Research Points" + "Electricity"). A bundle might also define prerequisites for starting research in an area, typically having acheived a minimum value in another area of study.

Each area of study has a rating from 0 to 100. After a certain level of researching in an area additional research may be possible, but would not enable additional technologies (only improve the technologies already enabled).