diff -Nur -Xfreecivdiff.ignore freeciv-cvs/doc/README.impr-gen freeciv-patched/doc/README.impr-gen --- freeciv-cvs/doc/README.impr-gen 1970-01-01 01:00:00.000000000 +0100 +++ freeciv-patched/doc/README.impr-gen 2003-07-24 17:03:11.000000000 +0100 @@ -0,0 +1,162 @@ +---------------------------------------------------------------------- + Generalised improvements +---------------------------------------------------------------------- + Ben Webb, ben@bellatrix.pcl.ox.ac.uk + +Overview +-------- + Freeciv uses rulesets to configure much of its behaviour (see + README.rulesets). However, what is not immediately apparent is that + the ruleset for city improvements is not as flexible as it would + appear; you cannot change the total number of buildings, for example, + and even if you change the name or stated behaviour of a building, + it will still function as before (for example, the first building + will always act as an Airport, no matter what you do). The minor + differences in building behaviour between CivI and CivII are + accommodated by means of the "variant" option, which again has a + fixed effect in the Freeciv code. + + Generalised improvements aims to eliminate this problem, to allow + modpack and ruleset writers much greater flexibility. A major drive + in the code development was support for alternative Civ-like games + such as Alpha Centauri and Call To Power, which have radically + different sets of buildings and effects. + +Rulesets +-------- + With generalised improvements, you must specify what effect each + building has by filling in the "effect" field. + data/default/buildings.ruleset lists the valid values for this field, + and supplies suitable values for standard Freeciv behaviour, so it + should be straightforward to modify this for your own buildings. There + are, however, a number of caveats: + + - The AI does not yet understand generalised improvements, so will + get very upset if you change things too radically. However, this + will shortly be remedied. + + - Any effect, from any building, can have a "World" range - i.e. it + affects every city and every unit in the game. Players, however, can + usually only see the buildings in their own cities, plus any Wonders, + so World-range effects for ordinary buildings can cause confusion + (since a player won't know _why_ his/her cities are under a particular + effect). It is therefore recommeded that you only use World-range + effects for Wonders. + + - Island-range effects affect every city and unit on the same island as + the building which confers the effect. However, players' ideas of what + constitutes an "island" can differ from the server, since they only + know part of the map (for instance, say you have discovered the southern + tips of two islands, but don't yet know whether they are linked by a + land bridge). This can also cause confusion, and so Island-range effects + are best treated with caution until this difference between client and + server is remedied in Freeciv. + + - Some effects do not have a defined "range" (and the range field will be + ignored even if you supply it). These are Adv_Parasite, Have_Embassies, + Reveal_Cities, Reveal_Map, No_Anarchy, Any_Government and Give_Imm_Adv. + + - Not all effects are currently implemented: + - Enemy_Peaceful, Improve_Rep and May_Declare_War involve diplomacy, + which is not yet fully supported by Freeciv. + - Barb_Attack, Barb_Defend, Slow_Nuke_Winter, Slow_Global_Warm and + Trade_Route_Pct are not yet coded for, but are not used in standard + Freeciv rulesets anyway. + - I'm not sure what Capital_Exists was intended to do... + + - Although effects with the "survives" field set persist even if the Wonder + that originally conferred them is destroyed (e.g. the Apollo or Manhattan + Wonders in the default ruleset) the client may lose track of these effects + if the game is saved and then reloaded. + +Non-building effects +-------------------- + impr-gen effects were originally designed for implementing the behaviour of + city improvements. However, the system has proved flexible enough to be able + to describe the effects of other game entities as well. To date, units, + governments and nations can all use impr-gen effects. It is simple to add + these effects - just add an effects field to the relevant unit, government + or nation in the ruleset, in exactly the same way as it's done in + buildings.ruleset. Note, however, that: + + - "range" has no meaning for effects in units.ruleset. All effects are + assumed to act only on the unit itself. This may be expanded in future. + + - Nation and government effects can only specify the ranges "Player" and + "World". + + - Many effects make little sense in units.ruleset; you are largely + restricted to the various Unit_xxx effects. + +Code +---- + The bulk of the generalised improvements code is located in + common/improvement.c and common/game.c. This takes care of making lists + of all active effects, which can then be iterated over elsewhere in the + code when effects are required. All effects generated by a city's + improvements are stored in pcity->effects, which is a list of eff_city + structures. To save on having to iterate over all cities affected by a + given effect, effects that have Island-, Player-, or World- range are + also copied into lists of eff_global structures (which are derived from + eff_city, with a city ID added) which are stored as + pplayer->island_effects, pplayer->effects, and game.effects + respectively. (For the purpose of considering the "equiv_range" + behaviour of buildings, similar lists of buildings are also + maintained, as pplayer->island_improv, pplayer->improvements, and + game.improvements, respectively.) + + When buildings are built, moved, or destroyed, their effects can also + change. Since buildings can deactivate other buildings (e.g. the Great + Wall wonder renders all City Walls redundant in the default ruleset) + while effects can have dependencies, including depending on other + effects, whenever this occurs all effects are updated by calling + update_all_effects(). Since this scales as O(N**2) with the number + of cities in the game, this function (and all calls to it) are prime + targets for optimisation. The update_all_effects() function marks + buildings as active, obsolete (due to tech advances) or redundant + (replaced by another building, via. equiv_repl/equiv_dupl) and also + marks which effects of the active buildings are themselves active. + Effects that can also dependent on terrain/special type, or other + buildings, must be explicitly tested for activation when they are + used (but the effect iterators - see below - handle this automatically). + + Effects of buildings that do not yet exist (for example, during AI + calculations) will not be activated. Thus, the is_effect_activated, + is_city_affected and is_unit_terrain_affected functions must be + called in this case to ascertain whether an effect is active. (Bear + in mind, however, that this may still be inaccurate, as another + effect may depend on this effect, and so will not be properly + activated without a call to update_all_effects). + + A number of functions and macros are provided for iterating over all + active effects. The eff_iterator_impr_init() function is used for + considering all effects that affect a given building in a given city, + owned by a given player (although arguments can be ommitted, so for + example, it could be used to only look at Player-range effects by + passing a NULL city pointer). The impr_effects_iterate and + city_effects_iterate macros are useful shortcuts for calling these + functions (the city_ variants assume that the player is the owner of + the city, and that no specific building in the city is targetted). + Additional macros ending in _full allow the terrain type of the city + tile to be overridden with passed values, e.g. for considering worked + tiles outside the city centre. eff_iterator_unit_init() considers + effects that influence a unit at given map coordinates, which may or + may not be within a city, and the unit_effects_iterate macro is a + useful shortcut. + + Older Freeciv code simply checked the current city's list of buildings + and the global list of Wonders; for instance, when calculating defence + strength, it simply needed to test if the current city had the City Walls + building, and if the current player owned the Great Wall Wonder. This + is extremely fast when compared to iterating over a list of multiple + effects at several ranges, particularly as many such lookups are typically + performed for each city and unit during the game. Thus, the aim is to + reduce the number of effect iterations as much as possible, storing + intermediate data in various game structures. For instance, the + calculation of city bonuses, happiness, and pollution modifiers is all + rolled into one effect iteration (in common/city.c). + +Credits +------- + - Code: Ben Webb + - Bug fixes and ruleset tweaks: Davide Pagnin diff -Nur -Xfreecivdiff.ignore freeciv-cvs/doc/README.rulesets freeciv-patched/doc/README.rulesets --- freeciv-cvs/doc/README.rulesets 2003-07-10 11:53:38.000000000 +0100 +++ freeciv-patched/doc/README.rulesets 2003-07-24 17:03:11.000000000 +0100 @@ -108,6 +108,10 @@ "TODO Variants" section below for which variant effects which have been implemented so far. +- Please note: the rulesets for buildings (city improvements) are currently + in the process of being generalised. Thus, some or all of the documentation + here will be out of date - see README.impr-gen for more details. + - Units have a new field, "roles", which is like "flags", but determines which units are used in various circumstances of the game (rather than intrinsic properties of the unit).