[Freeciv] Re: A call out to all you documenters out there

[Kenn Munro <kenn@xxxxxxxxxxxxxx>]

I've updated sections 4.0, 4.1 and 4.2 in the Freeciv Game User's Guide
(see attached files).

Main changes are:
* rapture size changed from 5 to 3 in the Population section
* added part of the README.cma to the "Working the Land and the Ocean"
section

Kenn

On Wed, 2002-05-15 at 14:20, Mike Kaufman wrote:
> 
> As many of you know, we all swiftly approaching a new release, and
> with a new release comes new people into the community who have never used
> freeciv (or even played payciv) before. 
> 
> Unfortunately our user guide for the client is horribly out-of-date.
> see http://www.freeciv.org/manual/client.html for the bad news.
> 
> I would like to get some volunteers from the community to update the guide.
> I need volunteers to create some screenshots of the various dialogs
> of win32 and gtk1.2.
> I need volunteers to contribute some text to explain how to do various
> things (e.g. how to operate the map in the city dialog).
> 
> There also needs to be updates to the graphics in the manual
> http://www.freeciv.org/manual/game-*.html
> (Daniel Speyer: perhaps you could do this?)
> 
> Again, volunteering does _not_ make you responsible for the entire
> documentation project. If you want to contribute just the intro, or just an
> explanation of the create nation dialog, or how to do diplomacy, please
> reply to this thread. (I would also like someone to volunteer to take over
> this thread and post revisions of the guide to the ftp site when updates
> of individual sections are posted). I'll attempt to keep the webmasters on
> board so that when major sections are considered complete, they are put up
> on the website without delay.
> 
> If somebody doesn't beat me to it, I'll post the gtk screenshots to the ftp
> site this weekend to get the ball rolling, (but please, somebody beat me to
> it :)
> 
> Here is a chance for the non-coders to get involved in a critical aspect of
> freeciv.
> 
> -mike
> 
> 



-- HTML Attachment decoded to text by Ecartis --
-- File: game-12.html

 The Freeciv Game User's Guide

Previous[1] Next[2] Contents[3] 
----------------------------------------------------------------------------
4.0 Cities 

The cities of your race are key to your civilization. Indeed, the very root
of our English word "civilization" is the Latin word for "city." Your cities
are where your citizens ("city people") live, work, produce, trade, and
support your nation. Cities contain buildings which improve the city's
productivity and morale, and produce mobile units to project your influence
across the globe. 4.1 Population 

The size of a city is measured in units called citizens. A city's size is
visible as a number of the main map, and as a series of citizen icons in the
city window. When you create a city with a Settler or Engineer, or discover
one from a Village, it consists of one citizen. As the city grows (that is,
as the number of citizens increases), more of the land around the city can
beworked, and more special talents may be employed. 

Each citizen requires two food units per turn to survive; in addition,
Settler and Engineer units supported by the city consume either one or two
food units, depending on your government. Each turn, the city produces food
from its surrounding land. Any amount of food in excess of that needed for
immediate consumption is added to the city's food storage (called the
"granary" in the window, whether or not the city has a Granary building).
When the amount of stored food reaches the size of the food storage, a new
citizen is created, and the food storage is emptied (or, if the city has a
Granary, it is reduced to half full). If not enough food is produced in a
turn to meet demand, the required food is removed from the food storage; if
the store is empty, Settlers, Engineers, or at last resort a citizen are
eliminated by starvation. 

The citizens of a city may be either workers or specialists. Workers work
theland around the city, producing food, production, and trade, as described
in Working the Land and the Ocean[4]. Specialists are citizens who are in
thecity but not working the land. You designate citizens as specialists by
moving them off of the map window (see next section); you assign them into
one of three specializations: 
  * Entertainers improve the morale of your city. One entertainer adds two
luxury points to the city; for the utility of luxury points, see below. 
    * Taxmen improve the gold tax production of your city. One taxman adds
three tax points to the city's output. Taxmen may only be created in cities
of at least size five. 
    * Scientists improve the research output of your city. One scientist
addsthree research points to the city's output. Scientists may only be
created in cities of at least size 5. 


Each worker citizen is in one of three states of morale: happy, content, and
unhappy; the citizen icons in the city window are different for each state.
If, at the time of the turn update, the number of unhappy citizens in a city
exceeds the number of happy citizens, the city falls into disorder. Cities
indisorder produce neither production points nor trade, and are more likely
to revolt if prompted by enemy Diplomats and Spies. Prolonged disorder under
Democracy can lead to a national revolution; see Democracy[5]. 

If the number of happy citizens is at least as great as the number of
contentcitizens, and there are no unhappy citizens, and the city is of at
least size 3, the city achieves "rapture." Under the Republic or Democracy,
araptured city increases its population by one each turn as long as there is
sufficient food and the criteria for rapture continue. 

The normal state of a citizen is contentment. However, as your cities grow
larger, crowding causes citizens to become unhappy. By default, each citizen
in a city beyond the fourth will be generated unhappy instead of content
(server option "unhappysize" controls this). If you have a large number of
cities (depending on your government, and controlled by server option
"cityfactor"), the limit on content citizens is reduced to 3. Under certain
forms of government, the presence of military units in or away from a city
can either create contentment or unhappiness (see Government Types[6]). 

In order to offset unhappiness, you may build buildings (Temple, Colosseum,
Cathedral), Wonders of the World (Michaelangelo's Chapel), more make
entertainers, or produce more luxuries by setting your national luxury rate.
For every 2 points of luxuries produced in a city, one content citizen there
is made happy, or (if there are no content citizens) one unhappy citizen is
made content. 

Large cities, especially in the age of the internal combustion engine,
produce pollution. Every turn the pollution of each city is evaluated. There
are two sorts of pollution, industrial and population. Industrial pollution
is measured by the production points generated by the city, including all
improvements such as Factory, possibly reduced by a Recycling Center, Hydro
Plant, etc. Population is measured by the city size, scaled up in the
presence of Industrialization, Automobile, Mass Production, or Plastics, or
eliminated by a Mass Transit system. If the sum of these two types of
pollution exceeds 20, that excess is the percentage chance of pollution
appearing in a square in the area of a city. This pollution percentage is
shown in the city window. 

If a city square becomes polluted, it is marked with a special symbol.
Polluted squares yield half the food, production points, and trade points.
This will continue to be in effect until the pollution is cleaned up by a
Settler or Engineer. Further, every turn in which there are polluted squares
anywhere in the world increases the chance of global warming. 

Global warming is a catastrophic event that models a sudden increase in the
size of the oceans as polar icecaps melt. Some number of randomly selected
land squares are changed: Coastal Forests become Jungles, coastal Deserts,
Plains, and Grasslands become Swamps. Inland Plains, Grassland, and Forest
squares become Deserts. An onset of global warming "resets the count" of
global pollution, so future pollution contributes to another possible wave
ofglobal warming. 
----------------------------------------------------------------------------
Previous[7] Next[8] Contents[9] 

--- Links ---
   1 game-11.html
   2 game-13.html
   3 game.html
   4 game-13.html
   5 game-11.html#democracy
   6 game-11.html
   7 game-11.html
   8 game-13.html
   9 game.html

-- HTML Attachment decoded to text by Ecartis --
-- File: game-13.html

 The Freeciv Game User's Guide

Previous[1] Next[2] Contents[3] 
----------------------------------------------------------------------------
4.2 Working the Land and the Ocean 

A city's area of influence measures 21 squares, a large square of five by
five squares centered on the city, excluding the corner squares. The city
maywork no squares beyond those, and a single square may be worked by only
one city. In the city window's map, squares being worked by other cities
(either your nation or another), or occupied by enemy units, are marked in
red, and you may not place workers there. You work squares by allocating
citizens to them. 

The square in the center, where your city resides, is automatically worked
toproduce food, production, and trade, without the allocation of citizens to
work it. A city's center is considered irrigated for this purpose but not
mined; further irrigation has no effect. A city has roads (and railroads,
when you have such knowledge) automatically, and always yields at least one
production point, even if the terrain does not allow it. 

The Freeciv server has algorithms that determine an optimal utilization of
the squares around a city; those algorithms are used by the AI players.
Newlycreated citizens are automatically assigned to squares by those
algorithms, which generally favor maximum food production. You may have
othercriteria for your city, and may wish to reassign workers to other
tasks.For instance, you may be aware that the city will have morale problems
if it grows too quickly, and may wish to move workers from growing food to
extracting ore. 

Clicking on a worked square in the city map window will remove that citizen
from the land, and make him/her an entertainer (the initial, default
specialist type). Clicking on an unused map square places an available
citizen to work there, and updates the map to show what yield is expected in
food, production, and trade points. You may have to try a number of
differentsquares to decide on the best placement of your citizens. Clicking
on the center map square will assign the citizens to the optimal utilization
as determined by the server. 

A new feature in version 1.12.1 is the City Management Agent (CMA). The
heartof CMA is an optimizing algorithm, that tries to deploy the workers of
acity in such a way that a user-defined goal is achieved as much as
possible.The new CMA goes far beyond the old form of optimizing. First, it
performs this task everytime anything changes with the city. If the city
grows or shrinks, troops go in or out, tiles get irrigation or mining, or
areoccupied by an enemy, the CMA becomes active. Second, it supports all
kinds of optimizing, like production (shields), gold, science, or luxury.
Third, it gives the player a fine-grained control over this, with the
possibility of setting constraints for any kind of city output. The latter
includes the constraint of celebration, which makes it very easy to let your
cities grow, even in harder times. The forth, and probably most valuable
thing in war times, is that is keeps your cities content, preventing them
from revolt. 

You can set up the CMA for a city by opening the city window and clicking on
the CMA tab. On the left side, you can choose a preset for a specified goal,
on the right side you can specify more complex goals by moving the sliders.
You can choose a preset at first, and then modify it. Once you have created
anew setting, you can add a preset name for it. This is not required, but
very useful, since you can watch and even change the city's setting from
within the city report, if it is given a name. Don't forget to save settings
(in the Game menu), when you've created new presets. 

The sliders are of two kinds: the rightmost sliders are factors, which
gaugeshow much one product is worth compared to the others (e.g how much
shields are worth with respect to everything else). The leftmost sliders are
constraints: you can command the city not to lose food, e.g. by setting the
surplus constraint to zero; and you can allow the city to lose gold by
setting the gold surplus to -3 e.g., and urge them to make at least 5
shieldsper round by setting the production surplus to 5. The most powerful
constraint, though, is the Celebrate contraint, which makes the city
celebrate at once (which usually takes effect the round after you change
it).

It is obvious that the CMA can't fulfill all these constraints in every
case.Whenever the constraints can't be fulfilled, the CMA quits its service
for that city, giving a message: "The agent can't fulfill the requirements
for Berlin. Passing back control." You then have the choice of either
managing the city on your own (which has some drawbacks), or open that city
and change the surplus requirements so that they can be fulfilled. 

When you have made a setup for a city, you need to click on "Control city"
toswitch on the CMA. If this button's text is greyed, either the CMA is
already active, or the task is impossible. In the latter case you see dashes
instead of numbers in the results block. If you ever want to switch off the
CMA deliberately, click "Release city". 
----------------------------------------------------------------------------
Previous[4] Next[5] Contents[6] 

--- Links ---
   1 game-12.html
   2 game-14.html
   3 game.html
   4 game-12.html
   5 game-14.html
   6 game.html