[Freeciv-Dev] (PR#12869) the happiness system

["Benoit Hudson" <bh@xxxxxxxxxxxxxxxxxxx>]

<URL: http://bugs.freeciv.org/Ticket/Display.html?id=12869 >

In PR#9480, Jason said:
> In general, I don't fully understand how happiness, celebration,              
>   
> unhappiness, and disorder work.  I know I've said this before, but: is        
>   
> there some documentation on this that anyone can point me to?

I don't know of any, but attached is a document.  Note the TODO:
I don't understand angry citizens.

At base, a city of size n has a certain number of citizens that are
content.  In the default ruleset, that's 4 with a small civ, and fewer as
the civ grows. The rest of the citizens start off unhappy.

Then we have a series of priority levels:
0- base
1- luxuries
2- buildings and some wonders
3- units
4- Bach wonder

Each level above 0 does some of three things:
- make citizens content [temple, martial law]
- make citizens happy   [luxuries, democracy+courthouse in original civ2]
- make citizens unhappy [democracy+bombers]

The rule is:
- first make citizens content
- then make citizens happy

Turns out we never make citizens unhappy at the same time as we make them
content or happy, so that order is undefined.  I'm not sure how we ever get
angry citizens.

'make content' operates first on angry citizens then on unhappy ones.
        It has no effect on content or happy citizens.
'make happy' operates first on content citizens, then unhappy, then angry.
'make unhappy' operates first on content citizens, then unhappy.

Moving a citizen up one level takes one unit of work.  For example, two
luxuries are one unit of make-happy work; one temple+mysticism is two units
of make-content work.  So if you have a temple and nothing else in a city
that has an angry citizen, the angry citizen becomes content.

Example:
Assume we have a city of size 7 with 8 luxuries, a temple, and a cathedral
in a medium-sized democracy (so base of 3 content) with 3 units in the
field and JS Bach's cathedral.  We know mysticism and theology.
We start with:
0:      0/3/4/0   happy/content/unhappy/angry
Level 1 applies the 8 luxuries, which are 4 make-happy work:
1:      3/1/3/0   [3 content became happy, 1 unhappy became content]
Level 2 applies the cathedral (4) and the temple (2) for 6 make-content:
2:      3/4/0/0   [3 unhappy became content, 3 units of work wasted]
Level 3 applies the 3 units, which are 6 make-unhappy work:
3:      2/0/6/0   [4 content became unhappy, 1 happy became unhappy]
Level 4 applies the JS Bach, which is 2 make-content work:
4:      2/2/4/0   [2 unhappy became content]


TODO: explain angry citizens and give an example with both make-happy and
make-content in the same step.