This file contains various advanced hints and documentation for developers. A section may assume that its readers already has some familiarity with its subject. Don't expect to be able to understand everything here even after reading the friendlier documentation.
Freeciv-web uses a patched version of Freeciv's master branch. This makes it easier to get Freeciv-web related changes into Freeciv. It also makes it easier for Freeciv-web to take advantage of the newest Freeciv features.
Graphics, static help texts, rulesets and scenarios are extracted from Freeciv. Parts of The Freeciv-web client's Freeciv protocol support is auto generated from Freeciv's common/networking/packets.def.
The Freeciv server is responsible for running the game. It makes sure that the rules are followed. It handles the player's orders. It "rolls the dice" when randomness is involved. It keeps track of the game state and what the player is allowed to see.
The Freeciv server has other responsibilities too. It creates, starts and manages the AI players. It is responsible for the beginning of saving and the end of loading a game.
Freeciv-web uses the Freeciv AI. Most of it lives in the ai folder of Freeciv. More information about the Freeciv AI can be found at the Freeciv wiki. Freeciv has AI related introduction tasks.
Activation of LongTurn games is handled by adding the server commands files: publite2/pubscript_longturn_*.serv
A collection of rules for Freeciv is called a ruleset. Freeciv-web doesn't support all the rules regular Freeciv can support. Rulesets with unsupported rules don't work properly with Freeciv-web.
The rulesets Freeciv-web currently uses comes bundled with Freeciv.
Freeciv-web's Freeciv version is set in freeciv/version.txt. The variable FCREV is set to the Git revision it should use. The latest version of Freeciv's master branch can be found in the Freeciv Git repository.
It is easy to break Freeciv-web by changing its Freeciv version. The difference between the two versions should therefore be carefully checked.
The new Freeciv version could have new bugs.
Freeciv-web patches may have been accepted.
Be careful when Freeciv changes
bootstrap/freeciv.project configure.ac m4/ data/ common/networking/dataio_json.* common/networking/packets.def fc_version server/save*
Was a patch accepted into the new Freeciv version? Remove the patch file. Update apply_patches.sh.
Check: Freeciv's bug tracker
Was (known) bugs introduced? Have a look at fixed bugs too if you upgrade to a version that isn't the most recent.
Does the project definition need an update?
Should the arguments prepare_freeciv.sh uses when it calls autogen.sh be updated?
Did helpdata_gen.py successfully extract the new version?
Has the bundled scenarios changed? Does the change conflict with Freeciv-web's modifications?
Was the ruleset format changed? Did the civciv3 rules change? Is Freeciv-web able to handle the modifications? Be aware that the client may have hard coded the old rule. (The classic ruleset and the webperimental ruleset are supposed to be web-compatible)
Was the tileset format changed? Does img-extract.py need an update?
Was any tag removed from a tileset? Does Freeciv-web use it?
Has there been changes to save game handling? Is there development version save game compatibility for format changes?
Did a packet change? Does Freeciv-web send it? Should the sender change?
Does the server send it? Is it handled in packhand.js? Who uses the packet after it is handled?
Does this change a field in a packet Freeciv-web sends or receives? Find its Freeciv-web users.
Has an enum gained or lost a value? Update the corresponding variables in Freeciv-web if they exist.
Is there a change to the meaning of a packet? Find its Freeciv-web users.